@weaccelerateinc/agent-sdk 0.10.3 → 0.12.0

package/postgres-whatsapp-journal.d.ts

@@ -0,0 +1,8 @@
+import type { WhatsAppDeliveryJournal } from './whatsapp-messaging.js';
+export const whatsappJournalMigrationSql: string;
+/** Short Postgres transactions with row locks; transaction poolers are supported.
+ * initialize() executes DDL only when called by an operator. Reservations and
+ * matched evidence never expire; unmatched statuses expire after 24 hours and
+ * are capped at 64 per sender/recipient. Run pruneExpired periodically. Only
+ * hashed identifiers/status/timestamps are stored. Requires real PG qualification. */
+export function createPostgresWhatsAppDeliveryJournal(options: { pool: { query(sql: string, args?: unknown[]): Promise<{ rows: any[]; rowCount?: number | null }>; connect(): Promise<{ query(sql: string, args?: unknown[]): Promise<{ rows: any[]; rowCount?: number | null }>; release(destroy?: boolean): void }> } }): Readonly<WhatsAppDeliveryJournal & { initialize(): Promise<void>; pruneExpired(): Promise<number> }>;

package/postgres-whatsapp-journal.js

@@ -0,0 +1,95 @@
+import { AccelerateError } from './index.js';
+const HASH = /^[a-f0-9]{64}$/, MESSAGE = /^wa:[a-f0-9]{64}$/;
+const check = value => { if (!value) throw new AccelerateError('request_failed'); };
+const exact = (obj, names) => obj && typeof obj === 'object' && !Array.isArray(obj) && Object.keys(obj).length === names.length && names.every(k => Object.hasOwn(obj, k));
+const scope = s => exact(s, ['key', 'sender', 'recipient']) && HASH.test(s.key) && HASH.test(s.sender) && HASH.test(s.recipient);
+const timestamp = x => typeof x === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(x) && Number.isFinite(Date.parse(x)) && Date.parse(x) <= Date.now();
+/** Operator-only setup. Rows contain hashed IDs and timestamps only. */
+export const whatsappJournalMigrationSql = `
+CREATE TABLE IF NOT EXISTS accelerate_whatsapp_reservations (
+ sender text NOT NULL, delivery_key text NOT NULL, recipient text NOT NULL, message_id text,
+ PRIMARY KEY(sender, delivery_key), UNIQUE(sender, message_id));
+CREATE INDEX IF NOT EXISTS accelerate_whatsapp_recipient ON accelerate_whatsapp_reservations(sender, recipient, delivery_key);
+CREATE TABLE IF NOT EXISTS accelerate_whatsapp_statuses (
+ sender text NOT NULL, recipient text NOT NULL, message_id text NOT NULL, status text NOT NULL,
+ occurred_at timestamptz NOT NULL, expires_at timestamptz, conflicted boolean NOT NULL DEFAULT false,
+ PRIMARY KEY(sender,recipient,message_id,status));
+CREATE INDEX IF NOT EXISTS accelerate_whatsapp_expiry ON accelerate_whatsapp_statuses(expires_at) WHERE expires_at IS NOT NULL;`;
+/** Durable reservation rows never expire. Pre-bind event rows expire after 24h;
+ * at most 64 active unmatched events per sender+recipient are retained. */
+export function createPostgresWhatsAppDeliveryJournal({ pool } = {}) {
+  check(typeof pool?.query === 'function' && typeof pool?.connect === 'function');
+  const query = async (sql, args = []) => { try { return await pool.query(sql, args); } catch { throw new AccelerateError('request_failed'); } };
+  const transaction = async work => {
+    let client, began = false, broken = false;
+    try {
+      client = await pool.connect();
+      await client.query('BEGIN'); began = true;
+      const output = await work(client);
+      await client.query('COMMIT'); began = false;
+      return output;
+    } catch {
+      broken = true;
+      if (began) try { await client.query('ROLLBACK'); } catch {}
+      throw new AccelerateError('request_failed');
+    } finally { if (client) client.release(broken); }
+  };
+  return Object.freeze({
+    async initialize() { await query(whatsappJournalMigrationSql); },
+    async reserve(s) {
+      check(scope(s));
+      const inserted = await query('INSERT INTO accelerate_whatsapp_reservations(sender,delivery_key,recipient) VALUES($1,$2,$3) ON CONFLICT DO NOTHING RETURNING delivery_key', [s.sender,s.key,s.recipient]);
+      if (inserted.rows.length) return { created: true };
+      const found = await query('SELECT recipient FROM accelerate_whatsapp_reservations WHERE sender=$1 AND delivery_key=$2', [s.sender,s.key]);
+      check(found.rows.length === 1 && found.rows[0].recipient === s.recipient); return { created: false };
+    },
+    async bind(s) {
+      check(exact(s, ['key','sender','recipient','message_id']) && scope({ key:s.key,sender:s.sender,recipient:s.recipient }) && MESSAGE.test(s.message_id));
+      await transaction(async client => {
+        // Lock first, then issue a fresh-snapshot promotion statement. A status
+        // writer that finished while this waited is visible to the second query.
+        const found = await client.query('SELECT message_id FROM accelerate_whatsapp_reservations WHERE sender=$1 AND delivery_key=$2 AND recipient=$3 FOR UPDATE', [s.sender,s.key,s.recipient]);
+        check(found.rows.length === 1 && (found.rows[0].message_id === null || found.rows[0].message_id === s.message_id));
+        await client.query('UPDATE accelerate_whatsapp_reservations SET message_id=$4 WHERE sender=$1 AND delivery_key=$2 AND recipient=$3', [s.sender,s.key,s.recipient,s.message_id]);
+        await client.query(`UPDATE accelerate_whatsapp_statuses SET expires_at=NULL
+          WHERE sender=$1 AND recipient=$2 AND message_id=$3 AND expires_at > clock_timestamp()`, [s.sender,s.recipient,s.message_id]);
+      });
+    },
+    async recordStatus(s) {
+      check(exact(s,['sender','recipient','message_id','status','timestamp']) && HASH.test(s.sender) && HASH.test(s.recipient) && MESSAGE.test(s.message_id) && ['sent','failed'].includes(s.status) && timestamp(s.timestamp));
+      await transaction(async client => {
+        // Select the same unbound candidate for a recipient in deterministic
+        // order. Separate post-lock statements see all preceding commits.
+        const locked = await client.query(`SELECT message_id FROM accelerate_whatsapp_reservations
+          WHERE sender=$1 AND recipient=$2 AND (message_id=$3 OR message_id IS NULL)
+          ORDER BY (message_id=$3) DESC NULLS LAST,delivery_key LIMIT 1 FOR UPDATE`, [s.sender,s.recipient,s.message_id]);
+        if (!locked.rows.length) return;
+        const bound = locked.rows[0].message_id === s.message_id;
+        if (!bound) {
+          const counted = await client.query(`SELECT count(*)::int AS count,
+            COALESCE(bool_or(message_id=$3 AND status=$4),false) AS existing FROM accelerate_whatsapp_statuses
+            WHERE sender=$1 AND recipient=$2 AND expires_at > clock_timestamp()`, [s.sender,s.recipient,s.message_id,s.status]);
+          if (counted.rows[0].count >= 64 && !counted.rows[0].existing) return;
+        }
+        await client.query(`INSERT INTO accelerate_whatsapp_statuses(sender,recipient,message_id,status,occurred_at,expires_at)
+          VALUES($1,$2,$3,$4,$5::timestamptz,CASE WHEN $6::boolean THEN NULL ELSE clock_timestamp()+interval '24 hours' END)
+          ON CONFLICT(sender,recipient,message_id,status) DO UPDATE SET
+            conflicted=accelerate_whatsapp_statuses.conflicted OR accelerate_whatsapp_statuses.occurred_at<>EXCLUDED.occurred_at,
+            expires_at=CASE WHEN accelerate_whatsapp_statuses.expires_at IS NULL THEN NULL ELSE EXCLUDED.expires_at END`,
+          [s.sender,s.recipient,s.message_id,s.status,s.timestamp,bound]);
+      });
+    },
+    async get(s) {
+      check(scope(s));
+      const result = await query(`SELECT r.recipient,r.message_id,
+        EXISTS(SELECT 1 FROM accelerate_whatsapp_statuses e WHERE e.sender=r.sender AND e.recipient=r.recipient AND e.message_id=r.message_id AND (e.expires_at IS NULL OR e.expires_at>clock_timestamp()) AND (e.status='failed' OR e.conflicted)) AS failed,
+        (SELECT e.occurred_at FROM accelerate_whatsapp_statuses e WHERE e.sender=r.sender AND e.recipient=r.recipient AND e.message_id=r.message_id AND (e.expires_at IS NULL OR e.expires_at>clock_timestamp()) AND e.status='sent' AND NOT e.conflicted) AS sent_at
+        FROM accelerate_whatsapp_reservations r WHERE r.sender=$1 AND r.delivery_key=$2`, [s.sender,s.key]);
+      check(result.rows.length === 1 && result.rows[0].recipient === s.recipient);
+      const row = result.rows[0], sent = row.sent_at == null ? undefined : new Date(row.sent_at).toISOString();
+      return { sender:s.sender, recipient:s.recipient, ...(row.message_id ? { message_id:row.message_id } : {}), status:row.failed ? 'failed' : sent ? 'sent' : 'pending', ...(sent && !row.failed ? { sent_at:sent } : {}) };
+    },
+    /** Only unmatched expired events; never reservation or confirmed evidence. */
+    async pruneExpired() { const result = await query(`DELETE FROM accelerate_whatsapp_statuses e WHERE e.expires_at IS NOT NULL AND e.expires_at<=clock_timestamp() AND NOT EXISTS (SELECT 1 FROM accelerate_whatsapp_reservations r WHERE r.sender=e.sender AND r.recipient=e.recipient AND r.message_id=e.message_id)`); return result.rowCount ?? 0; },
+  });
+}

package/private-chat.js

@@ -1,4 +1,5 @@
 import { AccelerateClient, AccelerateError } from './index.js';
+import { validateCheckoutReconciliation } from './checkout-diagnostics.js';
 import { createHash } from 'node:crypto';
 
 const idPattern = /^mcs_[A-Za-z0-9_-]{43}$/;
@@ -7,7 +8,7 @@ const identityPattern = /^[A-Za-z0-9_.:-]{1,500}$/;
 // This limit applies only to the private review image, not JSON responses.
 const maximumReviewImageBytes = 8 * 1024 * 1024;
 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 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 !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
 const check = (value, code = 'invalid_input') => { if (!value) throw new AccelerateError(code); };
 function keys(value, allowed, required = allowed, code = 'invalid_input') {
@@ -37,14 +38,20 @@ function quote(value, revision = false, afterFill = false) {
 }
 function state(value, expectedId) {
   keys(value, ['checkout', 'stage', 'handled', 'duplicate', 'cards', 'addresses', 'identity_field', 'approval', 'selection_error', 'review'], ['checkout', 'stage', 'handled', 'duplicate', 'cards', 'addresses'], 'invalid_response');
-  keys(value.checkout, ['id', 'status', 'revision', 'expires_at', 'card', 'address', 'quote', 'submit_expires_at', 'purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'fill_after_verification', 'retry_safe', 'payment_confirmed'],
+  keys(value.checkout, ['id', 'status', 'revision', 'expires_at', 'card', 'address', 'quote', 'submit_expires_at', 'purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'fill_after_verification', 'reconciliation', 'final_click_actor', 'submit_actor', 'retry_safe', 'payment_confirmed'],
     ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed'], 'invalid_response');
   const checkout = value.checkout;
+  if (checkout.reconciliation !== undefined) {
+    try { validateCheckoutReconciliation(checkout.reconciliation, checkout.status); } catch { check(false, 'invalid_response'); }
+  }
   if (checkout.purpose !== undefined || checkout.submit_allowed !== undefined) check(
     ['purchase', 'sandbox_source_comparison', 'sandbox_fill_only'].includes(checkout.purpose) &&
     checkout.submit_allowed === (checkout.purpose === 'purchase'), 'invalid_response');
   check(checkout.id === expectedId && statuses.has(checkout.status) && checkout.retry_safe === false && checkout.payment_confirmed === false, 'invalid_response');
-  if (checkout.approval_policy !== undefined || checkout.purchase_approved !== undefined) check(checkout.approval_policy === 'after_fill' && typeof checkout.purchase_approved === 'boolean' && (!checkout.purchase_approved || checkout.status === 'ready_for_submit' && checkout.purpose === 'purchase'), 'invalid_response');
+  if (checkout.approval_policy !== undefined || checkout.purchase_approved !== undefined) check(checkout.approval_policy === 'after_fill' && typeof checkout.purchase_approved === 'boolean' && (!checkout.purchase_approved || ['ready_for_submit', 'final_click_armed'].includes(checkout.status) && checkout.purpose === 'purchase'), 'invalid_response');
+  if (checkout.final_click_actor !== undefined) check(checkout.final_click_actor === 'customer' && checkout.purpose === 'purchase', 'invalid_response');
+  if (checkout.submit_actor !== undefined) check(checkout.submit_actor === 'customer' && checkout.final_click_actor === 'customer' && ['submit_attempted', 'outcome_unknown'].includes(checkout.status), 'invalid_response');
+  if (checkout.status === 'submit_attempted' && checkout.purpose === 'purchase') check(checkout.submit_actor === 'customer', 'invalid_response');
   if (checkout.fill_after_verification !== undefined) check(checkout.fill_after_verification === true && checkout.approval_policy === 'after_fill' &&
     ['purchase', 'sandbox_fill_only'].includes(checkout.purpose), 'invalid_response');
   integer(checkout.revision, 0); date(checkout.expires_at); if (checkout.submit_expires_at !== undefined) date(checkout.submit_expires_at);

package/private-ingress.d.ts

@@ -23,6 +23,10 @@ export interface PrivateCheckoutIngress<Request = unknown> {
    * and transient parsed text. Ordinary traffic is admitted only through the
    * callback as a new minimal event, never by passing the original envelope. */
   handle(request: Request, rawBody: Uint8Array): Promise<Readonly<{ handled: boolean; retry?: true }>>;
+  /** Trusted server-only entrypoint for a provider-authenticated direct message.
+   * Never expose as a model tool. Caller must invoke before history/AI, and must
+   * retry the webhook when retry is true. Clears message.text on every outcome. */
+  handleAuthenticated(message: AuthenticatedPrivateMessage): Promise<Readonly<{ handled: boolean; retry?: true }>>;
   /** Safely recover pending lifecycle/prompt/progress deliveries only. Never
    * repeats fill or submit. Requires authenticated context from the host. */
   drain(context: ManagedCheckoutContext): Promise<number>;

package/private-ingress.js

@@ -5,6 +5,7 @@ import { deliverPrivateCheckoutReview } from './private-chat.js';
 
 const MESSAGE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
 const PENDING = new Set(['identity_required', 'otp_required', 'selection_required', 'cvv_required', 'approval_required', 'review_delivery_required']);
+const BEFORE_FILL = new Set(['identity_required', 'otp_required', 'selection_required', 'cvv_required']);
 const TERMINAL = new Set(['cancelled', 'expired', 'failed', 'outcome_unknown', 'submit_attempted']);
 const check = condition => { if (!condition) throw new AccelerateError('invalid_input'); };
 function digest(value) { return createHash('sha256').update(value).digest('hex'); }
@@ -75,15 +76,9 @@ export function createPrivateCheckoutIngress({ authenticate, host, privateChat,
       await saveAndDeliver(trusted, owned, response, `event-${digest(item.id)}`);
     });
   });
-  return Object.freeze({ drain,
-    async handle(request, rawBody) {
-      let verified, context, messageId;
+  async function handleAuthenticated(verified) {
+      let context, messageId;
       try {
-        check(rawBody instanceof Uint8Array);
-        verified = await authenticate(request, rawBody);
-        // Withhold the original envelope even for admitted ordinary messages.
-        // Only a new minimal event can cross the AI/history boundary below.
-        clearBody(rawBody);
         if (verified?.kind === 'ignore') return Object.freeze({ handled: true });
         check(verified?.authenticated === true && verified.direct === true);
         context = authenticatedCheckoutContext(verified.context); messageId = verified.message_id;
@@ -106,6 +101,13 @@ export function createPrivateCheckoutIngress({ authenticate, host, privateChat,
           if (isStatus) response = await privateChat.chat.get(owned.checkout_id, binding);
           else if (isCancel) response = await privateChat.chat.cancel(owned.checkout_id, binding);
           else {
+            // Private verification can fill in the same service call. Recheck
+            // after the wait while the original reply ID is durably pending.
+            // Same-ID recovery must pass this fresh check again; status and
+            // cancel remain available without inspecting the payment page.
+            if (browserConnector && (BEFORE_FILL.has(owned.previous_stage) ||
+              owned.previous_stage === 'approval_required' && owned.checkout?.approval_policy !== 'after_fill'))
+              await browserConnector.assertPaymentReady(context, { checkout_id: owned.checkout_id });
             const input = { ...binding, message_id: messageId, text: text || '[non-text reply]', ...metadata };
             try { response = await privateChat.chat.reply(owned.checkout_id, input); } finally { input.text = ''; }
           }
@@ -126,7 +128,18 @@ export function createPrivateCheckoutIngress({ authenticate, host, privateChat,
           }); } catch {}
         }
         return Object.freeze({ handled: true, retry: true });
-      } finally { clearBody(rawBody); clearReply(verified); }
+      } finally { clearReply(verified); }
+  }
+  return Object.freeze({ drain, handleAuthenticated,
+    async handle(request, rawBody) {
+      let verified;
+      try {
+        check(rawBody instanceof Uint8Array);
+        verified = await authenticate(request, rawBody);
+        clearBody(rawBody);
+        return await handleAuthenticated(verified);
+      } catch { return Object.freeze({ handled: true, retry: true }); }
+      finally { clearBody(rawBody); clearReply(verified); }
     },
   });
 }

package/starter/README.md

@@ -72,14 +72,8 @@ The current safe capture is qualified only for the configured sandbox merchant's
 5. Fill the verified revision once. The private handler delivers the actual safe form image and exact total: PAN stars plus last four, visible expiry and CVV stars.
 6. For the default fill-only checkout, require successful informational image delivery, then cancel the same checkout. Submit is absent and forbidden. Do not inspect the populated browser.
 
-For an explicitly enabled purchase integration, the same private image asks for simple approve/decline and grants a full five-minute decision window from the actual provider receipt. `ready_for_submit` is insufficient: wait for `purchase_approved:true`, then use a separate explicit owner-authorized submit operation before the returned deadline. After qualification, purchase mode requires both of these backend settings:
+This managed-browser starter is fill-only. Accelerate never sends the final payment click, and its private Kernel browser cannot hand control to the customer without breaking custody, so `purpose:purchase` and the submit flag are rejected. For purchases use the existing-browser partner starter: the customer's own backend browser performs the single physical click.
 
-```dotenv
-ACCELERATE_STARTER_PURPOSE=purchase
-ACCELERATE_ENABLE_PURCHASE_SUBMIT=true
-```
-
-The model cannot enable these settings. `purpose:purchase` without the submit flag still exposes no submit tool.
 
 ## Explicit legacy compatibility
 

package/starter/package.json

@@ -12,7 +12,7 @@
     "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
-    "@weaccelerateinc/agent-sdk": "0.10.3",
+    "@weaccelerateinc/agent-sdk": "0.12.0",
     "@modelcontextprotocol/server": "2.3.1"
   },
   "devDependencies": {

package/starter/runtime.mjs

@@ -9,10 +9,15 @@ const requiredHooks = ['resolveContext', 'withOwnedCheckout', 'withCheckoutCreat
 export async function configureStarter(server, env = process.env) {
   const mode = env.ACCELERATE_STARTER_MODE ?? 'synthetic';
   const purpose = env.ACCELERATE_STARTER_PURPOSE ?? 'sandbox_fill_only';
-  const enableSubmit = env.ACCELERATE_ENABLE_PURCHASE_SUBMIT === 'true';
   if (!['sandbox_fill_only', 'purchase'].includes(purpose) ||
     env.ACCELERATE_ENABLE_PURCHASE_SUBMIT !== undefined && !['true', 'false'].includes(env.ACCELERATE_ENABLE_PURCHASE_SUBMIT) ||
-    enableSubmit && purpose !== 'purchase') throw Error('Unsupported server purchase policy.');
+    env.ACCELERATE_ENABLE_PURCHASE_SUBMIT === 'true' && purpose !== 'purchase') throw Error('Unsupported server purchase policy.');
+  // Accelerate never sends the final payment click, and its private managed browser cannot hand control to the
+  // customer without breaking custody. This starter is therefore fill-only; purchases use the existing-browser partner starter.
+  if (purpose !== 'sandbox_fill_only' || env.ACCELERATE_ENABLE_PURCHASE_SUBMIT === 'true') {
+    throw Error('The managed-browser starter is fill-only. Use the existing-browser partner starter for purchases.');
+  }
+  const enableSubmit = false;
   let host, privateChat;
   const matches = (state, event) => state.checkout.id === event.checkout.id && state.checkout.revision === event.checkout.revision &&
     state.checkout.purpose === purpose && state.checkout.approval_policy === 'after_fill' &&

package/starter/synthetic.mjs

@@ -13,7 +13,7 @@ const png = () => Buffer.from([137, 80, 78, 71, 13, 10, 26, 10, 1, 2, 3]);
 /** In-process fixtures only: no network, source, browser, raw OTP or security code.
  * Private verification is simulated; safe image delivery uses the real SDK. */
 export function createSyntheticHost({ purpose = 'sandbox_fill_only', deliverReview } = {}) {
-  if (!['sandbox_fill_only', 'purchase'].includes(purpose)) invalid();
+  if (purpose !== 'sandbox_fill_only') invalid();
   const records = new Map(), owners = new Map(), events = new Set(), messages = new Map();
   const calls = { create: 0, browser: 0, payment_requested: 0, approval_requested: 0,
     private_verification: 0, fill: 0, review: 0, review_sent: 0, review_acknowledged: 0,

package/starter/tests/starter.test.mjs

@@ -74,41 +74,6 @@ test('review delivery failure retains the same event and retries image delivery
   assert.equal(host.counters().submit, 0);
 });
 
-test('purchase profile waits the full five-minute receipt-bound window and requires a distinct final submit', async t => {
-  const originalNow = Date.now; let now = originalNow(); Date.now = () => now;
-  t.after(() => { Date.now = originalNow; });
-  const { host, checkout, dispatch, binding, reachFill } = await prepared('purchase');
-  const filled = await reachFill();
-  await assert.rejects(host.privateChat.chat.reply(checkout.id, { ...binding, message_id: 'too-early', text: 'approve', sent_at: new Date(now).toISOString() }));
-  await assert.rejects(host.client.checkouts.submit(checkout.id, { revision: filled.revision }), { code: 'submit_unavailable' });
-  now += 45000; await dispatch('review_ready', filled);
-  const reviewed = await host.privateChat.chat.get(checkout.id, binding);
-  assert.equal(reviewed.stage, 'approval_required'); assert.equal(Date.parse(reviewed.review.expires_at), now + 300000);
-  now += 299999;
-  const approved = await host.privateChat.chat.reply(checkout.id, { ...binding, message_id: 'private-decision', text: 'approve', sent_at: new Date(now).toISOString() });
-  assert.equal(approved.stage, 'approved_for_submit'); assert.equal(approved.checkout.purchase_approved, true);
-  assert.equal(host.counters().submit, 1); // Only the deliberately denied early request.
-  assert.equal((await host.client.checkouts.get(checkout.id)).status, 'ready_for_submit');
-  const submitted = await host.client.checkouts.submit(checkout.id, { revision: filled.revision });
-  assert.equal(submitted.status, 'submit_attempted'); assert.equal(submitted.payment_confirmed, false);
-  await assert.rejects(host.client.checkouts.submit(checkout.id, { revision: filled.revision }), { code: 'submit_unavailable' });
-});
-
-test('purchase decision at five minutes is expired, and a private decline cancels without submission', async t => {
-  const originalNow = Date.now; let now = originalNow(); Date.now = () => now;
-  t.after(() => { Date.now = originalNow; });
-  const expired = await prepared('purchase'), filled = await expired.reachFill();
-  await expired.dispatch('review_ready', filled); now += 300000;
-  await assert.rejects(expired.host.privateChat.chat.reply(expired.checkout.id, { ...expired.binding,
-    message_id: 'late-decision', text: 'approve', sent_at: new Date(now).toISOString() }));
-  assert.equal(expired.host.counters().purchase_decision, 0); assert.equal(expired.host.counters().submit, 0);
-  const declined = await prepared('purchase'), next = await declined.reachFill();
-  await declined.dispatch('review_ready', next); now++;
-  const closed = await declined.host.privateChat.chat.reply(declined.checkout.id, { ...declined.binding,
-    message_id: 'private-decline', text: 'decline', sent_at: new Date(now).toISOString() });
-  assert.equal(closed.checkout.status, 'cancelled'); assert.equal(declined.host.counters().submit, 0);
-});
-
 test('starter registers the supported managed review profile and never accepts model purchase policy', async () => {
   const tools = new Map();
   const configured = await configureStarter({ registerTool(name, config, callback) { tools.set(name, { config, callback }); } }, {});
@@ -118,10 +83,13 @@ test('starter registers the supported managed review profile and never accepts m
   assert.equal(created.ok, true); assert.equal(created.checkout.approval_policy, 'after_fill');
   const rejected = await call('accelerate_checkout_start', { start_url: syntheticCheckoutUrl, purpose: 'purchase' });
   assert.equal(rejected.ok, false); assert.equal(rejected.error.code, 'invalid_input');
-  const purchaseTools = new Map();
-  await configureStarter({ registerTool(name, _config, callback) { purchaseTools.set(name, callback); } },
-    { ACCELERATE_STARTER_PURPOSE: 'purchase', ACCELERATE_ENABLE_PURCHASE_SUBMIT: 'true' });
-  assert.equal(purchaseTools.has('accelerate_checkout_submit'), true);
+  // Kernel custody is fill-only: Accelerate never clicks and cannot hand its private browser to the customer.
+  for (const env of [{ ACCELERATE_STARTER_PURPOSE: 'purchase', ACCELERATE_ENABLE_PURCHASE_SUBMIT: 'true' }, { ACCELERATE_STARTER_PURPOSE: 'purchase' },
+    { ACCELERATE_STARTER_PURPOSE: 'purchase', ACCELERATE_ENABLE_PURCHASE_SUBMIT: 'false' }]) {
+    await assert.rejects(configureStarter({ registerTool() { assert.fail('Kernel purchase exposed tools.'); } }, env), /fill-only/);
+    await assert.rejects(configureStarter({ registerTool() { assert.fail('Kernel purchase exposed tools.'); } }, { ...env, ACCELERATE_STARTER_MODE: 'live' }), /fill-only/);
+  }
+  assert.throws(() => createSyntheticHost({ purpose: 'purchase' }));
   for (const env of [{ ACCELERATE_STARTER_PURPOSE: 'unknown' }, { ACCELERATE_ENABLE_PURCHASE_SUBMIT: 'true' },
     { ACCELERATE_ENABLE_PURCHASE_SUBMIT: '1' }]) await assert.rejects(configureStarter({ registerTool() { assert.fail('Invalid policy exposed tools.'); } }, env));
 });

package/whatsapp-journal.d.ts

@@ -0,0 +1,11 @@
+import type { WhatsAppDeliveryJournal } from './whatsapp-messaging.js';
+/** Persistence MUST use a dedicated namespace and an exclusive sender owner
+ * lock across processes. commit must be durable before it resolves and survive
+ * later remote failures. The included Postgres persistence can be used with a
+ * separate namespace and a session-affine connection. Records contain only
+ * hashes, statuses and timestamps. Capacity limits fail closed: 1000 permanent
+ * reservations and 3000 status records per sender. Unmatched events are limited to 64 per recipient and 1000 total, and ignored when full. No automatic deletion occurs;
+ * operators must plan safe archival/reconciliation before those limits. */
+export function createWhatsAppDeliveryJournal(options: { persistence: {
+  withLock<T>(owner: string, work: (access: { load(): Promise<unknown>; commit(record: unknown): Promise<void> }) => Promise<T>): Promise<T>;
+} }): Readonly<WhatsAppDeliveryJournal>;

package/whatsapp-journal.js

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto';
+import { AccelerateError } from './index.js';
+
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const HASH = /^[a-f0-9]{64}$/;
+const MESSAGE = /^wa:[a-f0-9]{64}$/;
+const time = value => typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value) && Number.isFinite(Date.parse(value)) && Date.parse(value) <= Date.now();
+const check = value => { if (!value) throw new AccelerateError('request_failed'); };
+const exact = (value, keys) => value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === keys.length && keys.every(k => Object.hasOwn(value, k));
+const scopeOK = s => exact(s, ['key', 'sender', 'recipient']) && HASH.test(s.key) && HASH.test(s.sender) && HASH.test(s.recipient);
+const statusOK = s => exact(s, ['sender', 'recipient', 'message_id', 'status', 'timestamp']) && HASH.test(s.sender) && HASH.test(s.recipient) && MESSAGE.test(s.message_id) && ['sent', 'failed'].includes(s.status) && time(s.timestamp);
+function validate(record, sender) {
+  check(exact(record, ['version', 'sender', 'reservations', 'statuses']) && record.version === 1 && record.sender === sender && Array.isArray(record.reservations) && record.reservations.length <= 1000 && Array.isArray(record.statuses) && record.statuses.length <= 3000);
+  const reservations = new Set(), events = new Set();
+  for (const item of record.reservations) {
+    check((exact(item, ['key', 'recipient']) || exact(item, ['key', 'recipient', 'message_id'])) && HASH.test(item.key) && HASH.test(item.recipient) && (item.message_id === undefined || MESSAGE.test(item.message_id)) && !reservations.has(item.key)); reservations.add(item.key);
+  }
+  for (const item of record.statuses) {
+    check((exact(item, ['recipient', 'message_id', 'status', 'timestamp']) ||
+      exact(item, ['recipient', 'message_id', 'status', 'timestamp', 'conflicted']) && item.conflicted === true) &&
+      statusOK({ sender, recipient: item.recipient, message_id: item.message_id, status: item.status, timestamp: item.timestamp }));
+    const k = `${item.recipient}:${item.message_id}:${item.status}`; check(!events.has(k)); events.add(k);
+  }
+}
+/** Use a dedicated encrypted persistence namespace. Each sender has one SHA-256
+ * owner lock, shared by reservations and out-of-order provider status events. */
+export function createWhatsAppDeliveryJournal({ persistence } = {}) {
+  check(typeof persistence?.withLock === 'function');
+  async function locked(sender, work) {
+    check(HASH.test(sender)); let calls = 0, complete = false, expected;
+    try {
+      const result = await persistence.withLock(`accelerate-partner-host:${digest(['whatsapp-journal-v1', sender])}`, async access => {
+        check(++calls === 1 && typeof access?.load === 'function' && typeof access?.commit === 'function');
+        const record = await access.load() ?? { version: 1, sender, reservations: [], statuses: [] };
+        validate(record, sender);
+        const commit = async () => { validate(record, sender); await access.commit(structuredClone(record)); };
+        expected = await work(record, commit); complete = true; return expected;
+      });
+      check(calls === 1 && complete && result === expected); return result;
+    } catch { throw new AccelerateError('request_failed'); }
+  }
+  const find = (record, s) => { const item = record.reservations.find(row => row.key === s.key); if (item) check(item.recipient === s.recipient); return item; };
+  return Object.freeze({
+    async reserve(s) { check(scopeOK(s)); return locked(s.sender, async (record, commit) => { if (find(record, s)) return { created: false }; check(record.reservations.length < 1000); record.reservations.push({ key: s.key, recipient: s.recipient }); await commit(); return { created: true }; }); },
+    async bind(s) {
+      check(exact(s, ['key', 'sender', 'recipient', 'message_id']) && scopeOK({ key: s.key, sender: s.sender, recipient: s.recipient }) && MESSAGE.test(s.message_id));
+      return locked(s.sender, async (record, commit) => { const item = find(record, s); check(item && (!item.message_id || item.message_id === s.message_id));
+        // One provider message cannot represent multiple reservations.
+        check(!record.reservations.some(other => other !== item && other.message_id === s.message_id));
+        if (!item.message_id) { item.message_id = s.message_id; await commit(); } });
+    },
+    async recordStatus(s) { check(statusOK(s)); return locked(s.sender, async (record, commit) => {
+      // Retain an unknown ID only while a reservation for this recipient has
+      // not yet been bound. Ignore unrelated business traffic.
+      const matched = record.reservations.some(x => x.recipient === s.recipient && x.message_id === s.message_id);
+      const pending = record.reservations.some(x => x.recipient === s.recipient && !x.message_id);
+      if (!matched && !pending) return;
+      const previous = record.statuses.find(x => x.recipient === s.recipient && x.message_id === s.message_id && x.status === s.status);
+      if (previous) {
+        if (previous.timestamp !== s.timestamp) {
+          if (!previous.conflicted) { previous.conflicted = true; await commit(); }
+          check(false);
+        }
+        return;
+      }
+      // Unmatched provider traffic cannot exhaust the bounded reference journal.
+      const unmatched = record.statuses.filter(x => x.recipient === s.recipient && !record.reservations.some(r => r.recipient === x.recipient && r.message_id === x.message_id));
+      const allUnmatched = record.statuses.filter(x => !record.reservations.some(r => r.recipient === x.recipient && r.message_id === x.message_id)).length;
+      if (!matched && (unmatched.length >= 64 || allUnmatched >= 1000 || record.statuses.length >= 3000)) return;
+      check(record.statuses.length < 3000); record.statuses.push({ recipient: s.recipient, message_id: s.message_id, status: s.status, timestamp: s.timestamp }); await commit();
+    }); },
+    async get(s) { check(scopeOK(s)); return locked(s.sender, async record => {
+      const item = find(record, s); check(item); const events = record.statuses.filter(x => x.recipient === s.recipient && x.message_id === item.message_id);
+      const sent = events.find(x => x.status === 'sent'), failed = events.find(x => x.status === 'failed' || x.conflicted === true);
+      return { sender: s.sender, recipient: s.recipient, ...(item.message_id ? { message_id: item.message_id } : {}), status: failed ? 'failed' : sent ? 'sent' : 'pending', ...(sent && !failed ? { sent_at: sent.timestamp } : {}) };
+    }); },
+  });
+}

package/whatsapp-messaging.d.ts

@@ -0,0 +1,64 @@
+import type { ManagedCheckoutContext } from './managed-mcp.js';
+import type { AuthenticatedPrivateMessage, PrivateMessagingAdapter } from './private-ingress.js';
+
+type Scope = { key: string; sender: string; recipient: string };
+type Destination = { phone_number_id: string; recipient_id: string; verified_wa_id?: string };
+type Identity = { phone_number: string; wa_id: string; phone_number_id: string };
+type Resolution = ManagedCheckoutContext | { context: ManagedCheckoutContext; verified_wa_id: string } | null;
+type Status = { sender: string; recipient: string; message_id: string; status: 'sent' | 'failed'; timestamp: string };
+/** Implement with a durable, atomic, linearizable shared database. reserve must
+ * create exactly once and check the same key's sender/recipient on every call.
+ * bind must bind exactly one hashed provider ID to that reservation and reject any
+ * conflict. recordStatus retains pre-bind events only for a matching recipient
+ * with an unbound reservation and ignores unrelated statuses. Match sender,
+ * recipient and hashed message ID when binding, tolerate duplicate/out-of-order events,
+ * and fail closed on conflicting sent/failed evidence. get returns pending until
+ * an exact matched sent event; its sent_at must be the provider event timestamp.
+ * Delivered/read timestamps never substitute for sent; missing proof stays pending.
+ * Provider IDs are deterministically hashed before journaling and SDK delivery.
+ * Never store raw envelopes, image bytes, message text, OTP or CVV. Apply bounded
+ * retention to unbound status events. Unknown reservations must not be cleared
+ * or retried without independently reconciling the provider outcome. */
+export interface WhatsAppDeliveryJournal {
+  reserve(scope: Scope): Promise<{ created: boolean }>;
+  bind(input: Scope & { message_id: string }): Promise<void>;
+  recordStatus(input: Status): Promise<void>;
+  get(scope: Scope): Promise<{ sender: string; recipient: string; message_id?: string; status: 'pending' | 'sent' | 'failed'; sent_at?: string }>;
+}
+/** Provider wrapper must make one native request per call and disable retries.
+ * sendImage sends the image and caption together. Never expose provider URLs. */
+export interface WhatsAppMessagingClient {
+  uploadImage(input: { bytes: Buffer; contentType: 'image/png'; signal: AbortSignal }): Promise<{ media_id: string }>;
+  sendImage(input: { phone_number_id: string; recipient_id: string; media_id: string; caption: string; signal: AbortSignal }): Promise<{ message_id: string }>;
+  sendText(input: { phone_number_id: string; recipient_id: string; text: string; signal: AbortSignal }): Promise<{ message_id: string }>;
+}
+export function createWhatsAppMessagingAdapter(options: {
+  client: WhatsAppMessagingClient; journal: WhatsAppDeliveryJournal; sendingPhoneId: string;
+  /** Resolve from authenticated backend state only. If the provider wa_id differs
+   * from the verified phone, verified_wa_id must equal the mapped recipient_id. */
+  resolveDestination(context: Readonly<ManagedCheckoutContext>): Promise<Destination> | Destination;
+}): Readonly<PrivateMessagingAdapter & {
+  /** Read-only exact-context/key reconciliation. Never sends or uploads. */
+  findReviewReceipt(context: Readonly<ManagedCheckoutContext>, idempotencyKey: string, options?: { signal?: AbortSignal }): Promise<{ message_id: string; sent_at: string }>;
+}>;
+export function createWhatsAppWebhookAuthenticator<Request = unknown>(options: {
+  /** Verify provider signature over exact raw bytes. No callback may log those bytes. */
+  verifyWebhook(request: Request, rawBody: Uint8Array): Promise<boolean> | boolean;
+  /** Return null for unknown senders; throw only on transient resolution errors. */
+  resolveIdentity(identity: Identity): Promise<Resolution> | Resolution;
+  sendingPhoneId: string; journal: WhatsAppDeliveryJournal;
+}): (request: Request, rawBody: Uint8Array) => Promise<AuthenticatedPrivateMessage | { kind: 'ignore' }>;
+/** Verify the exact original raw bytes once, then process statuses and inbound
+ * text in provider array order. Meta's separate arrays do not encode relative
+ * ordering: statuses are recorded before messages in each change. onMessage
+ * runs transiently before any history or AI processing; it MUST durably
+ * deduplicate message_id. A thrown error or retry:true is an item failure. A failure rejects the whole
+ * webhook; provider retries can repeat earlier callbacks. No raw webhook is
+ * reserialized or retained, and rawBody is zeroed even on failure. */
+export function createWhatsAppWebhookBatchHandler<Request = unknown>(options: {
+  verifyWebhook(request: Request, rawBody: Uint8Array): Promise<boolean> | boolean;
+  /** Return null for unknown senders; throw only on transient resolution errors. */
+  resolveIdentity(identity: Identity): Promise<Resolution> | Resolution;
+  sendingPhoneId: string; journal: WhatsAppDeliveryJournal;
+  onMessage(message: AuthenticatedPrivateMessage): Promise<void | { retry?: boolean }> | void | { retry?: boolean };
+}): (request: Request, rawBody: Uint8Array) => Promise<{ handled: true }>;