@tokenoftrust/storefront-runner 3.10.2 → 3.10.4

package/apps/storefront/migrations-apps/0019_commerce_source_authority.sql

@@ -0,0 +1,23 @@
+-- Source authority is independent of business event arrival and fulfillment progress.
+CREATE TABLE commerce_source_authority (
+ tenant_id TEXT NOT NULL, stage TEXT NOT NULL CHECK(stage IN ('preview','publication')),
+ source TEXT NOT NULL, provider_store_id TEXT NOT NULL, source_order_id TEXT NOT NULL,
+ order_id TEXT, source_state_version INTEGER NOT NULL, check_revision INTEGER NOT NULL,
+ active_check_id TEXT, pending_check INTEGER NOT NULL DEFAULT 1,
+ accepted_ledger_generation TEXT, accepted_business_event_set_digest TEXT,
+ source_proof_expires_at TEXT, source_sync_pending INTEGER NOT NULL DEFAULT 1,
+ unresolved_count INTEGER NOT NULL DEFAULT 0, authority_budget INTEGER NOT NULL DEFAULT 0,
+ binding_digest TEXT NOT NULL, state_json TEXT NOT NULL, mutation_id TEXT NOT NULL,
+ PRIMARY KEY(tenant_id,stage,source,provider_store_id,source_order_id),
+ UNIQUE(tenant_id,stage,source,source_order_id), UNIQUE(tenant_id,stage,order_id)
+);
+-- Immutable issued checks, results and hold openings survive retries and process restarts.
+CREATE TABLE commerce_source_observations (
+ tenant_id TEXT NOT NULL, stage TEXT NOT NULL, source TEXT NOT NULL,
+ provider_store_id TEXT NOT NULL, source_order_id TEXT NOT NULL,
+ record_kind TEXT NOT NULL CHECK(record_kind IN ('check','result','hold','manifest')),
+ record_id TEXT NOT NULL, payload_digest TEXT NOT NULL, payload_json TEXT NOT NULL,
+ resolved_version INTEGER, resolved_generation TEXT,
+ PRIMARY KEY(tenant_id,stage,source,provider_store_id,source_order_id,record_kind,record_id)
+);
+CREATE INDEX commerce_source_observations_scope ON commerce_source_observations(tenant_id,stage,source,source_order_id,record_kind);

package/apps/storefront/src/lib/checkout/commerce/finalCartAuthorization.ts

@@ -2,6 +2,8 @@
  * Final-cart authorization decision. Payment is admitted only when the caller
  * token, the bound cart, fresh evidence, the verification seam, and mirror stock
  * all agree. Catalog availability and a browser confirmation are not authority.
+ * A tenant that declares no inventory provider does not track stock: its stock
+ * evidence is `not-required` and its holds carry no balance.
  */
 import {
   admitCallerToken,
@@ -43,6 +45,11 @@ export interface FinalCartRequest {
   trustedIssuers: readonly string[];
   expectedAudience: string;
   activeKids: readonly string[];
+  /**
+   * False only when the tenant declares no inventory provider; `authorities` is read otherwise.
+   * Anything but an explicit `false` counts as tracked, so a caller that omits it fails closed.
+   */
+  stockTracked: boolean;
   authorities: readonly unknown[];
   payment?: PaymentState;
   stock?: StockState;
@@ -90,11 +97,11 @@ function cartFinding(quoted: FinalCartBinding, presented: FinalCartBinding, rout
   return null;
 }
 
-function evidenceFinding(evidence: CommerceEvidence | null): string | null {
+function evidenceFinding(evidence: CommerceEvidence | null, stockTracked: boolean): string | null {
   if (!evidence) return "missing-evidence";
   for (const field of EVIDENCE_FIELDS) {
     const state: EvidenceState | string = evidence[field];
-    if (state === "fresh" || (field !== "stock" && state === "not-required")) continue;
+    if (state === "fresh" || (state === "not-required" && (field !== "stock" || !stockTracked))) continue;
     if (state === "UNKNOWN") return `evidence-${field}-unknown`;
     if (state === "stale" || state === "unreadable" || state === "absent") return `evidence-${field}-${state}`;
     return `evidence-${field}-unreadable`;
@@ -157,7 +164,8 @@ export async function evaluateFinalCart(input: FinalCartRequest): Promise<FinalC
 
   if (input.presented.lines.length < 1) return { ok: false, finding: "malformed-request" };
 
-  const evidence = evidenceFinding(input.evidence);
+  const stockTracked = input.stockTracked !== false;
+  const evidence = evidenceFinding(input.evidence, stockTracked);
   if (evidence) return { ok: false, finding: evidence };
 
   const expiresAt = earlierExpiry(input.presented.verificationExpiresAt, input.presented.taxExpiresAt);
@@ -205,6 +213,10 @@ export async function evaluateFinalCart(input: FinalCartRequest): Promise<FinalC
   const holds: ReserveHold[] = [];
   for (const sku of [...quantities.keys()].sort()) {
     const quantity = quantities.get(sku)!;
+    if (!stockTracked) {
+      holds.push({ sku, locationId: "unspecified", quantity, onHand: 0 });
+      continue;
+    }
     const named =
       input.authorities.find((value) => {
         if (!value || typeof value !== "object") return false;

package/apps/storefront/src/lib/fulfillment/commerceRecovery.ts

@@ -11,6 +11,7 @@ export async function recoverTenantCommerce(
   now: string,
   deployedSha: string,
 ): Promise<number | null> {
+  let incomplete=false;
   for (const stage of ["preview", "publication"] as const) {
     const runId = crypto.randomUUID();
     await db.run(
@@ -37,16 +38,17 @@ export async function recoverTenantCommerce(
         });
       },
     });
-    if (!result.ok) throw new Error("scheduler-unavailable");
+    if(!result.ok)incomplete=true;
     await db.run(
       `UPDATE commerce_recovery_runs SET completed_at=?,delivered=?,retried=?,dead=? WHERE run_id=?`,
-      now,
-      result.delivered,
-      result.retried,
-      result.dead,
+      result.ok?now:null,
+      result.delivered ?? 0,
+      result.retried ?? 0,
+      result.dead ?? 0,
       runId,
     );
   }
+  if(incomplete)throw new Error("commerce-recovery-incomplete");
   const due = await db.first<{ available_at: string }>(
     `SELECT MIN(available_at) available_at FROM scrappy_commerce_outbox WHERE tenant_id=? AND state='pending'`,
     tenantId,

package/apps/storefront/src/lib/fulfillment/fulfillmentService.ts

@@ -6,6 +6,7 @@
  * read the admin fulfillment mock. Label purchase stays an intent row for a
  * separate adapter. UI fields are not source truth.
  */
+import { authorityHolds, authorityFence, type AuthorityRow, type SourceReadiness } from "../orders/data/sourceAuthorityStore.js";
 import type { APIContext } from "astro";
 import {
   COMPLIANCE_STATES,
@@ -149,6 +150,8 @@ export type FulfillmentResult<T> =
   | { ok: false; code: string; holds?: readonly ReleaseHold[] };
 
 interface LoadedOrder {
+  sourceAuthority: AuthorityRow|null;
+  sourceHolds: SourceReadiness[];
   order: {
     tenantId: string;
     stage: CommerceStage;
@@ -185,7 +188,7 @@ interface LoadedOrder {
 type CommitPlan =
   | { type: "done"; view: FulfillmentView }
   | { type: "refuse"; code: string; holds?: readonly ReleaseHold[] }
-  | { type: "write"; statements: SqlStatement[]; minimumChanges: number };
+  | { type: "write"; statements: SqlStatement[]; minimumChanges: number; sourceAdvance?:boolean };
 
 const FAIL_CLOSED_EVIDENCE: CommerceEvidence = {
   verification: "unreadable",
@@ -655,8 +658,10 @@ export class FulfillmentService {
         return this.batch(actor, [...batches][0] ?? "");
       }
       if (batches.size > 0) return refuse("conflict");
+      const sourceBlocked=states.find(s=>s.sourceHolds.length);
+      if(sourceBlocked)return refuse(sourceBlocked.sourceHolds[0]!,sourceBlocked.sourceHolds);
       const batchId = `batch_${crypto.randomUUID()}`;
-      const statements: SqlStatement[] = [claimUpdate(states)];
+      const statements: SqlStatement[] = [claimUpdate(states,this.now())];
       states.forEach((state, index) => {
         statements.push(
           auditStatement(
@@ -670,7 +675,7 @@ export class FulfillmentService {
           ),
         );
       });
-      const changes = await this.write(statements);
+      const changes = await this.write(statements,states.length);
       if (!changes) return refuse("unavailable");
       if ((changes[0] ?? 0) === states.length) return this.batch(actor, batchId);
       if (expectedVersions) return refuse("conflict");
@@ -823,10 +828,12 @@ export class FulfillmentService {
       if (state.shipment.labelPurchaseState === mapped.shipment && state.labelOutcome?.adultSignature === input.adultSignature) {
         return { type: "done", view: state.view };
       }
+      if(input.outcome==="purchased"&&state.sourceHolds.length)return {type:"refuse",code:state.sourceHolds[0]!,holds:state.sourceHolds};
       const version = state.order.eventVersion + 1;
       return {
         type: "write",
         minimumChanges: 1,
+        sourceAdvance:input.outcome==="purchased",
         statements: [
           {
             sql: `UPDATE scrappy_commerce_orders
@@ -906,6 +913,7 @@ export class FulfillmentService {
       return {
         type: "write",
         minimumChanges: 1,
+        sourceAdvance:true,
         statements: [
           {
             sql: `UPDATE scrappy_commerce_orders
@@ -967,6 +975,7 @@ export class FulfillmentService {
 
   private readiness(state: LoadedOrder): ReadinessInput {
     return {
+      sourceHolds: state.sourceHolds,
       payment: state.order.payment,
       stock: state.order.stock,
       fulfillment: state.order.fulfillment,
@@ -1032,7 +1041,7 @@ export class FulfillmentService {
         });
         statements.push(...intent);
       }
-      return { type: "write", statements, minimumChanges: 1 };
+      return { type: "write", statements, minimumChanges: 1, sourceAdvance:true };
     });
   }
 
@@ -1099,7 +1108,11 @@ export class FulfillmentService {
       if (plan.type === "done") return ok(plan.view);
       if (plan.type === "refuse") return refuse(plan.code, plan.holds);
       if (expectedVersion !== undefined && state.order.eventVersion !== expectedVersion) return refuse("conflict");
-      const changes = await this.write(plan.statements);
+      const fence=authorityFence(state.sourceAuthority,this.now(),plan.sourceAdvance===true);
+      const first=plan.statements[0];
+      if(!first)return refuse("unavailable");
+      const guarded=[{sql:`${first.sql} AND (${fence.sql})`,params:[...first.params,...fence.params]},...plan.statements.slice(1)];
+      const changes = await this.write(guarded);
       if (!changes) return refuse("unavailable");
       if ((changes[0] ?? 0) >= plan.minimumChanges) {
         const next = await this.load(scope.tenantId, scope.stage, orderId);
@@ -1110,10 +1123,17 @@ export class FulfillmentService {
     return refuse("conflict");
   }
 
-  private async write(statements: readonly SqlStatement[]): Promise<number[] | null> {
+  private async write(statements: readonly SqlStatement[],minimumChanges=1): Promise<number[] | null> {
     try {
-      return await this.db.batch(statements);
-    } catch {
+      if(!statements.length)return [];
+      // A competing transaction can occupy the expected next event version. Abort this
+      // entire batch unless its first CAS actually wrote; version-only side effects are unsafe.
+      const gated=[statements[0]!,{sql:`SELECT json(CASE WHEN changes() >= ? THEN 'true' ELSE 'cas-not-applied' END)`,params:[minimumChanges]},...statements.slice(1)];
+      const changes=await this.db.batch(gated);
+      return [changes[0] ?? 0,...changes.slice(2)];
+    } catch(error) {
+      let cause:unknown=error;
+      for(let depth=0;depth<4&&cause instanceof Error;depth++,cause=cause.cause){if(cause.message.includes("malformed JSON"))return statements.map(()=>0);}
       return null;
     }
   }
@@ -1222,7 +1242,7 @@ export class FulfillmentService {
     );
     if (snapshot.sourceVersion !== undefined) statements.push(projectionCheckpoint(snapshot,version,this.now()));
     const changes = await this.write(statements);
-    if (!changes) return refuse("unavailable");
+    if (!changes) {const existing=await this.load(snapshot.tenantId,snapshot.stage,snapshot.orderId);return existing?"exists":refuse("unavailable");}
     if ((changes[0] ?? 0) !== 1) return "exists";
     const loaded = await this.load(snapshot.tenantId, snapshot.stage, snapshot.orderId);
     return loaded ? ok(loaded.view) : refuse("unavailable");
@@ -1437,7 +1457,12 @@ export class FulfillmentService {
       amountMinor: Number(row.amount_minor),
       eventVersion: Number(row.event_version),
     };
+    let sourceAuthority:AuthorityRow|null=null;let sourceHolds:SourceReadiness[];
+    try { sourceAuthority=await this.db.get<AuthorityRow & Record<string,unknown>>(`SELECT * FROM commerce_source_authority WHERE tenant_id=? AND stage=? AND source=? AND source_order_id=?`,[tenantId,stage,order.source,order.sourceOrderId]) ?? null;
+      sourceHolds=sourceAuthority?.order_id!==order.orderId?["source-authority-unavailable"]:authorityHolds(sourceAuthority,this.now());
+    }catch{sourceHolds=["source-authority-unreadable"];}
     const loaded: LoadedOrder = {
+      sourceAuthority,sourceHolds,
       order,
       evidence,
       lines,
@@ -1477,6 +1502,7 @@ export class FulfillmentService {
     const readiness = this.readiness(loaded);
     const holds = releaseHolds(readiness);
     loaded.view.holds = holds;
+    if(sourceHolds.length&&order.fulfillment==="ready")loaded.view.fulfillment="held";
     loaded.view.canRelease = canRelease(readiness) && !loaded.shipment;
     loaded.view.canHandOff = handoffRefusal(readiness) === null && loaded.shipment?.handoffState !== "handed_off";
     loaded.view.shipment = loaded.shipment
@@ -1517,11 +1543,12 @@ function touchOrder(state: LoadedOrder, wantIntent: boolean): SqlStatement {
   };
 }
 
-function claimUpdate(states: readonly LoadedOrder[]): SqlStatement {
+function claimUpdate(states: readonly LoadedOrder[],now:string): SqlStatement {
   const first = states[0];
   if (!first) return { sql: "SELECT 0", params: [] };
-  const match = states.map(() => "(order_id = ? AND event_version = ?)").join(" OR ");
-  const versionParams = states.flatMap((state) => [state.order.orderId, state.order.eventVersion]);
+  const fences=states.map(state=>authorityFence(state.sourceAuthority,now,true));
+  const match = states.map((_,i) => `(order_id = ? AND event_version = ? AND (${fences[i]!.sql}))`).join(" OR ");
+  const versionParams = states.flatMap((state,i) => [state.order.orderId, state.order.eventVersion,...fences[i]!.params]);
   return {
     sql: `UPDATE scrappy_commerce_orders
       SET event_version = event_version + 1

package/apps/storefront/src/lib/fulfillment/readiness.ts

@@ -17,9 +17,15 @@ import {
   type ProviderOutcome,
   type StockState,
 } from "@tot/public-runtime";
+import type { SourceReadiness } from "../orders/data/sourceAuthorityStore.js";
 import { COMPLIANCE_RULE_PROFILES } from "@/config/compliance/rulesets";
 
 export const RELEASE_HOLDS = [
+  "source-check-pending",
+  "source-ledger-conflict",
+  "source-authority-unreadable",
+  "source-authority-unavailable",
+  "source-sync-pending",
   "evidence-unknown",
   "evidence-stale",
   "evidence-unreadable",
@@ -48,6 +54,7 @@ export interface CarrierPolicy {
 }
 
 export interface ReadinessInput {
+  sourceHolds?: readonly SourceReadiness[];
   payment: PaymentState;
   stock: StockState;
   fulfillment: FulfillmentState;
@@ -75,7 +82,7 @@ function add(holds: ReleaseHold[], hold: ReleaseHold | null): void {
 
 /** Holds that forbid creating a shipment intent. Compliance is not an input. */
 export function releaseHolds(input: ReadinessInput): ReleaseHold[] {
-  const holds: ReleaseHold[] = [];
+  const holds: ReleaseHold[] = [...(input.sourceHolds ?? [])];
   for (const field of ["verification", "tax", "risk", "stock"] as const) {
     const value = input.evidence[field];
     add(holds, value in EVIDENCE_HOLDS ? EVIDENCE_HOLDS[value as EvidenceState] : "evidence-unreadable");

package/apps/storefront/src/lib/integrations/webhooks/deliveryEngine.ts

@@ -326,7 +326,7 @@ function publicCommercePayload(payload: string): Record<string, unknown> | null
 
 export type CommerceSweepResult =
   | { ok: true; delivered: number; retried: number; dead: number }
-  | { ok: false; reason: "scheduler" };
+  | { ok: false; reason: "scheduler" | "storage"; delivered?:number; retried?:number; dead?:number; incomplete?:number };
 
 export type CommerceDeliver = (event: Record<string, unknown>, row: CommerceOutboxDue) => Promise<void>;
 
@@ -344,10 +344,13 @@ export async function sweepDurableCommerce(input: {
 }): Promise<CommerceSweepResult> {
   if (input.scheduler !== COMMERCE_SCHEDULER) return { ok: false, reason: "scheduler" };
   const port = new ScrappyCommerceOutbox(input.db);
-  const due = await port.due(input.now,input.tenantId,input.stage);
+  let due:CommerceOutboxDue[];
+  try{due=await port.due(input.now,input.tenantId,input.stage);}catch{return {ok:false,reason:"storage",delivered:0,retried:0,dead:0,incomplete:1};}
   let delivered = 0;
   let retried = 0;
   let dead = 0;
+  let incomplete=0;
+  const failedTenants=new Set<string>();
   const tenants: { tenantId: string; stage: string }[] = [];
   const seenTenant = (tenantId: string, stage: string) => {
     if (!tenants.some((item) => item.tenantId === tenantId && item.stage === stage)) {
@@ -356,39 +359,34 @@ export async function sweepDurableCommerce(input: {
   };
   for (const row of due) {
     seenTenant(row.tenant_id, row.stage);
-    const outcome = await settleCommerceRow(port, row, input.now, input.deliver);
+    let outcome:"delivered"|"retried"|"dead";
+    try{outcome=await settleCommerceRow(input.db,row,input.now,input.deliver);}catch{incomplete++;failedTenants.add(JSON.stringify([row.tenant_id,row.stage]));continue;}
     if (outcome === "delivered") delivered += 1;
     else if (outcome === "retried") retried += 1;
     else dead += 1;
   }
-  for (const tenant of tenants) await port.noteCursor(tenant.tenantId, tenant.stage, input.now);
+  for(const tenant of tenants){if(failedTenants.has(JSON.stringify([tenant.tenantId,tenant.stage])))continue;try{await port.noteCursor(tenant.tenantId,tenant.stage,input.now);}catch{incomplete++;}}
+  if(incomplete)return {ok:false,reason:"storage",delivered,retried,dead,incomplete};
   return { ok: true, delivered, retried, dead };
 }
 
+async function persistCommerceOutcome(db:Queryable,row:CommerceOutboxDue,state:"delivered"|"pending"|"dead",attemptCount=row.attempt_count,availableAt=row.available_at):Promise<void> {
+  const committed=await db.first<{outbox_id:string}>(`UPDATE scrappy_commerce_outbox SET state=?,attempt_count=?,available_at=? WHERE outbox_id=? AND tenant_id=? AND stage=? AND order_id=? AND state='pending' AND attempt_count=? RETURNING outbox_id`,state,attemptCount,availableAt,row.outbox_id,row.tenant_id,row.stage,row.order_id,row.attempt_count);
+  if(committed?.outbox_id!==row.outbox_id)throw new Error("commerce-outcome-incomplete");
+}
 async function settleCommerceRow(
-  port: ScrappyCommerceOutbox,
+  db:Queryable,
   row: CommerceOutboxDue,
   now: string,
   deliver: CommerceDeliver | undefined,
 ): Promise<"delivered" | "retried" | "dead"> {
-  const event = publicCommercePayload(row.payload);
-  if (!event) {
-    await port.markDead(row.outbox_id);
-    return "dead";
-  }
-  try {
-    if (!deliver) throw new Error("delivery-unconfigured");
-    await deliver(event,row);
-    await port.markDelivered(row.outbox_id);
-    return "delivered";
-  } catch {
-    const next = row.attempt_count + 1;
-    if (next >= MAX_DELIVERY_ATTEMPTS) {
-      await port.markDead(row.outbox_id, next);
-      return "dead";
-    }
-    const availableAt = new Date(Date.parse(now) + computeBackoffDelaySeconds(next) * 1000).toISOString();
-    await port.markRetry(row.outbox_id, next, availableAt);
-    return "retried";
-  }
+  const event=publicCommercePayload(row.payload);
+  if(!event){await persistCommerceOutcome(db,row,"dead");return "dead";}
+  let succeeded=false;
+  try{if(deliver){await deliver(event,row);succeeded=true;}}catch{/* Retry the failed order independently; diagnostic payloads stay private. */}
+  if(succeeded){await persistCommerceOutcome(db,row,"delivered");return "delivered";}
+  const next=row.attempt_count+1;
+  if(next>=MAX_DELIVERY_ATTEMPTS){await persistCommerceOutcome(db,row,"dead",next);return "dead";}
+  const availableAt=new Date(Date.parse(now)+computeBackoffDelaySeconds(next)*1000).toISOString();
+  await persistCommerceOutcome(db,row,"pending",next,availableAt);return "retried";
 }

package/apps/storefront/src/lib/inventory/allocations.ts

@@ -88,6 +88,11 @@ export interface ReserveInput {
   admissionStatement?: SqlStatement;
   /** Immutable provider identity, claimed atomically with its receipt and holds. */
   providerCart?: { provider: "foxycart"; id: string; digest: string; expectedAuthorizationId?: string };
+  /**
+   * The tenant declares no inventory provider: each hold records the order's units so payment
+   * confirmation and release work unchanged, but no balance bounds it.
+   */
+  stockUntracked?: boolean;
 }
 
 export type ReserveResult =
@@ -255,17 +260,28 @@ function reserveShape(input: ReserveInput): ReserveResult | null {
 }
 
 function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string): SqlStatement {
-  return {
-    sql: `INSERT INTO scrappy_allocations (tenant_id, stage, order_id, sku, location_id, quantity, state)
-      SELECT ?, ?, ?, ?, ?, ?, 'reserved'
-      WHERE (
+  const bound = input.stockUntracked ? "" : `(
         SELECT COALESCE(SUM(quantity), 0) FROM scrappy_allocations
         WHERE tenant_id = ? AND stage = ? AND sku = ? AND location_id = ? AND state IN ('reserved', 'confirmed')
       ) + ? <= ${input.admissionStatement
         ? `(SELECT COALESCE(SUM(quantity_delta), 0) FROM commerce_inventory_movements
             WHERE tenant_id = ? AND stage = ? AND sku = ? AND location_id = ?)`
         : "?"}
-      AND NOT EXISTS (
+      AND `;
+  const boundParams = input.stockUntracked ? [] : [
+    input.tenantId,
+    input.stage,
+    hold.sku,
+    hold.locationId,
+    hold.quantity,
+    ...(input.admissionStatement
+      ? [input.tenantId, input.stage, hold.sku, hold.locationId]
+      : [hold.onHand]),
+  ];
+  return {
+    sql: `INSERT INTO scrappy_allocations (tenant_id, stage, order_id, sku, location_id, quantity, state)
+      SELECT ?, ?, ?, ?, ?, ?, 'reserved'
+      WHERE ${bound}NOT EXISTS (
         SELECT 1 FROM scrappy_allocations
         WHERE tenant_id = ? AND stage = ? AND order_id = ? AND sku = ? AND location_id = ?
           AND state IN ('reserved', 'confirmed')
@@ -292,14 +308,7 @@ function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string
       hold.sku,
       hold.locationId,
       hold.quantity,
-      input.tenantId,
-      input.stage,
-      hold.sku,
-      hold.locationId,
-      hold.quantity,
-      ...(input.admissionStatement
-        ? [input.tenantId, input.stage, hold.sku, hold.locationId]
-        : [hold.onHand]),
+      ...boundParams,
       input.tenantId,
       input.stage,
       input.orderId,

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

@@ -32,6 +32,8 @@
  * compute one FOR either. `rawCustomerId` is accepted and simply unused;
  * see `docs/private-apps/order-forward-contract.md` for the full rationale.
  */
+import { SourceAuthorityStore } from "./sourceAuthorityStore.js";
+import { SourceAuthorityError, parseSourceWire, exactKeys, digestJson, type BeginAck, type ResultAck, type AuthorityCode, isRecord, isSourceId } from "./sourceAuthorityContract.js";
 import { OrdersStore, ScrappyOrderLedger, type OrderLineItem, type OrderStatus, type Order } from "./ordersStore.js";
 import { emitWebhookEvent } from "../../integrations/webhooks/emit.js";
 import type { WebhookTopic } from "../../integrations/webhooks/deliveryStore.js";
@@ -149,6 +151,7 @@ export async function receiveForwardedOrder(db: Queryable, input: OrderForwardIn
 }
 
 export interface CommerceCallerConfig {
+  expectedStage: CommerceStage;
   jwks: JSONWebKeySet;
   trustedIssuers: readonly string[];
   expectedAudience: string;
@@ -159,6 +162,7 @@ export interface CommerceCallerConfig {
 export type SignedCommerceRefusal = CallerTokenRefusal | "version" | "malformed" | "totals" | "private" | "replay";
 
 export type SignedCommerceResult =
+  | { ok:true; authorityAck:BeginAck|ResultAck; tenantId:string; stage:CommerceStage }
   | {
       ok: true;
       duplicate: boolean;
@@ -170,7 +174,7 @@ export type SignedCommerceResult =
       currency: string;
       tenantId: string;
     }
-  | { ok: false; status: number; reason: SignedCommerceRefusal | "order commit failed" };
+  | { ok: false; status: number; reason: SignedCommerceRefusal | AuthorityCode | "order commit failed" };
 
 function isStage(value: unknown): value is CommerceStage {
   return value === "preview" || value === "publication";
@@ -198,6 +202,7 @@ export async function verifySignedCommerceToken(
   config: CommerceCallerConfig,
   binding: { tenantId: string; stage: CommerceStage },
 ): Promise<{ ok: true; issuer: string; jti: string; digest: string } | { ok: false; reason: CallerTokenRefusal | "version" }> {
+  if(!isStage(config.expectedStage)||binding.stage!==config.expectedStage)return {ok:false,reason:"stage"};
   if (token.split(".").length !== 3) {
     const admitted = admitCallerToken({
       token: { scheme: "shared-secret" },
@@ -265,6 +270,7 @@ export async function verifySignedCommerceToken(
   });
   if (!isStage(claims.stage)) return { ok: false, reason: admitted.ok ? "stage" : admitted.reason === "signature" ? "signature" : "stage" };
   if (!admitted.ok) return admitted;
+  if(typeof claims.exp!=="number"||claims.exp-Math.floor(Date.parse(config.now)/1000)>60)return {ok:false,reason:"lifetime"};
   if (claims.ver !== 1) return { ok: false, reason: "version" };
   if (typeof claims.digest !== "string" || claims.digest === "") return { ok: false, reason: "signature" };
   return { ok: true, issuer: typeof claims.iss === "string" ? claims.iss : "", jti: typeof claims.jti === "string" ? claims.jti : "", digest: claims.digest };
@@ -277,6 +283,7 @@ export async function receiveSignedCommerceOrder(
   token: string,
   config: CommerceCallerConfig,
 ): Promise<SignedCommerceResult> {
+  if(!isStage(config.expectedStage))return {ok:false,status:503,reason:"source-authority-unavailable"};
   if (body === null || typeof body !== "object" || Array.isArray(body)) {
     return { ok: false, status: 400, reason: "malformed" };
   }
@@ -285,7 +292,7 @@ export async function receiveSignedCommerceOrder(
     return { ok: false, status: 401, reason: "tenant" };
   }
   if (!isStage(record.stage)) return { ok: false, status: 401, reason: "stage" };
-  if (!("event" in record)) return { ok: false, status: 400, reason: "malformed" };
+  if (!exactKeys(record,["tenantId","stage","event"])) return { ok: false, status: 400, reason: "malformed" };
 
   const verified = await verifySignedCommerceToken(token, config, {
     tenantId: record.tenantId,
@@ -298,18 +305,40 @@ export async function receiveSignedCommerceOrder(
   const digest = await sha256Hex(canonicalJson(envelope));
   if (digest !== verified.digest) return { ok: false, status: 401, reason: "signature" };
 
-  const event = normalizeCommerceEvent(record.event);
-  if (event === "malformed" || event === "totals") return { ok: false, status: 400, reason: event };
-
+  const authority=new SourceAuthorityStore(db);
   try {
+    const replay={issuer:verified.issuer,jti:verified.jti};
+    const seen=await db.first(`SELECT jti FROM scrappy_caller_replay WHERE tenant_id=? AND stage=? AND issuer=? AND jti=?`,record.tenantId,record.stage,replay.issuer,replay.jti);
+    if(seen)return {ok:false,status:401,reason:"replay"};
+    const wire=parseSourceWire(record.event);
+    if(!wire){
+      const e=record.event;
+      if(isRecord(e)&&e.source==="foxycart"&&isSourceId(e.providerStoreId)&&isSourceId(e.sourceOrderId)&&["validatedManifestCores","businessEventDigestPairs","resolvesHoldIds","completeValidatedManifestSetOrNull","conflictingValidatedGenerationsOrNull"].some(k=>Array.isArray(e[k])&&(e[k] as unknown[]).length>64)){await authority.budget({tenantId:record.tenantId,stage:record.stage,source:"foxycart",providerStoreId:e.providerStoreId,sourceOrderId:e.sourceOrderId},config.now);return {ok:false,status:409,reason:"authority-budget"};}
+      return {ok:false,status:400,reason:"malformed"};
+    }
+    if(wire.kind!=="source-order-event") {
+      const key={tenantId:record.tenantId,stage:record.stage,source:wire.source,providerStoreId:wire.providerStoreId,sourceOrderId:wire.sourceOrderId};
+      const authorityAck=wire.kind==="source-check-begin"?await authority.begin(key,wire,config.now,replay):await authority.result(key,wire,config.now,replay);
+      return {ok:true,authorityAck,tenantId:record.tenantId,stage:record.stage};
+    }
+    const event=normalizeCommerceEvent(wire.event);
+    if(event==="malformed"||event==="totals")return {ok:false,status:400,reason:event};
+    // Strict original bytes: defaults, aliases, omitted keys and additional keys cannot silently change the digest.
+    if(canonicalJson(wire.event)!==canonicalJson(event))return {ok:false,status:400,reason:"malformed"};
+    if(await digestJson(wire.event)!==wire.provenance.exactOriginalEventDigest)return {ok:false,status:401,reason:"signature"};
+    const sourceAuthority=await authority.authorizeEvent(record.tenantId,record.stage,event,wire.provenance);
     const committed = await new ScrappyOrderLedger(db).commit({
       tenantId: record.tenantId,
       stage: record.stage,
       event,
       now: config.now,
       replay: { issuer: verified.issuer, jti: verified.jti },
+      sourceAuthority,
     });
-    if (!committed.ok) return { ok: false, status: 401, reason: "replay" };
+    if(!committed.ok){
+      if(committed.reason==="conflict")await authority.budget({tenantId:record.tenantId,stage:record.stage,source:"foxycart",providerStoreId:sourceAuthority.provider_store_id,sourceOrderId:sourceAuthority.source_order_id},config.now);
+      return {ok:false,status:committed.reason==="conflict"?409:401,reason:committed.reason==="conflict"?"control-identity-conflict":"replay"};
+    }
     return {
       ok: true,
       duplicate: committed.duplicate,
@@ -321,7 +350,8 @@ export async function receiveSignedCommerceOrder(
       currency: committed.snapshot.currency,
       tenantId: record.tenantId,
     };
-  } catch {
+  } catch(error) {
+    if(error instanceof SourceAuthorityError)return {ok:false,status:error.code==="malformed"?400:error.code==="signature"?401:409,reason:error.code};
     return { ok: false, status: 500, reason: "order commit failed" };
   }
 }

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

@@ -10,6 +10,7 @@
  * `AppRegistryService` uses, so this runs unchanged against real D1 in the
  * Worker and an in-memory `node:sqlite` in tests.
  */
+import { SourceAuthorityStore, type AuthorityRow } from "./sourceAuthorityStore.js";
 import type { Queryable, QueryStatement } from "../../catalog/d1/catalog.js";
 import {
   canonicalJson,
@@ -233,6 +234,7 @@ export interface CommitCommerceInput {
   event: CommerceSourceEvent;
   now: string;
   replay?: { issuer: string; jti: string };
+  sourceAuthority?: AuthorityRow;
 }
 
 export type CommitCommerceResult =
@@ -288,7 +290,7 @@ export class ScrappyOrderLedger {
     );
     if (existing) {
       const storedDigest = await this.storedPayloadDigest(tenantId, stage, event.source, event.sourceEventId);
-      if (storedDigest !== null && storedDigest !== digest) return { ok: false, reason: "conflict" };
+      if (storedDigest !== digest) return { ok: false, reason: "conflict" };
       if (input.replay) {
         try {
           await this.insertReplay(input);
@@ -317,6 +319,10 @@ export class ScrappyOrderLedger {
     const key = idempotencyKey(tenantId, stage, event.source, event.sourceEventId);
     const outboxId = (await sha256Hex(key)).slice(0, 32);
     const statements: QueryStatement[] = [];
+    if (input.sourceAuthority) {
+      const a=input.sourceAuthority;
+      statements.push({sql:`SELECT json(CASE WHEN EXISTS(SELECT 1 FROM commerce_source_authority WHERE tenant_id=? AND stage=? AND source=? AND source_order_id=? AND source_state_version=? AND accepted_ledger_generation=? AND accepted_business_event_set_digest=?) THEN 'true' ELSE 'source-state-changed' END)`,params:[tenantId,stage,event.source,event.sourceOrderId,a.source_state_version,a.accepted_ledger_generation,a.accepted_business_event_set_digest]});
+    }
     if (input.replay) {
       statements.push({
         sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at) VALUES (?,?,?,?,?)`,
@@ -393,6 +399,7 @@ export class ScrappyOrderLedger {
       },
     );
 
+    if(input.sourceAuthority)statements.push(...await new SourceAuthorityStore(this.db).businessStatements(input.sourceAuthority,event.orderId));
     try {
       await atomic(this.db, statements);
     } catch (error) {
@@ -409,7 +416,7 @@ export class ScrappyOrderLedger {
         );
         if (raced) {
           const storedDigest = await this.storedPayloadDigest(tenantId, stage, event.source, event.sourceEventId);
-          if (storedDigest !== null && storedDigest !== digest) return { ok: false, reason: "conflict" };
+          if (storedDigest !== digest) return { ok: false, reason: "conflict" };
           const snapshotNow = await this.readSnapshot(tenantId, stage, event.orderId, event);
           return { ok: true, duplicate: true, snapshot: snapshotNow, outboxId: raced.outbox_id };
         }