@agenticprimitives/fabric 0.0.0-alpha.4 → 0.0.0-alpha.40

package/dist/cloudflare/principal-gateway-do.js

@@ -1,29 +1,79 @@
+import { canonicalizeJson } from '@agenticprimitives/types';
+import { TERMINAL_INTERACTION_STATES } from '../interaction-machines.js';
 import { admitDeliveryEnvelope, deliveryToExchangeRecord, } from '../delivery-envelope.js';
 import { createDurableObjectSqlVault } from './sql-vault.js';
 import { createDurableObjectOutboxStore } from './outbox-store.js';
 import { createDurableObjectExchangeStore } from './exchange-store.js';
+import { createDurableObjectInteractionStore } from './interaction-store.js';
+import { topicInteractionId, channelIdFromTopicInteraction } from '../protocol-binding.js';
+import { TOPIC_PROFILE } from '../interaction-profile.js';
 import { createDurableObjectAuthorityVerdictCache, } from './authority-verdict-cache.js';
 import { createDurableObjectRequestIdLedger } from './request-id-ledger.js';
 import { createDurableObjectReceiptSigner, } from './receipt-signer.js';
-import { runGatewayOrchestration } from './orchestration-runtime.js';
+import { runGatewayOrchestration, gatewayToolSpecs } from './orchestration-runtime.js';
 import { projectExchangeProvenance, projectRunProvenance, } from '@agenticprimitives/provenance';
 import { createDurableObjectProvenanceStore } from './provenance-store.js';
 import { createDurableObjectChannelStore, projectionAuthorizes } from './channel-store.js';
+/** An ingress was refused before anything was read or written (spec 445 §3.4, DATA-3). */
+export class GatewayAuthError extends Error {
+    reason;
+    constructor(reason) {
+        super(`PrincipalGatewayDO: ${reason}`);
+        this.reason = reason;
+        this.name = 'GatewayAuthError';
+    }
+}
+/** `openInteraction` was asked to open an interaction that already exists as something else — a
+ *  different shape, or one that has ended (spec 445 §3.4, DATB-2). Nothing was written. */
+export class InteractionExistsError extends Error {
+    interactionId;
+    state;
+    reason = 'interaction-exists';
+    constructor(interactionId, state) {
+        super(`PrincipalGatewayDO: interaction ${interactionId} already exists (${state}); open never overwrites`);
+        this.interactionId = interactionId;
+        this.state = state;
+        this.name = 'InteractionExistsError';
+    }
+}
 function json(body, status = 200) {
     return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
 }
+/**
+ * Is `offered` the SAME signed envelope the stored exchange was seeded with?
+ *
+ * The identity is the envelope's full canonical bytes — `canonicalizeJson` over the whole envelope,
+ * `signature` INCLUDED. That is strictly stronger than any of the three weaker identities and implies
+ * them all: same `id`, same `bodyHash`, same signed payload (`hashExchangeEnvelope` covers everything
+ * but the signature) and the same proof over it. An envelope that matches on id and body hash but
+ * carries a different signature, recipient list or timestamp is a DIFFERENT envelope and is refused.
+ * Compared against `envelopes[0]`: later envelopes are responses the exchange accrued, and a
+ * redelivery is of the one that opened it.
+ */
+function isSameSignedEnvelope(stored, offered) {
+    const seed = stored.envelopes[0];
+    return seed !== undefined && canonicalizeJson(seed) === canonicalizeJson(offered);
+}
+const sameAgent = (a, b) => a.toLowerCase() === b.toLowerCase();
+/** The account part of an id (`eip155:1:0xabc` → `0xabc`), lowercased — a verdict names its principal
+ *  as a bare address while a gateway is configured with a CAIP-10. */
+const accountOf = (id) => (id.split(':').pop() ?? '').toLowerCase();
+const sameAccount = (a, b) => accountOf(a) !== '' && accountOf(a) === accountOf(b);
 export class PrincipalGatewayDO {
     state;
     env;
     deps;
     sql;
     exchanges;
+    interactionStore;
     verdicts;
     requestIds;
     receipts;
     outbox;
     provenance;
     channels;
+    /** The callers `admitCaller` minted. Membership IS the proof of minting — nothing else is. */
+    minted = new WeakSet();
     constructor(state, env, deps) {
         this.state = state;
         this.env = env;
@@ -31,7 +81,9 @@ export class PrincipalGatewayDO {
         this.sql = state.storage.sql;
         // Co-resident, DO-local: exchange stream + vault + T1 verdict cache + request-id ledger all share the
         // one SQLite trust domain (L2, §4.0). The receipt signer holds a DO-local software key in DO KV storage.
-        this.exchanges = createDurableObjectExchangeStore(this.sql);
+        // Injected when the deployment's records live elsewhere (ADR-0055); DO-local otherwise.
+        this.exchanges = deps?.exchangeStore ?? createDurableObjectExchangeStore(this.sql);
+        this.interactionStore = deps?.interactionStore ?? createDurableObjectInteractionStore(this.sql);
         this.verdicts = createDurableObjectAuthorityVerdictCache(this.sql);
         this.requestIds = createDurableObjectRequestIdLedger(this.sql);
         this.receipts = createDurableObjectReceiptSigner(state.storage);
@@ -43,9 +95,32 @@ export class PrincipalGatewayDO {
     //  A channel is a shared context on this org's exchange stream; membership is the org's policy (projected
     //  from the app directory listing, spec 313); posting is member-gated fail-closed. Roles = delegations
     //  (C2) and token-gated join (C3) layer on top; the org agent acting in-channel is `orchestrate()` (§15).
-    /** Create/rename a channel owned by this org gateway. */
+    /**
+     * Create/rename a channel owned by this org gateway, and open the Interaction it IS (spec 340 W11).
+     *
+     * A topic was already a governed situation in everything but name: the org owns the board, members
+     * join and leave, `facilitator`/`contributor` are its roles, and it opens and closes. Opening the
+     * Interaction alongside it names that rather than adding a parallel object — the id is DERIVED
+     * (`ixn_topic_<channelId>`), so the two cannot drift and no join table exists to go stale.
+     *
+     * `participationMode: 'derived'`. Membership belongs to the channel (and, for an open topic, to the
+     * organization behind it), so the Interaction stores NO member list. Copying one per topic is what
+     * `apmsg:openParticipation` forbids, and a stale copy is how a removed member keeps posting.
+     */
     async createChannel(channel) {
-        return this.channels.createChannel(channel);
+        await this.channels.createChannel(channel);
+        // A RENAME CHANGES THE NAME AND NOTHING ELSE (spec 445 §3.4, audit DATB-2/DATB-6). The topic's
+        // interaction already exists under its derived id; whatever state it is in — active, suspended,
+        // concluded — and whatever `rev`/`createdAt` it carries are the lifecycle's, moved only by
+        // `transitionInteraction`. So an existing interaction is left exactly as it is, in EVERY state.
+        if (await this.interactionStore.getInteraction(topicInteractionId(channel.channelId)))
+            return;
+        await this.openInteraction({
+            interactionId: topicInteractionId(channel.channelId),
+            profileVersion: TOPIC_PROFILE.profileVersion,
+            participationMode: 'derived',
+            at: channel.createdAt,
+        });
     }
     /**
      * Add a member with a role (spec 318 C2 — the role IS the projection of an org-SA delegation caveat).
@@ -53,9 +128,19 @@ export class PrincipalGatewayDO {
      * satisfies it via the injected `verifyEntitlement` (fail-closed — no credential / no verifier / invalid ⇒
      * rejected). An ungated channel joins openly.
      */
-    async joinChannel(channelId, member, opts = {}) {
+    async joinChannel(channelId, member, caller, opts = {}) {
+        // WHO is being seated is not the caller's to assert (DATA-3): an agent seats ITSELF, or this
+        // gateway's own principal (the organization) seats a member.
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
+        if (!this.selfOrPrincipal(caller, member))
+            return { ok: false, reason: 'actor_mismatch' };
         const channel = await this.channels.getChannel(channelId);
-        if (channel?.joinGate) {
+        // A channel that does not exist has no gate to check, so a join before creation would seat an
+        // agent ahead of the gate it is later created with (audit DATA-10). Refused.
+        if (!channel)
+            return { ok: false, reason: 'unknown_channel' };
+        if (channel.joinGate) {
             const verify = this.deps?.verifyEntitlement;
             if (!verify)
                 return { ok: false, reason: 'gate_unverifiable' };
@@ -70,8 +155,13 @@ export class PrincipalGatewayDO {
         return { ok: true };
     }
     /** Remove a member — **kick = the org revokes** its role delegation (C2). */
-    async leaveChannel(channelId, member) {
-        return this.channels.leave(channelId, member);
+    async leaveChannel(channelId, member, caller) {
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
+        if (!this.selfOrPrincipal(caller, member))
+            return { ok: false, reason: 'actor_mismatch' };
+        await this.channels.leave(channelId, member);
+        return { ok: true };
     }
     async channelMembers(channelId) {
         return this.channels.members(channelId);
@@ -86,44 +176,71 @@ export class PrincipalGatewayDO {
     async projectConversationRole(channelId, projection) {
         await this.channels.putRoleProjection({ ...projection, conversationId: channelId });
     }
-    /** MANAGE-gated (spec 324 §8): project a member's conversation role. `by` must hold a cached projection
+    /** MANAGE-gated (spec 324 §8): project a member's conversation role. The AUTHENTICATED actor (never a
+     *  caller-named `by`, DATA-3) must hold a cached projection
      *  authorizing `manage`. This CACHES an org-issued RoleAssignment + its materializing delegation — it does
      *  not itself grant authority (ADR-0048 #4); the org issues the delegation, then the projection mirrors it. */
-    async putConversationRoleProjection(channelId, projection, by, at) {
-        if (!projectionAuthorizes(await this.channels.roleProjection(channelId, by), 'manage', at))
+    async putConversationRoleProjection(channelId, projection, caller, at) {
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
+        if (!projectionAuthorizes(await this.channels.roleProjection(channelId, caller.actor), 'manage', at))
             return { ok: false, reason: 'not_authorized' };
         await this.channels.putRoleProjection({ ...projection, conversationId: channelId });
         return { ok: true };
     }
     /** MANAGE-gated: clear a member's conversation-role projection (the org revoked the underlying delegation). */
-    async clearConversationRoleProjection(channelId, member, by, at) {
-        if (!projectionAuthorizes(await this.channels.roleProjection(channelId, by), 'manage', at))
+    async clearConversationRoleProjection(channelId, member, caller, at) {
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
+        if (!projectionAuthorizes(await this.channels.roleProjection(channelId, caller.actor), 'manage', at))
             return { ok: false, reason: 'not_authorized' };
         await this.channels.clearRoleProjection(channelId, member);
         return { ok: true };
     }
-    /** MODERATE-gated (spec 324 §8): remove a post from the channel board. `by` must hold a cached projection
+    /** MODERATE-gated (spec 324 §8): remove a post from the channel board. The AUTHENTICATED actor must hold a cached projection
      *  authorizing `moderate`. The exchange itself is NOT deleted (immutable stream + provenance); only its
      *  channel index entry is removed. */
-    async removeChannelPost(channelId, exchangeId, by, at) {
-        if (!projectionAuthorizes(await this.channels.roleProjection(channelId, by), 'moderate', at))
+    async removeChannelPost(channelId, exchangeId, caller, at) {
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
+        if (!projectionAuthorizes(await this.channels.roleProjection(channelId, caller.actor), 'moderate', at))
             return { ok: false, reason: 'not_authorized' };
         await this.channels.removePost(channelId, exchangeId);
         return { ok: true };
     }
     /**
-     * Post to a channel — MEMBER-GATED, fail-closed: only a current member (`record.parties.from`) may post.
+     * Post to a channel — MEMBER-GATED, fail-closed: only a current member may post, and the poster is the
+     * AUTHENTICATED actor: `record.parties.from` must be `caller.actor` (DATA-3), so membership is asked
+     * about who is actually posting, never about a name in the record. A topic whose interaction is not
+     * `active` takes no posts (`interaction-not-active`, DATB-2).
      * The post is persisted on the org's exchange stream via `deliver()` (so it accretes a provenance trace like
      * any exchange) and indexed into the channel. Fan-out to members is the org re-delivering (§4 / Blocker 6).
      */
-    async postToChannel(channelId, record) {
+    async postToChannel(channelId, record, caller) {
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
         const from = record.parties.from;
+        if (!sameAgent(String(from), String(caller.actor)))
+            return { ok: false, reason: 'actor-mismatch' };
         // A poster is either a channel MEMBER (person/org, C1/C2) or an admitted channel BOT (Service SA, C4).
+        // Kept as an explicit pre-check so the caller-facing reason stays `not_a_member`: ingress would also
+        // refuse, but as `not-a-participant`, and a post rejection should say the thing the poster can act on.
         if (!(await this.channels.isMember(channelId, from)) && !(await this.channels.isBot(channelId, from))) {
             return { ok: false, reason: 'not_a_member' };
         }
-        await this.deliver(record);
-        await this.channels.addPost(channelId, String(record.exchangeId), record.updatedAt);
+        // The post now OCCURS IN the topic's Interaction (spec 340 W11) — pinned here rather than trusted
+        // from the caller, because a poster naming someone else's interaction would otherwise file into it.
+        const posted = {
+            ...record,
+            interactionId: topicInteractionId(channelId),
+            profileVersion: TOPIC_PROFILE.profileVersion,
+        };
+        // Threading the refusal rather than discarding it: a post naming an interaction this gateway does
+        // not hold must not be indexed into the channel as though it landed.
+        const delivered = await this.deliver(posted, caller);
+        if (!delivered.ok)
+            return { ok: false, reason: delivered.reason };
+        await this.channels.addPost(channelId, String(posted.exchangeId), posted.updatedAt);
         return { ok: true };
     }
     // ─── C4: channel bots ARE Service Smart Agents (spec 318 §8) ─────────────────────────────────────────
@@ -179,8 +296,10 @@ export class PrincipalGatewayDO {
     async receiptPubkey() {
         return this.receipts.pubkey();
     }
-    /** Sign a `DeliveryReceiptV1` with the DO-local key — the delivery-proof-under-authority-at-T the sender
-     *  gets, decoupled from body storage (spec 316 §3a receipt / Blocker 4). Verify with `verifyDeliveryReceipt`. */
+    /** Sign a `DeliveryReceiptV1` with the DO-local key. PRIVATE: a receipt attests to a delivery this
+     *  gateway RECORDED, so the only callers are the two delivery paths, after the `delivered` fact is in
+     *  the stream. A public signer would be a receipt oracle for any fields a caller cared to name. Verify
+     *  with `verifyDeliveryReceipt`. */
     async signDeliveryReceipt(input) {
         return this.receipts.sign(input);
     }
@@ -188,48 +307,156 @@ export class PrincipalGatewayDO {
      * RECIPIENT-side peer delivery (spec 316 §4 / W4). Transport-admits an inbound `DeliveryEnvelopeV1` (routing
      * + addressing + structural), then persists the exchange, records the `delivered` fact, and returns a
      * DO-signed `DeliveryReceiptV1`. Sender AUTHORITY (envelope signature) is re-verified separately by the gateway
-     * (ADR-0041) — admission here is transport-level only. `recipient` is this gateway's principal.
+     * (ADR-0041) — admission here is transport-level only.
+     *
+     * `recipient` and `tier` are the AUTHENTICATED caller's `principal` and `tier`, and the envelope's `from`
+     * must be its `actor` (spec 445 §3.4, DATA-3): who a delivery is for, which lane it rides and who
+     * sent it are admission's findings, never fields of the call.
+     *
+     * A DELIVERY NEVER OVERWRITES (spec 445 §3.4, audit H-10 / DATA-1). The exchange id comes from the
+     * peer and is known to every counterparty, so it identifies nothing about who is sending. If a record
+     * is already held under it, exactly two things can be true:
+     *
+     *   · the offered envelope IS the stored one (`isSameSignedEnvelope` — full canonical bytes, signature
+     *     included) → an idempotent redelivery. Nothing is rewritten and no second `delivered` event is
+     *     appended; the receipt returned is for the ORIGINAL delivery. Receipts are not stored, so it is
+     *     re-signed over the original `delivered` event's time — same exchange, message, recipient and
+     *     `at`, hence the same attested fact, never a fresh claim that it arrived again now.
+     *   · anything else → refused `exchange-exists`, and NO receipt is signed: a receipt for a delivery
+     *     we did not store would attest to something false.
      */
-    async receiveDelivery(delivery, opts) {
-        const admission = admitDeliveryEnvelope(delivery, { recipient: opts.recipient });
+    async receiveDelivery(delivery, caller, opts) {
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
+        if (!sameAgent(String(delivery.envelope.from), String(caller.actor)))
+            return { ok: false, reason: 'actor-mismatch' };
+        const admission = admitDeliveryEnvelope(delivery, { recipient: caller.principal });
         if (!admission.ok)
             return admission;
-        const rec = deliveryToExchangeRecord(delivery, { tier: opts.tier, at: opts.at });
-        await this.deliver(rec);
-        await this.applyEvent(rec.exchangeId, {
+        const rec = deliveryToExchangeRecord(delivery, { tier: caller.tier, at: opts.at });
+        const held = await this.exchanges.get(rec.exchangeId);
+        if (held) {
+            if (!isSameSignedEnvelope(held, delivery.envelope))
+                return { ok: false, reason: 'exchange-exists' };
+            return this.redeliveryReceipt(held, delivery, opts.at);
+        }
+        // A peer naming an interaction we do not hold, or one it is not in, is refused BEFORE the receipt:
+        // signing a delivery receipt for an exchange we did not store would attest to something false.
+        const delivered = await this.ingest(rec);
+        if (!delivered.ok)
+            return { ok: false, reason: delivered.reason };
+        // A RECEIPT ATTESTS TO A RECORDED DELIVERY. If the `delivered` fact is not in the stream — the
+        // reducer refused it, or the exchange is not there — nothing is signed. The stored record stays;
+        // a redelivery of the same envelope completes it (`redeliveryReceipt`).
+        const recorded = await this.exchanges.append(rec.exchangeId, {
             kind: 'message', seq: 0, at: opts.at, eventType: 'delivered', actor: delivery.envelope.from, messageId: delivery.envelope.id,
         });
+        if (!recorded || !recorded.ok)
+            return { ok: false, reason: recorded ? recorded.reason : 'unknown_exchange' };
         const receipt = await this.signDeliveryReceipt({
             exchangeId: String(delivery.exchangeId), messageId: delivery.envelope.id, recipient: delivery.toGateway, at: opts.at,
         });
         return { ok: true, receipt };
     }
+    /**
+     * The receipt for a redelivery of an envelope this gateway already holds (spec 445 §3.4).
+     *
+     * The time attested is the ORIGINAL `delivered` event's. One case needs a write: a first attempt that
+     * stored the record and stopped before recording `delivered`. The redelivery then completes that
+     * delivery — one event, through the reducer — rather than signing for a fact the stream does not hold.
+     */
+    async redeliveryReceipt(held, delivery, at) {
+        const messageId = delivery.envelope.id;
+        const first = held.events.find((e) => e.kind === 'message' && e.eventType === 'delivered' && e.messageId === messageId);
+        let deliveredAt = first?.at;
+        if (deliveredAt === undefined) {
+            const applied = await this.exchanges.append(held.exchangeId, {
+                kind: 'message', seq: 0, at, eventType: 'delivered', actor: delivery.envelope.from, messageId,
+            });
+            if (!applied || !applied.ok)
+                return { ok: false, reason: applied ? applied.reason : 'unknown_exchange' };
+            deliveredAt = at;
+        }
+        const receipt = await this.signDeliveryReceipt({
+            exchangeId: String(held.exchangeId), messageId, recipient: delivery.toGateway, at: deliveredAt,
+        });
+        return { ok: true, receipt };
+    }
     /**
      * T2 orchestrated lane (spec 316 §15) — a `request`/agent-task INTENT is fulfilled by the Ring-0
      * orchestration loop running IN this gateway, with the co-resident MCP tools as the loop's ToolInvoker
-     * (in-process over the DO-local vault, under the verified `principal`). Only the LLM `planner` is injected;
-     * the loop, the tools, and the vault are the gateway's own. Returns the orchestration `RunResult`. (Absorbing
-     * `A2aTaskDO` + driving this from `alarm()` via a durable task queue is the remaining async-scheduling wrap.)
+     * (in-process over the DO-local vault). Only the LLM `planner` is injected; the loop, the tools, and the
+     * vault are the gateway's own. (Absorbing `A2aTaskDO` + driving this from `alarm()` via a durable task
+     * queue is the remaining async-scheduling wrap.)
+     *
+     * THE SAME §3a GATE AS `invokeFast`, PER STEP (spec 445 §3.4, audit DATA-4). A T2 intent is by design
+     * a peer's request and its text reaches the planner, so nothing here trusts the plan:
+     *
+     *  (A) the cached args-independent verdict for `key` — a miss runs NOTHING (cold path first). The
+     *      principal the tools run as, and whose KEK is resolved, is the VERDICT's. It must be this
+     *      gateway's principal when the deployment names one, and the one the caller says it expects
+     *      (`principal`) when it says: a verdict for A never reaches B's records.
+     *  (B) `runCaveatPass(verdict, tool, args)` for EVERY planned step against the concrete tool and
+     *      arguments — never cached; a denied step throws inside the loop and its tool does not run.
+     *  (C) a single-use `requestId` (+ `now`) for the run. A WRITE tool does not run without one — it is
+     *      not even offered to the planner — and a replayed id is refused before anything runs, so a
+     *      retried intent is not applied twice. The id is released only when no step ran (a legitimate
+     *      retry); once any tool ran it stays consumed, whatever the outcome.
      */
     async orchestrate(input) {
         const deps = this.requireDeps();
         if (!deps.planner)
             throw new Error('PrincipalGatewayDO: no planner configured for T2 orchestration');
-        const vault = this.vault(await deps.wrapperFor(input.principal));
-        const result = await runGatewayOrchestration(input.intent, {
-            planner: deps.planner,
-            registry: deps.tools,
-            vault,
-            principal: input.principal,
-            maxSteps: input.maxSteps,
-        });
-        // W5 — bridge the executed plan into the exchange's provenance A-box as a P-Plan (the SAME trace as the
-        // OrchestratedTask activity, §15). Merged by `exchangeId` when the caller ties the run to an exchange.
-        if (input.exchangeId && input.at) {
-            const { plan } = projectRunProvenance({ exchangeId: input.exchangeId, goal: input.intent.goal, steps: result.plan.steps.map((s) => ({ toolId: s.toolId })) });
-            await this.provenance.put(input.exchangeId, { version: 'ap.provenance.v1', agents: [], activities: [], entities: [], plans: [plan] }, input.at);
+        if (typeof input.runCaveatPass !== 'function')
+            throw new Error('PrincipalGatewayDO: orchestrate requires runCaveatPass');
+        const verdict = await this.verdicts.get(input.key); // (A)
+        if (!verdict)
+            return { ok: false, reason: 'verdict_miss_cold_path_required' };
+        const own = this.env.PRINCIPAL_SA?.trim();
+        if (own && !sameAccount(own, verdict.principal))
+            return { ok: false, reason: 'principal_mismatch' };
+        if (input.principal !== undefined && !sameAccount(input.principal, verdict.principal))
+            return { ok: false, reason: 'principal_mismatch' };
+        if ((input.requestId === undefined) !== (input.now === undefined) || input.requestId === '') {
+            return { ok: false, reason: 'request_id_incomplete' };
+        }
+        const reservation = input.requestId !== undefined ? await this.requestIds.reserve(input.requestId, input.now) : null; // (C)
+        if (input.requestId !== undefined && !reservation)
+            return { ok: false, reason: 'replay' };
+        let ran = 0;
+        try {
+            const vault = this.vault(await deps.wrapperFor(verdict.principal));
+            const offered = gatewayToolSpecs(deps.tools).filter((t) => reservation !== null || deps.tools.get(t.id)?.effect === 'read');
+            const result = await runGatewayOrchestration(input.intent, {
+                planner: deps.planner,
+                registry: deps.tools,
+                vault,
+                principal: verdict.principal,
+                tools: offered,
+                maxSteps: input.maxSteps,
+                authorizeStep: async (tool, args) => {
+                    if (tool.effect !== 'read' && !reservation)
+                        throw new Error('request_id_required');
+                    if (!(await input.runCaveatPass(verdict, tool.name, args)))
+                        throw new Error('caveat_denied'); // (B), never cached
+                    ran += 1;
+                },
+            });
+            // W5 — bridge the executed plan into the exchange's provenance A-box as a P-Plan (the SAME trace as the
+            // OrchestratedTask activity, §15). Merged by `exchangeId` when the caller ties the run to an exchange.
+            if (input.exchangeId && input.at) {
+                const { plan } = projectRunProvenance({ exchangeId: input.exchangeId, goal: input.intent.goal, steps: result.plan.steps.map((s) => ({ toolId: s.toolId })) });
+                await this.provenance.put(input.exchangeId, { version: 'ap.provenance.v1', agents: [], activities: [], entities: [], plans: [plan] }, input.at);
+            }
+            if (reservation)
+                await (ran > 0 ? reservation.commit() : reservation.release());
+            return { ok: true, principal: verdict.principal, result };
+        }
+        catch (e) {
+            if (reservation)
+                await (ran > 0 ? reservation.commit() : reservation.release());
+            throw e;
         }
-        return result;
     }
     /** SENDER-side store-and-forward (spec 316 §4): queue a peer delivery that could not be handed to the
      *  recipient gateway now; `alarm()` retries with backoff until delivered (offline-first, §11a). */
@@ -250,29 +477,294 @@ export class PrincipalGatewayDO {
      * accessor stays key-material-free. Same `state.storage.sql` as the exchange stream — one trust domain.
      */
     vault(wrapper) {
+        // INJECTED WINS. A deployment whose records live in the owner's vault passes `deps.vault`; the
+        // DO-SQL construction below is the fallback for tests and single-tenant self-hosting. Inheriting
+        // the fallback in production is exactly the drift ADR-0055's amendment refuses: a custody change
+        // arriving as a side effect of a runtime change.
+        if (this.deps?.vault)
+            return this.deps.vault(wrapper);
         return createDurableObjectSqlVault(this.sql, wrapper);
     }
     /**
      * T0 communication lane — persist a delivered exchange (sender-proof-only; no case, no RPC — §3). The
      * record is built upstream (envelope validated + `bodyHash`-verified at ingress); the DO is the durable
-     * single writer. Idempotent by `exchangeId` (put overwrites the same id; a genuine redelivery is caught by
-     * the message event's `idempotencyKey` at the reducer). Receipt signing (`DeliveryReceiptV1`, DO-local
-     * software key) is a W2 follow-step.
+     * single writer.
+     *
+     * AUTHENTICATED (spec 445 §3.4, audit DATA-3): `caller` is minted by `admitCaller`; the record's
+     * `principal` must be the caller's, its `parties.from` the caller's `actor`, and its `tier` is the
+     * caller's whatever the record says.
+     *
+     * INSERT-ONLY (spec 445 §3.4, audit H-10 / DATA-1). Every way into this method carries an exchange id
+     * somebody else chose — a peer's delivery, a member's channel post, a `/deliver` body — so it never
+     * overwrites: the store's `insert` either writes a new record or returns the one already held. An
+     * offer that is canonically identical to the held record is a retry and succeeds without writing;
+     * anything else under a held id is refused `exchange-exists`. (An exchange that has since accrued
+     * events no longer equals its seed, so a late retry of the seed is refused — `receiveDelivery`
+     * decides redelivery by the signed envelope instead, which is the identity that survives.) Changing a
+     * held exchange is the reducer's job (`applyEvent`), never a second delivery's.
      */
-    async deliver(record) {
-        await this.exchanges.put(record);
+    async deliver(record, caller) {
+        // WHOSE record, on WHICH lane, from WHOM — admission's findings, never the body's (DATA-3). A record
+        // naming another principal or another sender is refused; its `tier` is replaced, not believed.
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
+        if (!sameAgent(String(record.principal), String(caller.principal)))
+            return { ok: false, reason: 'principal-mismatch' };
+        if (!sameAgent(String(record.parties.from), String(caller.actor)))
+            return { ok: false, reason: 'actor-mismatch' };
+        return this.ingest(record.tier === caller.tier ? record : { ...record, tier: caller.tier });
+    }
+    /** The store half of `deliver`, after the caller has been established. */
+    async ingest(record) {
+        const admission = await this.admitIntoInteraction(record);
+        if (!admission.ok)
+            return admission;
+        const stored = await this.exchanges.insert(record);
+        if (!stored.inserted) {
+            if (canonicalizeJson(stored.existing) !== canonicalizeJson(record))
+                return { ok: false, reason: 'exchange-exists' };
+            // The identical record again: already stored, already projected. Nothing to write.
+            return admission;
+        }
         // W5 — project the exchange into the PRIVATE provenance A-box (one trace, §15). Off the sender's hot path
         // conceptually, but co-located here (demo-scale); a public row is derived SEPARATELY via the S1 firewall.
         await this.provenance.put(String(record.exchangeId), projectExchangeProvenance(this.exchangeToProvenanceInput(record)), record.updatedAt);
+        return admission;
     }
-    /** Append one event to an existing exchange (case transitions / transport moves), reduced fail-closed. */
-    async applyEvent(exchangeId, event) {
+    /**
+     * The interaction-aware half of ingress (spec 340 W7).
+     *
+     * THREE OUTCOMES, and which is which is the whole design:
+     *
+     * 1. NO `interactionId` → delivered, with an `unpinned-exchange` note. An Exchange without an
+     *    Interaction is a MESSAGE (ADR-0058 §12) — a legitimate state, and the overwhelmingly common
+     *    one. Auto-creating an interaction per message would make "a thread is a projection, not a
+     *    container" false by turning every message into a container.
+     *
+     *    Not unconditionally, though (spec 445 §3.4): with no interaction there is no membership to ask,
+     *    so the record must at least be true about its own parties — `admitUnpinned`. Like outcome 3
+     *    this is the record's shape, never authority.
+     *
+     * 2. UNKNOWN `interactionId` → REFUSED. Interactions are opened by their custodian
+     *    (`openInteraction`), never conjured by a sender. If ingress created one from a sender-supplied
+     *    id, any peer could seed arbitrary interactions with arbitrary participations on someone else's
+     *    gateway, then post into them — inventing a governed situation the owner never entered.
+     *
+     * 3. KNOWN `interactionId` → the interaction must be `active` (DATB-2), and the sender must be a
+     *    current participant. An exchange claiming to occur
+     *    in an interaction whose membership does not include its sender is a record that misrepresents
+     *    the situation. This is an integrity check on the record's shape, NOT authority: being a
+     *    participant is not permission to do anything (ADR-0048 §4).
+     *
+     * Two conditions are NOTED rather than refused, because refusing them would lose true records:
+     *   · a profile-version mismatch — a mid-flight profile bump is legal, and the per-exchange pin is
+     *     the signal that survives, so this reports (spec 340 §6);
+     *   · a pinned context digest we do not hold — normal for an INBOUND delivery, where the snapshot
+     *     lives on the sender's gateway. Dropping the message would be fail-closed in the wrong place;
+     *     the digest stays pinned and resolvable later. What we must not do is pretend it is replayable.
+     */
+    async admitIntoInteraction(record) {
+        if (!record.interactionId)
+            return this.admitUnpinned(record);
+        const interaction = await this.interactionStore.getInteraction(record.interactionId);
+        if (!interaction)
+            return { ok: false, reason: 'unknown-interaction' };
+        // THE LIFECYCLE IS ENFORCED HERE (spec 445 §3.4, audit DATB-2). `suspend`, `conclude` and `abandon`
+        // are the custodian's stop controls; they stop something only if ingress asks. Only `active` takes
+        // exchanges — checked BEFORE membership, so the refusal names the situation rather than the sender.
+        // Leaving `suspended` is `resume` (custodial, through the machine); nothing leaves a terminal state.
+        if (interaction.lifecycleState !== 'active') {
+            return { ok: false, reason: 'interaction-not-active', state: interaction.lifecycleState };
+        }
+        // ONE membership question, answered by whichever source actually owns it (spec 340 W11). For an
+        // `asserted` interaction the record IS the membership. For a `derived` one — an open org topic —
+        // the organization owns it, and this asks the org's own projection rather than a per-topic copy
+        // that could disagree with it. A stale copy of a membership list is how a removed member keeps
+        // posting, so there is no copy.
+        const isParticipant = interaction.participationMode === 'derived'
+            ? await this.resolveDerivedParticipation(interaction.interactionId, record.parties.from)
+            : interaction.participations.some((p) => p.agent === record.parties.from && p.leftAt === undefined);
+        if (!isParticipant)
+            return { ok: false, reason: 'not-a-participant' };
+        const notes = [];
+        if (record.profileVersion && record.profileVersion !== interaction.profileVersion) {
+            notes.push({ kind: 'profile-downgrade', pinned: record.profileVersion, inForce: interaction.profileVersion });
+        }
+        if (record.contextDigest && !(await this.interactionStore.getContextSnapshot(record.contextDigest))) {
+            notes.push({ kind: 'context-unavailable', digest: record.contextDigest });
+        }
+        return { ok: true, interactionId: interaction.interactionId, notes };
+    }
+    /**
+     * An exchange with no interaction is admitted only if its sender is a party of the record it
+     * delivers (spec 445 §3.4, audit H-10 / DATA-1). Two checks, both fail-closed:
+     *
+     *   · the delivered envelope's `from` IS the record's `parties.from` — a record cannot attribute
+     *     somebody's envelope to somebody else;
+     *   · this gateway's principal is a party (`from`, or in `to`/`cc`) — a gateway stores its own
+     *     principal's exchanges, as sender or as recipient, and nobody else's.
+     *
+     * The principal is `PRINCIPAL_SA` when the deployment names it, else the record's own `principal`
+     * (a gateway that cannot name itself can only check the record against itself).
+     */
+    admitUnpinned(record) {
+        const from = String(record.parties.from);
+        const seed = record.envelopes[0];
+        if (seed && !sameAgent(String(seed.from), from))
+            return { ok: false, reason: 'not-a-party' };
+        const holder = this.env.PRINCIPAL_SA?.trim() || String(record.principal);
+        const parties = [from, ...record.parties.to.map(String), ...(record.parties.cc ?? []).map(String)];
+        if (!parties.some((p) => sameAgent(p, holder)))
+            return { ok: false, reason: 'not-a-party' };
+        return { ok: true, notes: [{ kind: 'unpinned-exchange' }] };
+    }
+    /**
+     * Membership for a `derived` interaction.
+     *
+     * Topic interactions carry `ixn_topic_<channelId>`, so the channel is recoverable from the id and the
+     * answer comes from the channel store — the same member-or-bot test `postToChannel` already applies.
+     * That is the point of doing this: the gate stops being a second check that could drift from the
+     * first, and becomes the same check asked once.
+     *
+     * Fail-closed by construction: an id that names no known derivation source resolves to `false`, so a
+     * `derived` interaction with no resolver admits nobody rather than everybody.
+     */
+    async resolveDerivedParticipation(interactionId, agent) {
+        const channelId = channelIdFromTopicInteraction(interactionId);
+        if (!channelId)
+            return false;
+        return (await this.channels.isMember(channelId, agent)) || (await this.channels.isBot(channelId, agent));
+    }
+    /**
+     * Open a governed situation on this gateway. The custodian is always THIS principal — an interaction
+     * is custodied by the gateway that holds it, and accepting a caller-supplied principal would let a
+     * peer name someone else as custodian of a situation on our storage.
+     *
+     * CREATE-ONLY (spec 445 §3.4, audit DATB-2). Opening never overwrites: an interaction already held
+     * under this id is returned as it stands when it is LIVE and was opened with the same profile,
+     * participation mode, participations and bindings (a retry); anything else — a different shape, or
+     * an interaction that has ended — throws `InteractionExistsError` and writes nothing. In particular
+     * there is no reopening a concluded interaction: the machine has no transition out of a terminal
+     * state, and `open` is not a way round it. (`suspended → active` is `resume`, via
+     * `interactions.transitionInteraction`, custodial and counted in `rev`.)
+     */
+    async openInteraction(input) {
+        const participationMode = input.participationMode ?? 'asserted';
+        if (participationMode === 'derived' && (input.participations?.length ?? 0) > 0) {
+            // Refused rather than silently dropped: a caller passing both has a mental model where the list
+            // matters, and letting the write succeed would leave them believing a stale copy is authoritative.
+            throw new Error('openInteraction: a derived interaction must not carry participations');
+        }
+        const held = await this.interactionStore.getInteraction(input.interactionId);
+        if (held) {
+            const sameOpen = !TERMINAL_INTERACTION_STATES.includes(held.lifecycleState) &&
+                held.profileVersion === input.profileVersion &&
+                held.participationMode === participationMode &&
+                canonicalizeJson(held.participations) === canonicalizeJson(input.participations ?? []) &&
+                canonicalizeJson(held.protocolBindings ?? []) === canonicalizeJson(input.protocolBindings ?? []);
+            if (!sameOpen)
+                throw new InteractionExistsError(String(input.interactionId), held.lifecycleState);
+            return held;
+        }
+        const record = {
+            version: 'ap.interaction.v1',
+            interactionId: input.interactionId,
+            profileVersion: input.profileVersion,
+            principal: this.requirePrincipal(),
+            lifecycleState: 'active',
+            participationMode,
+            participations: input.participations ?? [],
+            ...(input.protocolBindings ? { protocolBindings: input.protocolBindings } : {}),
+            createdAt: input.at,
+            updatedAt: input.at,
+            rev: 0,
+        };
+        await this.interactionStore.putInteraction(record);
+        return record;
+    }
+    /**
+     * Append one event to an existing exchange (case transitions / transport moves), reduced fail-closed.
+     *
+     * The case machine authorizes a transition by comparing `event.actor` with the record's parties, so
+     * the actor must not be the caller's to choose (DATA-3): `event.actor` must be the AUTHENTICATED
+     * actor, on a minted caller for this gateway's principal. `null` ⇒ no such exchange. (`event.at` is
+     * still the caller's — audit DATB-11, open: the embedder stamps it.)
+     */
+    async applyEvent(exchangeId, event, caller) {
+        if (!this.isMinted(caller))
+            return { ok: false, reason: 'unauthenticated' };
+        // `message`/`case` events name their actor; `artifact`/`transport` events are the runtime's own
+        // moves on this stream and name none, so only the gateway's principal makes them.
+        const claimed = event.kind === 'message' || event.kind === 'case' ? event.actor : caller.principal;
+        if (!sameAgent(String(claimed), String(caller.actor)))
+            return { ok: false, reason: 'actor-mismatch' };
         return this.exchanges.append(exchangeId, event);
     }
+    /**
+     * Mint the caller for one admitted request (spec 445 §3.4, audit DATA-3) — the ONLY way to obtain an
+     * `AuthenticatedCaller`. Runs the injected authenticator; throws `GatewayAuthError` when none is
+     * configured (fail closed), when the request is not admitted, or when it was admitted for a
+     * principal other than this gateway's (`PRINCIPAL_SA`). A gateway that does not name itself takes the
+     * authenticator's principal — the embedder that built the port is the one that addressed this DO.
+     */
+    async admitCaller(request) {
+        const authenticate = this.deps?.authenticate;
+        if (typeof authenticate !== 'function')
+            throw new GatewayAuthError('authenticator_not_configured');
+        const found = await authenticate(request);
+        if (!found || !found.principal || !found.actor || !found.tier)
+            throw new GatewayAuthError('unauthenticated');
+        const own = this.env.PRINCIPAL_SA?.trim();
+        if (own && !sameAgent(own, String(found.principal)))
+            throw new GatewayAuthError('principal_mismatch');
+        const caller = Object.freeze({ principal: found.principal, tier: found.tier, actor: found.actor });
+        this.minted.add(caller);
+        return caller;
+    }
+    isMinted(caller) {
+        return typeof caller === 'object' && caller !== null && this.minted.has(caller);
+    }
+    /** `member` is the authenticated actor, or the actor is this gateway's own principal acting on it. */
+    selfOrPrincipal(caller, member) {
+        return sameAgent(String(caller.actor), member) || sameAgent(String(caller.actor), String(caller.principal));
+    }
+    // ─── The interaction spine (spec 340 W6) ────────────────────────────────────────────────────────────
+    //  Exposed as ONE accessor rather than a dozen forwarding methods. The DO is already large, and each
+    //  forwarder would be a place for the store's invariants to be quietly re-implemented — the point of
+    //  routing every transition through its machine is undone by a wrapper that sets state itself.
+    //
+    //  Persisting here confers nothing: an interaction record says a situation exists, a commitment record
+    //  says an obligation was recorded. Neither authorizes anything (ADR-0041/0043).
+    /** Interactions, context snapshots, decisions, commitments, per-viewer inbox state. */
+    get interactions() {
+        return this.interactionStore;
+    }
+    /**
+     * Everything still owed on this gateway — the query the single `case` field could not answer.
+     *
+     * A case could be `denied` while an obligation stayed outstanding with nowhere to record it, because
+     * one field was serving three machines (spec 340 §R). Concluding an interaction deliberately does NOT
+     * appear here as a discharge: closing a conversation ends the conversation, never the promise made
+     * inside it.
+     */
+    async openCommitments() {
+        return this.interactionStore.listOpenCommitments();
+    }
+    /** The gateway's own SA. Throws rather than defaulting: a wrong custodian on a governed situation is
+     *  worse than a refused write, and empty-string config is treated as unset (a wrangler `VAR = ""`
+     *  binds an empty string, which `??` would happily accept). */
+    requirePrincipal() {
+        const sa = this.env.PRINCIPAL_SA?.trim();
+        if (!sa)
+            throw new Error('PrincipalGatewayDO: PRINCIPAL_SA is not configured; cannot custody an interaction');
+        return sa;
+    }
     requireDeps() {
-        if (!this.deps)
+        const d = this.deps;
+        if (!d || !d.verifyToken || !d.wrapperFor || !d.tools) {
             throw new Error('PrincipalGatewayDO: co-resident MCP deps not configured (verifyToken/wrapperFor/tools)');
-        return this.deps;
+        }
+        return d;
     }
     /** The verdict cache (revoke / epoch-sweep hooks + read for tests). */
     get authority() {
@@ -304,6 +796,10 @@ export class PrincipalGatewayDO {
         const verdict = await this.verdicts.get(input.key); // (A)
         if (!verdict)
             return { ok: false, reason: 'verdict_miss_cold_path_required' };
+        // A verdict for another principal never reaches this gateway's vault (spec 445 §3.4, DATA-4).
+        const own = this.env.PRINCIPAL_SA?.trim();
+        if (own && !sameAccount(own, verdict.principal))
+            return { ok: false, reason: 'principal_mismatch' };
         if (!(await input.runCaveatPass(verdict, input.tool, input.args)))
             return { ok: false, reason: 'caveat_denied' }; // (B), never cached
         const tool = deps.tools.get(input.tool);
@@ -328,21 +824,47 @@ export class PrincipalGatewayDO {
     async inbox() {
         return this.exchanges.list();
     }
+    /**
+     * The HTTP surface. EVERY route authenticates first (spec 445 §3.4, audit DATA-3): `admitCaller`
+     * runs the injected authenticator before the path is even looked at, so with no authenticator the
+     * answer is 503 for everything, and an unadmitted request is 401 whatever it asked for. `principal`,
+     * `tier` and `actor` then come from that result alone — a body naming another principal or another
+     * actor is 403, and a body's `tier` is ignored.
+     */
     async fetch(request) {
         const url = new URL(request.url);
         try {
+            let caller;
+            try {
+                caller = await this.admitCaller(request);
+            }
+            catch (e) {
+                if (!(e instanceof GatewayAuthError))
+                    throw e;
+                const status = e.reason === 'authenticator_not_configured' ? 503 : e.reason === 'unauthenticated' ? 401 : 403;
+                return json({ ok: false, error: e.reason }, status);
+            }
+            const refusedIdentity = (reason) => reason === 'principal-mismatch' || reason === 'actor-mismatch' || reason === 'unauthenticated';
             if (request.method === 'POST' && url.pathname === '/deliver') {
-                await this.deliver((await request.json()));
-                return json({ ok: true });
+                const outcome = await this.deliver((await request.json()), caller);
+                // 403 for an identity the body asserted and admission did not; otherwise 409, not 400: the
+                // request is well-formed and the situation is what refuses it.
+                if (!outcome.ok)
+                    return json({ ok: false, error: outcome.reason, ...(outcome.state ? { state: outcome.state } : {}) }, refusedIdentity(outcome.reason) ? 403 : 409);
+                return json({ ok: true, interactionId: outcome.interactionId, notes: outcome.notes });
             }
             if (request.method === 'POST' && url.pathname === '/event') {
                 const body = (await request.json());
-                const result = await this.applyEvent(body.exchangeId, body.event);
+                const result = await this.applyEvent(body.exchangeId, body.event, caller);
                 if (result === null)
                     return json({ ok: false, error: 'unknown_exchange' }, 404);
-                return result.ok ? json({ ok: true }) : json({ ok: false, error: result.reason }, 409);
+                return result.ok ? json({ ok: true }) : json({ ok: false, error: result.reason }, refusedIdentity(result.reason) ? 403 : 409);
             }
             if (request.method === 'GET' && url.pathname === '/inbox') {
+                // The whole stream is the principal's own: an admitted third party (a peer delivering, a member
+                // posting) is a participant, and that does not make it a reader.
+                if (!sameAgent(String(caller.actor), String(caller.principal)))
+                    return json({ ok: false, error: 'actor-mismatch' }, 403);
                 return json({ ok: true, exchanges: await this.inbox() });
             }
             // TODO (W2 follow-steps, spec 316 §3/§4/§15):