@homie-rocks/studio 0.37.1 → 0.38.0

package/worker/payment-capabilities.mjs

@@ -0,0 +1,70 @@
+/** Stripe-backed, non-settling permission checks. Never uses a card or a wallet. */
+import { stripeCall, modeOf } from './stripe.mjs';
+import { digest } from "./purchase-crypto.mjs";
+
+export const MACHINE_API_VERSION = '2026-07-29.preview';
+export async function probeMachinePayments(env, { fetcher = fetch } = {}) {
+  const mode = modeOf(env.STRIPE_KEY);
+  const result = { mode, key: await digest(env.STRIPE_KEY), checkedAt: Date.now(), machine: { card: false, tempo: false, base: false }, reasons: {}, configuration: {} };
+  const call = (method, path, params) => stripeCall(env, method, path, params, { fetcher, version: MACHINE_API_VERSION });
+  try {
+    const profile = await call('GET', '/v2/network/business_profiles/me');
+    if (!/^profile_/.test(profile?.id ?? '')) throw new Error('Create a Stripe business profile in the Dashboard');
+    result.configuration.profile = profile.id;
+    result.machine.card = true;
+  } catch (e) {
+    result.reasons.card = `${e.message}. Enable PaymentIntents Write and access to Business Profiles on this restricted key, create the account profile, then reconnect shop. SPT eligibility is controlled by Stripe.`;
+  }
+  try {
+    const configs = await call('GET', '/v1/payment_method_configurations', { limit: 100 });
+    if (!configs.data?.some((c) => c.active && c.crypto?.available && c.crypto?.display_preference?.value === 'on')) throw new Error('Stablecoins and Crypto is not active for this Stripe account. Request it in Stripe payment method settings; Stripe reviews eligibility and country support');
+    for (const network of ['base']) {
+      try {
+        const listed = await call('GET', '/v1/crypto/deposit_addresses', { network });
+        const address = listed.data?.find((a) => /^0x[0-9a-fA-F]{40}$/.test(a.address));
+        if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address.address)) throw new Error('Provision a Base deposit address in Stripe, then reconnect; this read-only check creates nothing');
+        result.configuration[network] = address.address;
+        result.machine[network] = true;
+      } catch (e) { result.reasons[network] = `${e.message}. Enable Crypto Deposit Addresses access on this key and reconnect.`; }
+    }
+  } catch (e) { result.reasons.tempo = result.reasons.base = `${e.message}. Reconnect after Stripe enables this payment method.`; }
+  result.reasons.tempo = 'Tempo is disabled until an official client completes route tests in both modes.';
+  return result;
+}
+export async function machineCapabilities(env) {
+  try {
+    const cached = env.DB && await env.DB.prepare("SELECT value FROM meta WHERE key = 'purchase-capabilities'").first();
+    const configured = JSON.parse(env.PURCHASE_PAYMENT_CAPABILITIES ?? '{}');
+    const saved = cached ? JSON.parse(cached.value) : null;
+    const record = saved?.key === configured.key && saved.checkedAt >= configured.checkedAt ? saved : configured;
+    const configuration = JSON.parse(env.PURCHASE_MACHINE_PAYMENTS ?? '{}')[modeOf(env.STRIPE_KEY)];
+    if (record.mode !== modeOf(env.STRIPE_KEY) || record.key !== await digest(env.STRIPE_KEY) || !configuration?.profile)
+      return { ready: false, machine: {}, reasons: { setup: 'Reconnect shop to verify machine payment permissions and obtain the Stripe profile and deposit addresses.' } };
+    const machine = { ...record.machine, tempo: false };
+    if (configuration.manualRefunds !== true || !configuration.base || (record.mode === 'live' && (!env.CDP_API_KEY_ID || !env.CDP_API_KEY_SECRET))) machine.base = false;
+    return { ...record, machine, ready: Object.values(machine).some(Boolean) };
+  } catch { return { ready: false, machine: {}, reasons: { setup: 'Reconnect shop to repair its payment configuration.' } }; }
+}
+
+/** Scheduled checks share connect's probe. Office and public discovery never probe Stripe. */
+export async function refreshMachineCapabilities(env) {
+  const prior = await machineCapabilities(env);
+  if (prior.nextCheckAt > Date.now()) return prior;
+  const record = await probeMachinePayments(env);
+  const success = Object.values(record.machine).some(Boolean);
+  record.failures = success ? 0 : (prior.failures ?? 0) + 1;
+  record.nextCheckAt = Date.now() + (success ? 6 * 3600000 : Math.min(6 * 3600000, 300000 * 2 ** Math.min(record.failures - 1, 6)));
+  await env.DB.prepare("INSERT OR REPLACE INTO meta (key,value) VALUES (?1,?2)")
+    .bind('purchase-capabilities', JSON.stringify(record)).run();
+  return record;
+}
+export async function notePaymentRefusal(env, method, error) {
+  if ((error.statusCode ?? error.status) === 402 || error.type === 'card_error' || error.raw?.type === 'card_error') return;
+  const record = await machineCapabilities(env);
+  record.machine[method] = false;
+  record.reasons = { ...record.reasons, [method]: String(error.message).slice(0,500) };
+  record.checkedAt = Date.now();
+  record.nextCheckAt = 0;
+  await env.DB.prepare("INSERT OR REPLACE INTO meta (key,value) VALUES (?1,?2)")
+    .bind('purchase-capabilities', JSON.stringify(record)).run();
+}

package/worker/payment-dry-exchange.mjs

@@ -0,0 +1,30 @@
+/** Owner-only dry exchange through the real resource endpoint, without a wallet credential. */
+export async function dryPaymentExchange(env, origin, catalogue = {}) {
+  const { listOffers } = await import('./resource-kinds.mjs');
+  const resource = (await listOffers(env,origin)).find((r)=>r.offer.billing === 'one-time' && r.offer.currency === 'usd' && !r.offer.automaticTax && r.offer.taxBehavior !== 'exclusive');
+  const release = resource;
+  if (!release) return { verified: false, reason: 'No listed offer is eligible for a machine-payment challenge. Hosted Checkout remains available.' };
+  const { machineResource } = await import('./purchase-machine.mjs');
+  const { digest } = await import('./purchase-crypto.mjs');
+  const { byClaim } = await import('./purchase-store.mjs');
+  const claim = await digest(crypto.randomUUID());
+  const claimHash = await digest(claim);
+  try {
+    const url = new URL(`/api/purchases/resource/${resource.kind}/${resource.id}/${release.version}`, origin);
+    const request = new Request(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: resource.kind, resource: resource.id, version: release.version, buyer: await digest(crypto.randomUUID()), claim, offerVersion: release.offerVersion, ...(release.offer.scope === 'game' ? { game: 'readiness-check' } : {}) }) });
+    const challenge = await machineResource(request, env, url, catalogue, { dryRun: true });
+    if (challenge.status !== 402) return { verified: false, reason: (await challenge.json()).detail ?? `Dry exchange answered ${challenge.status}` };
+    const { Challenge } = await import('mppx');
+    const parsed = Challenge.fromResponse(challenge);
+    if (parsed.realm !== url.hostname || !parsed.expires) throw new Error('Challenge failed realm or expiry verification');
+    return { verified: true, checkedAt: Date.now(), resource: resource.id, version: release.version, challenge: { method: parsed.method, intent: parsed.intent, realm: parsed.realm, expires: parsed.expires }, scope: 'A real unpaid request passed offer, storage, signing-key and Stripe permission checks and returned a parseable payment challenge. No wallet credential was submitted. Token eligibility, live settlement and refunds are not verified by this dry exchange.' };
+  } catch (error) { return { verified: false, reason: error.message }; }
+  finally {
+    const order = await byClaim(env, claimHash);
+    if (order) await env.DB.batch([
+      env.DB.prepare("DELETE FROM purchase_orders WHERE id = ?1 AND status = 'started'").bind(order.id),
+      env.DB.prepare("DELETE FROM resource_snapshots WHERE hash = ?1 AND NOT EXISTS (SELECT 1 FROM purchase_orders WHERE manifest_hash = ?1)").bind(order.manifest_hash),
+      env.DB.prepare("DELETE FROM purchase_offers WHERE version = ?1 AND NOT EXISTS (SELECT 1 FROM purchase_orders WHERE offer_version = ?1)").bind(order.offer_version),
+    ]);
+  }
+}

package/worker/payment-manual-refund.mjs

@@ -0,0 +1,40 @@
+/** Exact chain evidence for the studio's explicitly accepted manual refund duty. */
+export async function manualRefundDetails(env, order) {
+  if (order.payment || !order.paid_at) return null;
+  const rows = (await env.DB.prepare("SELECT network,reference,payload FROM purchase_settlements WHERE order_id = ?1 AND state IN ('settled','complete')").bind(order.id).all()).results ?? [];
+  const transfers = rows.map((row) => {
+    const data = JSON.parse(row.payload);
+    const auth = data.payload?.payload?.authorization;
+    return { network: row.network, transaction: row.reference ?? data.reference, payer: auth?.from ?? null,
+      amount: auth?.value ?? null, token: data.requirements?.asset ?? null, recipient: auth?.to ?? null };
+  });
+  return { status: 'manual_refund_required', order: order.id, delivered: Boolean(order.fulfilled_at), transfers,
+    message: 'Stripe has not recorded this chain payment. The selling studio owes any requested refund directly to the original payer. Use the exact network, token, amount and transaction below; record the refund transaction in the order note. Do not mark refunded until the transfer is confirmed.' };
+}
+
+/** Owner-supplied refund transaction must actually return the exact token amount to the payer. */
+export async function confirmManualRefund(env, order, transaction) {
+  if (!/^0x[0-9a-fA-F]{64}$/.test(transaction ?? '')) return { ok: false, error: 'refund-transaction', message: 'Supply the confirmed Base refund transaction hash.' };
+  const manual = await manualRefundDetails(env, order);
+  if (!manual?.transfers.length || manual.transfers.some((t) => t.network !== 'base')) return { ok:false, error:'refund-evidence', message:'Verified Base transfers are required.' };
+  const original = manual.transfers[0];
+  if (manual.transfers.some((t) => ['payer','token','recipient','amount'].some((key) => t[key]?.toLowerCase() !== original[key]?.toLowerCase()))) return { ok: false, error: 'refund-evidence', message: 'These transfers need separate refund evidence.' };
+  if (transaction.toLowerCase() === original.transaction?.toLowerCase()) return {ok:false,error:'refund-evidence',message:'The original payment is not a refund.'};
+  const { rpcFor } = await import('./settlement-journal.mjs');
+  const rpc = rpcFor(env,'base',order.mode);
+  const receipt = await rpc('eth_getTransactionReceipt',[transaction]);
+  const paidReceipt = await rpc('eth_getTransactionReceipt',[original.transaction]);
+  if (!receipt?.blockNumber || !paidReceipt?.blockNumber || BigInt(receipt.blockNumber) <= BigInt(paidReceipt.blockNumber)) return { ok: false, error: 'refund-evidence', message: 'The refund must be mined after the original payment.' };
+  const block = await rpc('eth_getBlockByNumber', [receipt.blockNumber, false]);
+  if (!block?.timestamp || Number(BigInt(block.timestamp)) * 1000 <= order.created_at) return { ok: false, error: 'refund-evidence', message: 'The refund must be sent after this order.' };
+  const { keccak256, toHex } = await import('viem');
+  const topic = keccak256(toHex('Transfer(address,address,uint256)'));
+  if (receipt?.status !== '0x1' || !receipt.logs?.some((log) => log.address.toLowerCase() === original.token.toLowerCase() && log.topics[0] === topic && log.topics[1]?.slice(-40).toLowerCase() === original.recipient.slice(2).toLowerCase() && log.topics[2]?.slice(-40).toLowerCase() === original.payer.slice(2).toLowerCase() && BigInt(log.data) === BigInt(original.amount)))
+    return {ok:false,error:'refund-evidence',message:'The chain receipt does not prove the exact refund to the original payer.'};
+  const { orderFact } = await import('./purchase-core.mjs');
+  await env.DB.batch([
+    env.DB.prepare('INSERT INTO purchase_manual_refunds (transaction_hash,order_id) VALUES (?1,?2)').bind(transaction.toLowerCase(),order.id),
+    orderFact(env,order.id,'refunded',{refund:transaction,refunded_at:Date.now(),note:JSON.stringify({sender:original.recipient,payer:original.payer,amount:original.amount,transaction})}),
+  ]);
+  return {ok:true,order:order.id,status:'succeeded',refund:transaction};
+}

package/worker/payment-policy.mjs

@@ -0,0 +1,40 @@
+/** One vocabulary for recovery, expiry, buyer locks and office status. */
+export const jobStates = Object.freeze({
+  submitted: { pending: true, terminal: false, blocks: true },
+  paid_recording: { pending: true, terminal: false, blocks: true },
+  recorded: { pending: true, terminal: false, blocks: true },
+  processing: { pending: true, terminal: false, blocks: true },
+  duplicate_refund: { pending: true, terminal: false, blocks: true },
+  failed: { pending: false, terminal: true, blocks: false },
+  complete: { pending: false, terminal: true, blocks: false },
+  refunded: { pending: false, terminal: true, blocks: false },
+  duplicate_refunded: { pending: false, terminal: true, blocks: false },
+  manual_review: { pending: true, terminal: false, blocks: true },
+});
+export function jobPolicy(state) {
+  if (!jobStates[state]) throw new Error(`Unknown payment job state: ${state}`);
+  return jobStates[state];
+}
+export function jobsSQL(property, prefix = '') {
+  const names = Object.entries(jobStates).filter(([state, policy]) => property === 'visible' ? policy.pending || ['failed','manual_review'].includes(state) : property === 'cleanup' ? state === 'failed' : policy[property]).map(([state]) => `'${state}'`);
+  return `${prefix}state IN (${names.join(',')})`;
+}
+export const pendingJobsSQL = jobsSQL('pending');
+export const blockingJobsSQL = jobsSQL('blocks');
+export const REPLAY_LIMIT_MS = 23 * 60 * 60 * 1000;
+export function definitiveRefusal(error) {
+  const status = error.statusCode ?? error.status;
+  if ([401,403,408,409,429].includes(status) || error.type === 'idempotency_error') return false;
+  if (error.idempotentReplayed && status >= 400 && status < 500) return true;
+  return status === 402 && (error.type === 'card_error' || error.raw?.type === 'card_error');
+}
+/** Ordered decision table. Storage faults can never authorize a refund. */
+export function recoveryAction({ state, fulfilled, provider, files, settled, deadline = false }) {
+  if (fulfilled || state === 'fulfilled') return 'final';
+  if (['refunded','disputed','lapsed','lost'].includes(state)) return 'preserve';
+  if (provider === 'paid' || settled || state === 'paid') return files === 'present' ? 'deliver' : 'storage_retry';
+  if (provider === 'refused' || provider === 'absent' && deadline) return 'fail';
+  if (provider === 'absent') return 'replay';
+  if (provider === 'processing') return 'wait';
+  return 'reconcile';
+}

package/worker/payment-recovery.mjs

@@ -0,0 +1,163 @@
+import { pendingJobsSQL, definitiveRefusal, REPLAY_LIMIT_MS, recoveryAction } from './payment-policy.mjs';
+import { orderFact, recordOrderState, releaseClaim } from './purchase-core.mjs';
+import { resumeSettlement } from './settlement-journal.mjs';
+/** Durable provider recordings outlive responses. A verified chain transfer is payment. */
+import { stripeCall, refundPayment, modeOf } from './stripe.mjs';
+import { byId, resourceAvailable } from './purchase-store.mjs';
+export async function saveRecording(env, order, params, options) {
+  const chain = params.payment_method_options?.crypto?.transaction_verification_options;
+  const id = chain ? `${order.id}:${chain.network}:${chain.transaction_hash}` : options.idempotencyKey;
+  await env.DB.prepare("INSERT OR IGNORE INTO purchase_jobs (id,order_id,mode,state,payload,updated_at) VALUES (?1,?2,?3,?4,?5,?6)")
+    .bind(id, order.id, order.mode, chain ? 'paid_recording' : 'submitted', JSON.stringify({ params, options: { ...options, idempotencyKey: chain ? chain.transaction_hash : options.idempotencyKey }, chain, startedAt: Date.now() }), Date.now()).run();
+  if (chain) {
+    // Only the protocol's verified settlement callback reaches here, never buyer input.
+    await orderFact(env, order.id, 'payment', {paid_at: Date.now()}).run();
+    await env.DB.prepare("UPDATE purchase_settlements SET state = 'complete', updated_at = ?2 WHERE order_id = ?1 AND reference = ?3").bind(order.id, Date.now(), chain.transaction_hash).run();
+  }
+  return id;
+}
+export async function recordProviderResult(env, order, id, pi) {
+  if (pi.amount !== order.amount || pi.currency !== order.currency || pi.livemode !== (order.mode === 'live')) throw new Error('Provider receipt does not match order');
+  await env.DB.prepare("UPDATE purchase_jobs SET payment = ?2, state = ?3, error = NULL, updated_at = ?4 WHERE id = ?1").bind(id, pi.id, pi.status === 'succeeded' ? 'recorded' : ['canceled','requires_payment_method'].includes(pi.status) ? 'failed' : 'processing', Date.now()).run();
+  if (pi.status !== 'succeeded') return;
+
+  await env.DB.batch([
+    orderFact(env, order.id, 'payment', {payment: pi.id, paid_at: Date.now()}),
+    env.DB.prepare("INSERT OR IGNORE INTO purchase_payments (payment,order_id) VALUES (?1,?2)").bind(pi.id, order.id),
+  ]);
+  const current = await byId(env, order.id);
+  if (current.payment !== pi.id) {
+    const refund = await refundPayment(env, pi.id);
+    await env.DB.prepare("UPDATE purchase_jobs SET state = ?2 WHERE id = ?1").bind(id, refund.status === 'succeeded' ? 'duplicate_refunded' : 'duplicate_refund').run();
+    return;
+  }
+}
+export async function recordingFailure(env, id, error) {
+  if (definitiveRefusal(error)) {
+    await env.DB.prepare("UPDATE purchase_jobs SET state = 'failed', error = ?2, attempts = attempts + 1, updated_at = ?3 WHERE id = ?1 AND state = 'submitted'").bind(id, String(error.message).slice(0, 500), Date.now()).run();
+    return;
+  }
+  // A failure of our call is not a fact about the original payment.
+  await env.DB.prepare("UPDATE purchase_jobs SET error = ?2, attempts = attempts + 1, updated_at = ?3 WHERE id = ?1")
+    .bind(id, String(error.message).slice(0, 500), Date.now()).run();
+}
+
+/** Read existing objects first. Listing avoids the search index's delayed negative answers. */
+export async function readProviderPayment(env, order, job, payment = null) {
+  const options = { version: '2026-07-29.preview' };
+  if (payment && !/^pi_[A-Za-z0-9]+$/.test(payment)) throw new Error('Supply an existing Stripe PaymentIntent id');
+  if (job.payment || payment) {
+    const pi = await stripeCall(env, 'GET', `/v1/payment_intents/${encodeURIComponent(job.payment ?? payment)}`, null, options);
+    if (pi.metadata?.order !== order.id) throw new Error('The existing PaymentIntent belongs to another order');
+    return pi;
+  }
+  let cursor;
+  for (let page = 0; page < 100; page++) {
+    const result = await stripeCall(env, 'GET', '/v1/payment_intents', { limit: 100, created: { gte: Math.floor(order.created_at / 1000) - 60 }, ...(cursor ? { starting_after: cursor } : {}) }, options);
+    if (!Array.isArray(result.data)) throw new Error('Stripe did not return an existing-payment list');
+    const found = result.data.find((pi) => pi.metadata?.order === order.id);
+    if (found) return found;
+    if (!result.has_more) return null;
+    cursor = result.data.at(-1)?.id;
+    if (!cursor) throw new Error('Stripe payment list has no continuation');
+  }
+  throw new Error(`Existing payment scan exceeded 100 pages for order ${order.id}; the owner must reconcile this order.`);
+}
+async function releaseUnpaid(env, order, job, pi = null) {
+  await env.DB.batch([
+    env.DB.prepare("UPDATE purchase_jobs SET state = 'failed', error = NULL, updated_at = ?2, payment = COALESCE(payment, ?3) WHERE id = ?1").bind(job.id, Date.now(), pi?.id ?? null),
+    orderFact(env, order.id, 'failed', {}),
+    releaseClaim(env, order.id),
+  ]);
+}
+export async function reconcileRecordings(env, orderId = null, dependencies = {}) {
+  await reconcileSettlements(env, orderId, dependencies);
+  const rows = (await env.DB.prepare(`SELECT * FROM purchase_jobs WHERE mode = ?1 AND ${pendingJobsSQL} AND (?2 IS NULL OR order_id = ?2) ORDER BY updated_at LIMIT 100`).bind(modeOf(env.STRIPE_KEY), orderId).all()).results ?? [];
+  for (const job of rows) {
+    try {
+      const order = await byId(env, job.order_id);
+      if (!order) continue;
+      const { params, options, startedAt } = JSON.parse(job.payload);
+      // An interruption always starts with a read, even inside the replay window.
+      let pi = await readProviderPayment(env, order, job, orderId ? dependencies.payment : null);
+      const deadline = Date.now() - (startedAt ?? order.created_at) >= REPLAY_LIMIT_MS;
+      const observation = { state: order.status, fulfilled: order.fulfilled_at, settled: job.state === 'paid_recording' || Boolean(order.paid_at) || Boolean(JSON.parse(job.payload).chain),
+        provider: pi ? pi.status === 'succeeded' ? 'paid' : ['canceled','requires_payment_method'].includes(pi.status) ? 'refused' : 'processing' : 'absent', deadline };
+      if (observation.settled && pi && pi.status !== 'succeeded') throw new Error(`Settled transfer needs Stripe recording: order ${order.id}; payment ${pi.id}`);
+      switch (recoveryAction(observation)) {
+        case 'fail':
+          if (pi?.status === 'requires_payment_method') {
+            pi = await stripeCall(env, 'POST', `/v1/payment_intents/${encodeURIComponent(pi.id)}/cancel`, {}, { idempotencyKey: `cancel-action-${pi.id}`, version: '2026-07-29.preview' });
+            if (pi.status !== 'canceled') throw new Error('The unpaid payment could not be canceled; the claim remains reserved');
+          }
+          await releaseUnpaid(env, order, job, pi); continue;
+        case 'replay': pi = await stripeCall(env, 'POST', '/v1/payment_intents', params, { ...options, version: '2026-07-29.preview' }); break;
+        default:
+          if (!pi) {
+            if (deadline) throw new Error(`Paid transfer still needs recording: order ${order.id}; key ${options.idempotencyKey}`);
+            pi = await stripeCall(env, 'POST', '/v1/payment_intents', params, { ...options, version: '2026-07-29.preview' });
+          }
+      }
+      if (['requires_action','requires_confirmation','requires_capture','requires_payment_method'].includes(pi.status) || orderId && dependencies.cancel === true && pi.status === 'processing') pi = await stripeCall(env, 'POST', `/v1/payment_intents/${encodeURIComponent(pi.id)}/cancel`, {}, { idempotencyKey: `cancel-action-${pi.id}`, version: '2026-07-29.preview' });
+      await recordProviderResult(env, order, job.id, pi);
+      if (['canceled','requires_payment_method'].includes(pi.status)) { await releaseUnpaid(env, order, job, pi); continue; }
+      if (pi.status !== 'succeeded') {
+        if (Date.now() - (startedAt ?? order.created_at) >= REPLAY_LIMIT_MS && !['canceled','requires_payment_method'].includes(pi.status))
+          await env.DB.prepare("UPDATE purchase_jobs SET state = 'manual_review', error = 'Provider payment remains unresolved after deadline' WHERE id = ?1").bind(job.id).run();
+        continue;
+      }
+      if ((await byId(env, order.id)).payment !== pi.id) continue;
+      const current = await byId(env, order.id);
+      const final = recoveryAction({ state: current.status, fulfilled: current.fulfilled_at, provider: 'paid', settled: false, files: 'missing' });
+      if (final === 'final' || final === 'preserve') {
+        await env.DB.prepare("UPDATE purchase_jobs SET state = 'complete', updated_at = ?2 WHERE id = ?1").bind(job.id, Date.now()).run();
+        continue;
+      }
+      const available = await resourceAvailable(env, order.resource_kind, JSON.parse(order.manifest));
+      const action = recoveryAction({ state: current.status, fulfilled: current.fulfilled_at, provider: 'paid', settled: false, files: available ? 'present' : 'missing' });
+      if (action === 'storage_retry') throw new Error('Paid files unavailable. Restore storage; payment is retained and delivery will retry.');
+      if (action === 'deliver') {
+        await recordOrderState(env, current, 'fulfilled');
+        await env.DB.prepare("UPDATE purchase_jobs SET state = 'complete', updated_at = ?2 WHERE id = ?1").bind(job.id, Date.now()).run();
+      }
+    } catch (error) { await recordingFailure(env, job.id, error); }
+  }
+  return { checked: rows.length };
+}
+
+/** Resume even when the original isolate died before the provider callback. */
+export async function reconcileSettlements(env, orderId = null, dependencies = {}) {
+  const jobs = (await env.DB.prepare("SELECT * FROM purchase_settlements WHERE mode = ?1 AND state NOT IN ('complete','unpaid') AND (?2 IS NULL OR order_id = ?2) ORDER BY updated_at LIMIT 100").bind(modeOf(env.STRIPE_KEY), orderId).all()).results ?? [];
+  for (const job of jobs) {
+    try {
+      const order = await byId(env, job.order_id);
+      if (!order) throw new Error('Settlement order is missing');
+      const reference = await resumeSettlement(env, job, dependencies);
+      if (!reference) {
+        await env.DB.prepare('UPDATE purchase_settlements SET updated_at = ?2 WHERE id = ?1').bind(job.id, Date.now()).run();
+        continue;
+      }
+      if (reference.manual) {
+        await env.DB.prepare("UPDATE purchase_settlements SET state = 'manual_review', error = ?2, updated_at = ?3 WHERE id = ?1").bind(job.id, reference.reason, Date.now()).run();
+        continue;
+      }
+      if (reference.unpaid) {
+        await env.DB.batch([
+          env.DB.prepare("UPDATE purchase_settlements SET state = 'unpaid', error = ?2, updated_at = ?3 WHERE id = ?1").bind(job.id, reference.reason, Date.now()),
+          orderFact(env, order.id, 'expired', {}),
+          releaseClaim(env, order.id),
+        ]);
+        continue;
+      }
+      const payload = JSON.parse(job.payload);
+      const params = { amount: order.amount, currency: order.currency, confirm: true,
+        payment_method_data: { type: 'crypto' }, payment_method_types: ['crypto'],
+        payment_method_options: { crypto: { mode: 'transaction_verification', transaction_verification_options: { network: job.network, transaction_hash: reference } } },
+        metadata: { homie: 'purchase-v1', order: order.id, mpp_challenge_id: payload.challengeId, mpp_method: job.network === 'base' ? 'evm' : 'tempo' } };
+      await saveRecording(env, order, params, { idempotencyKey: reference });
+      await env.DB.prepare("UPDATE purchase_settlements SET state = 'complete', reference = ?2, error = NULL, updated_at = ?3 WHERE id = ?1").bind(job.id, reference, Date.now()).run();
+    } catch (error) {
+      await env.DB.prepare("UPDATE purchase_settlements SET error = ?2, updated_at = ?3, state = CASE WHEN ?4 THEN 'manual_review' ELSE state END WHERE id = ?1").bind(job.id, String(error.message).slice(0,500), Date.now(), Date.now() - job.created_at >= REPLAY_LIMIT_MS ? 1 : 0).run();
+    }
+  }
+}

package/worker/payment-test-exchange.mjs

@@ -0,0 +1,19 @@
+/** Explicit sandbox readiness uses the same read-only facts as scheduled readiness. */
+import { modeOf } from './stripe.mjs';
+import { probeMachinePayments } from './payment-capabilities.mjs';
+import { digest } from './purchase-crypto.mjs';
+export async function testPaymentExchange(env) {
+  if (modeOf(env.STRIPE_KEY) !== 'test') throw new Error('The sandbox readiness check requires a sandbox key');
+  const key = await digest(env.STRIPE_KEY);
+  const row = await env.DB.prepare("SELECT value FROM meta WHERE key = 'purchase-test-exchange'").first();
+  const prior = row ? JSON.parse(row.value) : null;
+  if (prior?.key === key && prior.nextCheckAt > Date.now()) return prior;
+  const observed = await probeMachinePayments(env);
+  const verified = Object.values(observed.machine).some(Boolean);
+  const report = { key, checkedAt: Date.now(), verified,
+    nextCheckAt: Date.now() + (verified ? 6 * 3600000 : 300000),
+    reason: verified ? null : Object.values(observed.reasons).join('; '),
+    scope: 'Read-only sandbox configuration check. No sale, PaymentIntent, entitlement or refund was created. Write permissions and real settlement remain unverified.' };
+  await env.DB.prepare("INSERT OR REPLACE INTO meta (key,value) VALUES ('purchase-test-exchange',?1)").bind(JSON.stringify(report)).run();
+  return report;
+}

package/worker/purchase-core.mjs

@@ -0,0 +1,140 @@
+/** Provider facts drive orders. Offers and entitlements are immutable purchase inputs. */
+import { canonicalJson } from "./referrals.mjs";
+import { digest } from "./purchase-crypto.mjs";
+
+
+export const states = Object.freeze(['started','paid','fulfilled','refunded','disputed','lapsed','expired','failed','lost']);
+export const transitions = Object.freeze({
+ started: ['paid','refunded','expired','failed','lapsed'],
+ paid: ['fulfilled','refunded','disputed','lapsed','lost'],
+ fulfilled: ['refunded','disputed','lapsed','lost'],
+ refunded: [],
+ disputed: ['paid','fulfilled','refunded','lapsed','lost'],
+ lapsed: ['paid','refunded','disputed'],
+ expired: ['paid','refunded'], failed: ['paid','refunded'], lost: ['paid','refunded'],
+});
+export function transition(from, to, { renewal = false, refundReversal = false } = {}) {
+  if ((renewal || refundReversal) && from === "refunded" && to === "paid") return to;
+  if (
+    !states.includes(from) ||
+    !states.includes(to) ||
+    (from !== to && !transitions[from].includes(to))
+  )
+    throw new Error(`Illegal purchase transition: ${from} -> ${to}`);
+  return to;
+}
+export async function offerVersion(resource, terms) {
+  const offer = { resource, terms };
+  return { ...offer, version: await digest(canonicalJson(offer)) };
+}
+export function entitlement(order, offer) {
+  if (order.offerVersion !== offer.version)
+    throw new Error("Order and offer version differ");
+  return {
+    order: order.id,
+    buyer: order.buyer,
+    resource: offer.resource,
+    terms: structuredClone(offer.terms),
+    active: ["paid", "fulfilled", "disputed"].includes(order.state),
+  };
+}
+
+/** D1 compare-and-swap gives mppx its required shared atomic replay store. */
+export function paymentStore(db, mode) {
+  const keyOf = (key) => `payment:${mode}:${key}`;
+  return {
+    async get(key) {
+      const row = await db
+        .prepare("SELECT value FROM meta WHERE key = ?1")
+        .bind(keyOf(key))
+        .first();
+      return row ? JSON.parse(row.value).value : null;
+    },
+    async put(key, value) {
+      await this.update(key, () => ({ op: "set", value, result: undefined }));
+    },
+    async delete(key) {
+      await this.update(key, () => ({ op: "delete", result: undefined }));
+    },
+    async update(key, fn) {
+      const k = keyOf(key);
+      for (let attempt = 0; attempt < 32; attempt++) {
+        const row = await db
+          .prepare("SELECT value FROM meta WHERE key = ?1")
+          .bind(k)
+          .first();
+        const change = fn(row ? JSON.parse(row.value).value : null);
+        if (change.op === "noop") return change.result;
+        // Tombstones retain a unique revision, avoiding an ABA race on deletion.
+        const value = JSON.stringify({
+          revision: crypto.randomUUID(),
+          value: change.op === "delete" ? null : change.value,
+        });
+        const result = row
+          ? await db
+              .prepare(
+                "UPDATE meta SET value = ?2 WHERE key = ?1 AND value = ?3",
+              )
+              .bind(k, value, row.value)
+              .run()
+          : await db
+              .prepare("INSERT OR IGNORE INTO meta (key,value) VALUES (?1,?2)")
+              .bind(k, value)
+              .run();
+        if (result.meta.changes === 1) return change.result;
+      }
+      throw new Error("Payment state busy; retry the same request");
+    },
+  };
+}
+
+/** The purchase table is the sole lifecycle record. Provider facts use this writer only. */
+export async function orderState(env, id) {
+  const order = await env.DB.prepare("SELECT * FROM purchase_orders WHERE id = ?1").bind(id).first();
+  return order && {...order, offerVersion:order.offer_version, state:order.status};
+}
+const mutable = new Set(['customer','subscription','paid_until','quantity','session','checkout_url','claim_hash','buyer','payment','tax','total','paid_at','refunded_at','refund','dispute','fulfilled_at','note']);
+export function orderFact(env, id, fact, fields = {}, { renewal = false, refundReversal = false } = {}) {
+  const target = fact === 'payment' ? 'paid' : fact;
+  if (fact !== 'details' && !states.includes(target)) throw new Error(`Unknown purchase fact: ${fact}`);
+  const allowed = fact === 'details' ? [] : states.filter((from) => {
+    try { transition(from,target,{renewal,refundReversal}); return true; } catch { return false; }
+  });
+  // Expiry/failure cannot revoke money already accepted. Re-reading the same
+  // payment preserves delivery and disputes; only reconciliation resolves them.
+  const sources = factSources(fact, allowed);
+  const status = fact === 'details' ? 'status' : `CASE ${target === 'paid' ? "WHEN status = 'fulfilled' THEN status " : ''}${target === 'fulfilled' ? "WHEN status = 'disputed' THEN status " : ''}WHEN status IN (${sources.map((v)=>`'${v}'`).join(',')}) THEN '${target}' ELSE status END`;
+  const values = [id, Date.now()];
+  const sets = [`status = ${status}`, 'updated_at = ?2'];
+  if (target === 'paid' && fields.paid_at === undefined) fields = {...fields,paid_at:Date.now()};
+  if (target === 'fulfilled') fields = {...fields,fulfilled_at:Date.now()};
+  if (target === 'refunded' && fields.refunded_at === undefined) fields = {...fields,refunded_at:Date.now()};
+  for (const [key,value] of Object.entries(fields)) {
+    if (!mutable.has(key)) throw new Error(`Immutable purchase field: ${key}`);
+    values.push(value ?? null);
+    const parameter = `?${values.length}`;
+    sets.push(`${key} = ${['paid_at','fulfilled_at'].includes(key) || key === 'payment' && !renewal ? `COALESCE(${key},${parameter})` : parameter}`);
+  }
+  return env.DB.prepare(`UPDATE purchase_orders SET ${sets.join(', ')} WHERE id = ?1`).bind(...values);
+}
+export async function recordOrderState(env, order, fact, fields, options) {
+  await orderFact(env,order.id,fact,fields,options).run();
+  const current = await orderState(env,order.id);
+  return current && { ...current, factResult: { fact, applied: fact === 'details' || current.status === (fact === 'payment' ? 'paid' : fact), state: current.status } };
+}
+
+export function factSources(fact, allowed) {
+  return fact === 'payment' ? ['started','expired','failed'] : ['expired','failed'].includes(fact) ? ['started'] : allowed;
+}
+export function factState(from, fact, options = {}) {
+  if (fact === 'details') return from;
+  const target = fact === 'payment' ? 'paid' : fact;
+  const allowed = states.filter((state) => { try { transition(state, target, options); return true; } catch { return false; } });
+  if (target === 'paid' && from === 'fulfilled' || target === 'fulfilled' && from === 'disputed') return from;
+  return factSources(fact, allowed).includes(from) ? target : from;
+}
+
+export const releaseClaim = (env, id) => env.DB.prepare("UPDATE purchase_orders SET claim_hash = ?2 WHERE id = ?1 AND payment IS NULL AND paid_at IS NULL").bind(id, `released:${id}`);
+
+/** Atomically reserve the first hosted session before processing its payment. */
+export const bindHostedSession = (env,id,session) => env.DB.prepare('UPDATE purchase_orders SET session = ?2 WHERE id = ?1 AND (session IS NULL OR session = ?2)').bind(id,session).run();

package/worker/purchase-crypto.mjs

@@ -0,0 +1,17 @@
+import { canonicalJson } from "./referrals.mjs";
+export const GRANT_TYPE = 'homie-purchase-grant+jwt';
+export const PROOF_TYPE = 'homie-purchase-proof+jwt';
+export const PROOF_AUDIENCE = 'homie-purchase-evidence';
+export const GRANT_AUDIENCE = 'homie-purchases';
+export const digest = async (value) => [...new Uint8Array(await crypto.subtle.digest('SHA-256', typeof value === 'string' ? new TextEncoder().encode(value) : value))].map((b) => b.toString(16).padStart(2, '0')).join('');
+export const manifestHash = (resource) => digest(canonicalJson(resource));
+export async function signGrant(key, claims, proof = false) {
+  const { calculateJwkThumbprint, SignJWT } = await import('jose');
+  return new SignJWT(claims).setProtectedHeader({ alg: 'Ed25519', typ: proof ? PROOF_TYPE : GRANT_TYPE, kid: await calculateJwkThumbprint(key.publicJwk) }).sign(key.privateKey);
+}
+export async function verifyGrant(token, jwk, { issuer, subject, resource, kind, version, proof = false, audience = proof ? PROOF_AUDIENCE : GRANT_AUDIENCE } = {}) {
+  const { calculateJwkThumbprint, importJWK, jwtVerify } = await import('jose');
+  const { payload, protectedHeader } = await jwtVerify(token, await importJWK(jwk, 'Ed25519'), { algorithms: ['Ed25519'], typ: proof ? PROOF_TYPE : GRANT_TYPE, issuer, audience, ...(subject ? { subject } : {}), requiredClaims: ['iss', 'aud', 'sub', 'iat', 'jti', 'resource', 'kind', 'version', ...(proof && audience !== PROOF_AUDIENCE ? [] : ['manifest']), 'mode', ...(proof ? [] : ['exp'])] });
+  if (protectedHeader.kid !== await calculateJwkThumbprint(jwk) || (resource && payload.resource !== resource) || (kind && payload.kind !== kind) || (version && payload.version !== version)) throw new Error('The purchase proof is for another key or release');
+  return payload;
+}

package/worker/purchase-delivery.mjs

@@ -0,0 +1,108 @@
+/** Studio licences use the shop's Stripe, order book, webhook and refund office. */
+import {
+  orderState,
+  recordOrderState,
+  entitlement,
+} from "./purchase-core.mjs";
+
+import { signingKey, publicKeys } from "./purchase-keys.mjs";
+
+import { GRANT_AUDIENCE, PROOF_AUDIENCE, manifestHash, signGrant, verifyGrant } from "./purchase-crypto.mjs";
+import { resourceKind } from "./resource-kinds.mjs";
+
+import {
+  json,
+  fail,
+  byId,
+  bearer,
+  purchasedResource,
+  active,
+  privateRelease,
+  coveredPurchase,
+  deliveryAllowed,
+  resourceAvailable,
+} from "./purchase-store.mjs";
+export async function grantPurchase(env, origin, o, b = {}) {
+  const bought = purchasedResource(o);
+  const version = b.version ?? bought.version;
+  const p =
+    version === bought.version
+      ? JSON.parse(o.manifest)
+      : await privateRelease(env, o.resource_kind, bought.id, version);
+  if (!p)
+    return fail(503, "Release temporarily unavailable; retry this purchase");
+  if (!(await coveredPurchase(env, origin, o, p)))
+    return fail(
+      403,
+      "This version needs a new licence and a fresh price approval",
+    );
+  if (!(await resourceAvailable(env, o.resource_kind, p)))
+    return fail(503, o.payment ? 'Paid file bytes are temporarily unavailable. The seller must restore storage. Do not pay again.' : 'Your chain payment settled but Stripe has not recorded it. Files are temporarily unavailable. Contact the seller for restoration or a manual refund to your original payer address. Do not pay again.');
+  if (!active(o)) return fail(402, `Purchase is ${o.status}; delivery is unavailable`);
+  await env.DB.prepare(
+    "INSERT OR IGNORE INTO purchase_grants (order_id,version,manifest_hash) VALUES (?1,?2,?3)",
+  )
+    .bind(o.id, p.version, await manifestHash(p))
+    .run();
+  const coreOrder = await recordOrderState(env, o, "fulfilled");
+  const offerRow =
+    coreOrder.offerVersion &&
+    (await env.DB.prepare("SELECT value FROM purchase_offers WHERE version = ?1")
+      .bind(coreOrder.offerVersion)
+      .first());
+  const rights = offerRow
+    ? entitlement(coreOrder, JSON.parse(offerRow.value))
+    : null;
+  if (!rights || !rights.active)
+    return fail(402, `Purchase is ${coreOrder.state}; delivery is unavailable`);
+  const key = await signingKey(env);
+  const now = Math.floor(Date.now() / 1000);
+  const claims = {
+    iss: origin,
+    aud: GRANT_AUDIENCE,
+    sub: o.buyer,
+    studio: o.buyer_label,
+    offer: o.offer ? JSON.parse(o.offer) : bought.sale,
+    jti: o.id,
+    iat: now,
+    claimVersion: o.claim_hash,
+    resource: p.id,
+    kind: o.resource_kind,
+    version: p.version,
+    manifest: await manifestHash(p),
+    terms: resourceKind(o.resource_kind).terms(bought),
+    quantity: o.quantity,
+    game: o.game,
+    mode: o.mode,
+    paidUntil: o.paid_until,
+    billing: bought.sale.billing,
+    onRefund: bought.sale.onRefund,
+    onExpiry: bought.sale.onExpiry,
+  };
+  return json({
+    ok: true,
+    entitlement: rights,
+    token: await signGrant(key, { ...claims, exp: now + 300 }),
+    proof: await signGrant(key, { ...claims, aud: PROOF_AUDIENCE }, true),
+    hubProof:
+      b.audience && /^https:\/\/[^/]+$/.test(b.audience)
+        ? await signGrant(
+            key,
+            {
+              iss: claims.iss,
+              aud: b.audience,
+              sub: claims.sub,
+              jti: claims.jti,
+              iat: claims.iat,
+              resource: claims.resource,
+              kind: claims.kind,
+              version: claims.version,
+              mode: claims.mode,
+            },
+            true,
+          )
+        : undefined,
+    manifest: p,
+    paidUntil: o.paid_until,
+  });
+}