@agenticprimitives/fabric 0.0.0-alpha.1

package/dist/exchange-record.d.ts

@@ -0,0 +1,131 @@
+import type { MessageEnvelopeV1, MessageKind, MessageEventType, MessageId, Hex32, ContextRefV1 } from './messaging/index.js';
+import { hashMessageEnvelope } from './messaging/index.js';
+import type { AuthorityRef } from './interactions/index.js';
+import type { AuthorityTier } from '@agenticprimitives/tool-policy';
+import type { CanonicalAgentId } from '@agenticprimitives/types';
+import type { VaultRef } from '@agenticprimitives/vault';
+import type { ExecState, CaseState } from './exchange-state.js';
+import type { CaseTransition } from './case-machine.js';
+/** The exchange spine id — replaces today's `taskId` / `int_`+`run_` / `conv_`+`msg_` id families. */
+export type ExchangeId = `xch_${string}`;
+/**
+ * The signed wire object (spec §b + spec 324 §9). Absorbs `MessageEnvelopeV1` + the A2A message. A
+ * communication envelope carries none of the execution fields, so it canonicalizes byte-for-byte as a
+ * `MessageEnvelopeV1` (zero wire change). `ExchangeEnvelopeV1` is the canonical name — not every envelope
+ * carries an Intent — with `MessageEnvelopeV1` as the communication-profile subtype and the execution profile
+ * (`skill`/`argsRef`/`argsHash` set) as the execution subtype.
+ */
+export interface ExchangeEnvelopeV1 extends MessageEnvelopeV1 {
+    /** Execution-tier only: the invoked skill NAME. The gate server-computes the selector from this
+     *  (`computeSkillSelector`) and never trusts a client-supplied selector. Absent on communication. */
+    skill?: string;
+    /** Execution-tier only: vault-ref to the canonical invocation args (hash-bound like `body`). Absent on
+     *  communication. */
+    argsRef?: VaultRef;
+    /** Execution-tier only: SHA-256 over the canonical args, bound into the single-use requestId (spec §3a). */
+    argsHash?: Hex32;
+}
+/** @deprecated Use {@link ExchangeEnvelopeV1} — structurally identical (`ap.message.v1`), retained for
+ *  callers; not every envelope carries an Intent (spec 324 §9). */
+export type IntentEnvelopeV1 = ExchangeEnvelopeV1;
+/** Reuses `messaging.hashMessageEnvelope` byte-for-byte so absorbed signatures/receipts stay valid (spec §b) —
+ *  ZERO wire change across the W5 rename. For an execution envelope the extra fields participate in the
+ *  canonical hash (a distinct signing domain). */
+export declare const hashExchangeEnvelope: typeof hashMessageEnvelope;
+/** @deprecated Use {@link hashExchangeEnvelope} — identical function (spec 324 §9). */
+export declare const hashIntentEnvelope: typeof hashMessageEnvelope;
+/** A vault-resident, hash-bound artifact produced by an exchange (result, file, generated credential, …). */
+export interface ArtifactRef {
+    ref: VaultRef;
+    hash: Hex32;
+    contentType?: string;
+}
+/** Common fields of every fabric event. Single-writer (the gateway DO), seq-numbered, idempotency-keyed,
+ *  hash-bound into the per-conversation causal chain (spec 306). */
+export interface ExchangeEventBase {
+    seq: number;
+    at: string;
+    /** Replayed event with the same key is a no-op (no second row). */
+    idempotencyKey?: string;
+    /** Hash binding this event into the spec-306 causal chain. */
+    entryHash?: Hex32;
+}
+/**
+ * The append-only fabric event stream element (spec §b) — the UNIFIED union that absorbs messaging's
+ * `MessageEventV1` (`kind:'message'`), the interaction transition (`kind:'case'`), artifact production
+ * (`kind:'artifact'`), and pure-transport exec moves driven by the T2 runtime (`kind:'transport'`).
+ *  - `message` events are INBOX read-receipt/lifecycle facts — they update the inbox projection, NOT exec/case.
+ *  - `case` events drive the case machine; `exec` follows by PROJECTION (`expectedExecForCase`).
+ *  - `transport` events are the only ones validated against `fulfillment`'s task-edge graph (`canTaskTransition`).
+ */
+export type ExchangeEventV1 = (ExchangeEventBase & {
+    kind: 'message';
+    eventType: MessageEventType;
+    actor: CanonicalAgentId;
+    messageId: MessageId;
+    evidenceRef?: VaultRef;
+}) | (ExchangeEventBase & {
+    kind: 'case';
+    transition: CaseTransition;
+    actor: CanonicalAgentId;
+    messageId?: MessageId;
+    evidenceRef?: VaultRef;
+    authorityRef?: AuthorityRef;
+}) | (ExchangeEventBase & {
+    kind: 'artifact';
+    artifact: ArtifactRef;
+}) | (ExchangeEventBase & {
+    kind: 'transport';
+    toExec: ExecState;
+});
+/**
+ * The ONE canonical exchange record (spec §b). Two-level FSM: `exec` (transport, always present) + `case`
+ * (business substate, execution-tier only). Authority is referenced, never satisfied here — approving a case
+ * advances `case`, it never unlocks a resource (ADR-0041).
+ */
+export interface ExchangeRecordV1 {
+    version: 'ap.exchange.v1';
+    exchangeId: ExchangeId;
+    /** Projection hint only — the authority TIER is server-classified from the skill selector, never `kind`. */
+    kind: MessageKind;
+    /** Server-classified ONCE at ingress (never client-asserted). */
+    tier: AuthorityTier;
+    /** The delegator / gateway owner SA — on whose behalf the exchange runs. Also the case RESPONDER by
+     *  convention (the gateway owner triages/approves inbound requests) — see `caseViewFromRecord`. */
+    principal: CanonicalAgentId;
+    /** WHO performed the acting move (spec 324 §9) — `actor == principal` unless a service agent acts for the
+     *  principal under delegation (the authorizing delegation is in `authorityRefs`). Optional for wire-compat;
+     *  absent ⇒ `principal` (use `actorOf`). The acting agent is never erased from provenance nor conflated with
+     *  the principal. */
+    actor?: CanonicalAgentId;
+    parties: {
+        from: CanonicalAgentId;
+        to: CanonicalAgentId[];
+        cc?: CanonicalAgentId[];
+    };
+    /** The case RESOURCE-OWNER, only when it differs from `principal` (e.g. the principal brokers for another
+     *  SA's resource). The ONE case role not derivable from `parties`/`principal`; defaults to `principal`. */
+    resourceOwner?: CanonicalAgentId;
+    /** Transport envelope state (always present). */
+    exec: ExecState;
+    /** Business substate — execution-tier only; `undefined` for a T0 communication exchange. */
+    case?: CaseState;
+    /** The signed wire objects (deliveries, responses, decisions). */
+    envelopes: ExchangeEnvelopeV1[];
+    /** The single append-only event stream (single-writer in the DO). */
+    events: ExchangeEventV1[];
+    /** By-hash pointers at delegation/entitlement/VC/receipt — never inline authority. */
+    authorityRefs?: AuthorityRef[];
+    /** Vault-resident, hash-bound outputs. */
+    artifacts?: ArtifactRef[];
+    /** Entities this exchange is ABOUT (spec 312) — carried through from the envelope. */
+    contextRefs?: ContextRefV1[];
+    /** Monotonic revision for the inbox-projection cursor. */
+    rev: number;
+    updatedAt: string;
+    expiresAt?: string;
+}
+/** The acting agent of a record (spec 324 §9): the explicit `actor` if present, else the `principal`
+ *  (`actor == principal` unless a delegated service agent acted). Provenance never loses the actor. */
+export declare function actorOf(record: Pick<ExchangeRecordV1, 'actor' | 'principal'>): CanonicalAgentId;
+//# sourceMappingURL=exchange-record.d.ts.map

package/dist/exchange-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-record.d.ts","sourceRoot":"","sources":["../src/exchange-record.ts"],"names":[],"mappings":"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"}

package/dist/exchange-record.js

@@ -0,0 +1,25 @@
+// The canonical exchange object (spec 316 §b). Everything a principal handles — a chat line, an approval
+// request, a credential delivery, a multi-step orchestrated task — is ONE `ExchangeRecordV1`, a deliberately
+// TWO-LEVEL object: an `ExecState` transport envelope carrying an optional `CaseState` business substate.
+//
+// `IntentEnvelopeV1` is the signed wire object; for the communication profile it is byte-for-byte a
+// `MessageEnvelopeV1`, so `hashIntentEnvelope` REUSES `hashMessageEnvelope` and every existing signature +
+// receipt digest stays valid across the absorption (spec §b). Execution-tier envelopes add the invoked skill
+// + a vault-ref to the canonical args; those fields are absent on communication envelopes, so a communication
+// `IntentEnvelopeV1` canonicalizes identically to today's `MessageEnvelopeV1`.
+//
+// NOTE (Wave 1, in progress): the append-only `ExchangeEventV1` stream + the case reducer are absorbed from
+// messaging/interactions in the next Wave-1 step; `ExchangeEventV1` here is the minimal seed union.
+import { hashMessageEnvelope } from './messaging/index.js';
+/** Reuses `messaging.hashMessageEnvelope` byte-for-byte so absorbed signatures/receipts stay valid (spec §b) —
+ *  ZERO wire change across the W5 rename. For an execution envelope the extra fields participate in the
+ *  canonical hash (a distinct signing domain). */
+export const hashExchangeEnvelope = hashMessageEnvelope;
+/** @deprecated Use {@link hashExchangeEnvelope} — identical function (spec 324 §9). */
+export const hashIntentEnvelope = hashMessageEnvelope;
+/** The acting agent of a record (spec 324 §9): the explicit `actor` if present, else the `principal`
+ *  (`actor == principal` unless a delegated service agent acted). Provenance never loses the actor. */
+export function actorOf(record) {
+    return record.actor ?? record.principal;
+}
+//# sourceMappingURL=exchange-record.js.map

package/dist/exchange-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-record.js","sourceRoot":"","sources":["../src/exchange-record.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,6GAA6G;AAC7G,0GAA0G;AAC1G,EAAE;AACF,oGAAoG;AACpG,2GAA2G;AAC3G,6GAA6G;AAC7G,8GAA8G;AAC9G,+EAA+E;AAC/E,EAAE;AACF,4GAA4G;AAC5G,oGAAoG;AAGpG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAiC3D;;kDAEkD;AAClD,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AACxD,uFAAuF;AACvF,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AA8EtD;uGACuG;AACvG,MAAM,UAAU,OAAO,CAAC,MAAqD;IAC3E,OAAO,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC;AAC1C,CAAC"}

package/dist/exchange-reducer.d.ts

@@ -0,0 +1,25 @@
+import { type CaseFsmFields } from './case-machine.js';
+import type { ExchangeRecordV1, ExchangeEventV1 } from './exchange-record.js';
+export type ExchangeApplyResult = {
+    ok: true;
+    record: ExchangeRecordV1;
+    changed: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Derive the transient case FSM view from a lean `ExchangeRecordV1` (option (a) — the record stays the lean
+ * spine; the case view is constructed only when applying a transition). Role convention: `requester` = the
+ * sender (`parties.from`); `responder` = the gateway owner (`principal`, who triages/approves inbound
+ * requests); `resource-owner` = `record.resourceOwner ?? principal` (the ONE role not derivable). Returns
+ * `null` for a case-less (T0) exchange.
+ */
+export declare function caseViewFromRecord(record: ExchangeRecordV1): CaseFsmFields | null;
+/**
+ * Apply one event to an exchange record. Single-writer semantics (the gateway DO): `event.seq` must be the
+ * next slot (`record.events.length`). Returns the next record (`changed: true`), a no-op for an idempotent
+ * replay (`changed: false`), or a typed rejection.
+ */
+export declare function applyExchangeEvent(record: ExchangeRecordV1, event: ExchangeEventV1): ExchangeApplyResult;
+//# sourceMappingURL=exchange-reducer.d.ts.map

package/dist/exchange-reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-reducer.d.ts","sourceRoot":"","sources":["../src/exchange-reducer.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE9E,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACxD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,aAAa,GAAG,IAAI,CAajF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAiExG"}

package/dist/exchange-reducer.js

@@ -0,0 +1,108 @@
+// The unified exchange-event reducer (spec 316 §b/§2) — ONE append-only stream, ONE reducer over the
+// canonical `ExchangeRecordV1`. This is the capstone of absorbing messaging (inbox events) + interactions
+// (case transitions) into the fabric. Two-layer coupling (the load-bearing design decision):
+//
+//   - `case` events drive the absorbed case machine; `exec` follows by PROJECTION (`expectedExecForCase`).
+//     The case FSM is the AUTHORITY, so the case-driven `exec` is NOT re-validated against `fulfillment`'s
+//     task-edge graph — that is exactly what lets `denied→rejected` and the `needs-info` loop couple cleanly
+//     without illegal task edges (e.g. `submitted→input-required`).
+//   - `message` events are inbox read-receipt / lifecycle FACTS — they append to the stream (and drive the
+//     inbox projection elsewhere), never `exec`/`case`.
+//   - `transport` events (a T2 runtime task step / an interrupt) are the ONLY `exec` moves validated against
+//     `canTaskTransition`, and must keep the `(exec, case)` pair coupling-consistent (`isExecCaseConsistent`).
+//
+// Fail-closed: an illegal case transition, an inconsistent transport move, or a seq gap is a typed rejection,
+// never a silent state change. Idempotent: a replayed event (same `idempotencyKey`) is a no-op.
+import { canTaskTransition, expectedExecForCase, isExecCaseConsistent } from './exchange-state.js';
+import { applyCaseTransition } from './case-machine.js';
+/**
+ * Derive the transient case FSM view from a lean `ExchangeRecordV1` (option (a) — the record stays the lean
+ * spine; the case view is constructed only when applying a transition). Role convention: `requester` = the
+ * sender (`parties.from`); `responder` = the gateway owner (`principal`, who triages/approves inbound
+ * requests); `resource-owner` = `record.resourceOwner ?? principal` (the ONE role not derivable). Returns
+ * `null` for a case-less (T0) exchange.
+ */
+export function caseViewFromRecord(record) {
+    if (record.case === undefined)
+        return null;
+    return {
+        id: record.exchangeId,
+        state: record.case,
+        requester: record.parties.from,
+        responder: record.principal,
+        resourceOwner: record.resourceOwner ?? record.principal,
+        expiresAt: record.expiresAt,
+        updatedAt: record.updatedAt,
+        evidenceRefs: [],
+        authorityRefs: record.authorityRefs ?? [],
+    };
+}
+/**
+ * Apply one event to an exchange record. Single-writer semantics (the gateway DO): `event.seq` must be the
+ * next slot (`record.events.length`). Returns the next record (`changed: true`), a no-op for an idempotent
+ * replay (`changed: false`), or a typed rejection.
+ */
+export function applyExchangeEvent(record, event) {
+    // Idempotent replay — a matching key already in the stream is a no-op (no second row).
+    if (event.idempotencyKey && record.events.some((e) => e.idempotencyKey === event.idempotencyKey)) {
+        return { ok: true, record, changed: false };
+    }
+    // Single-writer seq: the event must fill the next slot (no gaps, no out-of-order).
+    if (event.seq !== record.events.length) {
+        return { ok: false, reason: `seq-gap:expected ${record.events.length} got ${event.seq}` };
+    }
+    const appended = {
+        ...record,
+        events: [...record.events, event],
+        rev: record.rev + 1,
+        updatedAt: event.at,
+    };
+    switch (event.kind) {
+        case 'message':
+            // Inbox read-receipt / lifecycle fact — appended to the stream; the inbox projection reflects it.
+            // Never changes exec/case (a T0 message stays exec=submitted).
+            return { ok: true, record: appended, changed: true };
+        case 'artifact':
+            return { ok: true, changed: true, record: { ...appended, artifacts: [...(record.artifacts ?? []), event.artifact] } };
+        case 'case': {
+            const view = caseViewFromRecord(record);
+            if (!view)
+                return { ok: false, reason: 'no-case:case event on a case-less exchange' };
+            const res = applyCaseTransition(view, {
+                version: 'ap.case.event.v1',
+                caseId: record.exchangeId,
+                transition: event.transition,
+                actor: event.actor,
+                at: event.at,
+                messageId: event.messageId,
+                evidenceRef: event.evidenceRef,
+                authorityRef: event.authorityRef,
+            });
+            if (!res.ok)
+                return { ok: false, reason: `case:${res.reason}` };
+            const nextCase = res.case.state;
+            return {
+                ok: true,
+                changed: true,
+                record: {
+                    ...appended,
+                    case: nextCase,
+                    exec: expectedExecForCase(nextCase), // projection — the case FSM is the authority
+                    authorityRefs: res.case.authorityRefs,
+                },
+            };
+        }
+        case 'transport': {
+            // Pure-transport exec move (T2 runtime step / interrupt) — the ONLY exec change validated against the
+            // task-edge graph, and it must keep the (exec, case) pair coupling-consistent.
+            if (!canTaskTransition(record.exec, event.toExec)) {
+                return { ok: false, reason: `transport:illegal-exec ${record.exec}->${event.toExec}` };
+            }
+            if (!isExecCaseConsistent(event.toExec, record.case)) {
+                return { ok: false, reason: 'transport:coupling-inconsistent' };
+            }
+            return { ok: true, changed: true, record: { ...appended, exec: event.toExec } };
+        }
+    }
+}
+//# sourceMappingURL=exchange-reducer.js.map

package/dist/exchange-reducer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-reducer.js","sourceRoot":"","sources":["../src/exchange-reducer.ts"],"names":[],"mappings":"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"}

package/dist/exchange-state.d.ts

@@ -0,0 +1,56 @@
+import { canTaskTransition, type TaskState } from '@agenticprimitives/fulfillment';
+/** The transport/execution envelope state — reused from `fulfillment` (kept a pure leaf, unmodified). */
+export type ExecState = TaskState;
+export { canTaskTransition };
+/** All 8 transport `ExecState`s (mirrors `fulfillment` `TaskState`), for coverage assertions. */
+export declare const EXEC_STATES: readonly ExecState[];
+/** The business/interaction substate (spec 316 §2), 11 states. `delivered`/`seen` were REMOVED (Blocker 6):
+ *  they are inbox read-receipt facts, not lifecycle transitions. */
+export type CaseState = 'draft' | 'submitted' | 'triaged' | 'needs-info' | 'approved' | 'denied' | 'issued' | 'completed' | 'expired' | 'revoked' | 'failed';
+export declare const CASE_STATES: readonly CaseState[];
+/**
+ * EXEC_CASE_COUPLING (spec 316 §2) — the canonical `ExecState` each `CaseState` maps to. Exhaustive over all
+ * 11 `CaseState`. Rationale per row:
+ *  - `draft`/`submitted`      → `submitted` : case created, pre-triage/local — accepted, not yet worked.
+ *  - `triaged`/`approved`     → `working`   : responder actively working the request.
+ *  - `needs-info`             → `input-required` : the ONLY case → `input-required` (blocked awaiting requester;
+ *                                A2A `input-required` = blocked on the SENDER, so `triaged` must NOT map here).
+ *  - `issued`/`completed`     → `completed`.
+ *  - `denied`                 → `rejected`  : a rejected request is distinct from a failed task.
+ *  - `expired`/`revoked`/`failed` → `failed` (canonical; `canceled` is the transport-set alternative).
+ */
+export declare const EXEC_CASE_COUPLING: Record<CaseState, ExecState>;
+/**
+ * `ExecState`s set by the TRANSPORT/run layer, NOT derived from a `CaseState`:
+ *  - `auth-required` — raised by a step-up/authority interrupt (`raiseInterrupt`) on an in-flight execution
+ *    case; resolves back to `working`/`input-required` on `resume`.
+ *  - `canceled` — an explicit withdrawal of a not-yet-terminal exchange, or a terminal for
+ *    `expired`/`revoked`/`failed` cases.
+ * Both are consistent on any in-flight execution case (one with a defined `CaseState`); they are NOT
+ * "unmapped ⇒ reject". Together with the 6 case-derived exec values they cover all 8 `ExecState`s.
+ */
+export declare const TRANSPORT_SET_EXEC: readonly ExecState[];
+/** The exec envelope state expected for a given case. `undefined` case (T0 / pre-case delivery) ⇒ `submitted`. */
+export declare function expectedExecForCase(caseState: CaseState | undefined): ExecState;
+/**
+ * True when an `(exec, case)` pair is coupling-consistent (spec 316 §2, fail-closed):
+ *  - a transport-set exec (`auth-required`/`canceled`) is valid on any in-flight execution case (case defined),
+ *    never on a case-less T0 exchange;
+ *  - otherwise the case must map to EXACTLY this exec via `EXEC_CASE_COUPLING` (or `submitted` for no case).
+ * Any other pairing is inconsistent → the caller rejects (never silently drops).
+ */
+export declare function isExecCaseConsistent(exec: ExecState, caseState: CaseState | undefined): boolean;
+/**
+ * `canExchangeTransition = canTaskTransition(exec) ∧ isExecCaseConsistent(to)` (spec 316 §2). NOTE: the case
+ * LIFECYCLE validity (e.g. `draft → submitted` legal, `completed → triaged` illegal) is enforced by the
+ * absorbed interactions case reducer, composed at the fabric level; this function enforces the transport
+ * transition + the exec/case coupling invariant. A `false` here is always a fail-closed rejection.
+ */
+export declare function canExchangeTransition(from: {
+    exec: ExecState;
+    case?: CaseState;
+}, to: {
+    exec: ExecState;
+    case?: CaseState;
+}): boolean;
+//# sourceMappingURL=exchange-state.d.ts.map

package/dist/exchange-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-state.d.ts","sourceRoot":"","sources":["../src/exchange-state.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,iBAAiB,EAAE,KAAK,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEnF,yGAAyG;AACzG,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC;AAClC,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B,iGAAiG;AACjG,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAElC,CAAC;AAEX;oEACoE;AACpE,MAAM,MAAM,SAAS,GACjB,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,GAChD,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAC9C,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErC,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAElC,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,CAY3D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,SAAS,EAA2C,CAAC;AAE/F,kHAAkH;AAClH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAG/E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAG/F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EAC3C,EAAE,EAAE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,GACxC,OAAO,CAGT"}

package/dist/exchange-state.js

@@ -0,0 +1,81 @@
+// The two-level exchange state machine (spec 316 §1/§2). Every `ExchangeRecordV1` carries an **ExecState**
+// (the transport/execution envelope, reused verbatim from `@agenticprimitives/fulfillment` as a pure leaf)
+// and — on execution-tier exchanges only — a **CaseState** (the business/interaction substate absorbed from
+// `@agenticprimitives/interactions`). The two are coupled by an exhaustively-enumerated, fail-closed table:
+// an (exec, case) pair with no mapping is a typed rejection, never a silent drop (the convergence-critic gate).
+//
+// Communication (T0) exchanges carry NO case (`case === undefined`) and are always `exec === 'submitted'`;
+// `delivered`/`seen` are NOT case states — they are read-receipt facts on the inbox projection (Blocker 6).
+import { canTaskTransition } from '@agenticprimitives/fulfillment';
+export { canTaskTransition };
+/** All 8 transport `ExecState`s (mirrors `fulfillment` `TaskState`), for coverage assertions. */
+export const EXEC_STATES = [
+    'submitted', 'working', 'completed', 'failed', 'canceled', 'input-required', 'rejected', 'auth-required',
+];
+export const CASE_STATES = [
+    'draft', 'submitted', 'triaged', 'needs-info', 'approved', 'denied', 'issued', 'completed', 'expired', 'revoked', 'failed',
+];
+/**
+ * EXEC_CASE_COUPLING (spec 316 §2) — the canonical `ExecState` each `CaseState` maps to. Exhaustive over all
+ * 11 `CaseState`. Rationale per row:
+ *  - `draft`/`submitted`      → `submitted` : case created, pre-triage/local — accepted, not yet worked.
+ *  - `triaged`/`approved`     → `working`   : responder actively working the request.
+ *  - `needs-info`             → `input-required` : the ONLY case → `input-required` (blocked awaiting requester;
+ *                                A2A `input-required` = blocked on the SENDER, so `triaged` must NOT map here).
+ *  - `issued`/`completed`     → `completed`.
+ *  - `denied`                 → `rejected`  : a rejected request is distinct from a failed task.
+ *  - `expired`/`revoked`/`failed` → `failed` (canonical; `canceled` is the transport-set alternative).
+ */
+export const EXEC_CASE_COUPLING = {
+    draft: 'submitted',
+    submitted: 'submitted',
+    triaged: 'working',
+    'needs-info': 'input-required',
+    approved: 'working',
+    issued: 'completed',
+    completed: 'completed',
+    denied: 'rejected',
+    expired: 'failed',
+    revoked: 'failed',
+    failed: 'failed',
+};
+/**
+ * `ExecState`s set by the TRANSPORT/run layer, NOT derived from a `CaseState`:
+ *  - `auth-required` — raised by a step-up/authority interrupt (`raiseInterrupt`) on an in-flight execution
+ *    case; resolves back to `working`/`input-required` on `resume`.
+ *  - `canceled` — an explicit withdrawal of a not-yet-terminal exchange, or a terminal for
+ *    `expired`/`revoked`/`failed` cases.
+ * Both are consistent on any in-flight execution case (one with a defined `CaseState`); they are NOT
+ * "unmapped ⇒ reject". Together with the 6 case-derived exec values they cover all 8 `ExecState`s.
+ */
+export const TRANSPORT_SET_EXEC = ['auth-required', 'canceled'];
+/** The exec envelope state expected for a given case. `undefined` case (T0 / pre-case delivery) ⇒ `submitted`. */
+export function expectedExecForCase(caseState) {
+    if (caseState === undefined)
+        return 'submitted';
+    return EXEC_CASE_COUPLING[caseState];
+}
+/**
+ * True when an `(exec, case)` pair is coupling-consistent (spec 316 §2, fail-closed):
+ *  - a transport-set exec (`auth-required`/`canceled`) is valid on any in-flight execution case (case defined),
+ *    never on a case-less T0 exchange;
+ *  - otherwise the case must map to EXACTLY this exec via `EXEC_CASE_COUPLING` (or `submitted` for no case).
+ * Any other pairing is inconsistent → the caller rejects (never silently drops).
+ */
+export function isExecCaseConsistent(exec, caseState) {
+    if (TRANSPORT_SET_EXEC.includes(exec))
+        return caseState !== undefined;
+    return expectedExecForCase(caseState) === exec;
+}
+/**
+ * `canExchangeTransition = canTaskTransition(exec) ∧ isExecCaseConsistent(to)` (spec 316 §2). NOTE: the case
+ * LIFECYCLE validity (e.g. `draft → submitted` legal, `completed → triaged` illegal) is enforced by the
+ * absorbed interactions case reducer, composed at the fabric level; this function enforces the transport
+ * transition + the exec/case coupling invariant. A `false` here is always a fail-closed rejection.
+ */
+export function canExchangeTransition(from, to) {
+    if (!canTaskTransition(from.exec, to.exec))
+        return false;
+    return isExecCaseConsistent(to.exec, to.case);
+}
+//# sourceMappingURL=exchange-state.js.map

package/dist/exchange-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-state.js","sourceRoot":"","sources":["../src/exchange-state.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAC3G,2GAA2G;AAC3G,4GAA4G;AAC5G,4GAA4G;AAC5G,gHAAgH;AAChH,EAAE;AACF,2GAA2G;AAC3G,4GAA4G;AAE5G,OAAO,EAAE,iBAAiB,EAAkB,MAAM,gCAAgC,CAAC;AAInF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B,iGAAiG;AACjG,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,eAAe;CAChG,CAAC;AASX,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ;CAClH,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAiC;IAC9D,KAAK,EAAE,WAAW;IAClB,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,gBAAgB;IAC9B,QAAQ,EAAE,SAAS;IACnB,MAAM,EAAE,WAAW;IACnB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,QAAQ;IACjB,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,QAAQ;CACjB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAyB,CAAC,eAAe,EAAE,UAAU,CAAU,CAAC;AAE/F,kHAAkH;AAClH,MAAM,UAAU,mBAAmB,CAAC,SAAgC;IAClE,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAChD,OAAO,kBAAkB,CAAC,SAAS,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAe,EAAE,SAAgC;IACpF,IAAI,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,KAAK,SAAS,CAAC;IACtE,OAAO,mBAAmB,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAA2C,EAC3C,EAAyC;IAEzC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACzD,OAAO,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AAChD,CAAC"}

package/dist/gateway-surface.d.ts

@@ -0,0 +1,24 @@
+import type { CanonicalAgentId, Hex32 } from '@agenticprimitives/types';
+import type { AuthorityTier } from '@agenticprimitives/tool-policy';
+export interface GatewaySurfaceCommitmentV1 {
+    version: 'ap.gateway-surface.v1';
+    /** The gateway owner SA — the principal this surface serves. */
+    principal: CanonicalAgentId;
+    /** The origin serving this principal's gateway. Any origin ⇒ self-hostable (L1); the single-operator demo
+     *  is a labeled convenience, not architecture. */
+    gatewayOrigin: string;
+    /** The DO-local delivery-receipt attestation pubkey (so peers can verify receipts before/without a fetch). */
+    receiptPubkey: string;
+    /** The authority tiers this gateway serves (communication / execution-fast / execution-orchestrated). */
+    tiers: AuthorityTier[];
+    /** Deployment epoch (spec 311) — a stale-surface guard; a peer rejects a commitment on a superseded epoch. */
+    epoch: string;
+    updatedAt: string;
+}
+export declare function buildGatewaySurfaceCommitment(input: Omit<GatewaySurfaceCommitmentV1, 'version'>): GatewaySurfaceCommitmentV1;
+/** The `atl:gatewayRoot` value committed on-chain: sha256 of the canonical commitment (tiers sorted so order
+ *  is not significant). This is the ONE on-chain point-read discovery anchor (§4.1). */
+export declare function hashGatewaySurfaceCommitment(c: GatewaySurfaceCommitmentV1): Promise<Hex32>;
+/** Verify a fetched commitment against the on-chain `gatewayRoot` (hash match). Fail-closed on any error. */
+export declare function verifyGatewaySurfaceCommitment(c: GatewaySurfaceCommitmentV1, onchainGatewayRoot: Hex32): Promise<boolean>;
+//# sourceMappingURL=gateway-surface.d.ts.map

package/dist/gateway-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-surface.d.ts","sourceRoot":"","sources":["../src/gateway-surface.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAExE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAGpE,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,uBAAuB,CAAC;IACjC,gEAAgE;IAChE,SAAS,EAAE,gBAAgB,CAAC;IAC5B;sDACkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,8GAA8G;IAC9G,aAAa,EAAE,MAAM,CAAC;IACtB,yGAAyG;IACzG,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,8GAA8G;IAC9G,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,IAAI,CAAC,0BAA0B,EAAE,SAAS,CAAC,GACjD,0BAA0B,CAM5B;AAED;wFACwF;AACxF,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,KAAK,CAAC,CAYhG;AAED,6GAA6G;AAC7G,wBAAsB,8BAA8B,CAClD,CAAC,EAAE,0BAA0B,EAC7B,kBAAkB,EAAE,KAAK,GACxB,OAAO,CAAC,OAAO,CAAC,CAMlB"}

package/dist/gateway-surface.js

@@ -0,0 +1,33 @@
+import { canonicalizeJson } from '@agenticprimitives/types';
+import { sha256Hex32 } from './messaging/hash.js';
+export function buildGatewaySurfaceCommitment(input) {
+    if (!input.principal || !input.gatewayOrigin) {
+        throw new Error('buildGatewaySurfaceCommitment: principal + gatewayOrigin required');
+    }
+    if (input.tiers.length === 0)
+        throw new Error('buildGatewaySurfaceCommitment: at least one tier required');
+    return { version: 'ap.gateway-surface.v1', ...input };
+}
+/** The `atl:gatewayRoot` value committed on-chain: sha256 of the canonical commitment (tiers sorted so order
+ *  is not significant). This is the ONE on-chain point-read discovery anchor (§4.1). */
+export async function hashGatewaySurfaceCommitment(c) {
+    return sha256Hex32(canonicalizeJson({
+        version: c.version,
+        principal: c.principal,
+        gatewayOrigin: c.gatewayOrigin,
+        receiptPubkey: c.receiptPubkey,
+        tiers: [...c.tiers].sort(),
+        epoch: c.epoch,
+        updatedAt: c.updatedAt,
+    }));
+}
+/** Verify a fetched commitment against the on-chain `gatewayRoot` (hash match). Fail-closed on any error. */
+export async function verifyGatewaySurfaceCommitment(c, onchainGatewayRoot) {
+    try {
+        return (await hashGatewaySurfaceCommitment(c)) === onchainGatewayRoot;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=gateway-surface.js.map

package/dist/gateway-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-surface.js","sourceRoot":"","sources":["../src/gateway-surface.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAkBlD,MAAM,UAAU,6BAA6B,CAC3C,KAAkD;IAElD,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC3G,OAAO,EAAE,OAAO,EAAE,uBAAuB,EAAE,GAAG,KAAK,EAAE,CAAC;AACxD,CAAC;AAED;wFACwF;AACxF,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,CAA6B;IAC9E,OAAO,WAAW,CAChB,gBAAgB,CAAC;QACf,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,aAAa,EAAE,CAAC,CAAC,aAAa;QAC9B,aAAa,EAAE,CAAC,CAAC,aAAa;QAC9B,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,SAAS,EAAE,CAAC,CAAC,SAAS;KACvB,CAAC,CACH,CAAC;AACJ,CAAC;AAED,6GAA6G;AAC7G,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,CAA6B,EAC7B,kBAAyB;IAEzB,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,4BAA4B,CAAC,CAAC,CAAC,CAAC,KAAK,kBAAkB,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/inbox-doc.d.ts

@@ -0,0 +1,32 @@
+import { type ContextRefV1, type ConversationDescriptorV1, type InboxProjector, type MessageEnvelopeV1, type MessageEventV1 } from './messaging/index.js';
+import { type ActionCardV1, type InteractionCaseV1, type InteractionMandateV1, type InteractionStore, type InteractionTransitionEventV1 } from './interactions/index.js';
+export interface InboxDataV1 {
+    version: 1;
+    envelopes: MessageEnvelopeV1[];
+    events: MessageEventV1[];
+    /** Cases as they entered (draft) — current state is replayed from caseEvents. */
+    draftCases: InteractionCaseV1[];
+    caseEvents: InteractionTransitionEventV1[];
+    /** interactionId → sender-proposed transport card (render half is the app's). */
+    cards: Record<string, ActionCardV1>;
+    /** interactionId → the signed mandate the owner issued on approve (spec 310 W5). */
+    mandates?: Record<string, InteractionMandateV1>;
+    /** Owner-side conversation descriptors (spec 312) — this side's copies. */
+    conversations?: ConversationDescriptorV1[];
+}
+export declare function emptyInboxData(): InboxDataV1;
+/** Parse a persisted doc, dropping the legacy pre-cutover `bodies` key (dead storage, never re-read). */
+export declare function parseInboxData(raw: string): InboxDataV1;
+/** Rebuild the in-memory stores by replay — same events, same projection, any app. */
+export declare function hydrateInboxStores(streamId: string, doc: InboxDataV1): {
+    projector: InboxProjector;
+    interactions: InteractionStore;
+};
+/** Union `refs` into the descriptor's contextRefs by `kind:id`. Returns true when anything was added.
+ *  This is what keeps a long-running thread honest: a NEW context (e.g. a second org's invite) is
+ *  appended, never dropped and never allowed to overwrite the first. */
+export declare function mergeContextRefs(descriptor: ConversationDescriptorV1, refs: ContextRefV1[] | undefined): boolean;
+/** Insert the owner's copy of a conversation descriptor: first descriptor WINS for this owner
+ *  (later proposals never overwrite) — except contextRefs, which union (see mergeContextRefs). */
+export declare function upsertConversation(doc: InboxDataV1, descriptor: ConversationDescriptorV1): void;
+//# sourceMappingURL=inbox-doc.d.ts.map

package/dist/inbox-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-doc.d.ts","sourceRoot":"","sources":["../src/inbox-doc.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,4BAA4B,EAClC,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,iFAAiF;IACjF,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,UAAU,EAAE,4BAA4B,EAAE,CAAC;IAC3C,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACpC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAChD,2EAA2E;IAC3E,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAE5C;AAED,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED,yGAAyG;AACzG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAGvD;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,YAAY,EAAE,gBAAgB,CAAA;CAAE,CAYpI;AAED;;wEAEwE;AACxE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,wBAAwB,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,SAAS,GAAG,OAAO,CAOhH;AAED;kGACkG;AAClG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,wBAAwB,GAAG,IAAI,CAQ/F"}

package/dist/inbox-doc.js

@@ -0,0 +1,57 @@
+// The event-sourced INBOX DOCUMENT (spec 322 W1) — the one JSON record an owner's inbox persists to
+// (`inbox.data` in the owner's vault). Extracted from the Home app so EVERY app renders/mutates the
+// same doc through the same pure operations: the Home is one client of this substrate, never its
+// definition. Storage (which vault/KV, which key) and side effects (audit, body stores) stay with the
+// caller — this module is pure shape + replay + mutation.
+import { createInMemoryInboxProjector, } from './messaging/index.js';
+import { createInMemoryInteractionStore, } from './interactions/index.js';
+export function emptyInboxData() {
+    return { version: 1, envelopes: [], events: [], draftCases: [], caseEvents: [], cards: {} };
+}
+/** Parse a persisted doc, dropping the legacy pre-cutover `bodies` key (dead storage, never re-read). */
+export function parseInboxData(raw) {
+    const { bodies: _legacyBodies, ...doc } = JSON.parse(raw);
+    return doc;
+}
+/** Rebuild the in-memory stores by replay — same events, same projection, any app. */
+export function hydrateInboxStores(streamId, doc) {
+    const projector = createInMemoryInboxProjector({ streamId });
+    for (const envelope of doc.envelopes)
+        projector.putMessage(envelope);
+    for (const event of doc.events)
+        projector.appendEvent(event);
+    const interactions = createInMemoryInteractionStore();
+    for (const c of doc.draftCases)
+        interactions.putCase(c);
+    for (const e of doc.caseEvents) {
+        const r = interactions.applyEvent(e);
+        if (!r.ok)
+            throw new Error(`inbox replay diverged for ${e.interactionId}: ${r.reason}`);
+    }
+    return { projector, interactions };
+}
+/** Union `refs` into the descriptor's contextRefs by `kind:id`. Returns true when anything was added.
+ *  This is what keeps a long-running thread honest: a NEW context (e.g. a second org's invite) is
+ *  appended, never dropped and never allowed to overwrite the first. */
+export function mergeContextRefs(descriptor, refs) {
+    if (!refs?.length)
+        return false;
+    const seen = new Set((descriptor.contextRefs ?? []).map((r) => `${r.kind}:${r.id}`));
+    const fresh = refs.filter((r) => !seen.has(`${r.kind}:${r.id}`));
+    if (!fresh.length)
+        return false;
+    descriptor.contextRefs = [...(descriptor.contextRefs ?? []), ...fresh];
+    return true;
+}
+/** Insert the owner's copy of a conversation descriptor: first descriptor WINS for this owner
+ *  (later proposals never overwrite) — except contextRefs, which union (see mergeContextRefs). */
+export function upsertConversation(doc, descriptor) {
+    const existing = doc.conversations ?? [];
+    const prior = existing.find((d) => d.id === descriptor.id);
+    if (!prior) {
+        doc.conversations = [...existing, descriptor];
+        return;
+    }
+    mergeContextRefs(prior, descriptor.contextRefs);
+}
+//# sourceMappingURL=inbox-doc.js.map