@homie-rocks/studio 0.37.1 → 0.38.0

package/CHANGELOG.md

@@ -17,6 +17,66 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.38.0] - 2026-10-09
+
+**Plugin 0.39.0**
+
+Your own character answers as soon as you press, even when the room runs on the server.
+
+### Added
+
+- Rules games predict your own movement with the same movement code the host runs. They ease corrections from the host and smoothly draw everyone else. Authors get this through the view library.
+- The build checks that browser movement agrees with the server and stays within its budget.
+
+### Changed
+
+- New Gem Rush games use rules plus view, with the server keeping movement, pickups and scores. The canvas, controls, waves and knockback keep their familiar look and play. Coin Dash also uses server movement with prediction.
+
+### Fixed
+
+- Rules prediction keeps movement continuous when snapshots replace its catch-up path or its input clock recalibrates, fixing backward steps on delayed, lossy connections.
+- A rules correction that catches up to the current fractional tick uses the next movement preview instead of holding still and jumping when the next whole tick arrives. Snapshots also preserve the drawn catch-up pose when they replace its history. Offset fading is bounded by normal movement speed, so it does not compound a fast knock's catch-up speed.
+- Gem Rush reports its downward Y axis to the rules probe, so control checks judge its actual on-screen direction. Rules views can supply their camera axes through `screenBasis`.
+- Playtest no longer attributes its default timeout duration to a rules game that declares no round duration in `game.json`.
+- Perf checks body presence in the last drawn frame without imposing a hidden 400 ms frame-rate requirement on software rendering.
+- Studio checks accept two replicas when the server hosts the rules. Perf reports and regression guards include both replicas, and choose a replica as the default goal for server rooms.
+- Shoot sends held keys to the game frame and reports a server-only preview without a running room as not playing. Its saved receipt now includes the final verdict.
+- The Game Lab exits after writing its completed report, even when Chrome leaves a pipe open. Coin Dash includes a reproducible Lab take.
+- Control timing starts at the game frame's receipt of a key or completed thumb gesture, judges the first changed frame, collects enough frames on a slow renderer, and measures the round clock between matching observations (including slow screenshots). The response and steering limits are unchanged.
+- The controls check exercises a browser disconnect and late joining in server rooms as well as host takeover in browser rooms. A hold with too little runway is repeated after moving away from the wall, with the same steering requirements.
+
+### Upgrade notes
+
+- Existing games keep their own source when you upgrade. Games written the old way keep working.
+
+## [0.37.2] - 2026-10-09
+
+**Plugin 0.38.2** · [#70](https://github.com/homie-rocks/homie/pull/70)
+
+Sell game, app, music or video parts on your own studio's site, with your price and licence; another studio's AI can discover, pay for and install them.
+
+### Added
+
+- **Your own part shop.** Tell your AI which files to sell, their price and their licence. On a studio already deployed with Stripe, connection takes one browser approval when needed (zero if already connected); the AI creates Payment Links and the webhook in your account. It generates and installs the purchase signing key too. Nobody finds or pastes a key for this setup.
+- **An AI can pay without a checkout page.** MPP with Stripe shared payment tokens, x402 on Base, and MPP over MCP return verified files and a signed proof. The buyer approves the exact price or gives its wallet standing authority. Wallet-required approvals still apply. Stripe's hosted checkout is the fallback.
+- **Machine payments are an optional fuller connection.** Stripe's shared-token charge and stablecoin PaymentIntent recording APIs need a Worker credential; the MCP binding uses the same charge. Your AI can operate Stripe's key-creation page and transfer its Copy result privately with `shop connect --from-clipboard`; you only handle Stripe's sign-in, verification and approval prompts. Live Base also needs your CDP facilitator credentials. The guide distinguishes this setup from the one-approval keyless default.
+- Receipts, retries, private storage, refunds and payment recovery belong to your studio. **homie.rocks is not in the money path**, takes no fee, and can be unavailable while a buyer buys directly from your site.
+
+### Changed
+
+- Part kinds are labels you choose; app, music and video are suggestions alongside existing game kinds. Existing manifests and game imports still work. App pieces use the same extraction, imports and credits as games; music and video retain their provenance and intended uses.
+- Sellers choose licence scopes, refund windows, approval-intent lifetimes and recurring intervals supported by Stripe. No new price ceiling, seller kind list or spending cap. Turnstile on the hosted fallback is optional; request flood protection remains configurable.
+- Paid resources use the shop's webhook verification and refund-list reader, including keyless signed refund snapshots. Each purchase keeps its frozen terms and private claim. A second purchase has a fresh claim; retries keep the first claim and never request a second charge.
+- Selling code is loaded only by the selling entry. A studio that sells no parts keeps the ordinary Worker and its existing compatibility flags.
+
+### Upgrade notes
+
+- Follows [#74](https://github.com/homie-rocks/homie/pull/74), studio 0.37.1 / plugin 0.38.1. Main’s apps, keyless shop and visible Shop control remain available.
+
+- The AI applies `0015_purchases.sql` and `0016_purchase_facts.sql`, configures private storage, and uploads and verifies paid files when you deploy. Existing shop migrations stay unchanged. Keep paid files and the seller's signing key backed up.
+- Payment Links need no Stripe API key in the Worker. A keyless refund is made in Stripe or by the owner's connected AI; signed events update the studio. Missing events wait for Stripe redelivery. Dynamic quantities and provider-read recovery use the fuller connection.
+- Verification uses stand-in payment services in the local Workers runtime and Chrome. No real payment account was signed into and nothing was deployed. Actual account eligibility, settlement and provider permissions still need verification on the seller's account.
+
 ## [0.37.1] - 2026-10-09
 
 **Plugin 0.38.1** · [#74](https://github.com/homie-rocks/homie/pull/74)

package/bin/homie-studio.mjs

@@ -336,7 +336,7 @@ import { publish, publishBefore } from '../lib/directory.mjs';
 import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
-import { DEFAULT_GOAL, perfCompare, perfRun, perfSizes } from '../lib/perf.mjs';
+import { perfCompare, perfRun, perfSizes } from '../lib/perf.mjs';
 import { LAB_PORT, labServe, labSet, labStop } from '../lib/lab.mjs';
 import { R2_COST, lineOf, mediaPlan, r2OverOf, recordUpload, resolveMedia, sizeOf, typeOf } from '../lib/media.mjs';
 import { newStudio } from '../lib/scaffold.mjs';
@@ -819,7 +819,8 @@ const OUTWARD_FLAGS = {
   'lounge mod': ['url', 'remove'], 'lounge remove': ['url', 'all'],
   'chat remove': ['url', 'all'], 'chat budget': ['url'],
   'servers close': ['url', 'reopen'], 'servers level': ['url'], 'servers member': ['url', 'role', 'remove'],
-  'shop connect': ['url', 'managed', 'live', 'manual', 'renew'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note'], 'shop statements': ['url', 'period', 'send', 'cursor'],
+  'parts reissue': ['claim-hash', 'receipt-verified', 'buyer'], 'parts retire': [], 'parts keys': [], 'parts refund': ['game'],
+  'shop connect': ['url', 'managed', 'live', 'manual', 'renew', 'from-clipboard'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note', 'manual-transaction'], 'shop statements': ['url', 'period', 'send', 'cursor'],
   'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
   'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
   // With --device it adds a phone to the person's Apple team and installs on it: a flag it does not know stops it.
@@ -877,7 +878,7 @@ async function main() {
   }
   if (cmd === 'perf' && sub === 'compare') {
     if (!positional[2] || !positional[3]) return { ok: false, command: 'perf compare', why: 'usage: homie-studio perf compare <before dir> <after dir> [--goal <metric>] [--min 3]' };
-    return perfCompare(positional[2], positional[3], { goal: String(flags.get('goal') ?? DEFAULT_GOAL), min: flags.has('min') ? Number(flags.get('min')) / 100 : 0.03, guards: flags.get('guards') ? String(flags.get('guards')).split(',').map((x) => x.trim()).filter(Boolean) : null, also: flags.get('also') ? String(flags.get('also')).split(',').map((x) => x.trim()).filter(Boolean) : [] });
+    return perfCompare(positional[2], positional[3], { goal: flags.has('goal') ? String(flags.get('goal')) : null, min: flags.has('min') ? Number(flags.get('min')) / 100 : 0.03, guards: flags.get('guards') ? String(flags.get('guards')).split(',').map((x) => x.trim()).filter(Boolean) : null, also: flags.get('also') ? String(flags.get('also')).split(',').map((x) => x.trim()).filter(Boolean) : [] });
   }
   // The starter library and the optimiser work anywhere; the rest of style and assets inside a studio (lib/art-cli.mjs).
   if (cmd === 'assets' && ['find', 'optimise', 'optimize'].includes(sub)) return assetsCommand(null, sub, positional, flags, { log });
@@ -1057,7 +1058,7 @@ async function main() {
     if (!sub) return shopStatus(root, { url });
     if (sub === 'init') return shopInit(root, { supporter: flags.has('supporter'), currency: flags.get('currency') ?? 'usd', price: flags.get('price') ?? 500, managed: flags.has('managed') });
     if (sub === 'check') return shopCheck(root);
-    if (sub === 'connect') return shopConnect(root, { managed: flags.has('managed') ? true : null, live: flags.has('live'), manual: flags.has('manual'), renew: flags.has('renew'), log: (line) => process.stderr.write(`${line}\n`) });
+    if (sub === 'connect') return shopConnect(root, { managed: flags.has('managed') ? true : null, live: flags.has('live'), manual: flags.has('manual'), fromClipboard: flags.has('from-clipboard'), renew: flags.has('renew'), log: (line) => process.stderr.write(`${line}\n`) });
     if (sub === 'disconnect') return shopDisconnect(root);
     if (sub === 'catalog') {
       const from = flags.get('have');
@@ -1072,7 +1073,7 @@ async function main() {
       return catalogPlan(root, { have, mode: mode ?? null });
     }
     if (sub === 'orders') return shopOrders(root, { url });
-    if (sub === 'refund') return shopRefund(root, positional[2], { url, reason: flags.get('reason'), note: flags.get('note') });
+    if (sub === 'refund') return shopRefund(root, positional[2], { url, reason: flags.get('reason'), note: flags.get('note'), manualTransaction: flags.get('manual-transaction') });
     if (sub === 'statements') return shopStatements(root, { url, period: flags.get('period'), cursor: flags.get('cursor') ?? '', send: flags.has('send') });
     return { ok: false, command: 'shop', why: `unknown: shop ${sub} (init, check, connect, disconnect, catalog, orders, refund, statements)` };
   }
@@ -1326,7 +1327,7 @@ try {
   if (result && result.command !== 'help') print(result);
   if (result?.ok === false) process.exitCode = 1;
   // Chrome's pipes can outlive browser.close(); a finished check must not hang its caller.
-  if (['check', 'port check', 'look', 'perf', 'shoot'].includes(result?.command)) process.exit(process.exitCode ?? 0);
+  if (['check', 'port check', 'look', 'perf', 'shoot', 'lab check'].includes(result?.command)) process.exit(process.exitCode ?? 0);
 } catch (error) {
   await flushProgress().catch(() => {});
   print({ ok: false, why: error instanceof Error ? error.message : String(error) });

package/lib/cloudflare.mjs

@@ -1,3 +1,4 @@
+import { paidReleases, uploadPaidParts } from './parts-upload.mjs';
 /**
  * `homie-studio deploy` — the studio's site on the studio's OWN Cloudflare
  * account, through Cloudflare's own tool (Wrangler, pinned in the studio).
@@ -349,12 +350,25 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
     step(`created D1 ${cf.d1}`);
   }
 
+  // Paid objects use a separate private bucket, so even old Worker versions cannot serve them.
+  if (paidReleases(root).length && !storage) return refuse('Paid releases need private storage. Run homie-studio storage add before deploying.');
+  const purchaseBucket = storage && `${storage.slice(0, 52)}-purchases`;
+  if (paidReleases(root).length && !created.has(`r2:${purchaseBucket}`)) {
+    const listed = w(['r2', 'bucket', 'list']);
+    if (listed.code !== 0) return refuse('Could not inspect private purchase storage', listed.out);
+    const buckets = parseJson(listed.out);
+    if (!Array.isArray(buckets)) return refuse('Could not read the private storage list', listed.out);
+    if (buckets.some((bucket) => bucket.name === purchaseBucket)) return refuse('The private purchase bucket already exists and is not owned by this studio');
+    const made = w(['r2', 'bucket', 'create', purchaseBucket]);
+    if (made.code !== 0) return refuse('Could not create private purchase storage', made.out);
+    remember(`r2:${purchaseBucket}`);
+  }
   // Storage (R2) is bound only when `storage add` made the bucket. Deploy itself never creates or lists R2, so a
   // free account with no payment method deploys the whole studio.
   const r2 = storage;
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
-  writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), routes, triggers }));
+  writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), routes, triggers }));
   if (routes) step(`kept the studio's own route${routes.length === 1 ? '' : 's'} in wrangler.jsonc: ${routes.map((r) => r.pattern).join(', ')}`);
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
@@ -362,7 +376,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   step('D1 migrations applied');
   // Workers AI (0.17.0): bound only when a server's AI guides think with it.
   if (needsWorkersAi(root, w, cf.d1)) {
-    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true, routes, triggers }));
+    writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true, routes, triggers }));
     step('Workers AI bound (AI): a server\'s AI guides think with it and typed room chat is reviewed with it, each within its day\'s budget (free allocation: 10,000 neurons a day)');
   }
 
@@ -377,6 +391,11 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
     dep = w(['deploy', ...repoVar(root)]);
   }
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
+  if (paidReleases(root).length) {
+    const bin = wranglerBin(root);
+    const uploadOptions = { cwd: workerDir(root), env: { ...process.env, ...projectsCloudflareEnv(root), CLOUDFLARE_ACCOUNT_ID: accountId, WRANGLER_SEND_METRICS: 'false', CI: '1' } };
+    await uploadPaidParts(root, { bucket: purchaseBucket, log, put: (key, file) => wranglerRun(bin, ['r2', 'object', 'put', key, '--file', file, '--remote'], uploadOptions), hash: (key) => hashRemote(bin, key, uploadOptions) });
+  }
   remember(`worker:${cf.worker}`);
   // The workers.dev address names the Cloudflare account (often after its owner): it stays on this computer, in
   // .studio/local.json (git-ignored), and never in the committed studio.json. A custom domain stays in studio.json.
@@ -394,6 +413,12 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
 
   // The homie.rocks directory claim: the live site claims itself the first time its manifest is read (0.10.0), so
   // reading it once now is all it takes; nothing is stored by hand.
+  if (paidReleases(root).length) {
+    const { withKey } = await import('./office.mjs');
+    const synced = await withKey(root, url, (call) => call('/_studio/api/shop/sync-offers', {}));
+    if (!synced.ok) return refuse('Site deployed, but open part Checkouts could not be closed. Retry deploy: ' + (synced.message ?? synced.why ?? 'no answer'));
+    step(`closed ${synced.expired} obsolete part Checkouts`);
+  }
   const directory = homie || studio.homie?.directory || 'https://homie.rocks';
   recordDeploy(root, builtNow);
   let claim = null;
@@ -655,7 +680,7 @@ export async function storageAdd(root, { log = () => {} } = {}) {
   writeStudio(root, next);
   if (next.cloudflare.d1Id) {
     // The studio's own routes stay through this rewrite too (lib/routes.mjs).
-    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root), routes: keptRoutes(root, studio) }));
+    writeFileSync(configPath(root), wranglerConfig({ partsRateLimit: readConfig(root)?.ratelimits?.find((binding) => binding.name === 'PURCHASE_RATE_LIMITER'), paidParts: paidReleases(root).length > 0 || readConfig(root)?.alias?.['@homie-rocks/studio/worker'] === '@homie-rocks/studio/worker/selling', worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root), routes: keptRoutes(root, studio) }));
   }
   log(`created R2 ${bucket}`);
   return { ok: true, command: 'storage add', bucket, account: accountId, cost: R2_COST, next: ['npx --no-install homie-studio media move --dry-run   (which songs and videos go to R2: over 1 MiB, or left out of git)', 'npm run deploy   (binds the bucket as MEDIA, moves them, checks each by SHA-256, and serves them from R2 at the same addresses; the files stay in this folder)'] };

package/lib/dev.mjs

@@ -81,7 +81,7 @@ export function runsFromStudio(pid, root) {
 export function processOfStudio(pid, root, kind) {
   if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid || !isAlive(pid)) return false;
   const cmd = commandOf(pid);
-  if (cmd === null) return process.platform === 'win32'; // no ps: the registration file is all there is
+  if (cmd === null) return process.platform === 'win32' || runsFromStudio(pid, root); // no ps: the registration file is all there is
   if (kind === 'dev' ? /homie-studio/.test(cmd) : /wrangler|workerd/.test(cmd)) return true;
   return runsFromStudio(pid, root);
 }

package/lib/parts-build.mjs

@@ -1,4 +1,7 @@
 import { experienceDir, experienceFile } from './studio.mjs';
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../worker/referrals.mjs';
+import { publicFiles, saleProblems } from "../worker/parts-sale.mjs";
 /**
  * GAME PARTS IN THE BUILD (parts/PARTS.md). Three small things lib/build.mjs and the deploy plan call, so the build
  * itself stays one line longer in each place:
@@ -14,7 +17,7 @@ import { experienceDir, experienceFile } from './studio.mjs';
  *   partsPublishReport(root)    before a game that uses parts goes online: each part's licence and attribution, and
  *                               plainly where licences cannot be combined.
  */
-import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, readFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import {
   assetRecords, licenceIssues, licenseOfPart, listOwnParts, packPart, packedDir, packedVersions, publicPart, readOrigins, readPart, safePath, shareProblems,
@@ -33,6 +36,7 @@ export function resolvePartImport(root, spec, lock = readOrigins(root)) {
   let dir = null; let rest = []; let ref = null; let vendored = false;
   if (segs.length >= 2 && lock.parts[`${segs[0]}/${segs[1]}`]) { ref = `${segs[0]}/${segs[1]}`; dir = vendorDir(root, ref); rest = segs.slice(2); vendored = true; }
   else if (segs.length >= 1 && existsSync(join(root, 'parts', segs[0], 'part.json'))) { ref = segs[0]; dir = join(root, 'parts', segs[0]); rest = segs.slice(1); }
+  if (vendored && lock.parts[ref]?.purchase?.scope === 'game' && lock.parts[ref].purchase.game == null) return { error: 'The paid part needs a named game licence' };
   if (!dir) return { error: `'${spec}' names a part this studio does not have. Parts here: ${[...Object.keys(lock.parts), ...listOwnParts(root).map((o) => o.id)].join(', ') || 'none'}. Bring one in with part_add ("<studio site>/<part id>").` };
   if (!existsSync(dir)) return { error: `'${spec}': parts/origins.json names ${ref} but its files are gone. Add it again (${ref}@${lock.parts[ref].version}).` };
   if (rest.length) {
@@ -50,7 +54,7 @@ export function resolvePartImport(root, spec, lock = readOrigins(root)) {
 /** The esbuild plugin (lib/build.mjs passes it to every game's bundle). `game`: the game being bundled, to credit. */
 export function partsPlugin(root, game = null) {
   return {
-    name: 'homie-parts',
+    name: 'homie-purchases',
     setup(build) {
       const used = new Set();
       let lock = null;
@@ -58,6 +62,8 @@ export function partsPlugin(root, game = null) {
       build.onResolve({ filter: /^@parts\// }, (args) => {
         try { lock ??= readOrigins(root); } catch (error) { return { errors: [{ text: error.message }] }; }
         const r = resolvePartImport(root, args.path, lock);
+        const purchase = lock.parts[r.ref]?.purchases?.[game] ?? lock.parts[r.ref]?.purchase;
+        if (r.vendored && purchase?.scope === 'game' && game !== purchase.game) return { errors: [{ text: `The paid part ${r.ref} is licensed for ${purchase.game}, not ${game}. Use part_add to obtain this game's licence.` }] };
         if (r.error) return { errors: [{ text: r.error }] };
         if (r.vendored) used.add(r.ref);
         return { path: r.path };
@@ -103,19 +109,32 @@ export function buildParts(root, dist, { studio = {}, log = () => {} } = {}) {
   const sharing = sharedPartsOf(root);
   const names = new Map();
   const index = [];
+  const offerFile = join(root, 'parts', 'offers.json');
+  const offers = existsSync(offerFile) ? JSON.parse(readFileSync(offerFile, 'utf8')) : {};
   for (const { id, versions, part } of sharing) {
+    const releases = [];
     for (const v of versions) {
       const src = packedDir(root, id, v);
       const packed = readPart(src);
+      const config = offers[id];
+      // Release terms are authoritative. The optional price override survives releases.
+      const offer = packed.sale ? { ...packed.sale, ...(config?.price ?? {}) } : null;
+      if (offer && saleProblems({ ...packed, sale: offer }).length) throw new Error(`Invalid offer for ${id}`);
+      const selected = config?.releases?.[v];
+      const onSale = Boolean(offer && config?.active !== false && selected?.active !== false && (v === versions.at(-1) || selected?.keepOnSale === true));
+      if (offer && packed.sale.amount !== offer.amount) log(`warning: ${id} ${v} manifest price is historical; the current offer is ${offer.amount}. Use parts offer to change the selling price.`);
+      if (selected?.upgrade !== undefined && !['included', 'paid'].includes(selected.upgrade)) throw new Error('Release upgrade must be included or paid');
+      releases.push({ onSale, offerVersion: offer ? createHash('sha256').update(canonicalJson({ resource: { kind: 'part', id, release: v, manifest: createHash('sha256').update(canonicalJson(packed)).digest('hex') }, terms: offer })).digest('hex') : null, offer, upgrade: selected?.upgrade ?? 'paid', version: v, license: packed.license, licenseTerms: packed.licenseTerms ?? null, sale: packed.sale ?? null });
       if (!verifyFiles(src, packed).ok) throw new Error(`parts/_packed/${id}/${v} no longer matches its hashes: a shared version never changes. Restore it from git.`);
       const dest = join(out, id, v);
-      for (const f of packed.files) { mkdirSync(dirname(join(dest, f.path)), { recursive: true }); cpSync(join(src, f.path), join(dest, f.path)); }
+      for (const f of packed.files.filter((f) => !packed.sale || publicFiles(packed).has(f.path))) { mkdirSync(dirname(join(dest, f.path)), { recursive: true }); cpSync(join(src, f.path), join(dest, f.path)); }
+      mkdirSync(dest, { recursive: true });
       writeFileSync(join(dest, 'part.json'), `${JSON.stringify(publicPart({ ...packed, share: true }))}\n`);
     }
     // The game it came out of, by the name the studio gives it.
     const g = part.from?.game ?? part.from?.app;
     if (g && !names.has(g)) names.set(g, gameFacts(root, g).name);
-    index.push({ ...part, ...(g ? { from: { ...part.from, name: names.get(g) } } : {}), url: `/parts/${id}/${versions.at(-1)}/`, page: `/parts/${id}/`, versions });
+    index.push({ ...part, ...(part.sale ? { sale: releases.at(-1).offer } : {}), ...(g ? { from: { ...part.from, name: names.get(g) } } : {}), url: `/parts/${id}/${versions.at(-1)}/`, page: `/parts/${id}/`, versions, releases });
     log(`shared part ${id} (${versions.join(', ')})`);
   }
   mkdirSync(out, { recursive: true });

package/lib/parts-cli.mjs

@@ -1,3 +1,8 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readPart, partDir } from './parts.mjs';
+import { saleProblems } from "../worker/parts-sale.mjs";
+import { purchasePortal, prepareRecovery } from './parts-purchase.mjs';
 /**
  * `homie-studio parts …`: the plumbing behind the four chat tools (lib/parts-tools.mjs; parts/PARTS.md). A creator
  * works in chat and never types these; an agent with a shell and no MCP connection may.
@@ -14,7 +19,7 @@
 import { newPart } from './parts.mjs';
 import { addPart, checkParts, findParts, sharePart } from './parts-store.mjs';
 
-export const PARTS_VERBS = ['find', 'new', 'add', 'share', 'unshare', 'check'];
+export const PARTS_VERBS = ['find', 'new', 'add', 'share', 'unshare', 'check', 'manage', 'recover', 'reissue', 'keys', 'offer', 'refund', 'retire', 'test-access'];
 
 /**
  * What `parts add` takes, in the words the command prints when it is not given a part. `--no-install` is said as
@@ -32,7 +37,51 @@ export async function partsCommand(root, sub, positional, flags, { log = () => {
     case 'check': return checkParts(root, arg ?? null, { write: true });
     case 'share': return arg ? sharePart(root, arg, true) : { ok: false, command: 'parts share', why: 'name the part to share' };
     case 'unshare': return arg ? sharePart(root, arg, false) : { ok: false, command: 'parts unshare', why: 'name the part to stop sharing' };
-    case 'add': return arg ? addPart(root, arg, { fetch, ...(npm ? { npm } : {}), install: !flags.has('no-install'), say: log, game: str('game'), overwrite: flags.has('overwrite') }) : { ok: false, command: 'parts add', why: `name the part: "<studio site>/<part id>"\n${PARTS_ADD_USAGE}` };
+    case 'offer': {
+      const p = readPart(partDir(root, arg)); const version = str('release');
+      if (str('upgrade') && (!version || !['included', 'paid'].includes(str('upgrade')))) throw new Error('--upgrade included|paid requires --release');
+      if (flags.has('keep-on-sale') && !version) throw new Error('--keep-on-sale requires --release');
+      const file = join(root, 'parts', 'offers.json'); const offers = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+      const old = offers[arg] ?? {};
+      const price = { ...old.price, ...(str('amount') ? { amount: Number(str('amount')) } : {}) };
+      const problems = saleProblems({ ...p, sale: { ...p.sale, ...price } });
+      if (problems.length) throw new Error(problems.join('; '));
+      offers[arg] = { price, active: !version && flags.has('withdraw') ? false : flags.has('on-sale') ? true : old.active !== false, releases: { ...old.releases } };
+      if (version) offers[arg].releases[version] = { ...old.releases?.[version], ...(flags.has('withdraw') ? { active: false } : flags.has('on-sale') ? { active: true } : {}), ...(flags.has('keep-on-sale') ? { keepOnSale: true } : {}), ...(str('upgrade') ? { upgrade: str('upgrade') } : {}) };
+      writeFileSync(file, JSON.stringify(offers, null, 2) + '\n');
+      return { ok: true, command: 'parts offer', message: 'Offer updated. Deploy to publish it. Existing purchase terms stay unchanged.' };
+    }
+    case 'test-access': {
+      const { withKey } = await import('./office.mjs');
+      return withKey(root, null, (call) => call('/_studio/api/shop/test-access', { order: arg }));
+    }
+    case 'recover': return prepareRecovery(root, arg, str('order'), str('game'));
+    case 'reissue': {
+      const { withKey } = await import('./office.mjs');
+      return withKey(root, null, (call) => call('/_studio/api/shop/reissue', { order: arg, claimHash: str('claim-hash'), receiptVerified: flags.has('receipt-verified'), ...(str('buyer') ? { buyer: str('buyer') } : {}) }));
+    }
+    case 'keys': {
+      const { generateKeyPair, exportJWK } = await import('jose');
+      const { runner } = await import('./cloudflare.mjs');
+      const { siteUrl } = await import('./studio.mjs');
+      const url = siteUrl(root);
+      let old = [];
+      try { const r = await (fetch ?? globalThis.fetch)(`${url}/purchases/keys.json`); if (r.ok) old = (await r.json()).keys; else if (r.status !== 404 || !flags.has('initialize')) throw new Error('Cannot read keys; only an explicit --initialize accepts a missing endpoint'); } catch { throw new Error('Cannot read the current public key ring; restore connectivity before rotating'); }
+      if (!Array.isArray(old) || old.length >= 32) throw new Error('Retain the existing ring. Its 32-key protocol limit requires an explicit key retirement before rotating again');
+      const pair = await generateKeyPair('Ed25519', { extractable: true });
+      const ring = [await exportJWK(pair.privateKey), ...old.map(({ kty, crv, x }) => ({ kty, crv, x }))];
+      const r = runner(root)(['secret', 'put', 'PURCHASE_SIGNING_KEYS'], { input: JSON.stringify(ring) + '\n' });
+      return { ok: r.code === 0, command: 'parts keys', message: 'The parts signing key is a Worker secret. Retained public keys verify earlier purchases.' };
+    }
+    case 'refund': return purchasePortal(root, arg, { game: str('game'), fetch, action: 'refund' });
+    case 'retire': {
+      const { withKey } = await import('./office.mjs');
+      const result = await withKey(root, null, (call) => call('/_studio/api/shop/retire', { kind: 'part', resource: arg }));
+      if (result.ok) sharePart(root, arg, false);
+      return { ...result, command: 'parts retire' };
+    }
+    case 'manage': return purchasePortal(root, arg, { game: str('game'), fetch });
+    case 'add': return arg ? addPart(root, arg, { fetch, ...(npm ? { npm } : {}), install: !flags.has('no-install'), approve: str('approve'), wallet: str('wallet'), quantity: str('quantity') ? Number(str('quantity')) : 1, offline: flags.has('offline'), say: log, game: str('game'), overwrite: flags.has('overwrite') }) : { ok: false, command: 'parts add', why: `name the part: "<studio site>/<part id>"\n${PARTS_ADD_USAGE}` };
     default: return { ok: false, command: 'parts', why: `"${sub}" is not a parts command: ${PARTS_VERBS.join(', ')}` };
   }
 }
@@ -46,6 +95,8 @@ const packageLines = (rows) => rows.filter((p) => p.state !== 'ok').map((p) => (
 
 function addLines(r) {
   const L = [];
+  if (r.purchase?.offline) L.push('Restored from the verified private backup. Refund status is only last known; the seller was not contacted.');
+  if (r.purchase?.mode === 'test') L.push('TEST purchase: this is not proof of a live payment.');
   if (r.was && r.same) L.push(`${r.ref} ${r.version} is already here and unchanged.`);
   else if (r.was) L.push(`${r.ref}: ${r.was} → ${r.version}. ${[r.changes.changed.length ? `changed: ${r.changes.changed.join(', ')}` : '', r.changes.added.length ? `new: ${r.changes.added.join(', ')}` : '', r.changes.removed.length ? `gone: ${r.changes.removed.join(', ')}` : ''].filter(Boolean).join('; ') || 'the same files'}. Your tuning.json was kept${r.replaced?.length ? `; REPLACED your edited ${r.replaced.join(', ')} as asked` : ''}.`);
   else L.push(`${r.name} ${r.version} (${r.kind}) from ${r.host} is in ${r.dir}: ${r.files} files, every one checked against its SHA-256. It is this studio's to tune now.`);
@@ -67,7 +118,7 @@ export function partsLines(r) {
       if (!r.hub.ok) L.push(r.hub.why, '');
       if (!r.results.length) L.push(r.hub.ok ? `No shared part matches${r.query ? ` "${r.query}"` : ''} (${r.searched.hub} in the catalogue, ${r.searched.here} in this studio). Write it; if it turns out reusable, it can become a part.` : 'Nothing in this studio matches.');
       for (const p of r.results) {
-        L.push(`${p.name} (${p.kind}) ${p.version ?? ''} · ${p.license ?? 'no licence named'} · ${p.where === 'hub' ? p.ref : p.where === 'here' ? `${p.ref} (already here)` : `${p.id} (this studio's own${p.share ? ', shared' : ', private'})`}`);
+        L.push(`${p.name} (${p.kind}) ${p.version ?? ''} · ${p.license ?? 'no licence named'} · ${p.price ?? 'Free'} · ${p.where === 'hub' ? p.ref : p.where === 'here' ? `${p.ref} (already here)` : `${p.id} (this studio's own${p.share ? ', shared' : ', private'})`}`);
         if (p.summary) L.push(`  ${p.summary}`);
         if (p.from?.name || (p.from?.game ?? p.from?.app)) L.push(`  from ${p.from.name ?? (p.from.game ?? p.from.app)}${p.from.studio ? ` by ${p.from.studio}` : ''}`);
         const bits = [costWords(p.cost) && `costs ${costWords(p.cost)}`, buildsWords(p.requires) && `builds on ${buildsWords(p.requires)}`, p.rig && `rig ${p.rig}`, p.netplay && `in a room: ${p.netplay}`].filter(Boolean);

package/lib/parts-purchase.mjs

@@ -0,0 +1,174 @@
+import { payWithWallet } from './purchase-wallet.mjs';
+/** Buyer purchase records and pristine backups never belong in public source or game bundles. */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { digest, manifestHash, verifyGrant } from "../worker/purchase-crypto.mjs";
+import { priceWords } from "../worker/purchase-pricing.mjs";
+import { quoteHash } from "../worker/parts-sale.mjs";
+import { checkPart, parseRef, sha256 } from './parts.mjs';
+
+const directory = (root) => join(root, '.homie', 'paid-parts');
+const recordName = (ref, game) => sha256(`${ref}\n${game ?? ''}`);
+function privateWrite(root, path, value) {
+  mkdirSync(directory(root), { recursive: true, mode: 0o700 });
+  const ignore = join(root, '.gitignore');
+  const text = existsSync(ignore) ? readFileSync(ignore, 'utf8') : '';
+  if (!text.split('\n').includes('/.homie/paid-parts/')) writeFileSync(ignore, `${text}${text && !text.endsWith('\n') ? '\n' : ''}/.homie/paid-parts/\n`);
+  writeFileSync(`${path}.tmp`, JSON.stringify(value), { mode: 0o600 }); chmodSync(`${path}.tmp`, 0o600); renameSync(`${path}.tmp`, path);
+}
+function read(path) { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } }
+const recordPath = (root, ref, game) => join(directory(root), `${recordName(ref, game)}.json`);
+export async function purchaseFetch(url, { fetch: f = globalThis.fetch, method = 'GET', body, authorization, max = 1024 * 1024 } = {}) {
+  const r = await f(url, { method, redirect: 'error', signal: AbortSignal.timeout(30000), headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}), ...(authorization ? { authorization: `Bearer ${authorization}` } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+  const reader = r.body?.getReader(); let count = 0; const chunks = [];
+  if (reader) for (;;) { const { done, value } = await reader.read(); if (done) break; count += value.length; if (count > max) { await reader.cancel(); throw new Error('Purchase response exceeds its size limit'); } chunks.push(value); }
+  let data;
+  try { data = JSON.parse(Buffer.concat(chunks).toString()); } catch { throw new Error(`Purchase service answered ${r.status} without JSON`); }
+  return { status: r.status, data };
+}
+function purchaseNeeded(purchase) {
+  const error = new Error(purchase.message); error.purchase = purchase; throw error;
+}
+
+/** Request payment from the existing wallet only for the approved immutable quote. */
+export async function paidAccess(root, ref, part, { game = null, quantity = 1, approve = null, fetch, offer = part.sale, wallet, walletPay = payWithWallet } = {}) {
+  game = offer.scope === 'game' ? game : null;
+  const origin = `https://${ref.host}`; const hash = await manifestHash(part); const quote = await quoteHash(part, quantity, game, offer); const path = recordPath(root, ref.ref, game);
+  let record = read(path);
+  let exchange;
+  if (record?.recovery) {
+    const recovered = await purchaseFetch(`${origin}/api/purchases/recover`, { fetch, method: 'POST', authorization: record.claim, body: {} });
+    if (!recovered.data.ok || recovered.data.order !== record.order) throw new Error('Seller has not reissued this purchase yet');
+    const r = recovered.data;
+    record = { ...record, recovery: false, buyer: r.buyer, quantity: r.quantity, game: r.game, version: r.manifest.version, manifestHash: await manifestHash(r.manifest), quote: await quoteHash(r.manifest, r.quantity, r.game), price: priceWords(r.manifest.sale, r.quantity) };
+    privateWrite(root, recordPath(root, ref.ref, r.game), record);
+  }
+  if (!record) {
+    if (approve !== quote) purchaseNeeded({ required: true, quote, part: ref.ref, version: part.version, price: priceWords(offer, quantity), sale: offer, licence: part.license, terms: `${origin}/parts/${ref.id}/${part.version}/${part.licenseTerms}`, quantity, game, message: `Ask first: ${part.name} from ${ref.host}, ${priceWords(offer, quantity)}. Show the licence, refund and recurring terms. Only authority for this exact price permits requesting payment through the person’s wallet; Checkout is the fallback.` });
+    if (!Number.isSafeInteger(quantity) || quantity < 1) throw new Error('Quantity must be a positive whole number');
+    if (offer.scope === 'game' && !game) throw new Error('This licence needs the game being licensed');
+    const identityPath = join(directory(root), 'identity.json'); let identity = read(identityPath);
+    if (!identity) { identity = { buyer: randomBytes(32).toString('hex') }; privateWrite(root, identityPath, identity); }
+    record = { createdAt: Date.now(), buyer: identity.buyer, buyerName: String(read(join(root, 'studio.json'))?.name ?? 'Buying studio').slice(0, 80), claim: randomBytes(32).toString('hex'), quote, manifestHash: hash, version: part.version, price: priceWords(offer, quantity), quantity, game, origin, ref: ref.ref };
+    privateWrite(root, path, record);
+  }
+  if (!record.order) {
+    // A retry of a previously approved intent is bound to its original quote and quantity.
+    if ((record.quote !== quote || record.quantity !== quantity) && approve === quote) { privateWrite(root, path, null); return paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay }); }
+    if (record.quote !== quote || record.quantity !== quantity) purchaseNeeded({ required: true, quote, price: priceWords(offer, quantity), message: 'Price, terms or quantity changed. Approve the new quote with a new purchase record.' });
+    if (offer.billing === 'one-time' && offer.currency === 'usd' && !offer.automaticTax && offer.taxBehavior !== 'exclusive' && (wallet || process.env.HOMIE_PARTS_WALLET)) {
+      const paid = await walletPay(`${origin}/api/purchases/resource`, { kind: 'part', resource: part.id, version: part.version, buyer: record.buyer, claim: record.claim, quote, quantity, game, amount: offer.amount * quantity }, { client: wallet, pending: record.walletPending });
+      if (paid?.pending) {
+        record.walletPending = paid.pending; privateWrite(root, path, record);
+        purchaseNeeded({ required: true, wallet: paid.approval, quote, price: priceWords(offer, quantity), message: 'Approve this spend in your wallet app, then call part_add again. The wallet controls authority and limits.' });
+      }
+      record.walletPending = null;
+      privateWrite(root, path, record);
+      if (paid?.data?.order) {
+        exchange = paid.data;
+        record.order = paid.data.order; privateWrite(root, path, record);
+      } else {
+        const reason = paid?.data?.detail ?? paid?.data?.message ?? 'The wallet could not complete this payment';
+        if (paid?.uncertain || /Settlement|recording|processing|do not pay again/i.test(reason)) throw new Error(reason);
+        record.walletUnavailable = reason;
+        // Retain this private claim so a corrected wallet can retry it.
+        privateWrite(root, path, record);
+        if (!paid?.data?.checkout) purchaseNeeded({ required: true, quote, price: priceWords(offer, quantity), walletUnavailable: reason, machine: `${origin}/api/purchases/resource`, message: `${reason}. Retry part_add with the corrected wallet, or omit wallet to choose the hosted Checkout fallback. No payment was confirmed.` });
+      }
+    }
+    if (!record.order) {
+    if (record.walletUnavailable) { record.claim = randomBytes(32).toString('hex'); privateWrite(root, path, record); }
+    const { status, data } = await purchaseFetch(`${origin}/api/purchases/intent`, { fetch, method: 'POST', body: { kind: 'part', resource: part.id, version: part.version, buyer: record.buyer, buyerName: record.buyerName, claimHash: await digest(record.claim), quote, quantity: record.quantity, game } });
+    if (status !== 200 || !data.ok) throw new Error(data.message ?? 'Purchase could not be prepared');
+    if (new URL(data.url).origin !== origin) throw new Error('Purchase URL is not on the seller origin');
+    record.order = data.order; record.url = data.url; privateWrite(root, path, record);
+    purchaseNeeded({ required: true, checkout: record.url, price: priceWords(offer, quantity), message: `${record.walletUnavailable ? record.walletUnavailable + ". " : ""}Machine payments are also available: name link-cli or purl as the wallet before starting Checkout. Hosted Checkout fallback: the person opens ${record.url}, reads the licence and pays on Stripe. Then call part_add again. Nothing has been charged by the assistant.` });
+    }
+  }
+  const { status, data } = exchange ? { status: 200, data: exchange } : await purchaseFetch(`${origin}/api/purchases/grant`, { fetch, method: 'POST', authorization: record.claim, body: { version: part.version } });
+  if (status !== 200 || !data.ok) {
+    if (status === 401 && record.createdAt && Date.now() - record.createdAt > (offer.intentMinutes ?? 30) * 60000) data.status = 'expired';
+    if (approve === quote && ((status === 401 && quote !== record.quote) || (status === 403 && quote !== record.quote) || ['expired', 'failed', 'refunded', 'lost'].includes(data.status))) {
+      privateWrite(root, join(directory(root), `${recordName(ref.ref, game)}-${record.order}.purchase.json`), record);
+      privateWrite(root, path, null);
+      return paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay });
+    }
+    if (data.status) record.status = data.status;
+    if (data.paidUntil !== undefined) record.paidUntil = data.paidUntil;
+    record.checkedAt = new Date().toISOString(); privateWrite(root, path, record);
+    purchaseNeeded({ required: true, checkout: record.url, status: record.status, quote, price: priceWords(offer, quantity), sale: offer, licence: part.license, terms: `${origin}/parts/${ref.id}/${part.version}/${part.licenseTerms}`, message: data.message ?? 'Finish the purchase on Stripe, then call part_add again' });
+  }
+  const { calculateJwkThumbprint, decodeProtectedHeader } = await import('jose');
+  let jwk = record.jwk;
+  if (!jwk || decodeProtectedHeader(data.token).kid !== await calculateJwkThumbprint(jwk)) {
+    const keys = await purchaseFetch(`${origin}/purchases/keys.json`, { fetch });
+    if (keys.status !== 200 || !Array.isArray(keys.data.keys) || !keys.data.keys.length) throw new Error('The seller supplied no unambiguous signing key');
+    jwk = keys.data.keys.find((k) => k.kid === decodeProtectedHeader(data.token).kid);
+    if (!jwk) throw new Error('Seller key is not in its HTTPS key ring');
+  }
+  const claims = await verifyGrant(data.token, jwk, { issuer: origin, subject: record.buyer, kind: 'part', resource: part.id, version: part.version });
+  if (claims.manifest !== hash || await manifestHash(data.manifest) !== hash || (part.version === record.version && hash !== record.manifestHash) || claims.jti !== record.order || (claims.quantity !== record.quantity && claims.billing === 'one-time') || claims.game !== record.game || (record.mode && record.mode !== claims.mode)) throw new Error('The signed licence differs from the approved purchase');
+  const evidence = await verifyGrant(data.proof, jwk, { proof: true, issuer: origin, subject: record.buyer, kind: 'part', resource: part.id, version: part.version });
+  if (evidence.manifest !== claims.manifest || evidence.jti !== claims.jti) throw new Error('Purchase evidence does not match the download');
+  record = { ...record, trustedKeys: [...new Map([...(record.trustedKeys ?? []), ...(record.jwk ? [record.jwk] : []), jwk].map((k) => [k.x, k])).values()], quantity: claims.quantity, paidUntil: claims.paidUntil, jwk, token: data.token, proof: data.proof, mode: claims.mode, status: 'paid', checkedAt: new Date().toISOString() }; privateWrite(root, path, record);
+  return { token: data.token, proof: data.proof, claims, jwk, record, files: exchange?.files };
+}
+
+export function savePurchaseBackup(root, got, access, game) {
+  game = access.claims.game;
+  const path = recordPath(root, got.ref.ref, game); const record = read(path);
+  // One JSON archive retains exact bytes, including files the buyer later edits. Its token is private.
+  const archive = { ref: got.ref, part: got.part, entry: got.entry, base: got.base, version: got.version, versions: got.versions, token: access.proof, jwk: access.jwk, buyer: record.buyer, files: [...got.files].map(([path, bytes]) => [path, bytes.toString('base64')]) };
+  const name = `${recordName(got.ref.ref, game)}-${got.version}.backup.json`;
+  privateWrite(root, join(directory(root), name), archive);
+  record.backup = name; privateWrite(root, path, record);
+}
+export async function offlinePurchase(root, refText, game) {
+  const ref = parseRef(refText); if (!ref) throw new Error('Name a part');
+  const record = read(recordPath(root, ref.ref, game)) ?? read(recordPath(root, ref.ref, null));
+  game = record?.game;
+  const name = ref.version ? `${recordName(ref.ref, game)}-${ref.version}.backup.json` : record?.backup;
+  const backup = name ? read(join(directory(root), name)) : null;
+  if (!backup) throw new Error('No private purchase backup for this part and game');
+  if (backup.ref?.ref !== ref.ref || backup.ref?.host !== ref.host || backup.ref?.id !== ref.id || backup.version !== backup.part?.version || backup.base !== record.origin) throw new Error('Purchase backup identifies another release');
+  if (![...(record.trustedKeys ?? []), record.jwk].some((key) => key?.x === backup.jwk?.x)) throw new Error('Archive key is not a pinned seller key');
+  const claims = await verifyGrant(backup.token, backup.jwk, { proof: true, issuer: backup.base, subject: backup.buyer, kind: 'part', resource: ref.id, version: backup.version });
+  if (!checkPart(backup.part).ok || claims.manifest !== await manifestHash(backup.part)) throw new Error('Purchase backup manifest failed verification');
+  if (record.status === 'refunded' || record.status === 'lost') { if (claims.onRefund === 'terminate') throw new Error('This purchase was revoked under its refund terms'); }
+  if (claims.paidUntil && claims.paidUntil <= Date.now() && claims.onExpiry === 'terminate') throw new Error('This subscription licence has expired');
+  const files = new Map(backup.files.map(([path, bytes]) => [path, Buffer.from(bytes, 'base64')]));
+  if (files.size !== backup.part.files.length || files.size !== backup.files.length) throw new Error('Purchase backup contains unlisted files');
+  for (const f of backup.part.files) if (!files.has(f.path) || files.get(f.path).length !== f.bytes || sha256(files.get(f.path)) !== f.sha256) throw new Error('Purchase backup files failed verification');
+  return { ...backup, files, purchase: { version: claims.version, mode: claims.mode, scope: claims.terms.scope, game: claims.game, quantity: claims.quantity, paidUntil: claims.paidUntil, onExpiry: claims.onExpiry, onRefund: claims.onRefund, checkedAt: record.checkedAt, offline: true, status: record.status } };
+}
+export async function purchasePortal(root, refText, { game = null, fetch, action = 'portal' } = {}) {
+  const ref = parseRef(refText); const record = ref && (read(recordPath(root, ref.ref, game)) ?? read(recordPath(root, ref.ref, null)));
+  if (!record?.order && action === 'portal' && ref) {
+    const { status, data } = await purchaseFetch(`https://${ref.host}/api/purchases/portal-login`, { fetch });
+    if (status !== 200) throw new Error(data.message);
+    return { ...data, command: 'parts manage' };
+  }
+  if (!record?.order) throw new Error('No purchase here to manage');
+  const { status, data } = await purchaseFetch(`${record.origin}/api/purchases/${action}`, { fetch, method: 'POST', authorization: record.claim, body: {} });
+  if (status !== 200) throw new Error(data.message ?? 'Stripe portal unavailable');
+  if (action === 'refund') return { ...data, command: 'parts refund' };
+  return { ok: true, command: 'parts manage', url: data.url, message: `Open ${data.url} to manage or cancel this subscription in Stripe.` };
+}
+
+/** Last checked state for publish reports; private credentials never leave this module. */
+export function purchaseFacts(root, ref, game) {
+  const r = read(recordPath(root, ref, game)) ?? read(recordPath(root, ref, null));
+  return r ? { status: r.status, paidUntil: r.paidUntil, checkedAt: r.checkedAt } : {};
+}
+
+/** Prepare a recovery request without giving the seller the new claim secret. */
+export function prepareRecovery(root, refText, order, game = null) {
+  const ref = parseRef(refText);
+  if (!ref || !/^ord_[A-Za-z0-9]{20}$/.test(order ?? '')) throw new Error('Supply the part and order from the receipt or seller');
+  const existing = read(recordPath(root, ref.ref, game)) ?? read(recordPath(root, ref.ref, null));
+  if (existing?.claim && !existing.recovery) return { ok: false, command: 'parts recover', message: 'A healthy purchase claim already exists; keep it and run parts add' };
+  const claim = randomBytes(32).toString('hex');
+  privateWrite(root, recordPath(root, ref.ref, game), { claim, order, origin: `https://${ref.host}`, ref: ref.ref, game, recovery: true });
+  return digest(claim).then((claimHash) => ({ ok: true, command: 'parts recover', order, claimHash, message: 'Give the seller this order and claimHash with your Stripe receipt. After reissue, run parts add again. Keep this private purchase folder.' }));
+}