@homie-rocks/studio 0.51.8 → 0.53.0

package/shop/SHOP.md

@@ -122,27 +122,34 @@ calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
 3. Append `{ "method": "POST", "path": "…", "params": {…}, "body": <Stripe response> }`
    for **writes as well as reads**. Keep this setup's observations across batches.
    Product creation includes its default Price; link creation expands line items.
-   Product and Price Search use studio/origin metadata. Existing links are fetched by
-   IDs from the verified configuration; Stripe has no Payment Link metadata search.
-   Keep `.studio/stripe-mcp.json` when moving the studio to another computer. Without
-   it, repeat creates use their idempotency keys; outside Stripe's idempotency retention
-   window, recover the studio's existing link IDs before setup to avoid duplicates.
-   Follow search `next_page` cursors. Search is eventually consistent: write responses
-   are the immediate evidence. On an uncertain write, retry its exact idempotency key;
-   never discard successful responses or invent IDs. Start a new read set when checking
-   later external edits, changing accounts, or changing mode.
+   Product and Price Search use studio/origin metadata. Payment Links use paginated
+   list reads with `expand[]=data.line_items`, then filter studio/origin metadata locally;
+   Stripe has no Payment Link metadata search. There is no per-link read loop.
+   The planner saves public observations in `.studio/stripe-mcp-observations.json` and
+   reuses them on the next call; send only new responses. Keep that file and
+   `.studio/stripe-mcp.json` when moving computers. Changed shop/slot settings refresh
+   mutable links while retaining product/price discovery. Account, mode and origin
+   changes start separate reads. Pass `refresh: true` for Dashboard changes or a fresh
+   verification before webhook installation (CLI: include it in `--have` input).
+   Follow search `next_page` and list `starting_after` cursors. On an uncertain write,
+   retry its exact idempotency key; never discard successful responses or invent IDs.
 4. Call `stripe_shop_plan` with `verify: true` using those observations (CLI
    `homie-studio shop verify --have plan-input.json`). Verification checks real fields,
    line items, menus, slot limits and portal settings. It saves compact public Worker
    configuration and provenance to `.studio/stripe-mcp.json`, never API response history.
-   Deploy installs those links. Checkout then reports only `webhook-secret` missing;
+   Build writes public links to `site/dist/_site/stripe-shop-links.json`; deploy ships
+   that asset, with only its path in Wrangler vars. Large catalogues never use a text
+   binding. Deploy after verifying, including when setup began on an already-live site. Checkout then reports only `webhook-secret` missing;
    it cannot open until signed payment events can confirm orders. Changing shop.json,
    the slot manifest or origin requires verification again. Local test configuration
    goes to `.dev.vars`.
 5. For a deployed HTTPS studio, run `stripe_webhook` (CLI `homie-studio shop webhook`).
    Follow `studio_job`. This uses Stripe CLI only for private webhook installation,
-   checks the same account as the MCP, and installs the signing secret and verified
-   links through Wrangler stdin. The CLI needs one separate browser approval if its
+   checks the same account as the MCP, and installs only the signing secret through
+   Wrangler stdin. If Stripe CLI is missing, the tool installs the official
+   `@stripe/cli@latest` npm package automatically, checks the executable, then continues.
+   An installation failure reports npm permissions/PATH and a retry command. The CLI
+   needs one separate browser approval if its
    studio profile is not already connected. MCP approval cannot be reused or exported.
    Cloudflare authorization and an existing deployment are prerequisites.
 6. After installation, perform the returned `retire` operations through Stripe MCP to
@@ -153,6 +160,14 @@ calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
    endpoint's delivery result and the app's verified records. Do not type a card into
    a page for an automated proof; use Stripe's documented test PaymentMethods/fixtures.
 
+Upgrades accept 0.51.6 verifications without a source fingerprint only when their
+saved content fingerprint still matches the current shop, slots, site and mode.
+Actual changes name the affected settings and require verification. An unfinished
+setup still builds and deploys with checkout closed and one next step: finish
+`stripe_shop_plan` with `verify: true`. Missing/unreadable assets also close checkout;
+old link secrets cannot reopen it. Cached observations never renew the verification
+time; use fresh reads if the private webhook tool requests them.
+
 Never create a webhook through model-visible Stripe MCP: its response exposes the signing secret.
 
 **Why the separate approval (checked 2026-10-14).** Stripe's

package/shop/shop.ts

@@ -71,7 +71,7 @@ export interface Shop {
   cart(): CartLine[];
   clear(): void;
   /** Opens Checkout: keyless bookings are pending until paid; explicit session checkout holds capacity. The returned ID tracks the public booking record. */
-  book(item: string, booking: { collection: string; slot: string }, quantity?: number): Promise<{ ok: boolean; booking?: string; error?: string }>;
+  book(item: string, booking: { collection: string; slot: string; hold?: string; token?: string }, quantity?: number, options?: { reference?: string }): Promise<{ ok: boolean; booking?: string; error?: string }>;
   checkout(options?: { reference?: string }): Promise<boolean>;
   buy(item: string, quantity?: number, amount?: number, options?: { reference?: string }): Promise<boolean>;
   /** Mark an item used; the studio's refundUsedItems policy decides whether self-service refunds still apply. */
@@ -154,8 +154,8 @@ export function createShop(opts: ShopOptions = {}): Shop {
     add: (item, quantity = 1, amount) => { cart.push({ item, quantity, ...(amount === undefined ? {} : { amount }) }); },
     cart: () => cart.map((line) => ({ ...line })),
     clear: () => { cart = []; },
-    book: async (item, booking, quantity = 1) => {
-      const r = await send({ op: 'checkout', booking, lines: [{ item, quantity }] });
+    book: async (item, booking, quantity = 1, options = {}) => {
+      const r = await send({ op: 'checkout', booking, reference: options.reference, lines: [{ item, quantity }] });
       return { ok: Boolean(r.ok), ...(typeof r.booking === 'string' ? { booking: r.booking } : {}), ...(typeof r.message === 'string' ? { error: r.message } : {}) };
     },
     checkout: async (options = {}) => { const ok = Boolean((await send({ op: 'checkout', lines: cart, reference: options.reference })).ok); if (ok) cart = []; return ok; },

package/tools/tools.ts

@@ -6,6 +6,15 @@ export interface ToolContext {
   records(args: { app: string; role?: string; collection: string; id?: string; operation?: 'read' | 'create' | 'update' | 'delete'; data?: Record<string, unknown>; version?: number }): Promise<unknown>;
   office(path: string, body?: Record<string, unknown>, query?: Record<string, string>): Promise<unknown>;
   shop(): Promise<unknown>;
+  bookings: {
+    calendar(args: {app:string;startDate:string;endDate:string;timeZone?:string;time?:string;days?:number;durationMinutes?:number;capacity?:number;weekdays?:number[];resources?:string[];options?:unknown[];prefix?:string}): Array<{id:string;start:string;end:string;capacity:number;date:string;timeZone:string}>;
+    hold(args: {app: string; collection: string; slot?: string; time?: string; option?: string; resource?: string; preferredResource?: string; addons?: string[] | Record<string,number>; addOns?: string[] | Record<string,number>; quantity?: number; id: string; token?: string; expiresAt: number}): Promise<BookingHold>;
+    get(args: {id: string; token?: string}): Promise<BookingHold>;
+    confirm(args: {id: string; token?: string; version: number}): Promise<BookingHold>;
+    release(args: {id: string; token?: string; version: number}): Promise<BookingHold>;
+    releaseExpired(args: {app: string; collection: string; now?: number}): Promise<{released: number}>;
+  };
+  events: { publish(event: {feed: string; id: string; data: unknown}): Promise<{id: string}> };
   rooms: { send(event: {game: string; room: string; event: string; data: unknown}): Promise<unknown> };
   database: {
     get(key: string): Promise<unknown>;
@@ -32,7 +41,11 @@ export interface StudioTool<Input = Record<string, unknown>> {
   namespace?: string;
   /** A named HMAC secret delegates this one tool as an existing account. */
   webhook?: { secret: string; person: string };
+  /** Named business feeds this trusted definition may publish. */
+  publish?: string[];
   events?: Record<string, {game: string; schema: Record<string, unknown>; audience?: Audience}>;
   handler(input: Input, context: ToolContext): unknown | Promise<unknown>;
 }
 export function defineTool<Input = Record<string, unknown>>(tool: StudioTool<Input>): StudioTool<Input> { return tool; }
+
+export interface BookingHold { allocations?: Array<{resource:string;collection:string;start:number;end:number;units:number}>; choices?: {option:string|null;resource:string|null;addons:Record<string,number>}; id: string; slot: string; quantity: number; state: string; version: number; expiresAt: number | null; paid: boolean }

package/worker/app-format.mjs

@@ -6,6 +6,7 @@ const object = (x) => x && typeof x === 'object' && !Array.isArray(x);
 export function appProblems(meta) {
   const bad = [];
   if (!object(meta)) return ['app.json must be an object'];
+  if(meta.web!==undefined && (!object(meta.web)||!object(meta.web.manifest)||meta.web.serviceWorker!==undefined&&(typeof meta.web.serviceWorker!=='string'||meta.web.serviceWorker.includes('..')||!/^[-\w/]+\.js$/.test(meta.web.serviceWorker))))bad.push('web needs a manifest object and optional relative serviceWorker .js path');
   const roles = object(meta.roles) ? meta.roles : {};
   const collections = object(meta.records?.collections) ? meta.records.collections : {};
   if (!object(meta.roles) || !Object.keys(meta.roles).length) bad.push('roles must declare at least one role');
@@ -18,13 +19,15 @@ export function appProblems(meta) {
   if (!object(meta.records) || typeof meta.records.persist !== 'boolean' || !object(meta.records.collections)) bad.push('records declares persist and collections');
   for (const [id, c] of Object.entries(collections)) {
     if (!key.test(id) || !object(c) || !object(c.fields)) { bad.push(`collection ${id}: declare fields`); continue; }
-    for (const [field, spec] of Object.entries(c.fields)) if (!/^[a-z][a-z0-9_]*$/.test(field) || !object(spec) || !['string', 'number', 'boolean'].includes(spec.type) || (spec.enum && (!Array.isArray(spec.enum) || !spec.enum.length))) bad.push(`collection ${id}.${field}: invalid field: names start with a lowercase letter and use lowercase letters, digits and underscore; declare a string, number or boolean type`);
+    for (const [field, spec] of Object.entries(c.fields)) if (!/^[a-z][a-z0-9_]*$/.test(field) || !object(spec) || !['string', 'number', 'boolean', 'array', 'object'].includes(spec.type) || (spec.enum && (!Array.isArray(spec.enum) || !spec.enum.length))) bad.push(`collection ${id}.${field}: invalid field: names start with a lowercase letter and use lowercase letters, digits and underscore; declare a string, number, boolean, array or object type`);
   }
   for (const [id, c] of Object.entries(collections)) if (c.booking) {
     const spec = c.booking;
     if (!object(spec) || !key.test(spec.slots ?? '') || !collections[spec.slots] || typeof spec.item !== 'string' || !spec.item.trim()) bad.push(`collection ${id}: booking needs slots collection and shop item`);
+    if(spec.resources!==undefined&&(!key.test(spec.resources)||!collections[spec.resources]))bad.push(`collection ${id}: booking needs a declared resources collection`);
+    if(spec.holdMinutes!==undefined&&(!Number.isSafeInteger(spec.holdMinutes)||spec.holdMinutes<1||spec.holdMinutes>1440))bad.push(`collection ${id}: holdMinutes is 1–1440`);
     if (!meta.records.persist) bad.push(`collection ${id}: bookings need persistent records`);
-    for (const role of Object.values(roles)) if (!role.signIn && (role.can ?? []).some(cap => ['create','update','delete'].some(op => cap === `${op}:${id}` || cap === `${op}:${spec.slots}`))) bad.push(`collection ${id}: booking and slot writes require a signed-in staff role`);
+    for (const role of Object.values(roles)) if (!role.signIn && (role.can ?? []).some(cap => ['create','update','delete'].some(op => cap === `${op}:${id}` || cap === `${op}:${spec.slots}` || spec.resources&&cap === `${op}:${spec.resources}`))) bad.push(`collection ${id}: booking, slot and resource writes require a signed-in staff role`);
   }
   for (const r of Object.values(roles)) for (const cap of Array.isArray(r?.can) ? r.can : []) if (!Object.hasOwn(meta.records?.collections ?? {}, String(cap).split(':')[1])) bad.push(`unknown collection in ${cap}`);
   for (const [k, v] of Object.entries(meta.words ?? {})) if (!/^[a-z][a-zA-Z0-9-]*$/.test(k) || typeof v !== 'string' || v.length > 500) bad.push(`words.${k}: use a short label`);
@@ -43,7 +46,7 @@ export function recordProblem(collection, data, { create = false } = {}) {
   for (const [k, s] of Object.entries(collection.fields)) {
     const v = data[k];
     if (v === undefined) { if (s.required) return `missing ${k}`; continue; }
-    if (typeof v !== s.type || (s.type === 'number' && !Number.isFinite(v)) || (typeof v === 'string' && v.length > (s.maxLength ?? 256)) || (s.enum && !s.enum.includes(v)) || (create && s.initial !== undefined && v !== s.initial)) return `invalid ${k}`;
+    if ((s.type==='array'?!Array.isArray(v):s.type==='object'?!object(v):typeof v !== s.type) || (s.type === 'number' && !Number.isFinite(v)) || (typeof v === 'string' && v.length > (s.maxLength ?? 256)) || (s.enum && !s.enum.includes(v)) || (create && s.initial !== undefined && v !== s.initial)) return `invalid ${k}`;
   }
   return null;
 }

package/worker/app-records.mjs

@@ -47,7 +47,7 @@ export async function appAccess(request, env, meta, url) {
   const caller = toolIdentity(request);
   if (caller) {
     if (caller.owner) return { ok: true, role, can: declared.can };
-    if(env.HOMIE_LOCAL_TEST_SECRET && caller.localTest && caller.roles?.[meta.id]?.includes(role))return {ok:true,role,can:declared.can};
+    if((env.HOMIE_LOCAL_TEST_SECRET || caller.remoteTest) && caller.localTest && caller.roles?.[meta.id]?.includes(role))return {ok:true,role,can:declared.can};
     if (!caller.id) return { ok: false, status: 401, error: 'sign in to this studio' };
     const grant = await env.DB.prepare("SELECT player FROM app_roles WHERE app IN (?1, '*') AND role = ?2 AND player = ?3").bind(meta.id, role, caller.id).first();
     return grant ? { ok: true, role, can: declared.can } : { ok: false, status: 403, error: 'this account has no role grant' };
@@ -91,7 +91,7 @@ export async function appRecordsRoute(request, env, meta, url, sub) {
     if (!access.ok) return fail(access.status, access.error);
     const [, collection, id] = match;
     const session = await localSession(request, env);
-    const testScope = (session?.app === meta.id ? session.scope : null) ?? (env.HOMIE_LOCAL_TEST_SECRET ? toolIdentity(request)?.testScope : null);
+    const testScope = (session?.app === meta.id ? session.scope : null) ?? (env.HOMIE_LOCAL_TEST_SECRET || toolIdentity(request)?.remoteTest ? toolIdentity(request)?.testScope : null);
     const recordApp = testScope ? `${meta.id}:check:${testScope}` : meta.id;
     const op = ({ GET: 'read', POST: 'create', PUT: 'update', DELETE: 'delete' })[request.method];
     if (!op || !access.can.includes(`${op}:${collection}`)) return fail(403, 'role cannot perform this operation');
@@ -103,18 +103,22 @@ export async function appRecordsRoute(request, env, meta, url, sub) {
       for(const r of rows) {
         const record={id:r.id,data:JSON.parse(r.value),version:r.version,updatedAt:r.updated_at};
         const link=linkConfig(env)?.slots?.find(l=>l.app===meta.id&&l.slots===collection&&l.slot===r.id);
+        if(Object.values(meta.records.collections).some(c=>c.booking?.slots===collection)) {
+          const count=await env.DB.prepare("SELECT COALESCE(SUM(quantity),0) n FROM shop_bookings WHERE app=?1 AND slots=?2 AND slot=?3 AND state IN ('held','confirmed')").bind(recordApp,collection,r.id).first();
+          record.booking={full:count.n>=record.data.capacity,available:Math.max(0,record.data.capacity-count.n),synced:true};
+        }
         if(link) {
           const saved=await env.DB.prepare('SELECT value FROM meta WHERE key=?1').bind(`shop-slot-link:${link.id}`).first();
           const observed=saved?JSON.parse(saved.value):null;
           const status=observed && observed.capacity===(link.limit??link.capacity) ? observed : link;
-          const count=await env.DB.prepare("SELECT COALESCE(SUM(quantity),0) n FROM shop_bookings WHERE app=?1 AND slots=?2 AND slot=?3 AND state='confirmed'").bind(recordApp,collection,r.id).first();
+          const count=await env.DB.prepare("SELECT COALESCE(SUM(quantity),0) n FROM shop_bookings WHERE app=?1 AND slots=?2 AND slot=?3 AND state IN ('held','confirmed')").bind(recordApp,collection,r.id).first();
           record.booking={full:!status.active||status.count>=(link.limit??link.capacity)||count.n>=link.capacity,available:status.active?Math.max(0,Math.min(link.capacity-count.n,(link.limit??link.capacity)-status.count)):0,synced:link.capacity===record.data.capacity};
         }
         records.push(record);
       }
       return json({ok:true,records});
     }
-    if (!id) return fail(400, 'record id required');
+    if (!id) return fail(400, `Put the record id in the URL: /${meta.id}/api/app/records/${collection}/<id> (1–64 letters, digits, underscore or hyphen).`);
     const body = await bodyOf(request);
     if (meta.records.collections[collection].booking) {
       if (op !== 'update' || !meta.roles[access.role].signIn) return fail(403, 'bookings are created and released through checkout');
@@ -128,7 +132,19 @@ export async function appRecordsRoute(request, env, meta, url, sub) {
       ? env.DB.prepare('INSERT OR IGNORE INTO app_records (app, collection, id, value, version, updated_at) VALUES (?1, ?2, ?3, ?4, 1, ?5)').bind(recordApp, collection, id, JSON.stringify(body.data), Date.now())
       : op === 'update' ? env.DB.prepare('UPDATE app_records SET value = ?4, version = version + 1, updated_at = ?5 WHERE app = ?1 AND collection = ?2 AND id = ?3 AND version = ?6').bind(recordApp, collection, id, JSON.stringify(body.data), Date.now(), body.version)
       : env.DB.prepare('DELETE FROM app_records WHERE app = ?1 AND collection = ?2 AND id = ?3 AND version = ?4').bind(recordApp, collection, id, body.version);
-    const result = await stmt.run();
+    const bookingCollections=Object.entries(meta.records.collections).filter(([,c])=>c.booking?.slots===collection);
+    const writes=[stmt];
+    if(!testScope&&op!=='delete')for(const [bookings,c] of bookingCollections) {
+      const link=linkConfig(env)?.slots?.find(l=>l.app===meta.id&&l.slots===collection&&l.slot===id);
+      if(link&&link.capacity===body.data?.capacity)continue;
+      const expected=op==='create'?1:body.version+1;
+      writes.push(env.DB.prepare(`INSERT OR IGNORE INTO studio_events(id,type,data,at)
+        SELECT ?1,'booking.slots_need_payment_links',json_object('app',?2,'slots',json_array(json_object('app',?2,'collection',?3,'slots',?4,'slot',?5,'item',?6,'capacity',json_extract(value,'$.capacity')))),?7
+        FROM app_records WHERE app=?8 AND collection=?4 AND id=?5 AND version=?9
+        AND EXISTS(SELECT 1 FROM function_subscriptions WHERE type='booking.slots_need_payment_links')`)
+        .bind(`slot-links:${recordApp}:${collection}:${id}:${expected}`,meta.id,bookings,collection,id,c.booking.item,Date.now(),recordApp,expected));
+    }
+    const result=writes.length>1?(await env.DB.batch(writes))[0]:await stmt.run();
     return result.meta.changes ? json({ ok: true, id, version: op === 'create' ? 1 : body.version + 1 }) : fail(409, 'record changed or already exists; reload');
   } catch (error) {
     if (/booking capacity|capacity below|slot has active/.test(error.message)) return fail(409, error.message);

package/worker/app-shell.mjs

@@ -2,7 +2,7 @@
 export const APP_SHELL_JS = String.raw`(function () {
   var boot = window.__HOMIE_PLAY || window.__HOMIE_APP || window.__HOMIE_WATCH;
   if (!boot || boot.kind !== 'app') return;
-  var frame = document.querySelector('iframe.game') || document.querySelector('iframe');
+  var frame = boot.direct ? {contentWindow:window} : document.querySelector('iframe.game') || document.querySelector('iframe');
   var params = new URLSearchParams(location.search);
   // Share short-lived reads across same-origin screens with the exact same role/access.
   // No records are persisted. Writes always reach the Worker and invalidate all views.
@@ -13,14 +13,14 @@ export const APP_SHELL_JS = String.raw`(function () {
   function share(m) { accept(m); if (channel) channel.postMessage(m); }
   function locked(run) { return typeof navigator !== 'undefined' && navigator.locks ? navigator.locks.request('homie-app-records-v1', run) : run(); }
   async function request(path, m) {
-    var read = m.method === 'GET';
+    var read = m.type!=='homie-app-tool' && m.method === 'GET';
     if (read && pending.has(path)) return pending.get(path);
     var job = locked(async function() {
       var cached = recent.get(path);
       if (read && cached && cached.until > Date.now()) return cached.result;
       var result;
       try {
-        var res = await fetch(path, { method: m.method, headers: { 'content-type': 'application/json' }, body: read ? undefined : JSON.stringify({ data: m.data, version: m.version }), signal: AbortSignal.timeout(8000) });
+        var res = await fetch(path, { method: m.type==='homie-app-tool'?'POST':m.method, headers: { 'content-type': 'application/json' }, body: m.type==='homie-app-tool'?JSON.stringify({name:m.name,input:m.input}):read ? undefined : JSON.stringify({ data: m.data, version: m.version }), signal: AbortSignal.timeout(8000) });
         result = await res.json();
         if (res.status === 429 || res.status >= 500) throw new Error('reconnect');
         failures.delete(path);
@@ -35,15 +35,38 @@ export const APP_SHELL_JS = String.raw`(function () {
     if (read) { pending.set(path, job); job.finally(function() { pending.delete(path); }); }
     return job;
   }
+  var live, collections=new Set(), presence=0, clock=null;
+  function query() {
+    var q=new URLSearchParams();
+    ['role','surface','access','room'].forEach(function(k){var v=params.get(k);if(v)q.set(k,v);});
+    if(boot.screen&&!q.has('role'))q.set('surface','wall');
+    return q;
+  }
+  function context() {return {app:boot.game,origin:location.origin,url:location.origin+'/'+boot.game+'/open',presence:presence,now:clock};}
+  function sendContext(){frame?.contentWindow?.postMessage({type:'homie-app-context',context:context()},'*');}
+  function connect(){
+    live?.close();
+    var q=query();collections.forEach(function(c){q.append('collection',c);});
+    live=new EventSource((boot.site||'')+'/'+boot.game+'/api/app/live?'+q);
+    live.onmessage=function(e){var value=JSON.parse(e.data);if(presence!==value.presence){presence=value.presence;sendContext();}if(value.collections?.length){share({invalidate:true});Promise.allSettled([...pending.values()]).then(function(){share({invalidate:true});frame?.contentWindow?.postMessage({type:'homie-app-changed',collections:value.collections},'*');});}};
+  }
+  window.homieApp=Object.freeze({get context(){return context();},setTestClock:function(value){if(!boot.test)throw new Error('Local proof session required');if(value!==null&&!Number.isFinite(value))throw new Error('Invalid clock');clock=value;sendContext();}});
+  addEventListener('pagehide',function(){live?.close();});
   addEventListener('message', async function (e) {
     var m = e.data;
+    if(frame&&e.source===frame.contentWindow&&m?.type==='homie-app-context'){sendContext();return;}
+    if(frame&&e.source===frame.contentWindow&&m?.type==='homie-app-subscribe'){
+      if(!Array.isArray(m.collections)||m.collections.some(c=>!/^[a-z][a-z0-9-]{0,39}$/.test(c)))return;
+      m.collections.forEach(c=>collections.add(c));connect();return;
+    }
     if (frame && e.source === frame.contentWindow && m?.type === 'homie-app-ticket' && /^[a-f0-9]{32}$/.test(m.ticket)) { params.set('ticket', m.ticket); history.replaceState(null, '', location.pathname + '?' + params); return; }
-    if (!frame || e.source !== frame.contentWindow || !m || m.type !== 'homie-app' || !/^[a-f0-9]{32}$/.test(m.id || '')) return;
-    if (!/^[a-z][a-z0-9-]{0,39}$/.test(m.collection || '') || !['GET','POST','PUT','DELETE'].includes(m.method) || (m.record !== undefined && !/^[A-Za-z0-9_-]{1,64}$/.test(m.record))) return;
+    if (!frame || e.source !== frame.contentWindow || !m || !['homie-app','homie-app-tool'].includes(m.type) || !/^[a-f0-9]{32}$/.test(m.id || '')) return;
+    if (m.type==='homie-app' && (!/^[a-z][a-z0-9-]{0,39}$/.test(m.collection || '') || !['GET','POST','PUT','DELETE'].includes(m.method) || (m.record !== undefined && !/^[A-Za-z0-9_-]{1,64}$/.test(m.record)))) return;
     var q = new URLSearchParams();
     ['role','surface','access'].forEach(function (k) { var v = params.get(k); if (v) q.set(k, v); });
     if (boot.screen && !q.has('role')) q.set('surface', 'wall');
     var path = (boot.site || '') + '/' + boot.game + '/api/app/records/' + m.collection + (m.record ? '/' + m.record : '') + '?' + q;
+    if(m.type==='homie-app-tool')path=(boot.site||'')+'/'+boot.game+'/api/app/tools?'+q;
     var result = await request(path, m);
     e.source.postMessage({ type: 'homie-app-result', id: m.id, result: result }, '*');
   });

package/worker/app-streams.mjs

@@ -0,0 +1,57 @@
+import {appAccess} from './app-records.mjs';
+import {localSession} from './local-test.mjs';
+import {settingsOf,launchOf,accessOf} from './office.mjs';
+export const APP_LIVE_MIGRATION_FILE='0027_app_live.sql';
+export const APP_LIVE_MIGRATION=`
+CREATE TABLE app_record_revisions(app TEXT NOT NULL,collection TEXT NOT NULL,revision INTEGER NOT NULL,PRIMARY KEY(app,collection));
+${['INSERT','UPDATE','DELETE'].map(op=>{const row=op==='DELETE'?'OLD':'NEW';return `CREATE TRIGGER app_records_live_${op.toLowerCase()} AFTER ${op} ON app_records BEGIN
+ INSERT INTO app_record_revisions VALUES(${row}.app,${row}.collection,1) ON CONFLICT(app,collection) DO UPDATE SET revision=revision+1;
+END;`;}).join('\n')}
+`;
+const frame=value=>new TextEncoder().encode('data: '+JSON.stringify(value)+'\n\n');
+export const appHub=(env,app)=>env.LOBBY.get(env.LOBBY.idFromName('@app-records/'+app));
+export async function pushAppRecords(env,cat){
+ if(!env.LOBBY||!env.DB)return;
+ await Promise.all((cat.games??[]).filter(g=>g.kind==='app').map(meta=>appHub(env,meta.id).fetch('https://app/__app_records',{method:'POST',body:JSON.stringify({op:'wake',meta})}).catch(error=>console.error('App notification wake failed',error))));
+}
+/** Collection invalidations, never record bodies or identifiers. Reads recheck current authorization. */
+export class AppRecordStreams {
+ constructor(env,ctx){this.env=env;this.ctx=ctx;this.streams=new Set();}
+ dispose(){for(const s of [...this.streams])this.close(s);}
+ close(s){if(!this.streams.delete(s))return;clearInterval(s.timer);try{s.controller.close();}catch{}this.presence();}
+ count(s){return [...this.streams].filter(x=>x.app===s.app&&x.room===s.room).length;}
+ send(s,data){if(s.controller.desiredSize<=0){this.close(s);return;}try{s.controller.enqueue(frame(data));}catch{this.close(s);}}
+ presence(){for(const s of this.streams)this.send(s,{presence:this.count(s)});}
+ async authorized(s){
+  const access=await appAccess(s.request,this.env,s.meta,s.url);
+  if(!access.ok||s.collections.some(c=>!access.can.includes('read:'+c)))return false;
+  const launch=launchOf(s.meta,await settingsOf(this.env,{fresh:true}),this.env);
+  return launch==='public'||(await accessOf(s.request,this.env,s.meta.id,launch)).ok;
+ }
+ async revisions(s){return (await this.env.DB.prepare('SELECT collection,revision FROM app_record_revisions WHERE app=?1').bind(s.app).all()).results;}
+ async open({meta,url,headers,collections=[]}){
+  if(!Array.isArray(collections)||collections.some(c=>typeof c!=='string'||!Object.hasOwn(meta.records?.collections??{},c)))return new Response('unknown collection',{status:400});
+  const s={meta,url:new URL(url),request:new Request(url,{headers}),collections,seen:new Map()};
+  if(!await this.authorized(s))return new Response('role cannot read collections',{status:403});
+  const session=await localSession(s.request,this.env);
+  s.app=session?.app===meta.id&&session.scope?`${meta.id}:check:${session.scope}`:meta.id;
+  s.room=s.url.searchParams.get('room')??'main';
+  for(const row of await this.revisions(s))s.seen.set(row.collection,row.revision);
+  const body=new ReadableStream({start:controller=>{s.controller=controller;},cancel:()=>this.close(s)});
+  this.streams.add(s);this.send(s,{collections:s.collections,presence:this.count(s),reset:true});
+  for(const other of this.streams)if(other!==s)this.send(other,{presence:this.count(other)});
+  // Recovery after a missed wake; this is not the screen's refresh clock.
+  s.timer=setInterval(()=>this.ctx.waitUntil(this.pump(s)),15000);
+  return new Response(body,{headers:{'content-type':'text/event-stream','cache-control':'no-store'}});
+ }
+ async pump(s){
+  if(!this.streams.has(s))return;if(s.busy){s.dirty=true;return;}s.busy=true;
+  try{
+   if(!await this.authorized(s)){this.close(s);return;}
+   const changed=[];
+   for(const row of await this.revisions(s)){if(s.collections.includes(row.collection)&&s.seen.get(row.collection)!==row.revision)changed.push(row.collection);s.seen.set(row.collection,row.revision);}
+   this.send(s,{collections:changed,presence:this.count(s)});
+  }catch{this.close(s);}finally{s.busy=false;if(s.dirty){s.dirty=false;await this.pump(s);}}
+ }
+ async wake(meta){for(const s of this.streams)if(meta)s.meta=meta;await Promise.all([...this.streams].map(s=>this.pump(s)));return new Response('ok');}
+}

package/worker/app-tools.mjs

@@ -0,0 +1,44 @@
+import {CfWorkerJsonSchemaValidator} from '@modelcontextprotocol/server/validators/cf-worker';
+import {allowed,services} from './mcp-tools.mjs';
+import {appAccess} from './app-records.mjs';
+import {localSession} from './local-test.mjs';
+import {players} from './players.mjs';
+import {isOwner,sameOrigin} from './office.mjs';
+import {audit,callsPerMinute,rateLimit} from './mcp-store.mjs';
+const validator=new CfWorkerJsonSchemaValidator();
+export async function invokeAppTool(tool,input,context){
+ if(!validator.getValidator(tool.inputSchema)(input).valid)throw Object.assign(new Error('Input does not match the tool schema'),{status:400});
+ return tool.handler(input,context);
+}
+export async function appCaller(request,env,meta,url){
+ const access=await appAccess(request,env,meta,url);
+ if(!access.ok)throw Object.assign(new Error(access.error),{status:access.status});
+ const session=await localSession(request,env);
+ if(session?.app===meta.id)return {id:`local-test-${session.app}-${session.role}`,owner:!session.remoteTest&&session.role==='owner',client:null,localTest:true,...(session.remoteTest?{remoteTest:true}:{}),roles:{[meta.id]:[session.role]},testApp:meta.id,testScope:session.scope};
+ const person=await players.of(request,env);
+ const owner=await isOwner(request,env);
+ const roles={};
+ if(person&&!person.guest){for(const row of (await env.DB.prepare('SELECT app,role FROM app_roles WHERE player=?1').bind(person.id).all()).results)(roles[row.app]??=[]).push(row.role);}
+ return {id:owner?(person?.id??'browser-owner'):person&&!person.guest?person.id:null,owner,client:null,roles};
+}
+/** Same-origin shell transport; body fields never supply an identity or a role. */
+export async function appToolsRoute(request,env,meta,url,cat,definitions){
+ const fail=(status,error)=>Response.json({ok:false,error},{status});
+ if(request.method!=='POST')return fail(405,'POST required');
+ if(!sameOrigin(request,url))return fail(403,'same origin required');
+ let caller,tool,outcome='error';
+ try{
+  caller=await appCaller(request,env,meta,url);
+  const reader=request.body?.getReader();let size=0,text='';const decoder=new TextDecoder();
+  if(reader)for(;;){const {done,value}=await reader.read();if(done)break;size+=value.byteLength;if(size>12288){await reader.cancel();return fail(413,'body too large');}text+=decoder.decode(value,{stream:true});}
+  const body=JSON.parse(text+decoder.decode());
+  tool=definitions.find(t=>t.name===body.name&&(!t.kind||t.kind==='tool'));
+  if(!tool||!await allowed(tool.audience,caller,env)){outcome='denied';return fail(403,'Permission denied or unknown tool');}
+  if(tool.price)return fail(402,'Use MCP to approve payment for this tool');
+  if(!await rateLimit(env,caller.id??`public:${request.headers.get('cf-connecting-ip')??'local'}`,callsPerMinute(cat)))return fail(429,'Rate limit reached');
+  const namespace=(tool.namespace??tool.name)+(caller.testScope?':check:'+caller.testScope:'');
+  const data=await invokeAppTool(tool,body.input??{},services(env,cat,url.origin,caller,namespace,tool));
+  outcome='ok';return Response.json({ok:true,data});
+ }catch(error){return fail(error.status??(error instanceof SyntaxError?400:500),error.status||error.name==='StudioOperationError'?error.message:'Tool request failed');}
+ finally{if(caller)await audit(env,caller,tool?.name??'unknown-tool',outcome);}
+}

package/worker/app-web.mjs

@@ -0,0 +1,23 @@
+import {APP_SHELL_JS} from './app-shell.mjs';
+/** Explicit same-origin, public app surface for installation. */
+export async function appWeb(request,env,meta,url,sub,document) {
+ if(!meta.web?.manifest)return null;
+ const base=`/${meta.id}/`;
+ if(sub==='manifest.webmanifest')return Response.json({...meta.web.manifest,id:base,start_url:base+'install',scope:base,display:meta.web.manifest.display??'standalone'},{headers:{'content-type':'application/manifest+json'}});
+ if(sub==='service-worker.js') {
+  const file=meta.web.serviceWorker;
+  if(typeof file!=='string'||file.includes('..')||!/^[-\w/]+\.js$/.test(file))return new Response('not found',{status:404});
+  const res=await env.ASSETS.fetch(new Request(url.origin+`/games/${meta.id}/${file}`));
+  return new Response(res.body,{status:res.status,headers:{'content-type':'text/javascript','service-worker-allowed':base,'cache-control':'no-cache'}});
+ }
+ if(sub!=='install')return null;
+ const role=meta.surfaces?.phone;
+ if(meta.room||meta.roles?.[role]?.signIn!==false)return new Response('Install requires a public records-only app',{status:409});
+ const response=await document(),headers=new Headers(response.headers);
+ if(!response.ok)return response;
+ headers.set('content-security-policy',"frame-ancestors 'self'");
+ const boot=JSON.stringify({kind:'app',direct:true,game:meta.id}).replace(/</g,'\\u003c');
+ const tags=`<base href="${base}__game/"><link rel="manifest" href="${base}manifest.webmanifest"><script>window.__HOMIE_APP=${boot};</script><script>${APP_SHELL_JS}</script>${meta.web.serviceWorker?`<script>if('serviceWorker' in navigator)navigator.serviceWorker.register('${base}service-worker.js',{scope:'${base}'}).catch(console.error);</script>`:''}`;
+ const html=await response.text();
+ return new Response(/<head[^>]*>/i.test(html)?html.replace(/<head[^>]*>/i,m=>m+tags):tags+html,{headers});
+}

package/worker/booking-calendar.mjs

@@ -0,0 +1,26 @@
+const dayMs=86400000;
+const date=value=>{if(!/^\d{4}-\d{2}-\d{2}$/.test(value??''))throw new Error('Use a calendar date YYYY-MM-DD');const stamp=Date.parse(value+'T00:00:00Z');if(!Number.isFinite(stamp)||new Date(stamp).toISOString().slice(0,10)!==value)throw new Error('Invalid calendar date');return stamp;};
+/** Resolve wall time, refusing DST gaps and ambiguous times instead of silently moving a booking. */
+function instant(day,time,format) {
+ const wanted=day+'T'+time,base=Date.parse(wanted+':00Z');
+ const parts=stamp=>Object.fromEntries(format.formatToParts(stamp).map(p=>[p.type,p.value]));
+ const local=stamp=>{const p=parts(stamp);return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}`;};
+ const offsets=new Set([-dayMs,0,dayMs].map(delta=>{const p=parts(base+delta);return Date.UTC(+p.year,+p.month-1,+p.day,+p.hour,+p.minute)-(base+delta);}));
+ const matches=[...offsets].map(offset=>base-offset).filter(stamp=>local(stamp)===wanted);
+ if(matches.length!==1)throw new Error(`${wanted} does not exist or is ambiguous in this time zone; choose another time or publish an explicit offset timestamp`);
+ return matches[0];
+}
+/** Inclusive season dates; each returned slot may span several local calendar days. */
+export function calendarSlots({startDate,endDate,timeZone,time='09:00',days,durationMinutes=60,capacity=1,weekdays,resources,options,prefix='slot'}) {
+ const start=date(startDate),end=date(endDate);
+ if(end<start||end-start>3660*dayMs||!/^([01]\d|2[0-3]):[0-5]\d$/.test(time)||!Number.isSafeInteger(capacity)||capacity<1||days!==undefined&&(!Number.isSafeInteger(days)||days<1)||!Number.isSafeInteger(durationMinutes)||durationMinutes<1)throw new Error('Invalid calendar range, time, duration or capacity');
+ if(weekdays&&(!Array.isArray(weekdays)||weekdays.some(n=>!Number.isInteger(n)||n<0||n>6)))throw new Error('weekdays uses 0 (Sunday) through 6 (Saturday)');
+ if(typeof timeZone!=='string'||!timeZone)throw new Error('Declare the place timeZone');
+ const format=new Intl.DateTimeFormat('en-CA',{timeZone,year:'numeric',month:'2-digit',day:'2-digit',hour:'2-digit',minute:'2-digit',hourCycle:'h23'}),slots=[];
+ for(let at=start;at<=end;at+=dayMs) {
+  if(weekdays&&!weekdays.includes(new Date(at).getUTCDay()))continue;
+  const day=new Date(at).toISOString().slice(0,10),from=instant(day,time,format),to=days?instant(new Date(at+days*dayMs).toISOString().slice(0,10),time,format):from+durationMinutes*60000;
+  slots.push({id:`${prefix}-${day}-${time.replace(':','')}`,date:day,timeZone,start:new Date(from).toISOString(),end:new Date(to).toISOString(),capacity,...(resources?{resources}:{}),...(options?{options}:{})});
+ }
+ return slots;
+}

package/worker/booking-holds.mjs

@@ -0,0 +1,100 @@
+import {calendarSlots} from './booking-calendar.mjs';
+import {allocateResources} from './booking-resources.mjs';
+import {normalizeBookingArgs} from './booking-options.mjs';
+import {BOOKINGS_MIGRATION} from './booking-store.mjs';
+import {linkConfig,hasStripeKey} from './shop-links.mjs';
+export const BOOKING_HOLDS_MIGRATION_FILE='0029_booking_holds.sql';
+export const BOOKING_HOLDS_MIGRATION=`
+ALTER TABLE shop_bookings ADD COLUMN paid_at INTEGER;
+ALTER TABLE shop_bookings ADD COLUMN actor TEXT;
+ALTER TABLE shop_bookings ADD COLUMN token_hash TEXT;
+ALTER TABLE shop_bookings ADD COLUMN hold_until INTEGER;
+DROP TRIGGER booking_capacity_move;
+CREATE TRIGGER booking_capacity_move BEFORE UPDATE OF slot,quantity,state ON shop_bookings
+WHEN NEW.state IN ('held','confirmed') BEGIN
+ SELECT RAISE(ABORT,'booking capacity unavailable') WHERE NOT EXISTS (
+ SELECT 1 FROM app_records s WHERE s.app=NEW.app AND s.collection=NEW.slots AND s.id=NEW.slot
+ AND json_type(s.value,'$.capacity')='integer' AND json_extract(s.value,'$.capacity') >= NEW.quantity +
+ (SELECT COALESCE(SUM(quantity),0) FROM shop_bookings WHERE app=NEW.app AND slots=NEW.slots AND slot=NEW.slot AND id!=NEW.id AND state IN ('held','confirmed')));
+END;
+CREATE TRIGGER booking_hold_claim BEFORE UPDATE OF order_id ON shop_bookings BEGIN
+ SELECT RAISE(ABORT,'booking hold changed or expired') WHERE NEW.order_id IS NULL OR OLD.order_id!='hold:'||OLD.id OR OLD.state NOT IN ('held','confirmed') OR (OLD.state='held' AND OLD.hold_until<=NEW.updated_at);
+END;
+DROP TRIGGER booking_order_state;
+CREATE TRIGGER booking_order_state AFTER UPDATE OF status,paid_at ON shop_orders
+WHEN NEW.status!=OLD.status OR (OLD.paid_at IS NULL AND NEW.paid_at IS NOT NULL) BEGIN
+ UPDATE shop_bookings SET state=CASE WHEN NEW.status='paid' THEN 'confirmed' ELSE 'released' END,
+ paid_at=COALESCE(NEW.paid_at,paid_at),version=version+1,updated_at=NEW.updated_at
+ WHERE order_id=NEW.id AND ((state IN ('pending','held','confirmed') AND NEW.status='paid')
+ OR (state IN ('pending','held') AND NEW.status IN ('expired','failed'))
+ OR (state IN ('pending','held','confirmed') AND NEW.status IN ('refunded','lost')));
+END;
+${['insert','update'].map(op=>{
+ const trigger=BOOKINGS_MIGRATION.match(new RegExp('CREATE TRIGGER booking_record_'+op+'[\\s\\S]*?END;'))[0];
+ return 'DROP TRIGGER booking_record_'+op+';\n'+trigger.replace("'state',NEW.state)","'state',NEW.state,'paid',json(CASE WHEN NEW.paid_at IS NULL THEN 'false' ELSE 'true' END))");
+}).join('\n')}
+UPDATE shop_bookings SET paid_at=(SELECT paid_at FROM shop_orders WHERE id=order_id),version=version+1 WHERE EXISTS(SELECT 1 FROM shop_orders WHERE id=order_id AND paid_at IS NOT NULL);
+`;
+const refusal=(message,status=400)=>Object.assign(new Error(message),{name:'StudioOperationError',status});
+const valid=v=>typeof v==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(v);
+const hash=async token=>Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(token))),b=>b.toString(16).padStart(2,'0')).join('');
+export async function ownedHold(env,caller,{id,token}){
+ if(!valid(id))throw refusal('Invalid booking id');
+ const row=await env.DB.prepare('SELECT * FROM shop_bookings WHERE id=?1').bind(id).first();
+ if(!row||!(caller.owner||row.actor&&row.actor===caller.id||row.token_hash&&typeof token==='string'&&await hash(token)===row.token_hash))throw refusal('Booking owner required',403);
+ if(caller.testScope&&!row.app.endsWith(':check:'+caller.testScope))throw refusal('Booking owner required',403);
+ return row;
+}
+/** A hold is the very row checkout later confirms. Secrets never enter its public projection. */
+export function bookingHolds(env,caller,cat){
+ const result=r=>({id:r.id,slot:r.slot,quantity:r.quantity,state:r.state,version:r.version,expiresAt:r.hold_until,paid:r.paid_at!==null,...(r.allocation&&r.allocation!=='[]'?{allocations:JSON.parse(r.allocation)}:{}),...(r.choices&&r.choices!=='{}'?{choices:JSON.parse(r.choices)}:{})});
+ const change=async(args,state)=>{
+  const row=await ownedHold(env,caller,args);
+  if(row.order_id!=='hold:'+row.id)throw refusal('Checkout owns this booking; reconcile payment before release');
+  if(!Number.isSafeInteger(args.version)||args.version<1)throw refusal('Booking version required');
+  const changed=await env.DB.prepare(`UPDATE shop_bookings SET state=?2,version=version+1,updated_at=?3 WHERE id=?1 AND version=?4 AND state IN ('held','confirmed') AND (?2='released' OR hold_until>?3) RETURNING *`).bind(row.id,state,Date.now(),args.version).first();
+  if(!changed)throw refusal('Booking changed or expired; reload',409);return result(changed);
+ };
+ return Object.freeze({
+  calendar({app,...options}){const meta=cat.games.find(g=>g.id===app&&g.kind==='app');if(!meta)throw refusal('Unknown app');return calendarSlots({timeZone:meta.timeZone,...options});},
+  async hold(input){
+   const args=normalizeBookingArgs(input);
+   let {app,collection,slot,quantity=1,id,token,expiresAt}=args;
+   const meta=cat.games.find(g=>g.id===app&&g.kind==='app'),spec=meta?.records?.collections?.[collection]?.booking;
+   if(!spec||!valid(id)||!valid(slot)||!Number.isSafeInteger(quantity)||quantity<1)throw refusal('Choose a declared slot, positive quantity and stable booking id');
+   if(!Number.isSafeInteger(expiresAt)||expiresAt<=Date.now())throw refusal('Hold needs a future expiry');
+   if(token!==undefined&&!(typeof token==='string'&&/^[a-f0-9]{32,128}$/.test(token)))throw refusal('Invalid private booking token');
+   if(!caller.id&&!token)throw refusal('Booking owner or private token required');
+   if(!hasStripeKey(env)&&linkConfig(env)?.slots?.some(l=>l.app===app&&l.slots===spec.slots&&l.slot===slot))throw refusal('Keyless Stripe inventory cannot share local holds; configure session checkout first');
+   const scope=caller.testScope?`${app}:check:${caller.testScope}`:app;
+   id=await hash(JSON.stringify([scope,collection,id]));
+   const choices={option:args.option??null,resource:args.resource??null,addons:args.addons??{}};
+   if(await env.DB.prepare('SELECT id FROM shop_bookings WHERE id=?1').bind(id).first()) {
+     const previous=await ownedHold(env,caller,{id,token});
+     if(previous.app!==scope||previous.collection!==collection||previous.slot!==slot||previous.quantity!==quantity||JSON.stringify({...choices,...JSON.parse(previous.choices??'{}')})!==JSON.stringify(choices))throw refusal('Booking id reused with different request',409);
+     return result(previous);
+   }
+   let allocation;try{allocation=await allocateResources(env,scope,spec,slot,args);}catch(error){throw refusal(error.message,409);}
+   const secret=token?await hash(token):null;
+   try {await env.DB.prepare(`INSERT INTO shop_bookings(id,app,collection,slots,slot,quantity,order_id,state,updated_at,actor,token_hash,hold_until,allocation,choices)
+    SELECT ?1,?2,?3,?4,?5,?6,'hold:'||?1,'held',?7,?8,?9,?10,?11,?12 WHERE NOT EXISTS(SELECT 1 FROM shop_bookings WHERE id=?1)`).bind(id,scope,collection,spec.slots,slot,quantity,Date.now(),caller.id??null,secret,expiresAt,JSON.stringify(allocation),JSON.stringify(choices)).run();}catch(error){if(/booking capacity unavailable|resource capacity unavailable/.test(error.message))throw refusal('That slot or resource capacity is unavailable. No place has been taken.',409);throw error;}
+   const row=await ownedHold(env,caller,{id,token});
+   if(row.app!==scope||row.collection!==collection||row.slot!==slot||row.quantity!==quantity||JSON.stringify(JSON.parse(row.choices??'{}'))!==JSON.stringify(choices))throw refusal('Booking id reused with different request',409);
+   return result(row);
+  },
+  async get(args){return result(await ownedHold(env,caller,args));},
+  confirm:args=>change(args,'confirmed'),release:args=>change(args,'released'),
+  async releaseExpired({app,collection,now=Date.now()}){
+   if(!caller.owner)throw refusal('Owner or scheduled function required');
+   if(!Number.isSafeInteger(now))throw refusal('Invalid release time');
+   const scope=caller.testScope?`${app}:check:${caller.testScope}`:app;
+   const r=await env.DB.prepare("UPDATE shop_bookings SET state='released',version=version+1,updated_at=?3 WHERE app=?1 AND collection=?2 AND order_id='hold:'||id AND state='held' AND hold_until<=?3").bind(scope,collection,now).run();return {released:r.meta.changes};
+  }
+ });
+}
+/** Used in the same transaction as the order reservation. A second checkout cannot claim the hold. */
+export function claimHoldStatement(env,{hold,app,collection,slots,slot,quantity,order,now=Date.now()}){
+ return env.DB.prepare(`UPDATE shop_bookings SET order_id=CASE WHEN app=?4 AND collection=?5 AND slots=?6 AND slot=?7 AND quantity=?8 THEN ?2 ELSE NULL END,version=version+1,updated_at=?3
+ WHERE id=?1
+ AND EXISTS(SELECT 1 FROM shop_orders WHERE id=?2)`).bind(hold,order,now,app,collection,slots,slot,quantity);
+}

package/worker/booking-options.mjs

@@ -0,0 +1,23 @@
+/** Shared by trusted booking tools and phone flows. Aliases never silently win. */
+export function normalizeBookingArgs(input) {
+ const args={...input};
+ for(const [canonical,aliases] of [['slot',['time']],['resource',['preferredResource','preferred_resource']],['addons',['addOns','add-ons']]]) {
+  for(const alias of aliases)if(args[alias]!==undefined) {
+   if(args[canonical]!==undefined&&JSON.stringify(args[canonical])!==JSON.stringify(args[alias]))throw Object.assign(new Error(`conflicting ${canonical}/${alias}`),{name:'StudioOperationError',status:400});
+   args[canonical]=args[alias];delete args[alias];
+  }
+ }
+ if(args.addons!==undefined) {
+  const list=Array.isArray(args.addons)?args.addons.map(id=>[id,1]):Object.entries(args.addons??{}),addons={};
+  for(const [id,count] of list) {
+   if(!/^[a-z][a-z0-9-]{0,39}$/.test(id)||!Number.isSafeInteger(count)||count<1||count>100)throw new Error('Invalid add-on id or quantity');
+   addons[id]=(addons[id]??0)+count;
+  }
+  args.addons=Object.fromEntries(Object.entries(addons).sort(([a],[b])=>a.localeCompare(b)));
+ }
+ return args;
+}
+
+const text={type:'string',maxLength:64};
+const addons={oneOf:[{type:'array',maxItems:100,items:text},{type:'object',additionalProperties:{type:'integer',minimum:1,maximum:100}}]};
+export const bookingInputSchema={type:'object',properties:{app:text,collection:text,slot:text,time:text,option:text,resource:text,preferredResource:text,preferred_resource:text,addons,addOns:addons,'add-ons':addons,quantity:{type:'integer',minimum:1},id:text,token:{type:'string',pattern:'^[a-f0-9]{32,128}$'},expiresAt:{type:'integer'}},required:['app','collection','id','expiresAt'],additionalProperties:false};