@weaccelerateinc/agent-sdk 0.0.0-stage → 0.11.0

package/host-adapter.js

@@ -0,0 +1,357 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash, randomUUID } from 'node:crypto';
+import { AccelerateError } from './index.js';
+import { validateCheckoutDiagnostics, validateCheckoutReconciliation } 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', 'final_click_armed'].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', 'final_click_armed', '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', 'reconciliation', 'final_click_actor', 'submit_actor'], '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.final_click_actor !== undefined) check(value.final_click_actor === 'customer' && value.purpose === 'purchase', 'invalid_response');
+  if (value.submit_actor !== undefined) check(value.submit_actor === 'customer' && value.final_click_actor === 'customer' && ['submit_attempted', 'outcome_unknown'].includes(value.status), 'invalid_response');
+  if (value.status === 'submit_attempted' && value.purpose === 'purchase') check(value.submit_actor === 'customer', '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');
+  if (value.reconciliation !== undefined) { try { validateCheckoutReconciliation(value.reconciliation, value.status); } catch { check(false, '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.final_click_actor === 'customer' && 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;
+    }),
+  });
+}

package/index.d.ts

@@ -0,0 +1,253 @@
+import type { BrowserOperation, BrowserResult } from './browser-operations.js';
+import type { CheckoutDiagnostics, CheckoutReconciliation, CheckoutReconciliationState } from './checkout-diagnostics.js';
+export { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+export type { CheckoutDiagnostics, CheckoutDiagnosticStage, CheckoutDiagnosticAction, CheckoutCleanupStatus, CheckoutReconciliation, CheckoutReconciliationState } from './checkout-diagnostics.js';
+export type { BrowserOperation, BrowserResult, BrowserStep, BrowserCondition } from './browser-operations.js';
+
+export type CheckoutId = `mcs_${string}`;
+export type CheckoutPurpose = 'purchase' | 'sandbox_source_comparison' | 'sandbox_fill_only';
+export type CheckoutStatus = 'wallet_required' | 'selection_ready' | 'details_ready' | 'approval_required' |
+  'approved' | 'ready_for_submit' | 'final_click_armed' | 'cancelled' | 'expired' | 'failed' | 'submit_attempted' | 'outcome_unknown';
+export interface RequestOptions { signal?: AbortSignal }
+export interface WaitForCheckout {
+  /** Return on these states, or immediately on ready_for_submit or any terminal state. GET requests only. */
+  statuses: readonly CheckoutStatus[];
+  /** Overall wait, including requests. Default 60 seconds; range 1–300000 milliseconds. */
+  timeoutMs?: number;
+  /** Delay between successful status reads. Default 1000; range 250–5000 milliseconds. Errors are never retried. */
+  intervalMs?: number;
+}
+export type AccelerateNextAction = 'check_configuration' | 'check_request' | 'check_status' | 'complete_wallet' |
+  'complete_verification' | 'refresh_quote' | 'refresh_revision' | 'reconcile_order' | 'stop';
+export interface AccelerateEnvironment {
+  /** Optional HTTPS origin; defaults to Accelerate's hosted managed service. */
+  ACCELERATE_BASE_URL?: string;
+  ACCELERATE_API_KEY?: string;
+  ACCELERATE_MERCHANT_ID?: string;
+}
+export interface AccelerateConnection {
+  status: 'connected';
+  api_version: 'v1';
+  merchant_id: string;
+  interaction_modes: ['chat', 'hosted'];
+  currencies: ['USD'];
+}
+export interface Checkout {
+  id: CheckoutId;
+  status: CheckoutStatus;
+  revision: number;
+  expires_at: string;
+  /** Immutable policy metadata. Omitted only by service versions predating this field. */
+  purpose?: CheckoutPurpose;
+  /** Submission is enabled only for purchase purpose; never for sandbox_fill_only. */
+  submit_allowed?: boolean;
+  /** after_fill: final customer approval follows a privately delivered masked review. */
+  approval_policy?: 'after_fill';
+  purchase_approved?: boolean;
+  /** Explicit v2 policy acknowledged at creation; a later explicit quote arm lets private CVV continue
+   * one fill under the backend lock. Does not authorize final submission. */
+  fill_after_verification?: true;
+  /** Purchases only: the customer's own trusted backend/browser performs the physical final click. Accelerate never does. */
+  final_click_actor?: 'customer';
+  /** Present on submit_attempted (required for a purchase) and optionally on outcome_unknown, which cannot assert that a click happened. Never payment confirmation. */
+  submit_actor?: 'customer';
+  card?: { last4: string | null; brand: string | null };
+  address?: { label: string | null; city?: string | null; state?: string | null; postal_code_mask?: string | null };
+  quote?: { checkout_origin: string; amount_cents: number; currency: 'USD' };
+  submit_expires_at?: string;
+  /** Present once the client backend recorded the merchant's result. Absent on older services.
+   * This is the client's statement, not Accelerate's proof, so payment_confirmed stays false. */
+  reconciliation?: CheckoutReconciliation;
+  retry_safe: false;
+  payment_confirmed: false;
+  /** Negotiated safe metadata; absent when connecting to an older service. */
+  diagnostics?: CheckoutDiagnostics;
+}
+export interface CreatedCheckout extends Checkout { wallet_url?: string }
+export interface ReconciledCheckout extends Checkout { reconciliation: CheckoutReconciliation }
+/** Server only, after your backend checked the merchant's order system. Never model input.
+ * order_reference is stored only as a hash and is never returned. */
+export type CheckoutReconciliationRequest = {
+  state: 'confirmed';
+  order_reference: string;
+  /** Must equal the approved quote exactly. */
+  amount_cents: number;
+  currency: 'USD';
+  source: string;
+} | {
+  state: Exclude<CheckoutReconciliationState, 'confirmed'>;
+  order_reference?: string;
+  amount_cents?: number;
+  currency?: 'USD';
+  source: string;
+};
+/** Server-owned existing browser, resolved from the authenticated application's
+ * durable browser record. Never accept this binding from model arguments.
+ * The customer backend retains provider access; this is not private-from-creation custody. */
+export interface BrowserUseBrowserBinding {
+  provider: 'browser_use';
+  browser_id: string;
+  custody_mode: 'customer_backend_trusted';
+}
+/** Registered server-side executor connector; IDs are resolved from owned backend records. */
+export interface RegisteredBrowserBinding {
+  provider: 'connector';
+  connector_id: string;
+  browser_id: string;
+  custody_mode: 'customer_backend_trusted';
+}
+export type CustomerBrowserBinding = BrowserUseBrowserBinding | RegisteredBrowserBinding;
+/** Derive every field from authenticated server ownership and its immutable browser reservation. Never expose as model input. */
+export interface CreationInspectionRequest {
+  customer_id: string;
+  workspace_id: string;
+  conversation_id: string;
+  idempotency_key: string;
+  browser: BrowserUseBrowserBinding;
+}
+export type CreationInspection = { confirmed: false } | {
+  confirmed: true;
+  checkout_id: CheckoutId;
+  revision: 0;
+  purpose: 'purchase' | 'sandbox_fill_only';
+  creation_key_sha256: string;
+  retirement: { browser_provider: 'browser_use'; browser_id: string; retired: true; provider_stopped: true; private_lease_closed: true; recording_disabled: true };
+};
+/** Read-only proof for an already terminal, retired fill-only attempt. Never permits replay or purchase. */
+export interface RetirementInspectionRequest extends CreationInspectionRequest { revision: number; }
+export type RetirementInspection = { confirmed: false } | {
+  confirmed: true;
+  checkout_id: CheckoutId;
+  revision: number;
+  status: 'outcome_unknown';
+  purpose: 'sandbox_fill_only';
+  approval_policy: 'after_fill';
+  submit_allowed: false;
+  purchase_approved: false;
+  creation_key_sha256: string;
+  retirement: Extract<CreationInspection, { confirmed: true }>['retirement'];
+};
+export interface CreateCheckout {
+  /** Derive from your server's authenticated user, never model input. */
+  customer_id: string;
+  /** Derive from the authenticated workspace. */
+  workspace_id: string;
+  phone_number: string;
+  start_url: string;
+  /** Reuse only for this exact creation attempt. */
+  idempotency_key: string;
+  /** Default hosted. Chat creates no hosted wallet link or browser session capability. */
+  interaction_mode?: 'hosted' | 'chat';
+  /** Required in chat mode; derive from the authenticated messaging webhook. */
+  conversation_id?: string;
+  /** Immutable. Source comparison cannot approve/fill/submit. Fill-only uses chat and can never submit. */
+  purpose?: CheckoutPurpose;
+  /** Defaults before_fill for compatibility. after_fill requires chat and private review delivery acknowledgement. */
+  approval_policy?: 'before_fill' | 'after_fill';
+  /** Declare v2 before OTP and require its true acknowledgement. Does not arm filling until requestApproval explicitly repeats true. */
+  fill_after_verification?: true;
+  /** Explicit chat/after_fill attachment. Omit to retain Accelerate-created
+   * private Kernel custody. Attachment never navigates or replaces the document. */
+  browser?: CustomerBrowserBinding;
+  /** Required for purchase (the default purpose): the customer's backend, not Accelerate, performs the final click.
+   * Purchase also requires chat, after_fill and a customer_backend_trusted browser. */
+  final_click_actor?: 'customer';
+  /** Your own provider read of `browser`, so Accelerate never needs your provider API key.
+   * Send it on every create. It is held in memory for this checkout and never stored. */
+  browser_resource?: ClientBrowserResource;
+}
+/** The fields of Browser Use `GET /api/v4/browsers/{id}` that Accelerate needs. */
+export interface ClientBrowserResource {
+  id: string;
+  status: 'active';
+  cdpUrl: string;
+  startedAt: string;
+  timeoutAt: string;
+  recordingAvailable: false;
+  metadata: Record<string, string>;
+  extensions: [{ id: string; version: string; runtimeId: string }];
+}
+/** Hypothesis to inspect against the actual checkout; never a caller assertion of currency evidence. */
+export interface QuoteVerificationRequest {
+  revision: number;
+  checkout_url: string;
+  expected_amount_cents: number;
+  expected_currency: 'USD';
+  checkout_total_selector: string;
+}
+/** Read-only verification of this revision. Does not authorize approval, CVV, filling or submission. */
+export interface VerifiedCheckoutQuote {
+  checkout_id: CheckoutId;
+  revision: number;
+  verified: true;
+  quote: { checkout_origin: string; amount_cents: number; currency: 'USD' };
+}
+export interface ApprovalRequest {
+  checkout_url: string;
+  amount_cents: number;
+  currency: 'USD';
+  checkout_total_selector: string;
+  submit_selector: string;
+  /** Opt in explicitly; only chat/after_fill purchase or sandbox_fill_only.
+   * Successful private verification fills this exact revision without AI. */
+  fill_after_verification?: true;
+}
+/** BACKEND ONLY. The target and arm_id must never appear in MCP arguments, results, history or outbox. */
+export interface ArmedFinalClick {
+  /** Opaque bounded string (20..16000 printable ASCII). Never display or log. */
+  arm_id: string;
+  /** Short window (service limit 15 seconds) in which the customer host may click once. */
+  armed_expires_at: string;
+  target: { checkout_url: string; submit_selector: string };
+  retry_safe: false;
+  payment_confirmed: false;
+}
+export interface AccelerateClientOptions {
+  baseUrl: string;
+  apiKey: string;
+  merchantId: string;
+  fetchImpl?: typeof fetch;
+  /** Test servers only. Production origins must use HTTPS. */
+  allowLoopbackForTests?: boolean;
+}
+export class AccelerateError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly retrySafe: false;
+  readonly paymentConfirmed: false;
+  /** Fixed local guidance only; it never authorizes or performs a payment action. */
+  readonly nextAction: AccelerateNextAction;
+  /** Opaque support correlation only, never an authorization capability. */
+  readonly supportReference?: string;
+  constructor(code?: string, status?: number, supportReference?: string);
+}
+export class AccelerateClient {
+  /** Reads process.env by default. Requires API key and merchant ID; server only. */
+  static fromEnv(env?: AccelerateEnvironment): AccelerateClient;
+  constructor(options: AccelerateClientOptions);
+  /** Authenticated API/configuration check only; does not qualify downstream payment readiness. */
+  readonly connection: { check(options?: RequestOptions): Promise<AccelerateConnection> };
+  readonly checkouts: {
+    /** Pure inspection of an exact failed creation and authoritative provider/lease retirement; never creates, cancels, verifies or fills. */
+    inspectCreation(input: CreationInspectionRequest, options?: RequestOptions): Promise<CreationInspection>;
+    inspectRetirement(id: CheckoutId, input: RetirementInspectionRequest, options?: RequestOptions): Promise<RetirementInspection>;
+    create(input: CreateCheckout, options?: RequestOptions): Promise<CreatedCheckout>;
+    get(id: CheckoutId, options?: RequestOptions): Promise<Checkout>;
+    /** Stops on readiness/terminal states even if not requested; inspect returned status before continuing. */
+    waitFor(id: CheckoutId, input: WaitForCheckout, options?: RequestOptions): Promise<Checkout>;
+    browser(id: CheckoutId, input: BrowserOperation, options?: RequestOptions): Promise<BrowserResult>;
+    applyDetails(id: CheckoutId, input: { checkout_url: string }, options?: RequestOptions): Promise<Checkout>;
+    verifyQuote(id: CheckoutId, input: QuoteVerificationRequest, options?: RequestOptions): Promise<VerifiedCheckoutQuote>;
+    requestApproval(id: CheckoutId, input: ApprovalRequest, options?: RequestOptions): Promise<Checkout>;
+    fill(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<Checkout>;
+    /** Removed behavior: Accelerate never clicks. Always rejects with customer_click_required and sends no request. */
+    submit(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<never>;
+    /** Backend only: prepare one short-lived customer-owned final click. Accelerate sends no physical input. */
+    armFinalClick(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<ArmedFinalClick>;
+    /** Backend only: observe the customer's click once. Dispatch claims are not sent; never retry. */
+    completeFinalClick(id: CheckoutId, input: { revision: number; arm_id: string }, options?: RequestOptions): Promise<Checkout>;
+    cancel(id: CheckoutId, options?: RequestOptions): Promise<Checkout>;
+    /** Records one merchant result after submit. Repeating the same input returns the same result; different input is refused. */
+    reconcile(id: CheckoutId, input: CheckoutReconciliationRequest, options?: RequestOptions): Promise<ReconciledCheckout>;
+  };
+}