@weaccelerateinc/agent-sdk 0.0.0-stage → 0.10.3

package/host-adapter.d.ts

@@ -0,0 +1,90 @@
+import type { Checkout, CheckoutId, AccelerateClient } from './index.js';
+import type { ManagedCheckoutContext, ManagedCheckoutEvent, ManagedCheckoutToolsOptions } from './managed-mcp.js';
+import type { PrivateChatState, PrivateChatPrompt, PrivateChatProgress } from './private-chat.js';
+
+export type HostOwner = Pick<ManagedCheckoutContext, 'customer_id' | 'workspace_id' | 'conversation_id'>;
+export interface HostCheckoutAttempt {
+  idempotency_key: string;
+  checkout_id?: CheckoutId;
+  phase: 'creating' | 'active' | 'uncertain' | 'closed';
+  /** Sticky across successful status/cancel; requires separate operator reconciliation. */
+  uncertain: boolean;
+  /** Durable one-use fill/submit admissions survive a lost final commit ACK. */
+  /** Independent provider cleanup proof, separate from service ACK. */
+  cleanup_confirmed?: boolean;
+  effects?: Array<'accelerate_checkout_fill' | 'accelerate_checkout_submit'>;
+  pending?: { operation: string; message_id?: string; revision?: number };
+  private_stage?: PrivateChatState['stage'];
+  checkout?: Checkout;
+}
+export type HostOutboxItem = {
+  id: string;
+  delivered: boolean;
+} & ({ kind: 'checkout_event'; payload: ManagedCheckoutEvent } |
+  { kind: 'private_prompt'; payload: PrivateChatPrompt & { checkout_id: CheckoutId } } |
+  { kind: 'safe_progress'; payload: PrivateChatProgress & { checkout_id: CheckoutId } });
+/** No OTP, CVV, PAN, image bytes, browser connection credentials or private reply
+ * text may enter this record. Encrypt at rest according to host policy. */
+export interface HostCheckoutRecord {
+  version: 'v1';
+  owner: HostOwner;
+  /** Authenticated original phone binding hash; never the raw phone number. */
+  phone_binding?: string;
+  attempt?: HostCheckoutAttempt;
+  history: Array<{ idempotency_key: string; checkout_id: CheckoutId; status: 'cancelled' | 'expired' | 'failed'; uncertain: false }>;
+  outbox: HostOutboxItem[];
+  /** Native-send receipts only, never image bytes/URLs or reply text. A pending
+   * send without receipt requires provider reconciliation, not another upload. */
+  deliveries?: Array<{ idempotency_key: string; receipt?: { message_id: string; sent_at: string } }>;
+}
+export interface HostPersistenceAccess {
+  load(): Promise<HostCheckoutRecord | undefined>;
+  /** Resolve only after a DURABLE independent commit. This write MUST survive a
+   * later callback failure; an enclosing rollback transaction is incompatible. */
+  commit(record: HostCheckoutRecord): Promise<void>;
+}
+export interface HostPersistence {
+  /** Hold a cross-process owner lock and call work exactly once. No automatic
+   * transaction/callback retries. Lost locks/commit acknowledgements must reject.
+   * A local Map/mutex does not implement this production durability contract. */
+  withLock<T>(ownerKey: string, work: (access: HostPersistenceAccess) => Promise<T>): Promise<T>;
+}
+export interface PrivateHostOperation {
+  operation: 'private_start' | 'private_reply' | 'private_state' | 'private_cancel' | 'review_delivery';
+  /** Original authenticated provider ID; required for recoverable reply replay. */
+  message_id?: string;
+}
+export interface OwnedPrivateCheckout extends ManagedCheckoutContext {
+  checkout_id: CheckoutId;
+  previous_stage?: PrivateChatState['stage'];
+  checkout?: Readonly<Checkout>;
+  /** Validates and commits only the safe state/progress/outgoing prompt. */
+  savePrivateState(state: PrivateChatState, options: { messageId: string; suppressPrompt?: boolean }): Promise<void>;
+}
+export interface DurableCheckoutHost<Extra = unknown> {
+  resolveContext: ManagedCheckoutToolsOptions<Extra>['resolveContext'];
+  withCheckoutCreation: ManagedCheckoutToolsOptions<Extra>['withCheckoutCreation'];
+  withOwnedCheckout: ManagedCheckoutToolsOptions<Extra>['withOwnedCheckout'];
+  dispatchCheckoutEvent: ManagedCheckoutToolsOptions<Extra>['dispatchCheckoutEvent'];
+  /** Durable actual native-send receipt cache; lost SDK ACK can reuse receipt
+   * without uploading/sending the same review again. */
+  withPrivateDelivery(context: ManagedCheckoutContext, idempotencyKey: string,
+    deliver: () => Promise<{ message_id: string; sent_at: string }>): Promise<Readonly<{ message_id: string; sent_at: string }>>;
+  /** Call ONLY after connector independently verifies stopped/cleared and retained fence. */
+  confirmBrowserCleanup(context: ManagedCheckoutContext, checkoutId: CheckoutId): Promise<void>;
+  withPrivateCheckout<T>(context: ManagedCheckoutContext, metadata: PrivateHostOperation,
+    work: (checkout: Readonly<OwnedPrivateCheckout>) => Promise<T>): Promise<T | undefined>;
+  /** Safe deliveries only. Recipient/queue must durably deduplicate item.id.
+   * Failure leaves the same pending delivery; never repeat fill or submit here. */
+  drainOutbox(context: ManagedCheckoutContext,
+    deliver: (item: Readonly<HostOutboxItem>, context: Readonly<ManagedCheckoutContext>) => Promise<void>): Promise<number>;
+}
+/** Strict runtime validation only; caller must actually authenticate upstream. */
+export function authenticatedCheckoutContext(value: unknown): Readonly<ManagedCheckoutContext>;
+/** Hash-only key scopes one active payment fence to customer+workspace. Exact
+ * authenticated conversation is additionally checked under the owner lock. */
+export function checkoutHostOwnerKey(context: ManagedCheckoutContext): string;
+export function createDurableCheckoutHost<Extra = unknown>(options: {
+  persistence: HostPersistence;
+  resolveContext: ManagedCheckoutToolsOptions<Extra>['resolveContext'];
+}): Readonly<DurableCheckoutHost<Extra>>;

package/host-adapter.js

@@ -0,0 +1,353 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash, randomUUID } from 'node:crypto';
+import { AccelerateError } from './index.js';
+import { validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+import { renderPrivateChatState, privateChatProgress } from './private-chat.js';
+
+const ID = /^mcs_[A-Za-z0-9_-]{43}$/;
+const OWNER = /^[A-Za-z0-9_.:-]{1,500}$/;
+const MESSAGE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+const RECOVER = new Set(['accelerate_checkout_status', 'accelerate_checkout_cancel', 'private_state', 'private_cancel']);
+const TERMINAL = new Set(['cancelled', 'expired', 'failed']);
+const STATUS_ORDER = new Map(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved', 'ready_for_submit'].map((status, index) => [status, index]));
+const STAGES = new Set(['not_started', 'identity_required', 'otp_required', 'selection_required', 'preparing_checkout', 'approval_required', 'cvv_required', 'verified', 'review_delivery_required', 'review_delivered', 'approved_for_submit', 'closed']);
+const STATUSES = new Set(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved', 'ready_for_submit', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+const object = value => value && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const check = (condition, code = 'invalid_input') => { if (!condition) throw new AccelerateError(code); };
+const clone = value => structuredClone(value);
+const validDate = value => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value) && Number.isFinite(Date.parse(value));
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (object(value)) return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  return value;
+}
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function exact(value, required, optional = [], code = 'invalid_input') {
+  check(object(value) && required.every(key => Object.hasOwn(value, key)) && Object.keys(value).every(key => required.includes(key) || optional.includes(key)), code);
+}
+export function authenticatedCheckoutContext(value) {
+  exact(value, ['customer_id', 'workspace_id', 'conversation_id', 'phone_number'], [], 'permission_denied');
+  check(['customer_id', 'workspace_id', 'conversation_id'].every(key => typeof value[key] === 'string' && OWNER.test(value[key])) && /^\+[1-9]\d{6,14}$/.test(value.phone_number), 'permission_denied');
+  return Object.freeze({ ...value });
+}
+function owner(value) {
+  return Object.fromEntries(['customer_id', 'workspace_id', 'conversation_id'].map(key => [key, value[key]]));
+}
+export function checkoutHostOwnerKey(context) {
+  const resolved = authenticatedCheckoutContext(context);
+  return `accelerate-partner-host:${digest(['v1', resolved.customer_id, resolved.workspace_id])}`;
+}
+function sameOwner(left, right) { return ['customer_id', 'workspace_id', 'conversation_id'].every(key => left[key] === right[key]); }
+function sameAccount(left, right) { return ['customer_id', 'workspace_id'].every(key => left[key] === right[key]); }
+function samePhone(record, context) { return record.phone_binding === undefined || record.phone_binding === digest(['v1', context.customer_id, context.workspace_id, context.phone_number]); }
+function requireCleanClosedAttempt(record) {
+  const old = record.attempt;
+  check(old?.phase === 'closed' && !old.uncertain && !old.pending && TERMINAL.has(old.checkout?.status) && old.checkout?.diagnostics?.cleanup_status === 'confirmed' && old.cleanup_confirmed === true, 'outcome_unknown');
+  check(record.outbox.every(item => item.delivered) && (record.deliveries ?? []).every(item => item.receipt !== undefined), 'operation_conflict');
+}
+function safeText(value, max = 10000) {
+  check(typeof value === 'string' && value.length > 0 && value.length <= max && !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]|(?:\d[ -]?){13,19}|(?:wss?|devtools|chrome-extension):\/\/|Bearer\s|\b(?:session_token|handoff_token|submit_token|api_key)\b/i.test(value), 'invalid_response');
+  return value;
+}
+function safeCheckout(value) {
+  exact(value, ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed'], ['purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'fill_after_verification', 'card', 'address', 'quote', 'submit_expires_at', 'diagnostics'], 'invalid_response');
+  check(ID.test(value.id) && STATUSES.has(value.status) && Number.isSafeInteger(value.revision) && value.revision >= 0 && value.retry_safe === false && value.payment_confirmed === false && validDate(value.expires_at), 'invalid_response');
+  if (value.card !== undefined) {
+    exact(value.card, ['brand', 'last4'], [], 'invalid_response');
+    check(value.card.last4 === null || typeof value.card.last4 === 'string' && /^\d{4}$/.test(value.card.last4), 'invalid_response');
+    if (value.card.brand !== null) safeText(value.card.brand, 40);
+  }
+  if (value.address !== undefined) {
+    exact(value.address, ['label'], ['city', 'state', 'postal_code_mask'], 'invalid_response');
+    for (const key of ['label', 'city', 'state']) if (value.address[key] != null) safeText(value.address[key], 400);
+    check(value.address.postal_code_mask == null || /^\*{3}[A-Za-z0-9 -]{1,2}$/.test(value.address.postal_code_mask), 'invalid_response');
+  }
+  if (value.quote !== undefined) {
+    exact(value.quote, ['checkout_origin', 'amount_cents', 'currency'], [], 'invalid_response');
+    let url; try { url = new URL(value.quote.checkout_origin); } catch { check(false, 'invalid_response'); }
+    check(url.protocol === 'https:' && url.origin === value.quote.checkout_origin && !url.username && !url.password && !url.port && Number.isSafeInteger(value.quote.amount_cents) && value.quote.amount_cents > 0 && value.quote.currency === 'USD', 'invalid_response');
+  }
+  if (value.purpose !== undefined) check(['purchase', 'sandbox_fill_only', 'sandbox_source_comparison'].includes(value.purpose) && value.submit_allowed === (value.purpose === 'purchase'), 'invalid_response');
+  if (value.submit_expires_at !== undefined) check(validDate(value.submit_expires_at), 'invalid_response');
+  if (value.submit_allowed !== undefined) check(typeof value.submit_allowed === 'boolean', 'invalid_response');
+  if (value.fill_after_verification !== undefined) check(value.fill_after_verification === true && value.approval_policy === 'after_fill' && ['purchase', 'sandbox_fill_only'].includes(value.purpose), 'invalid_response');
+  if (value.purchase_approved !== undefined) check(typeof value.purchase_approved === 'boolean', 'invalid_response');
+  if (value.approval_policy !== undefined) check(value.approval_policy === 'after_fill' && typeof value.purchase_approved === 'boolean', 'invalid_response');
+  // The SDK owns detailed diagnostics validation. This projection keeps no URLs,
+  // provider capabilities or data that could accidentally become an effect input.
+  const result = clone(value);
+  if (result.diagnostics !== undefined) result.diagnostics = validateCheckoutDiagnostics(result.diagnostics, result);
+  return result;
+}
+function validateRecord(value, context) {
+  if (value === undefined || value === null) return { version: 'v1', owner: owner(context), phone_binding: digest(['v1', context.customer_id, context.workspace_id, context.phone_number]), outbox: [], history: [], deliveries: [] };
+  exact(value, ['version', 'owner', 'outbox', 'history'], ['attempt', 'deliveries', 'phone_binding'], 'operation_conflict');
+  check(value.version === 'v1' && sameOwner(value.owner, context), 'permission_denied');
+  if (value.phone_binding !== undefined) {
+    check(typeof value.phone_binding === 'string' && /^[a-f0-9]{64}$/.test(value.phone_binding), 'operation_conflict');
+    if (context.phone_number !== undefined) check(value.phone_binding === digest(['v1', context.customer_id, context.workspace_id, context.phone_number]), 'permission_denied');
+  }
+  exact(value.owner, ['customer_id', 'workspace_id', 'conversation_id'], [], 'operation_conflict');
+  check(['customer_id', 'workspace_id', 'conversation_id'].every(key => typeof value.owner[key] === 'string' && OWNER.test(value.owner[key])), 'operation_conflict');
+  check(Array.isArray(value.outbox) && value.outbox.length <= 500 && Array.isArray(value.history) && value.history.length <= 1000, 'operation_conflict');
+  if (value.attempt !== undefined) {
+    exact(value.attempt, ['idempotency_key', 'phase', 'uncertain'], ['checkout_id', 'pending', 'private_stage', 'checkout', 'effects', 'cleanup_confirmed'], 'operation_conflict');
+    check(/^accelerate-host:[a-f0-9-]{36}$/.test(value.attempt.idempotency_key) && ['creating', 'active', 'uncertain', 'closed'].includes(value.attempt.phase) && typeof value.attempt.uncertain === 'boolean', 'operation_conflict');
+    if (value.attempt.cleanup_confirmed !== undefined) check(typeof value.attempt.cleanup_confirmed === 'boolean', 'operation_conflict');
+    if (value.attempt.effects !== undefined) check(Array.isArray(value.attempt.effects) && value.attempt.effects.every(item => ['accelerate_checkout_fill', 'accelerate_checkout_submit'].includes(item)) && new Set(value.attempt.effects).size === value.attempt.effects.length, 'operation_conflict');
+    if (value.attempt.checkout_id !== undefined) check(ID.test(value.attempt.checkout_id), 'operation_conflict');
+    if (value.attempt.pending !== undefined) {
+      exact(value.attempt.pending, ['operation'], ['message_id', 'revision'], 'operation_conflict');
+      check(/^[a-z_]{1,100}$/.test(value.attempt.pending.operation) && (value.attempt.pending.message_id === undefined || MESSAGE.test(value.attempt.pending.message_id)), 'operation_conflict');
+    }
+    if (value.attempt.pending?.revision !== undefined) check(Number.isSafeInteger(value.attempt.pending.revision) && value.attempt.pending.revision > 0, 'operation_conflict');
+    if (value.attempt.private_stage !== undefined) check(STAGES.has(value.attempt.private_stage), 'operation_conflict');
+    if (value.attempt.checkout) check(safeCheckout(value.attempt.checkout).id === value.attempt.checkout_id, 'operation_conflict');
+  }
+  for (const item of value.history) {
+    exact(item, ['idempotency_key', 'checkout_id', 'status', 'uncertain'], [], 'operation_conflict');
+    check(ID.test(item.checkout_id) && TERMINAL.has(item.status) && item.uncertain === false, 'operation_conflict');
+  }
+  if (value.deliveries !== undefined) {
+    check(Array.isArray(value.deliveries) && value.deliveries.length <= 500, 'operation_conflict');
+    for (const item of value.deliveries) {
+      exact(item, ['idempotency_key'], ['receipt'], 'operation_conflict');
+      check(/^accelerate-chat:[a-f0-9]{64}$/.test(item.idempotency_key), 'operation_conflict');
+      if (item.receipt !== undefined) { exact(item.receipt, ['message_id', 'sent_at'], [], 'operation_conflict'); check(MESSAGE.test(item.receipt.message_id) && validDate(item.receipt.sent_at), 'operation_conflict'); }
+    }
+  }
+  for (const item of value.outbox) validateOutbox(item);
+  return clone(value);
+}
+function validateOutbox(item) {
+  exact(item, ['id', 'kind', 'payload', 'delivered'], [], 'invalid_response');
+  check(/^accelerate-(?:checkout-event|chat|progress):[a-f0-9]{64}$/.test(item.id) && ['checkout_event', 'private_prompt', 'safe_progress'].includes(item.kind) && typeof item.delivered === 'boolean', 'invalid_response');
+  if (item.kind === 'checkout_event') {
+    exact(item.payload, ['version', 'kind', 'idempotency_key', 'checkout'], [], 'invalid_response');
+    check(item.payload.version === 'v1' && ['created', 'payment_requested', 'approval_requested', 'review_ready'].includes(item.payload.kind) && item.payload.idempotency_key === item.id, 'invalid_response');
+    safeCheckout(item.payload.checkout);
+  } else {
+    exact(item.payload, ['checkout_id', 'text', 'idempotency_key'], item.kind === 'safe_progress' ? ['stage'] : [], 'invalid_response');
+    check(ID.test(item.payload.checkout_id) && item.payload.idempotency_key === item.id, 'invalid_response'); safeText(item.payload.text);
+    if (item.kind === 'safe_progress') check(['preparing_checkout', 'verified', 'approved_for_submit', 'closed'].includes(item.payload.stage), 'invalid_response');
+  }
+}
+function observe(record, checkout) {
+  const projection = safeCheckout(checkout);
+  check(projection.id === record.attempt.checkout_id, 'permission_denied');
+  const saved = record.attempt.checkout;
+  if (saved && !['outcome_unknown', 'submit_attempted'].includes(projection.status)) {
+    if (projection.revision < saved.revision) return;
+    if (projection.revision === saved.revision && STATUS_ORDER.has(saved.status) && STATUS_ORDER.has(projection.status) && STATUS_ORDER.get(saved.status) > STATUS_ORDER.get(projection.status)) return;
+  }
+  // Inline review delivery may have already closed this browser while the outer
+  // fill callback still holds its earlier ready_for_submit projection.
+  if (saved && TERMINAL.has(saved.status) && !TERMINAL.has(projection.status) && !['outcome_unknown', 'submit_attempted'].includes(projection.status) && projection.revision <= saved.revision) return;
+  record.attempt.checkout = projection;
+  if (['outcome_unknown', 'submit_attempted'].includes(projection.status)) record.attempt.uncertain = true;
+  record.attempt.phase = record.attempt.uncertain ? 'uncertain' : TERMINAL.has(projection.status) ? 'closed' : 'active';
+}
+function recoverable(record, metadata) {
+  const attempt = record.attempt;
+  if (!attempt?.pending && !attempt?.uncertain) return;
+  const duplicatePrivateReply = metadata.operation === 'private_reply' && metadata.message_id && attempt.pending?.operation === 'private_reply' && metadata.message_id === attempt.pending.message_id && !attempt.uncertain;
+  check(RECOVER.has(metadata.operation) || duplicatePrivateReply, 'outcome_unknown');
+}
+
+/** The host owns persistence. No memory store or timer can satisfy this contract. */
+export function createDurableCheckoutHost({ persistence, resolveContext } = {}) {
+  check(typeof persistence?.withLock === 'function' && typeof resolveContext === 'function');
+  const scope = new AsyncLocalStorage();
+  const locked = async (input, work, { creationRebind = false } = {}) => {
+    const context = authenticatedCheckoutContext(input), key = checkoutHostOwnerKey(context), current = scope.getStore();
+    if (current?.active) {
+      // A live nested operation may not rebind even a closed record. Existing
+      // callbacks retain the original conversation/phone until they unwind.
+      check(current.key === key && sameOwner(current.record.owner, context) && samePhone(current.record, context), 'permission_denied');
+      return work(current, context);
+    }
+    let calls = 0, completed = false, expected;
+    const result = await persistence.withLock(key, async access => {
+      check(++calls === 1 && typeof access?.load === 'function' && typeof access?.commit === 'function', 'operation_conflict');
+      const saved = await access.load();
+      let record;
+      if (creationRebind && saved !== undefined && saved !== null) {
+        // Validate the persisted schema before considering a different verified
+        // conversation. Account identity still scopes this same owner lock.
+        record = validateRecord(saved, saved.owner);
+        check(sameAccount(record.owner, context), 'permission_denied');
+        if (!sameOwner(record.owner, context) || !samePhone(record, context)) requireCleanClosedAttempt(record);
+      } else record = validateRecord(saved, context);
+      const active = { key, access, record, active: true, effectDepth: 0 };
+      try { return await scope.run(active, async () => { expected = await work(active, context); completed = true; return expected; }); }
+      finally { active.active = false; }
+    });
+    check(calls === 1 && completed && result === expected, 'operation_conflict'); return result;
+  };
+  const commit = async active => {
+    check(active.active, 'operation_conflict');
+    // Never pass live mutable state to a persistence implementation.
+    validateRecord(active.record, active.record.owner);
+    await active.access.commit(clone(active.record));
+    check(active.active, 'operation_conflict');
+  };
+  const enqueue = async (active, item) => {
+    validateOutbox(item);
+    const existing = active.record.outbox.find(entry => entry.id === item.id);
+    if (existing) { check(JSON.stringify(canonical({ ...existing, delivered: false })) === JSON.stringify(canonical(item)), 'idempotency_conflict'); return; }
+    check(active.record.outbox.length < 500, 'operation_conflict');
+    active.record.outbox.push(clone(item)); await commit(active);
+  };
+  const withOwned = (context, checkoutId, work, metadata = { operation: 'unclassified' }) => locked(context, async (active, resolved) => {
+    check(typeof work === 'function' && ID.test(checkoutId) && active.record.attempt?.checkout_id === checkoutId, 'permission_denied');
+    exact(metadata, ['operation'], ['message_id', 'revision']);
+    check(metadata.revision === undefined || Number.isSafeInteger(metadata.revision) && metadata.revision > 0); check(/^[a-z_]{1,100}$/.test(metadata.operation));
+    if (!active.effectDepth || active.record.attempt.uncertain) recoverable(active.record, metadata);
+    // A lost previous effect acknowledgement remains sticky even if a safe read
+    // succeeds. Read-only failures do not create a new payment ambiguity.
+    if (active.record.attempt.effects?.includes(metadata.operation)) check(false, 'checkout_frozen');
+    if (metadata.operation === 'accelerate_checkout_fill') {
+      const checkout = active.record.attempt.checkout;
+      check(checkout?.status === 'approved' && active.record.attempt.private_stage === 'verified' && metadata.revision === checkout.revision, 'verification_required');
+    }
+    if (metadata.operation === 'accelerate_checkout_submit') {
+      const checkout = active.record.attempt.checkout;
+      check(checkout?.purpose === 'purchase' && checkout.submit_allowed === true && checkout.status === 'ready_for_submit' && checkout.purchase_approved === true && active.record.attempt.private_stage === 'approved_for_submit' && validDate(checkout.submit_expires_at) && Date.parse(checkout.submit_expires_at) > Date.now() && metadata.revision === checkout.revision, 'submit_unavailable');
+    }
+    const oneUse = ['accelerate_checkout_fill', 'accelerate_checkout_submit'].includes(metadata.operation);
+    if (oneUse) {
+      active.record.attempt.effects ??= [];
+      check(!active.record.attempt.effects.includes(metadata.operation), 'checkout_frozen');
+      active.record.attempt.effects.push(metadata.operation);
+    }
+    const recovery = RECOVER.has(metadata.operation), previousPending = active.record.attempt.pending;
+    if (!recovery) { active.record.attempt.pending = { ...metadata }; await commit(active); }
+    const binding = Object.freeze({ ...resolved, checkout_id: checkoutId });
+    try {
+      active.effectDepth++;
+      let result;
+      try { result = await work(binding); } finally { active.effectDepth--; }
+      if (result?.checkout) observe(active.record, result.checkout);
+      if (!recovery) delete active.record.attempt.pending;
+      else if (previousPending) active.record.attempt.pending = previousPending;
+      await commit(active); return result;
+    } catch (error) {
+      if (!recovery) {
+        // Preserve the already-committed pending marker if this acknowledgement
+        // also fails; a later process must still refuse another effect.
+        active.record.attempt.uncertain = true; active.record.attempt.phase = 'uncertain';
+        try { await commit(active); } catch {}
+      }
+      throw error instanceof AccelerateError ? error : new AccelerateError(recovery ? 'request_failed' : 'outcome_unknown');
+    }
+  });
+  return Object.freeze({
+    resolveContext: async extra => authenticatedCheckoutContext(await resolveContext(extra)),
+    withCheckoutCreation: (context, work) => locked(context, async (active, resolved) => {
+      check(typeof work === 'function');
+      if (active.record.attempt) {
+        const old = active.record.attempt;
+        requireCleanClosedAttempt(active.record);
+        // Ordinary closed history is bounded. Uncertain attempts are never
+        // admitted here, aged out or removed by this compaction.
+        active.record.history = active.record.history.slice(-999);
+        active.record.history.push({ idempotency_key: old.idempotency_key, checkout_id: old.checkout_id, status: old.checkout.status, uncertain: false });
+      }
+      if (active.record.attempt) { active.record.outbox = []; active.record.deliveries = []; }
+      // Rebind only in the same durable write as the new creation fence. A lost
+      // commit acknowledgement cannot leave an unfenced owner-only row.
+      active.record.owner = owner(resolved);
+      active.record.phone_binding = digest(['v1', resolved.customer_id, resolved.workspace_id, resolved.phone_number]);
+      active.record.attempt = { idempotency_key: `accelerate-host:${randomUUID()}`, phase: 'creating', uncertain: false, cleanup_confirmed: false, effects: [], pending: { operation: 'creation' } };
+      await commit(active);
+      let persisted = false;
+      try {
+        const result = await work({ idempotency_key: active.record.attempt.idempotency_key, persistCreated: async binding => {
+          check(!persisted && binding?.checkout_id && ID.test(binding.checkout_id) && sameOwner(binding, resolved) && binding.phone_number === resolved.phone_number, 'permission_denied');
+          check(!active.record.attempt.checkout_id || active.record.attempt.checkout_id === binding.checkout_id, 'idempotency_conflict');
+          active.record.attempt.checkout_id = binding.checkout_id; await commit(active); persisted = true;
+        } });
+        check(persisted, 'outcome_unknown');
+        if (result?.checkout) observe(active.record, result.checkout);
+        else active.record.attempt.phase = 'active';
+        delete active.record.attempt.pending; await commit(active); return result;
+      } catch (error) {
+        active.record.attempt.uncertain = true; active.record.attempt.phase = 'uncertain'; try { await commit(active); } catch {}
+        throw error instanceof AccelerateError ? error : new AccelerateError('outcome_unknown');
+      }
+    }, { creationRebind: true }),
+    withOwnedCheckout: withOwned,
+    dispatchCheckoutEvent: (context, event) => locked(context, async active => {
+      check(active.record.attempt?.checkout_id === event?.checkout?.id, 'permission_denied');
+      await enqueue(active, { id: event.idempotency_key, kind: 'checkout_event', payload: event, delivered: false });
+    }),
+    withPrivateDelivery: (context, idempotencyKey, deliver) => locked(context, async active => {
+      check(/^accelerate-chat:[a-f0-9]{64}$/.test(idempotencyKey) && typeof deliver === 'function');
+      active.record.deliveries ??= [];
+      const saved = active.record.deliveries.find(item => item.idempotency_key === idempotencyKey);
+      if (saved?.receipt) return Object.freeze(clone(saved.receipt));
+      // An unconfirmed native send requires provider reconciliation; do not
+      // create a different attachment under an already-used message key.
+      check(!saved, 'outcome_unknown');
+      check(active.record.deliveries.length < 500, 'operation_conflict');
+      const entry = { idempotency_key: idempotencyKey }; active.record.deliveries.push(entry); await commit(active);
+      const receipt = await deliver();
+      exact(receipt, ['message_id', 'sent_at'], [], 'invalid_response');
+      check(MESSAGE.test(receipt.message_id) && validDate(receipt.sent_at) && Date.parse(receipt.sent_at) <= Date.now(), 'invalid_response');
+      entry.receipt = clone(receipt); await commit(active); return Object.freeze(clone(receipt));
+    }),
+    confirmBrowserCleanup: (context, checkoutId) => locked(context, async active => {
+      check(active.record.attempt?.checkout_id === checkoutId && active.record.attempt.checkout?.diagnostics?.cleanup_status === 'confirmed', 'operation_conflict');
+      active.record.attempt.cleanup_confirmed = true; await commit(active);
+    }),
+    /** For private callbacks only. A provider message ID may recover its own
+     * idempotent reply; no reply text enters persistence or the outbox. */
+    withPrivateCheckout: (context, metadata, work) => locked(context, async (active, resolved) => {
+      exact(metadata, ['operation'], ['message_id']);
+      check(metadata.message_id === undefined || typeof metadata.message_id === 'string' && MESSAGE.test(metadata.message_id));
+      const attempt = active.record.attempt;
+      if (!attempt?.checkout_id) return undefined;
+      if (!active.effectDepth || attempt.uncertain) recoverable(active.record, metadata);
+      check(['private_start', 'private_reply', 'private_state', 'private_cancel', 'review_delivery'].includes(metadata.operation) && typeof work === 'function');
+      const recovery = RECOVER.has(metadata.operation), previousPending = attempt.pending, nested = active.effectDepth > 0;
+      if (!recovery) { attempt.pending = { ...metadata }; await commit(active); }
+      try {
+        active.effectDepth++;
+        let result;
+        try { result = await work(Object.freeze({ ...resolved, checkout_id: attempt.checkout_id,
+          previous_stage: attempt.private_stage, checkout: attempt.checkout ? Object.freeze(clone(attempt.checkout)) : undefined,
+          savePrivateState: async (state, { messageId, suppressPrompt = false } = {}) => {
+            check(state?.checkout?.id === attempt.checkout_id && MESSAGE.test(messageId), 'invalid_response');
+            // These renderers revalidate the complete private projection. Only
+            // safe outgoing wording is eligible for durable storage.
+            const prompt = renderPrivateChatState(state, { messageId }), progress = privateChatProgress(state, { messageId });
+            const previousStage = attempt.private_stage;
+            observe(active.record, state.checkout); attempt.private_stage = state.stage;
+            await commit(active);
+            if (prompt && !suppressPrompt && state.stage !== 'review_delivery_required') await enqueue(active, { id: prompt.idempotency_key, kind: 'private_prompt', payload: { checkout_id: attempt.checkout_id, ...prompt }, delivered: false });
+            if (progress && (previousStage !== state.stage || state.duplicate)) await enqueue(active, { id: progress.idempotency_key, kind: 'safe_progress', payload: { checkout_id: attempt.checkout_id, ...progress }, delivered: false });
+          },
+        })); } finally { active.effectDepth--; }
+        if (previousPending && (recovery || nested)) attempt.pending = previousPending; else if (!recovery) delete attempt.pending;
+        await commit(active); return result;
+      } catch (error) {
+        // A reply may be replayed ONLY under its original authenticated provider
+        // ID, relying on the private service's durable deduplication. Other
+        // uncertain effects block future effects while retaining safe recovery.
+        if (!recovery && metadata.operation !== 'private_reply') { attempt.uncertain = true; attempt.phase = 'uncertain'; try { await commit(active); } catch {} }
+        throw new AccelerateError('request_failed');
+      }
+    }),
+    /** At-least-once SAFE delivery only. The downstream provider/queue must
+     * deduplicate item.id. Never put a payment action in this handler. */
+    drainOutbox: (context, deliver) => locked(context, async (active, resolved) => {
+      check(typeof deliver === 'function'); let delivered = 0;
+      for (const item of active.record.outbox) {
+        if (item.delivered) continue;
+        await deliver(Object.freeze(clone(item)), resolved);
+        item.delivered = true; await commit(active); delivered++;
+      }
+      return delivered;
+    }),
+  });
+}