@tokenoftrust/storefront-runner 3.10.2 → 3.10.4

package/apps/storefront/src/lib/orders/data/sourceAuthorityStore.ts

@@ -0,0 +1,830 @@
+/** Durable authority transitions and immutable control receipts, fenced by D1 CAS. */
+import type { Queryable, QueryStatement } from "../../catalog/d1/catalog.js";
+import type { CommerceStage } from "@tot/public-runtime";
+import {
+  SOURCE_LEASE_MS,
+  isHash,
+  canonicalInstant,
+  isSourceId,
+  exactKeys,
+  SOURCE_LIMIT,
+  SourceAuthorityError,
+  digestJson,
+  observationId,
+  conditionDigest,
+  faultProof,
+  validateManifestSet,
+  uniqueLineage,
+  type SourceKey,
+  type SourceBegin,
+  type SourceResult,
+  type SourceHold,
+  type ManifestCore,
+  type BusinessPair,
+  type BeginAck,
+  type ResultAck,
+  type Provenance,
+} from "./sourceAuthorityContract.js";
+interface State {
+  version: number;
+  revision: number;
+  active: string | null;
+  pending: boolean;
+  accepted: string | null;
+  businessDigest: string | null;
+  pairs: BusinessPair[];
+  expires: string | null;
+  sync: boolean;
+  holds: SourceHold[];
+  budget: boolean;
+  orderId: string | null;
+}
+export interface AuthorityRow {
+  tenant_id: string;
+  stage: CommerceStage;
+  source: string;
+  provider_store_id: string;
+  source_order_id: string;
+  order_id: string | null;
+  source_state_version: number;
+  check_revision: number;
+  active_check_id: string | null;
+  pending_check: number;
+  accepted_ledger_generation: string | null;
+  accepted_business_event_set_digest: string | null;
+  source_proof_expires_at: string | null;
+  source_sync_pending: number;
+  unresolved_count: number;
+  authority_budget: number;
+  binding_digest: string;
+  state_json: string;
+  mutation_id: string;
+}
+interface Replay {
+  issuer: string;
+  jti: string;
+}
+const WHERE =
+  "tenant_id=? AND stage=? AND source=? AND provider_store_id=? AND source_order_id=?";
+const keyParams = (k: SourceKey): unknown[] => [
+  k.tenantId,
+  k.stage,
+  k.source,
+  k.providerStoreId,
+  k.sourceOrderId,
+];
+const initial = (): State => ({
+  version: 0,
+  revision: 0,
+  active: null,
+  pending: true,
+  accepted: null,
+  businessDigest: null,
+  pairs: [],
+  expires: null,
+  sync: true,
+  holds: [],
+  budget: false,
+  orderId: null,
+});
+export type SourceReadiness =
+  | "source-check-pending"
+  | "source-ledger-conflict"
+  | "source-authority-unreadable"
+  | "source-authority-unavailable"
+  | "source-sync-pending";
+export function authorityHolds(
+  row: AuthorityRow | null,
+  now: string,
+): SourceReadiness[] {
+  if (!row) return ["source-authority-unavailable"];
+  try {
+    const s = JSON.parse(row.state_json) as State;
+    if (
+      !Number.isSafeInteger(row.source_state_version) ||
+      row.source_state_version < 0 ||
+      !Number.isSafeInteger(row.check_revision) ||
+      row.check_revision < 0 ||
+      ![0, 1].includes(row.pending_check) ||
+      ![0, 1].includes(row.source_sync_pending) ||
+      ![0, 1].includes(row.authority_budget) ||
+      !isSourceId(row.provider_store_id) ||
+      !isHash(row.binding_digest) ||
+      (row.accepted_ledger_generation !== null &&
+        !isHash(row.accepted_ledger_generation)) ||
+      (row.accepted_business_event_set_digest !== null &&
+        !isHash(row.accepted_business_event_set_digest)) ||
+      (row.source_proof_expires_at !== null &&
+        !canonicalInstant(row.source_proof_expires_at))
+    )
+      return ["source-authority-unreadable"];
+    if (
+      Array.isArray(s.pairs) &&
+      s.pairs.some(
+        (p, i) =>
+          !exactKeys(p, ["sourceEventId", "originalEventDigest"]) ||
+          typeof p.sourceEventId !== "string" ||
+          !/^[-A-Za-z0-9._:]{1,128}$/.test(p.sourceEventId) ||
+          !isHash(p.originalEventDigest) ||
+          (i > 0 && s.pairs[i - 1]!.sourceEventId >= p.sourceEventId),
+      )
+    )
+      return ["source-authority-unreadable"];
+    if (
+      !Number.isSafeInteger(s.version) ||
+      !Number.isSafeInteger(s.revision) ||
+      !Array.isArray(s.holds) ||
+      s.holds.length > SOURCE_LIMIT ||
+      !Array.isArray(s.pairs) ||
+      s.pairs.length > SOURCE_LIMIT ||
+      s.version !== row.source_state_version ||
+      s.revision !== row.check_revision ||
+      s.active !== row.active_check_id ||
+      Number(s.pending) !== row.pending_check ||
+      s.accepted !== row.accepted_ledger_generation ||
+      s.businessDigest !== row.accepted_business_event_set_digest ||
+      s.expires !== row.source_proof_expires_at ||
+      Number(s.sync) !== row.source_sync_pending ||
+      s.holds.length !== row.unresolved_count ||
+      Number(s.budget) !== row.authority_budget ||
+      s.orderId !== row.order_id
+    )
+      return ["source-authority-unreadable"];
+  } catch {
+    return ["source-authority-unreadable"];
+  }
+  const holds: SourceReadiness[] = [];
+  if (row.pending_check) holds.push("source-check-pending");
+  if (row.unresolved_count || row.authority_budget)
+    holds.push("source-ledger-conflict");
+  if (
+    !row.accepted_ledger_generation ||
+    !row.accepted_business_event_set_digest ||
+    !row.source_proof_expires_at ||
+    !Number.isFinite(Date.parse(row.source_proof_expires_at)) ||
+    Date.parse(row.source_proof_expires_at) <= Date.parse(now)
+  )
+    holds.push("source-authority-unavailable");
+  if (row.source_sync_pending) holds.push("source-sync-pending");
+  return holds;
+}
+/** SQL checks both the loaded receiver revision and its live lease at the write boundary. */
+export function authorityFence(
+  row: AuthorityRow | null,
+  now: string,
+  requireHealthy: boolean,
+): { sql: string; params: unknown[] } {
+  if (!row)
+    return {
+      sql: requireHealthy
+        ? "0"
+        : "NOT EXISTS(SELECT 1 FROM commerce_source_authority sa WHERE sa.tenant_id=scrappy_commerce_orders.tenant_id AND sa.stage=scrappy_commerce_orders.stage AND sa.source=scrappy_commerce_orders.source AND sa.source_order_id=scrappy_commerce_orders.source_order_id)",
+      params: [],
+    };
+  return {
+    sql: `EXISTS(SELECT 1 FROM commerce_source_authority sa WHERE sa.tenant_id=scrappy_commerce_orders.tenant_id AND sa.stage=scrappy_commerce_orders.stage AND sa.source=scrappy_commerce_orders.source AND sa.source_order_id=scrappy_commerce_orders.source_order_id AND sa.order_id=scrappy_commerce_orders.order_id AND sa.provider_store_id=? AND sa.source_state_version=? AND sa.check_revision=? AND sa.binding_digest=? AND json_valid(sa.state_json)=1 ${requireHealthy ? "AND sa.pending_check=0 AND sa.unresolved_count=0 AND sa.authority_budget=0 AND sa.source_sync_pending=0 AND sa.accepted_ledger_generation IS NOT NULL AND sa.source_proof_expires_at>?" : ""})`,
+    params: [
+      row.provider_store_id,
+      row.source_state_version,
+      row.check_revision,
+      row.binding_digest,
+      ...(requireHealthy ? [now] : []),
+    ],
+  };
+}
+export class SourceAuthorityStore {
+  constructor(private readonly db: Queryable) {}
+  async read(key: SourceKey): Promise<AuthorityRow | null> {
+    return this.db.first<AuthorityRow>(
+      `SELECT * FROM commerce_source_authority WHERE ${WHERE}`,
+      ...keyParams(key),
+    );
+  }
+  async forOrder(
+    tenant: string,
+    stage: CommerceStage,
+    source: string,
+    sourceOrderId: string,
+  ): Promise<AuthorityRow | null> {
+    return this.db.first<AuthorityRow>(
+      `SELECT * FROM commerce_source_authority WHERE tenant_id=? AND stage=? AND source=? AND source_order_id=?`,
+      tenant,
+      stage,
+      source,
+      sourceOrderId,
+    );
+  }
+  private async consumeReplay(
+    key: SourceKey,
+    now: string,
+    replay?: Replay,
+  ): Promise<void> {
+    if (replay)
+      await this.db.run(
+        `INSERT INTO scrappy_caller_replay(tenant_id,stage,issuer,jti,seen_at) VALUES(?,?,?,?,?)`,
+        key.tenantId,
+        key.stage,
+        replay.issuer,
+        replay.jti,
+        now,
+      );
+  }
+  private async record<T>(
+    key: SourceKey,
+    kind: string,
+    id: string,
+  ): Promise<{ payload_digest: string; payload: T } | null> {
+    const r = await this.db.first<{
+      payload_digest: string;
+      payload_json: string;
+    }>(
+      `SELECT payload_digest,payload_json FROM commerce_source_observations WHERE ${WHERE} AND record_kind=? AND record_id=?`,
+      ...keyParams(key),
+      kind,
+      id,
+    );
+    return r
+      ? {
+          payload_digest: r.payload_digest,
+          payload: JSON.parse(r.payload_json) as T,
+        }
+      : null;
+  }
+  private async transition(
+    key: SourceKey,
+    old: AuthorityRow | null,
+    state: State,
+    now: string,
+    records: { kind: string; id: string; digest: string; payload: unknown }[],
+    replay?: Replay,
+    resolve: string[] = [],
+  ): Promise<boolean> {
+    if (!this.db.batchResults)
+      throw new SourceAuthorityError("source-authority-unavailable");
+    const mutation = crypto.randomUUID();
+    const binding = await digestJson({ ...key, orderId: state.orderId });
+    const values = [
+      state.orderId,
+      state.version,
+      state.revision,
+      state.active,
+      state.pending ? 1 : 0,
+      state.accepted,
+      state.businessDigest,
+      state.expires,
+      state.sync ? 1 : 0,
+      state.holds.length,
+      state.budget ? 1 : 0,
+      binding,
+      JSON.stringify(state),
+      mutation,
+    ];
+    const statements: QueryStatement[] = [
+      old
+        ? {
+            sql: `UPDATE commerce_source_authority SET order_id=?,source_state_version=?,check_revision=?,active_check_id=?,pending_check=?,accepted_ledger_generation=?,accepted_business_event_set_digest=?,source_proof_expires_at=?,source_sync_pending=?,unresolved_count=?,authority_budget=?,binding_digest=?,state_json=?,mutation_id=? WHERE ${WHERE} AND source_state_version=? AND mutation_id=? RETURNING source_state_version`,
+            params: [
+              ...values,
+              ...keyParams(key),
+              old.source_state_version,
+              old.mutation_id,
+            ],
+          }
+        : {
+            sql: `INSERT INTO commerce_source_authority(tenant_id,stage,source,provider_store_id,source_order_id,order_id,source_state_version,check_revision,active_check_id,pending_check,accepted_ledger_generation,accepted_business_event_set_digest,source_proof_expires_at,source_sync_pending,unresolved_count,authority_budget,binding_digest,state_json,mutation_id) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?) ON CONFLICT DO NOTHING RETURNING source_state_version`,
+            params: [...keyParams(key), ...values],
+          },
+    ];
+    // One bounded insert persists every immutable record inside the authority CAS.
+    statements.push({
+      sql: `INSERT INTO commerce_source_observations(tenant_id,stage,source,provider_store_id,source_order_id,record_kind,record_id,payload_digest,payload_json)
+      SELECT sa.tenant_id,sa.stage,sa.source,sa.provider_store_id,sa.source_order_id,json_extract(r.value,'$.kind'),json_extract(r.value,'$.id'),json_extract(r.value,'$.digest'),json_extract(r.value,'$.payloadJson')
+      FROM commerce_source_authority sa,json_each(?) r
+      WHERE sa.tenant_id=? AND sa.stage=? AND sa.source=? AND sa.provider_store_id=? AND sa.source_order_id=? AND sa.mutation_id=?`,
+      params: [
+        JSON.stringify(
+          records.map((r) => ({
+            kind: r.kind,
+            id: r.id,
+            digest: r.digest,
+            payloadJson: JSON.stringify(r.payload),
+          })),
+        ),
+        ...keyParams(key),
+        mutation,
+      ],
+    });
+    for (const r of records.filter(
+      (r) => r.kind === "check" || r.kind === "result",
+    )) {
+      const controlId = `source-control:${await digestJson({ key, kind: r.kind, id: r.id })}`;
+      statements.push({
+        sql: `INSERT INTO scrappy_commerce_inbox(tenant_id,stage,source,source_event_id,event_version,idempotency_key,payload_digest,received_at) SELECT tenant_id,stage,source,?,1,?,?,? FROM commerce_source_authority WHERE ${WHERE} AND mutation_id=?`,
+        params: [
+          controlId,
+          controlId,
+          r.digest,
+          now,
+          ...keyParams(key),
+          mutation,
+        ],
+      });
+    }
+    if (replay)
+      statements.push({
+        sql: `INSERT INTO scrappy_caller_replay(tenant_id,stage,issuer,jti,seen_at) SELECT tenant_id,stage,?,?,? FROM commerce_source_authority WHERE ${WHERE} AND mutation_id=?`,
+        params: [replay.issuer, replay.jti, now, ...keyParams(key), mutation],
+      });
+    statements.push({
+      sql: `UPDATE commerce_source_observations SET resolved_version=?,resolved_generation=? WHERE ${WHERE} AND record_kind='hold' AND record_id IN(SELECT value FROM json_each(?)) AND resolved_version IS NULL AND EXISTS(SELECT 1 FROM commerce_source_authority WHERE ${WHERE} AND mutation_id=?)`,
+      params: [
+        state.version,
+        state.accepted,
+        ...keyParams(key),
+        JSON.stringify(resolve),
+        ...keyParams(key),
+        mutation,
+      ],
+    });
+    // Every authority change invalidates a previously loaded fulfillment CAS. Terminal progress is retained.
+    statements.push({
+      sql: `UPDATE scrappy_commerce_orders SET event_version=event_version+1 WHERE tenant_id=? AND stage=? AND source=? AND source_order_id=? AND EXISTS(SELECT 1 FROM commerce_source_authority WHERE ${WHERE} AND mutation_id=?)`,
+      params: [
+        key.tenantId,
+        key.stage,
+        key.source,
+        key.sourceOrderId,
+        ...keyParams(key),
+        mutation,
+      ],
+    });
+    statements.push({
+      sql: `INSERT INTO scrappy_shipment_audit(audit_id,tenant_id,stage,order_id,at,actor_id,kind,from_state,to_state)
+      SELECT ?,tenant_id,stage,order_id,?,'commerce-source-authority','source-authority','source',?
+      FROM scrappy_commerce_orders WHERE tenant_id=? AND stage=? AND source=? AND source_order_id=?
+      AND EXISTS(SELECT 1 FROM commerce_source_authority WHERE ${WHERE} AND mutation_id=?)`,
+      params: [
+        `audit_${crypto.randomUUID()}`,
+        `${now}#source-${state.version}`,
+        state.pending || state.sync || state.holds.length || state.budget
+          ? "held"
+          : "verified",
+        key.tenantId,
+        key.stage,
+        key.source,
+        key.sourceOrderId,
+        ...keyParams(key),
+        mutation,
+      ],
+    });
+    const result = await this.db.batchResults(statements);
+    return Boolean(result[0]?.results.length);
+  }
+  async begin(
+    key: SourceKey,
+    event: SourceBegin,
+    now: string,
+    replay?: Replay,
+  ): Promise<BeginAck> {
+    for (let attempt = 0; attempt < 8; attempt++) {
+      const old = await this.read(key);
+      const priorBegin = await this.db.first<{ payload_json: string }>(
+        `SELECT payload_json FROM commerce_source_observations WHERE ${WHERE} AND record_kind='check' AND json_extract(payload_json,'$.requestId')=?`,
+        ...keyParams(key),
+        event.requestId,
+      );
+      if (priorBegin) {
+        await this.consumeReplay(key, now, replay);
+        return (JSON.parse(priorBegin.payload_json) as { beginAck: BeginAck })
+          .beginAck;
+      }
+      const state: State = old ? JSON.parse(old.state_json) : initial();
+      if (state.active && state.pending) {
+        const check = await this.record<{
+          issuedAt: string;
+          checkRevision: number;
+        }>(key, "check", state.active);
+        if (
+          !check ||
+          !canonicalInstant(check.payload.issuedAt) ||
+          check.payload.checkRevision !== state.revision ||
+          Date.parse(check.payload.issuedAt) > Date.parse(now)
+        )
+          throw new SourceAuthorityError("source-authority-unavailable");
+        if (
+          Date.parse(check.payload.issuedAt) + SOURCE_LEASE_MS >
+          Date.parse(now)
+        ) {
+          await this.consumeReplay(key, now, replay);
+          return {
+            ok: true,
+            duplicate: true,
+            checkId: state.active,
+            checkRevision: state.revision,
+            sourceStateVersion: state.version,
+            acceptedLedgerGeneration: state.accepted,
+            acceptedBusinessEventSetDigest: state.businessDigest,
+            unresolvedHolds: state.holds,
+          };
+        }
+      }
+      state.version++;
+      state.revision++;
+      state.active = `check_${crypto.randomUUID()}`;
+      state.pending = true;
+      const beginAck: BeginAck = {
+        ok: true,
+        duplicate: false,
+        checkId: state.active,
+        checkRevision: state.revision,
+        sourceStateVersion: state.version,
+        acceptedLedgerGeneration: state.accepted,
+        acceptedBusinessEventSetDigest: state.businessDigest,
+        unresolvedHolds: state.holds,
+      };
+      const check = {
+        issuedAt: now,
+        checkRevision: state.revision,
+        sourceStateVersion: state.version,
+        requestId: event.requestId,
+        beginAck,
+      };
+      if (
+        await this.transition(
+          key,
+          old,
+          state,
+          now,
+          [
+            {
+              kind: "check",
+              id: state.active,
+              digest: await digestJson(check),
+              payload: check,
+            },
+          ],
+          replay,
+        )
+      )
+        return {
+          ok: true,
+          duplicate: false,
+          checkId: state.active,
+          checkRevision: state.revision,
+          sourceStateVersion: state.version,
+          acceptedLedgerGeneration: state.accepted,
+          acceptedBusinessEventSetDigest: state.businessDigest,
+          unresolvedHolds: state.holds,
+        };
+    }
+    throw new SourceAuthorityError("source-state-changed");
+  }
+  async result(
+    key: SourceKey,
+    event: SourceResult,
+    now: string,
+    replay?: Replay,
+  ): Promise<ResultAck> {
+    const digest = await digestJson(event);
+    for (let attempt = 0; attempt < 8; attempt++) {
+      const old = await this.read(key);
+      if (!old) throw new SourceAuthorityError("source-authority-unavailable");
+      const state: State = JSON.parse(old.state_json);
+      const prior = await this.record<{ ack: ResultAck; event: SourceResult }>(
+        key,
+        "result",
+        event.observationId,
+      );
+      if (prior) {
+        if (prior.payload_digest === digest) {
+          await this.consumeReplay(key, now, replay);
+          return prior.payload.ack;
+        }
+        await this.conflict(key, old, state, now);
+        throw new SourceAuthorityError("control-identity-conflict");
+      }
+      if ((await observationId(key, event)) !== event.observationId) {
+        await this.conflict(key, old, state, now);
+        throw new SourceAuthorityError("control-identity-conflict");
+      }
+      const check = await this.record<{
+        issuedAt: string;
+        checkRevision: number;
+        sourceStateVersion: number;
+      }>(key, "check", event.checkId);
+      if (
+        !check ||
+        check.payload.checkRevision !== event.expectedCheckRevision ||
+        event.expectedSourceStateVersion < check.payload.sourceStateVersion ||
+        event.expectedSourceStateVersion > state.version
+      )
+        throw new SourceAuthorityError("source-state-changed");
+      const records: {
+        kind: string;
+        id: string;
+        digest: string;
+        payload: unknown;
+      }[] = [];
+      let resolves: string[] = [];
+      if (event.outcome === "fault") {
+        const proof = faultProof(event);
+        const { conditionDigest: _, ...facts } = proof;
+        if ((await conditionDigest(key, facts)) !== event.conditionDigest)
+          throw new SourceAuthorityError("malformed");
+        const manifests = event.completeValidatedManifestSetOrNull
+          ? await validateManifestSet(
+              key,
+              event.completeValidatedManifestSetOrNull,
+            )
+          : new Map<string, ManifestCore>();
+        if (
+          event.faultKind === "fork" &&
+          (!event.completeValidatedManifestSetOrNull ||
+            !event.conflictingValidatedGenerationsOrNull ||
+            event.conflictingValidatedGenerationsOrNull.some(
+              (id) =>
+                !manifests.has(id) ||
+                manifests.get(id)!.parent !== event.divergenceParentOrNull,
+            ))
+        )
+          throw new SourceAuthorityError("malformed");
+        for (const [id, c] of manifests)
+          if (!(await this.record(key, "manifest", id)))
+            records.push({ kind: "manifest", id, digest: id, payload: c });
+        let changed = false;
+        if (
+          !state.holds.some((h) => h.conditionDigest === event.conditionDigest)
+        ) {
+          changed = true;
+          if (state.holds.length >= SOURCE_LIMIT) state.budget = true;
+          else {
+            const hold: SourceHold = {
+              holdId: `hold_${crypto.randomUUID()}`,
+              conditionDigest: event.conditionDigest,
+              faultKind: event.faultKind,
+              openingObservationId: event.observationId,
+              openingProof: proof,
+            };
+            state.holds.push(hold);
+            records.push({
+              kind: "hold",
+              id: hold.holdId,
+              digest: await digestJson(hold),
+              payload: hold,
+            });
+          }
+        }
+        if (changed) state.version++;
+      } else {
+        if (
+          state.active !== event.checkId ||
+          !state.pending ||
+          state.version !== event.expectedSourceStateVersion ||
+          state.revision !== event.expectedCheckRevision
+        )
+          throw new SourceAuthorityError("source-state-changed");
+        const issued = Date.parse(check.payload.issuedAt);
+        if (
+          Date.parse(event.actualObservedAt) < issued ||
+          Date.parse(event.actualObservedAt) > Date.parse(now) ||
+          issued + SOURCE_LEASE_MS <= Date.parse(now)
+        )
+          throw new SourceAuthorityError("source-authority-unavailable");
+        const map = await validateManifestSet(
+          key,
+          event.validatedManifestCores,
+        );
+        if (
+          !uniqueLineage(map, event.tipGeneration) ||
+          (state.accepted && !map.has(state.accepted))
+        )
+          throw new SourceAuthorityError("source-state-changed");
+        const retained = await this.db.all<{ record_id: string }>(
+          `SELECT record_id FROM commerce_source_observations WHERE ${WHERE} AND record_kind='manifest'`,
+          ...keyParams(key),
+        );
+        if (retained.some((r) => !map.has(r.record_id)))
+          throw new SourceAuthorityError("source-state-changed");
+        if (
+          state.budget ||
+          state.holds.some(
+            (h) =>
+              ![
+                "source-unavailable",
+                "census-incomplete",
+                "census-changing",
+                "committed-payload-missing",
+              ].includes(h.faultKind) ||
+              (h.faultKind === "committed-payload-missing" &&
+                h.openingProof.completeValidatedManifestSetOrNull === null),
+          )
+        )
+          throw new SourceAuthorityError("source-state-changed");
+        const expected = state.holds.map((h) => h.holdId).sort();
+        if (
+          JSON.stringify(expected) !==
+          JSON.stringify([...event.resolvesHoldIds].sort())
+        )
+          throw new SourceAuthorityError("source-state-changed");
+        if (
+          (await digestJson(event.businessEventDigestPairs)) !==
+          event.businessEventSetDigest
+        )
+          throw new SourceAuthorityError("malformed");
+        // A new accepted source set must preserve all immutable business identities already admitted.
+        if (
+          state.pairs.some(
+            (p) =>
+              !event.businessEventDigestPairs.some(
+                (q) =>
+                  q.sourceEventId === p.sourceEventId &&
+                  q.originalEventDigest === p.originalEventDigest,
+              ),
+          )
+        )
+          throw new SourceAuthorityError("source-state-changed");
+        const persisted = await this.persistedPairs(key);
+        if (
+          persisted.some(
+            (p) =>
+              !event.businessEventDigestPairs.some(
+                (q) =>
+                  q.sourceEventId === p.sourceEventId &&
+                  q.originalEventDigest === p.originalEventDigest,
+              ),
+          )
+        )
+          throw new SourceAuthorityError("source-state-changed");
+        for (const [id, c] of map)
+          if (!(await this.record(key, "manifest", id)))
+            records.push({ kind: "manifest", id, digest: id, payload: c });
+        resolves = expected;
+        state.holds = [];
+        state.version++;
+        state.pending = false;
+        state.accepted = event.tipGeneration;
+        state.businessDigest = event.businessEventSetDigest;
+        state.pairs = event.businessEventDigestPairs;
+        state.expires = new Date(issued + SOURCE_LEASE_MS).toISOString();
+        state.sync = (await digestJson(persisted)) !== state.businessDigest;
+      }
+      const ack: ResultAck = {
+        ok: true,
+        duplicate: false,
+        checkId: event.checkId,
+        observationId: event.observationId,
+        sourceStateVersion: state.version,
+        acceptedLedgerGeneration: state.accepted,
+        acceptedBusinessEventSetDigest: state.businessDigest,
+        sourceProofExpiresAt: state.expires,
+        pendingCheck: state.pending,
+        unresolvedHoldIdsDigest: await digestJson(
+          state.holds.map((h) => h.holdId).sort(),
+        ),
+        sourceSyncPending: state.sync,
+      };
+      records.push({
+        kind: "result",
+        id: event.observationId,
+        digest,
+        payload: { event, ack },
+      });
+      // A result receipt shares the exact authority transaction; ACK loss is safely retryable.
+      try {
+        if (
+          await this.transition(key, old, state, now, records, replay, resolves)
+        )
+          return ack;
+      } catch (error) {
+        const receipt = await this.record<{
+          ack: ResultAck;
+          event: SourceResult;
+        }>(key, "result", event.observationId);
+        if (receipt?.payload_digest === digest) return receipt.payload.ack;
+        throw error;
+      }
+    }
+    throw new SourceAuthorityError("source-state-changed");
+  }
+  async budget(key: SourceKey, now: string): Promise<void> {
+    for (let n = 0; n < 8; n++) {
+      const old = await this.read(key);
+      const s: State = old ? JSON.parse(old.state_json) : initial();
+      s.budget = true;
+      s.version++;
+      if (await this.transition(key, old, s, now, [])) return;
+    }
+    throw new SourceAuthorityError("source-state-changed");
+  }
+  private async conflict(
+    key: SourceKey,
+    old: AuthorityRow,
+    state: State,
+    now: string,
+  ): Promise<void> {
+    state.version++;
+    state.budget = true;
+    if (!(await this.transition(key, old, state, now, []))) {
+      const current = await this.read(key);
+      if (!current)
+        throw new SourceAuthorityError("source-authority-unavailable");
+      return this.conflict(key, current, JSON.parse(current.state_json), now);
+    }
+  }
+  async persistedPairs(key: SourceKey): Promise<BusinessPair[]> {
+    const rows = await this.db.all<{
+      source_event_id: string;
+      payload_digest: string;
+    }>(
+      `SELECT i.source_event_id,i.payload_digest FROM scrappy_commerce_inbox i JOIN scrappy_commerce_outbox o ON o.tenant_id=i.tenant_id AND o.stage=i.stage AND o.source=i.source AND o.source_event_id=i.source_event_id WHERE o.tenant_id=? AND o.stage=? AND o.source=? AND json_extract(o.payload,'$.source.sourceOrderId')=? ORDER BY i.source_event_id`,
+      key.tenantId,
+      key.stage,
+      key.source,
+      key.sourceOrderId,
+    );
+    return rows.map((r) => ({
+      sourceEventId: r.source_event_id,
+      originalEventDigest: r.payload_digest,
+    }));
+  }
+  async authorizeEvent(
+    tenantId: string,
+    stage: CommerceStage,
+    event: {
+      source: string;
+      sourceOrderId: string;
+      orderId: string;
+      sourceEventId: string;
+    },
+    provenance: Provenance,
+  ): Promise<AuthorityRow> {
+    const row = await this.forOrder(
+      tenantId,
+      stage,
+      event.source,
+      event.sourceOrderId,
+    );
+    if (!row) throw new SourceAuthorityError("source-authority-unavailable");
+    const state: State = JSON.parse(row.state_json);
+    const expected = state.pairs.find(
+      (p) => p.sourceEventId === event.sourceEventId,
+    );
+    if (
+      expected &&
+      expected.originalEventDigest !== provenance.exactOriginalEventDigest
+    ) {
+      await this.budget(
+        {
+          tenantId,
+          stage,
+          source: "foxycart",
+          providerStoreId: row.provider_store_id,
+          sourceOrderId: row.source_order_id,
+        },
+        new Date().toISOString(),
+      );
+      throw new SourceAuthorityError("control-identity-conflict");
+    }
+    if (
+      (row.order_id !== null && row.order_id !== event.orderId) ||
+      event.orderId !== event.sourceOrderId ||
+      state.accepted !== provenance.acceptedLedgerGeneration ||
+      state.businessDigest !== provenance.businessEventSetDigest ||
+      !state.pairs.some(
+        (p) =>
+          p.sourceEventId === event.sourceEventId &&
+          p.originalEventDigest === provenance.exactOriginalEventDigest,
+      )
+    )
+      throw new SourceAuthorityError("source-state-changed");
+    return row;
+  }
+  /** Part of the business commit transaction: sync reflects the exact committed immutable set. */
+  async businessStatements(
+    row: AuthorityRow,
+    orderId: string,
+  ): Promise<QueryStatement[]> {
+    const key: SourceKey = {
+      tenantId: row.tenant_id,
+      stage: row.stage,
+      source: "foxycart",
+      providerStoreId: row.provider_store_id,
+      sourceOrderId: row.source_order_id,
+    };
+    return [
+      {
+        sql: `UPDATE commerce_source_authority SET source_state_version=source_state_version+1,mutation_id=?,order_id=?,binding_digest=?,source_sync_pending=CASE WHEN (SELECT COUNT(*) FROM json_each(state_json,'$.pairs'))=(SELECT COUNT(*) FROM scrappy_commerce_outbox o WHERE o.tenant_id=commerce_source_authority.tenant_id AND o.stage=commerce_source_authority.stage AND o.source=commerce_source_authority.source AND json_extract(o.payload,'$.source.sourceOrderId')=commerce_source_authority.source_order_id) AND NOT EXISTS(SELECT 1 FROM json_each(state_json,'$.pairs') p WHERE NOT EXISTS(SELECT 1 FROM scrappy_commerce_inbox i WHERE i.tenant_id=commerce_source_authority.tenant_id AND i.stage=commerce_source_authority.stage AND i.source=commerce_source_authority.source AND i.source_event_id=json_extract(p.value,'$.sourceEventId') AND i.payload_digest=json_extract(p.value,'$.originalEventDigest'))) THEN 0 ELSE 1 END WHERE ${WHERE}`,
+        params: [
+          crypto.randomUUID(),
+          orderId,
+          await digestJson({ ...key, orderId }),
+          ...keyParams(key),
+        ],
+      },
+      {
+        sql: `UPDATE commerce_source_authority SET state_json=json_set(state_json,'$.version',source_state_version,'$.orderId',order_id,'$.sync',json(CASE WHEN source_sync_pending=0 THEN 'false' ELSE 'true' END)) WHERE ${WHERE}`,
+        params: keyParams(key),
+      },
+    ];
+  }
+}