Loomworks Scoping Note — Minimal testable inbound seam slice — v0.2

Document: loomworks-scoping-note-inbound-seam-minimal-slice-v0_2 Version: v0.2 Date: 2026-06-29 Provenance: Claude.ai scoping session. Operator: Marvin Percival. Follows the bidirectional-governed-integration-substrate investigation (b7a0703); the Operator chose to scope the inbound half first, as a minimal testable slice, to gain confidence in the architectural intent before scoping the harder outbound (provider) half — which is where the thread began ("web requests and resolution of returned text into Companion"). Status: Scoping note. Decisions + a Step-0 grounding brief. NOT yet a CR. The full inbound architecture (all caller kinds, OVA-issued auth, intent-gating, anomaly surfacing — investigation §4/§6/§10) is deferred; this is the walking skeleton that proves the seam, to be extended against what it teaches. Reads with: loomworks-investigation-bidirectional-governed-integration-substrate-v0_1 (the inbound half it instances); loomworks-investigation-companion-source-provider-abstraction-v0_1 (the outbound half, sequenced after).

Plain-language summary

The smallest real thing that proves the inbound seam: one authenticated endpoint that an external system can POST a fact to, targeting an engagement — and the fact lands in that engagement's Memory, attested by FORAY, marked as having arrived through the inbound seam. You test it with a single curl: POST a JSON fact, then look at the engagement's Memory and see it there, governed. It accepts data only (a fact), never a command — so the bright line (data, not commands) is enforced by construction, not policy. Everything else the inbound investigation named — other caller kinds, the full auth model, Operator-gated intent — is deferred until this skeleton proves the seam works. This is the confidence-builder before the harder outbound half.

Why inbound first, minimal, now

• Testable from a terminal. Inbound you can drive — curl a POST and watch what Loomworks does. Outbound requires a live external source you don't control. Prove the governed-transit pattern on the edge you can drive, then carry the confidence to the harder half.
• Walking-skeleton discipline. The smallest real slice that exercises the whole path (arrive → authenticate → attest → land in Memory → provenance) is worth more than a full architecture that's never had a real POST through it. Scope the rest against what the skeleton teaches — the "exists is not works" discipline applied to architecture.
• The sequencing the Operator named: minimal inbound → confidence in architectural intent → then outbound (where the thread started).

Worked use cases (what inbound pass-through is for)

To make the seam concrete: a foreign system sends a fact into Loomworks, and Loomworks makes that fact attested (FORAY signs that it happened, when, from where), provenanced (which system sent it is recorded), and remembered (it lands in an engagement's Memory, where the Companion can reason about it). The foreign system gets an audit trail and a memory it didn't build. The integration is trivial — it's a POST — but the value is the band it passes through. Four cases:

1. A coaching client's assessment tool reports a score. A coach has a client engagement in Loomworks. The client finishes a 360-feedback assessment in a third-party tool; that tool POSTs the result ({"client": ..., "assessment": "360-feedback", "score": 72}). It lands in the client's engagement Memory as an attested event — "this score arrived from the assessment tool on this date." When the coach later asks the Companion "where's my client at?", the Companion knows the assessment came in, from where, and when — without the coach re-typing it.

2. A field sensor reports a reading (FarmGuard-style). An agricultural engagement has soil sensors. A sensor hub POSTs a reading ({"sensor": "bed-3", "moisture": 18}). It lands in the engagement's Memory, attested and provenanced. The value isn't the number — it's that the reading is now part of the engagement's remembered history, the Companion can notice patterns across readings, and each reading carries proof of when it arrived and from which sensor.

3. A foreign SaaS announces a state change (webhook). An expense system fires a webhook when an invoice is approved ({"event": "invoice_approved", "amount": ..., "vendor": ...}). Loomworks receives it into the relevant engagement's Memory as an attested event. The SaaS already did its job; Loomworks adds that the approval is now recorded in the engagement's governed memory with provenance — so "show me what happened on this engagement" includes the approval, traceable to its source. The Companion can answer questions spanning the foreign system's events and the Operator's own work, because both live in one remembered place.

4. One Loomworks engagement notifies another (internal — same shape). A credit-management engagement notices a balance crossed a threshold and POSTs that fact into a different engagement's Memory. Internally, "one engagement telling another" uses the exact same inbound seam as an external system — the seam doesn't care whether the caller is outside or inside. Building the seam once gives both external integration and internal engagement-to-engagement signalling, with the same governance.

The common thread: a foreign system sends a fact; Loomworks makes it attested, provenanced, and remembered. And the boundary that makes it safe: every case is a fact arriving, never a command. The assessment tool reports a score; it doesn't tell Loomworks to do something. The sensor reports moisture; it doesn't trigger an action. The seam takes data in and remembers it — it never lets the foreign system reach through and drive Loomworks. (A foreign system wanting Loomworks to act becomes Operator-gated intent — a separate, later capability, not a pass-through.) This minimal slice is only the fact-arriving case — which is exactly why it's both useful and safe to test first.

The slice (what gets built — pending Step-0 grounding)

One authenticated, engagement-scoped inbound endpoint. An external system POSTs a JSON fact targeting an engagement. It lands as a FORAY-attested event in that engagement's Memory, with provenance marking source = inbound_seam. Curl-testable. Data only — bright-line-safe by construction.

Decisions (leans — Operator overrides any)

1. Endpoint shape. POST /engagements/{id}/inbound — engagement-scoped, target in the URL, mirroring the existing upload/seed engagement-scoped routes. (Confirm the exact path convention at Step 0.)
2. Auth — minimal-but-real. A per-engagement inbound token the caller presents (a declared secret). NOT "no auth" (that wouldn't test the seam) and NOT the full OVA-issued-credential model (that's the ship version) — a per-engagement token is small, real, and the seed of the OVA model. (Step 0: does an equivalent already exist — API tokens, a per-engagement secret mechanism — or is this net-new? The engine has session cookies + passkeys; an inbound token is a different shape.)
3. What lands — an event. The inbound payload lands as an event (the substrate's existing event type), provenance-marked source = inbound_seam. Assertion-drafting deferred — the event is the faithful record; turning it into an assertion is a later step (same posture as the upload pathway, which writes events but leaves assertion-drafting unbuilt). Event first, attested; assertions later.
4. FORAY attestation — REQUIRED, even minimal. The inbound event is FORAY-attested at the engine substrate (the reserved seam), per the standing FORAY-at-substrate discipline. This is the point of the slice — proving governed transit — so it cannot be skipped. A non-attested inbound endpoint would not test the architectural intent.
5. Bright line — enforced by construction. The endpoint accepts a data payload only and structurally only writes an event to Memory. It cannot express a command — there is no code path from the inbound endpoint to an action. So the §6 bright line (data, not commands) is enforced structurally, not by a policy check. This is the cleanest first proof of the bright line.
6. The test (acceptance). curl -X POST .../engagements/{id}/inbound -H "<token>" -d '{"fact": ...}' → the fact appears in the target engagement's Memory as an attested event, provenance-marked inbound. POST it, look at Memory, it's there and it's governed. A real POST against the running engine — the live-check acceptance, not a mocked test.

Deferred (NOT this slice — investigation §4/§6/§10)

• Other inbound caller kinds (stream-in, internal events, channel messages) — §4.1.
• The full auth model (OVA-issued credentials) — this slice uses a per-engagement token as the seed.
• Idempotency keys — named in §5.1; a real ship concern, deferred for the skeleton (a re-POST may double-write in the minimal slice; acceptable for a test, flagged for the next slice).
• Operator-gated structured intent (§6) — this slice is data-only; intent-gating is the next capability, with its own approval surface.
• Anomaly surfacing — §10.
• Assertion-drafting from the inbound event — deferred (§3 above).

Step 0 — grounding brief (run BEFORE the CR; read-only, no build)

The slice's true size depends entirely on the attachment point. The investigation flagged the push gateway as "a new architectural surface," but the upload pathway is the strongest candidate to reuse — the inbound seam is structurally an upload that arrives via API instead of a file. Ground, against the current engine main:

1. The upload pathway's event-writing machinery. The upload pathway writes UploadEventReceived events with provenance (filed: "engine writes UploadEventReceived events with provenance"). Show the code path: where the event is written, how provenance is attached, how FORAY attestation is invoked. Can the inbound endpoint reuse this machinery — swapping file-arrival for API-payload-arrival — or is it genuinely net-new? This is the load-bearing question; it sizes the whole slice.
2. Engagement-scoped route convention. Confirm the existing engagement-scoped route shape (upload, seed, instantiate) so POST /engagements/{id}/inbound follows convention.
3. Event type + provenance. What event type does the inbound fact become — reuse an existing event, or a new InboundEventReceived? How is provenance source marked, and is there an existing inbound-vs-upload-vs-conversation provenance distinction to extend?
4. FORAY attestation seam. Where/how is FORAY invoked for an event-writing action (the 16 reserved seams)? Confirm the inbound event hits the same attestation path — the slice's whole point.
5. Auth mechanism for a per-engagement token. Does anything token-shaped exist (API tokens, per-engagement secrets), or is the inbound token net-new? What's the smallest real auth that isn't the session-cookie/passkey path (those are Operator-interactive; inbound is system-to-system)?
6. Where the landed event is visible. After the POST, where does the Operator SEE the inbound event — the engagement's Memory room (the event list)? Confirm the test is observable through the existing surface (so "look at Memory and see it" is a real check).

Report especially #1 — reuse-upload-machinery vs. net-new — because that determines whether this is a thin route (likely, small) or a new surface (bigger). Then the CR is scoped against the real attachment point.

What this proves (the confidence the Operator wants)

If a curl'd external fact lands in an engagement's Memory, attested, provenance-marked, data-only — then the architectural intent is proven on the testable edge: external system → inbound seam → governance band (FORAY/provenance) → Memory, with the bright line holding by construction. That is the inbound half of the bidirectional thesis, walking. With that confidence, the outbound (provider) half — the harder, reach-out-to-live-sources direction where the thread began — gets scoped next, against a proven governed-transit pattern.

Companion documents

• loomworks-investigation-bidirectional-governed-integration-substrate-v0_1 — the inbound half this instances (§4 caller kinds, §6 bright line, §10 open questions — this slice settles a minimal subset).
• loomworks-investigation-companion-source-provider-abstraction-v0_1 — the outbound half, sequenced after this slice proves the pattern.
• The upload pathway (filed: UploadEventReceived events with provenance) — the candidate attachment point (Step 0 #1).
• The Loomworks seed + architecture spec — FORAY-at-substrate, provenance, the event model, engagement-scoped routes.

DUNIN7 — Done In Seven LLC — Miami, Florida Loomworks Scoping Note — Minimal testable inbound seam slice — v0.2 — 2026-06-29 The walking skeleton of the inbound seam: one authenticated, engagement-scoped endpoint (POST /engagements/{id}/inbound, per-engagement token) where an external system POSTs a JSON fact that lands as a FORAY-attested event in the target engagement's Memory, provenance-marked source=inbound_seam, curl-testable. Data only — the bright line (data, not commands) enforced by CONSTRUCTION (the endpoint can only write an event; no path to action). Proves the governed-transit pattern (external → seam → FORAY/provenance → Memory) on the edge the Operator can drive with curl, building confidence before the harder OUTBOUND (provider) half — where the thread began. Step-0 grounding is load-bearing: does the inbound endpoint REUSE the upload pathway's event/provenance/FORAY machinery (likely → thin route) or is it net-new (→ new surface)? Deferred: other caller kinds, OVA-issued auth, idempotency, Operator-gated intent, anomaly surfacing, assertion-drafting. Sequencing: minimal inbound → confidence → outbound.