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

Document: loomworks-scoping-note-inbound-seam-minimal-slice-v0_1 Version: v0.1 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).

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.1 — 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.