@homie-rocks/studio 0.50.6 → 0.51.0

package/shop/SHOP.md

@@ -108,7 +108,7 @@ If the studio is not deployed yet, approval is retained: deploy with `studio_dep
 `cloudflare_login` first if needed), then rerun connect. Webhooks require the deployed HTTPS address.
 
 **The default is keyless.** Connect syncs one Product and Price for each shop.json item and one
-Payment Link for each paid item. Tip Prices use custom amounts; free orders stay local. It creates
+Payment Link for each paid item, adjustable-quantity menus, and one capacity-limited link per published booking slot. Tip Prices use custom amounts; free orders stay local. It creates
 an account webhook at `<site>/api/shop/hook`, captures its signing secret without displaying it,
 and installs `STRIPE_WEBHOOK_SECRET` and `STRIPE_SHOP_LINKS` through Wrangler stdin. No Stripe
 API key goes into the Worker. Repeat connect after editing shop.json: changed prices get new
@@ -132,7 +132,7 @@ items; failed refunds restore the financial booking. A lost dispute revokes good
 
 | Need | Keyless behavior / fuller connection |
 |---|---|
-| Several different items in one payment | Buy separately. Stripe supports static multi-item links (up to 20 fixed-price lines), but they are not an arbitrary buyer cart. Dynamic carts use the keyed path. |
+| Several different items in one payment | A synced menu opens several fixed-price lines; guests choose quantities on Stripe, including zero. Stripe limits Payment Links to 20 lines; larger catalogues use separate menus. Custom amounts and subscriptions keep separate links. |
 | Reserve an optional spending allowance | Requires keyed Checkout; a reusable public link cannot atomically reserve this studio's local cap. No silent weakening of a configured cap. |
 | Expire an abandoned session | Stripe controls the lifetime; deactivating a link prevents new sessions, not existing sessions. Custom expiry/cancellation requires the keyed path. |
 | Refund in one tap / player self-refund | Owner uses Stripe Dashboard or asks their Stripe-connected AI. Signed events update books. Office shows guidance instead of a paid-order refund button. Free refunds remain local. |
@@ -142,8 +142,7 @@ items; failed refunds restore the financial booking. A lost dispute revokes good
 | Managed Payments | Payment Links support managed_payments.enabled; connect uses it when the studio selects Stripe as seller, subject to Stripe eligibility and terms. |
 | Currency display | Payment Links always enable Stripe Adaptive Pricing. Bookkeeping uses integration currency; presentment details describe what the customer saw. |
 
-An existing `STRIPE_KEY` selects the fuller path automatically. Only if requested, explain:
-“The fuller connection adds combined carts, spending limits, automatic recovery and refunds here.”
+A key alone never selects the fuller path. It requires explicit `STRIPE_CHECKOUT_MODE=sessions` as well as a Worker key. Only if requested, explain: “The optional session connection adds exact app-built carts, spending reservations, expiring holds and runtime refunds.”
 The explicit `shop connect --manual` path remains available, including `--live`, but requires the
 owner's existing Dashboard key step; it does not satisfy one approval. Never choose it automatically.
 Running default connect again saves links, removes the API key, and keeps signed-event fulfillment.
@@ -202,7 +201,7 @@ the full amount toward a cap. The additive schema preserves its original rows an
 
 ## Shop button on the screen
 
-An open shop with items for this game or app shows **Shop** above its play/open screen. The shell reserves 52 pixels plus the safe area above the content, so the button never covers its controls. In `game.json` or `app.json`, set `"screen": { "shop": false }` to hide this button (merge with any existing screen settings). The room panel and your own shop buttons still work. Closed shops, kids policies and an empty selection show no button.
+An open shop with items for this game or app shows **Shop** above its play/open screen. The shell reserves 52 pixels plus the safe area above the content, so the button never covers its controls. In `game.json` or `app.json`, set `"screen": { "shop": false }` to disable the experience’s shop (merge with any existing screen settings). Keep it true or omitted when your app uses its own `createShop` buttons; false also refuses their checkout bridge requests. Closed shops, kids policies and an empty selection show no button.
 
 ```ts
 import { createShop } from '@homie-rocks/studio/shop';
@@ -218,3 +217,119 @@ These calls open the same shop in games and apps. Inside a player card, purchase
 Create the booking/ticket/gift intention first. `shop.buy('full-tune', 1, undefined, { reference: booking.id })` or `shop.checkout({ reference: booking.id })` sends the app's own reference through checkout. Existing boolean returns are unchanged: checkout opened is not paid. The verified durable `order.paid` event carries `data.order`, `data.reference` (null if omitted) and `data.app`. Reopened Payment Links retain the reference. A reference is buyer-supplied correlation, not authorization: verify the record, app, amount and currency, deduplicate by event/order ID, then fulfil it. Keep personal data out of references. Before Stripe is connected, local prices and unpaid requests can be demonstrated; actual payment and recurring collection remain unverified. Test events must be labelled simulations.
 
 For referrals, use Stripe Connect to split payments or a Stripe-based affiliate service; Homie builds none.
+
+## Keyless menus, paid seats and monthly giving (0.51.0)
+
+Use `shop connect` by default. All objects belong to the owner's Stripe account and
+are created through its approved CLI session. Homie has no platform key, OAuth
+backend, payment intermediary or cut. A desktop is needed to sync, not to take money.
+
+**A round to table 7:** declare fixed-price drinks in shop.json and run connect.
+
+```ts
+shop.add('negroni', 2);
+shop.add('spritz', 1);
+await shop.checkout({ reference: 'table-7' });
+```
+
+The default opens the synced Stripe menu containing those items. The guest chooses
+final quantities **on Stripe**, starting at one for each menu line; the local cart's
+quantities are not prefilled. Adjustable quantity minimum is zero (Stripe prevents
+removing the last item). Payment Links support at most 20 lines. Keyless sync splits catalogues into menus of ten to fit signed invoice snapshots without authenticated pagination. Split larger menus;
+if selected items span menus, the app receives `menu` and should offer separate
+checkouts. Custom amounts cannot be mixed into this menu; offer a separate tip link.
+Stripe invoice creation is enabled for menus (Stripe's invoice pricing applies).
+Only signed paid invoice lines supply `order.paid.data.lines`, including actual
+item, quantity and amount; no quantity is guessed from the total. Incomplete invoice
+snapshots remain pending for recovery rather than granting a guessed order.
+
+The opaque local order ID is `client_reference_id`; its durable reference maps back
+to `table-7` in `order.paid.data.reference` and the buyer's order response. No personal
+data goes in that reference. A return URL is never proof of payment.
+
+**Book a tune; the seat is held only when paid:** declare a staff-written `slots`
+collection with integer `capacity` and a server-managed `bookings` collection with
+`"booking":{"slots":"slots","item":"full-tune"}`. Publish slot records, then have
+the owner's AI write the complete manifest to `.studio/booking-slots.json` and run
+`shop connect`, or call local MCP `stripe_bookings_sync` with the same `slots` array:
+
+```json
+[{"app":"tune","collection":"bookings","slots":"slots","slot":"sat-0900","item":"full-tune","capacity":1}]
+```
+
+Sync after publishing or changing slots. Removed or inactive slots deactivate their
+links. Each link has `restrictions.completed_sessions.limit = capacity`, with one
+fixed service and one seat per checkout. Re-sync preserves Stripe's lifetime completed
+count. Free slots stay local and use separate slot records from paid links. Never increment capacity just to hide a full-link error.
+Refunds do not decrement Stripe's completed-session counter; the owner's AI must
+review availability and resync explicitly. A changed price should use a new slot;
+do not replace a sold link and accidentally reset its capacity counter.
+
+```ts
+const result = await shop.book('full-tune', {collection:'bookings',slot:'sat-0900'});
+// result.booking is the tracking record ID.
+```
+
+Opening the link creates local `pending` state, best effort. It does **not** block
+other guests. Confirmed payment creates `confirmed`; expiry/failure/refund releases
+the local record. The app must say “Pay to secure your seat,” not promise an exclusive
+unpaid hold. Slot reads expose `record.booking.full`, `available` and `synced` for the
+UI; Stripe's full-link update and verified confirmations make the app show Full.
+Events include `booking.pending`, `.confirmed`, `.released`, `.moved`; free and
+explicit keyed bookings also use `.held`. Before staff moves, the owner's AI syncs **both affected slots** with `active:false`;
+sync deactivates their links and expires open sessions. Wait for signed payment events,
+then staff makes the versioned `{slot:...}` update. Moving into an unpaused paid target
+is refused. Read fresh confirmed booking counts and sync each affected slot with
+`confirmed:<count>` and `active:true`. Sync adjusts the lifetime completion budget to
+`Stripe completed + capacity - confirmed` (initial publication uses capacity exactly).
+This also reopens refunded availability after an explicit review. Never use a stale
+confirmed count or skip pausing: local staff movement cannot mutate Stripe by itself.
+An explicit keyed session connection retains exclusive expiring unpaid holds.
+
+**Give $20 monthly:** `shop init --giving --currency CAD` includes fixed suggested
+monthly gifts. Declare a recurring item, then run connect:
+
+```json
+{"id":"monthly-gift","kind":"donation","name":"Give $20 monthly","price":2000,"interval":"month","gives":[]}
+```
+
+`shop.buy('monthly-gift',1,undefined,{reference:'gift-20'})` opens a recurring Price
+on a Payment Link (subscription mode). The giver chooses among the preset options.
+Arbitrary custom monthly amounts require the explicitly selected keyed connection;
+never silently request it or ask the person to find/paste a key. One-time custom
+amounts remain keyless. `giving.receiptText` is the owner's receipt wording.
+
+Signed `subscription.started`, `.renewed`, `.failed`, `.cancelled` events drive
+membership and giving. Membership access ends at the paid invoice line's period end;
+failed invoices cannot extend it and cancellation ends access. Unknown Prices grant
+nothing. Keyless portal configuration supports cancellation, payment-method updates
+and invoice history. `shop connect` enables `login_page.enabled` through the CLI API
+and stores Stripe's no-code login URL; **no Dashboard toggle is required**. Givers
+verify their email with Stripe to manage/cancel. The buyer-owned `/api/shop/portal`
+returns this URL. Plan changes require deliberate portal configuration and fulfilment
+mapping; the optional keyed path retains current-provider reconciliation for upgrades.
+
+For offline development, import `startStripeFixture` from the installed toolkit's
+`lib/dev-stripe-fixture.mjs`, start it with `{origin:'http://127.0.0.1:8787'}`, and
+write its `bindings` as local Wrangler `.dev.vars` in a disposable studio. Keep it
+running alongside `homie-studio dev`. The checkout page explicitly says simulation;
+it takes no card and no money. Call `close()` and delete the disposable studio when
+finished. This tests signed webhook plumbing, not Stripe account permissions.
+
+The giving starter now reads the actual shop donation options with `shop.catalog()`.
+`shop init --giving --currency CAD` includes $20 monthly; `app new giving --from giving`
+opens Checkout for the selected amount and frequency. A disconnected shop displays
+a disabled preview. No intention record or unverified collected total is created.
+Use the Manage my gifts link for the buyer-owned Stripe portal in the shop.
+
+For real sandbox acceptance without copying any API key, import `startKeylessStripeSandbox`
+from `lib/dev-stripe-sandbox.mjs` and pass `{origin, profile, shop, bookingSlots}` with an explicit
+sandbox CLI profile and loopback studio origin. It drives only that profile's
+Stripe CLI, starts `stripe listen --forward-to` with the required events, and
+returns local dev `bindings` and `close()`. Keep bindings private: the webhook
+signing secret is real even in test mode. The keyless helper encodes link configuration for safe .dev.vars transport; do not decode or rewrite that binding. Use the helper’s `links` property for native link IDs when testing. `await helper.sync(manifest)` updates its `links` and `bindings`; save the new bindings and restart dev after a slot sync. `close()` deactivates its sandbox links and stops forwarding. Supply them to the local dev harness
+only, never source control or logs. The local webhook forwarding listener needs the desktop; production uses the signed public webhook directly. No API adapter or key is installed in the keyless Worker. It never exports CLI credentials.
+Use Stripe's published CLI test fixtures/tokens to complete Checkout via API;
+never type card details into a form. Stop on an expired profile and ask the owner
+to approve `stripe login --project-name <profile>` once. Stop the adapter and remove
+dev bindings and disposable studios when finished.

package/shop/shop.ts

@@ -44,10 +44,19 @@ export interface ShopOptions {
 
 export interface CartLine { item: string; quantity: number; amount?: number }
 
+export interface ShopCatalog {
+  open: boolean;
+  currency: string;
+  currencyScale: number;
+  items: Array<{ id: string; kind: string; name: string; interval?: 'month'; price: number | 'choose'; min?: number; max?: number | null; shown: string; way: string }>;
+}
+
 export interface Shop {
   /** Resolves once the shell answered (or after `timeoutMs` with no shell: an empty, closed shop). */
   readonly ready: Promise<ShopState>;
   readonly state: ShopState;
+  /** Current gift/item options and payment readiness, without exposing account details. */
+  catalog(): Promise<ShopCatalog>;
   /** Whether the player owns this entitlement key now ("skin:ember", "badge:supporter"). Synchronous, for a render loop. */
   has(key: string): boolean;
   /** Every key the player owns now. */
@@ -61,6 +70,8 @@ export interface Shop {
   add(item: string, quantity?: number, amount?: number): void;
   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 }>;
   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. */
@@ -121,6 +132,20 @@ export function createShop(opts: ShopOptions = {}): Shop {
   let cart: CartLine[] = [];
   const shop: Shop = {
     ready,
+    catalog: async () => {
+      const result: ShopCatalog = { open: false, currency: 'usd', currencyScale: 100, items: [] };
+      let cursor: string | undefined;
+      do {
+        const m = await send({ op: 'catalog', cursor });
+        if (!m.ok) return result;
+        result.open = Boolean(m.open);
+        result.currency = String(m.currency ?? 'usd');
+        result.currencyScale = Number(m.currencyScale) || 100;
+        if (Array.isArray(m.items)) result.items.push(...m.items as ShopCatalog['items']);
+        cursor = typeof m.nextCursor === 'string' ? m.nextCursor : undefined;
+      } while (cursor);
+      return result;
+    },
     get state() { return { ...state }; },
     has: (key) => owns.includes(String(key)),
     entitlements: () => owns.slice(),
@@ -129,6 +154,10 @@ 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 }] });
+      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; },
     buy: async (item, quantity = 1, amount, options = {}) => Boolean((await send({ op: 'checkout', reference: options.reference, lines: [{ item, quantity, ...(amount === undefined ? {} : { amount }) }] })).ok),
     close: () => { void send({ op: 'close' }); },

package/tools/tools.ts

@@ -7,7 +7,14 @@ export interface ToolContext {
   office(path: string, body?: Record<string, unknown>, query?: Record<string, string>): Promise<unknown>;
   shop(): Promise<unknown>;
   rooms: { send(event: {game: string; room: string; event: string; data: unknown}): Promise<unknown> };
-  database: { get(key: string): Promise<unknown>; put(key: string, value: unknown): Promise<void> };
+  database: {
+    get(key: string): Promise<unknown>;
+    getVersioned(key: string): Promise<{value: unknown; version: number} | null>;
+    put(key: string, value: unknown, options?: {version?: number}): Promise<{ok: boolean; version?: number; conflict?: boolean}>;
+    increment(key: string, amount?: number): Promise<{value: number; version: number}>;
+    append(key: string, value: unknown): Promise<{value: unknown[]; version: number}>;
+    list(options?: {prefix?: string; after?: string; limit?: number}): Promise<{items: {key: string; value: unknown; version: number}[]; next: string | null}>;
+  };
   fetch: typeof fetch;
   fetchWithSecret(name: string, url: string, init?: RequestInit): Promise<Response>;
   ai(model: string, input: unknown): Promise<unknown>;

package/worker/app-format.mjs

@@ -18,7 +18,13 @@ 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 (!key.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`);
+    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 [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 (!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 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`);
@@ -32,6 +38,7 @@ export function appRole(meta, url) {
 }
 export function recordProblem(collection, data, { create = false } = {}) {
   if (!object(data) || JSON.stringify(data).length > 8192) return 'record must be an object below 8 KB';
+  for (const k of Object.keys(data)) if (!/^[a-z][a-z0-9_]*$/.test(k)) return `invalid field ${k}: names start with a lowercase letter and use lowercase letters, digits and underscore`;
   for (const k of Object.keys(data)) if (!Object.hasOwn(collection.fields, k)) return `unknown field ${k}`;
   for (const [k, s] of Object.entries(collection.fields)) {
     const v = data[k];

package/worker/app-frame.mjs

@@ -0,0 +1,9 @@
+/** Opaque frames retain their isolation. Unavailable Web Storage falls back to frame-local memory. */
+export const APP_STORAGE_JS=String.raw`(()=>{
+ for(const name of ['localStorage','sessionStorage']) {
+  try {const storage=window[name];const probe='homie-storage-probe';storage.setItem(probe,'1');storage.removeItem(probe);continue;}catch{}
+  const data=new Map();const methods={getItem:k=>data.get(String(k))??null,setItem:(k,v)=>{data.set(String(k),String(v));},removeItem:k=>{data.delete(String(k));},clear:()=>data.clear(),key:i=>[...data.keys()][Number(i)]??null};
+  const storage=new Proxy(methods,{get:(target,key)=>key==='length'?data.size:key in target?target[key]:data.get(String(key)),set:(_,key,value)=>{data.set(String(key),String(value));return true;},deleteProperty:(_,key)=>data.delete(String(key)),ownKeys:()=>[...data.keys()],getOwnPropertyDescriptor:()=>({enumerable:true,configurable:true})});
+  Object.defineProperty(window,name,{value:storage,configurable:true});
+ }
+})();`;

package/worker/app-records.mjs

@@ -1,3 +1,6 @@
+import { linkConfig } from './shop-links.mjs';
+import {localSession} from './local-test.mjs';
+import { moveBooking } from './booking-store.mjs';
 import { toolIdentity } from './tool-identity.mjs';
 /** Lasting app records in the studio's own D1. Room hosts never authorize writes. */
 import { appRole, recordProblem } from './app-format.mjs';
@@ -38,12 +41,14 @@ export async function appAccess(request, env, meta, url) {
   const declared = Object.hasOwn(meta.roles ?? {}, role) ? meta.roles[role] : null;
   if (!declared) return { ok: false, status: 404, error: 'unknown role' };
   if (!declared.signIn) return { ok: true, role, can: declared.can };
+  const session = await localSession(request, env);
+  if (session?.app === meta.id && session.role === role) return {ok:true,role,can:declared.can};
   if (!env.DB) return { ok: false, status: 503, error: 'app roles need the studio database' };
   const caller = toolIdentity(request);
   if (caller) {
     if (caller.owner) 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 = ?1 AND role = ?2 AND player = ?3').bind(meta.id, role, caller.id).first();
+    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' };
   }
   const link = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, role).first();
@@ -51,7 +56,7 @@ export async function appAccess(request, env, meta, url) {
   if (await isOwner(request, env)) return { ok: true, role, can: declared.can };
   const person = await players.of(request, env);
   if (!person || person.guest) return { ok: false, status: 401, error: 'sign in to this studio' };
-  const grant = await env.DB.prepare('SELECT player FROM app_roles WHERE app = ?1 AND role = ?2 AND player = ?3').bind(meta.id, role, person.id).first();
+  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, person.id).first();
   return grant ? { ok: true, role, can: declared.can } : { ok: false, status: 403, error: 'this account has no role grant' };
 }
 export async function appRecordsRoute(request, env, meta, url, sub) {
@@ -69,39 +74,63 @@ export async function appRecordsRoute(request, env, meta, url, sub) {
         if (!ID.test(b.player)) return fail(400, 'invalid account');
         const p = await players.get(b.player, env);
         if (!p || p.guest) return fail(400, 'role grants require an existing signed-in account');
-        await env.DB.prepare(b.revoke === true ? 'DELETE FROM app_roles WHERE app = ?1 AND role = ?2 AND player = ?3' : 'INSERT OR IGNORE INTO app_roles (app, role, player) VALUES (?1, ?2, ?3)').bind(meta.id, b.role, b.player).run();
+        await env.DB.prepare(b.revoke === true ? 'DELETE FROM app_roles WHERE app = ?1 AND role = ?2 AND player = ?3' : 'INSERT OR IGNORE INTO app_roles (app, role, player) VALUES (?1, ?2, ?3)').bind(b.studio === true ? '*' : meta.id, b.role, b.player).run();
       }
       const token = crypto.randomUUID().replaceAll('-', '');
       if (b.rotate === true) await env.DB.prepare('DELETE FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).run();
       await env.DB.prepare('INSERT OR IGNORE INTO app_role_links (app, role, token) VALUES (?1, ?2, ?3)').bind(meta.id, b.role, token).run();
       const row = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).first();
-      return json({ ok: true, link: `${url.origin}/${meta.id}/open?role=${b.role}&access=${row.token}`, role: b.role });
+      return json({ ok: true, link: `${url.origin.replace('127.0.0.1','localhost')}/${meta.id}/open?role=${b.role}&access=${row.token}`, role: b.role });
     }
     const match = /^api\/app\/records\/([a-z][a-z0-9-]{0,39})(?:\/([A-Za-z0-9_-]{1,64}))?$/.exec(sub);
+    if(!match && /^api\/app\/records\/[^/]+\//.test(sub))return fail(400,'record id: 1–64 letters, digits, underscore or hyphen');
     if (!match || !Object.hasOwn(meta.records?.collections ?? {}, match[1])) return fail(404, 'unknown collection');
     if (meta.records.persist !== true) return fail(409, 'use netplay state for transient records, or enable records.persist');
     const access = await appAccess(request, env, meta, url);
     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 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');
     if (op !== 'read' && !sameOrigin(request, url) && !(appOriginOf(request) && !meta.roles[access.role].signIn)) return fail(403, 'same origin required');
     if (op === 'read') {
-      const rows = id ? [await env.DB.prepare('SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 AND id = ?3').bind(meta.id, collection, id).first()].filter(Boolean)
-        : (await env.DB.prepare('SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 ORDER BY updated_at, id LIMIT 1000').bind(meta.id, collection).all()).results;
-      return json({ ok: true, records: rows.map((r) => ({ id: r.id, data: JSON.parse(r.value), version: r.version, updatedAt: r.updated_at })) });
+      const rows = id ? [await env.DB.prepare('SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 AND id = ?3').bind(recordApp, collection, id).first()].filter(Boolean)
+        : (await env.DB.prepare('SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 ORDER BY updated_at, id LIMIT 1000').bind(recordApp, collection).all()).results;
+      const records=[];
+      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(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();
+          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');
     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');
+      if (!Number.isSafeInteger(body.version) || !ID.test(body.data?.slot ?? '') || Object.keys(body.data ?? {}).some(k => k !== 'slot')) return fail(400, 'move requires slot and current version');
+      const moved = await moveBooking(env, { app: recordApp, collection, id, slot: body.data.slot, version: body.version });
+      return moved ? json({ ok: true, id, version: body.version + 1 }) : fail(409, 'booking changed or is released; reload');
+    }
     if (op !== 'delete') { const bad = recordProblem(meta.records.collections[collection], body.data, { create: op === 'create' }); if (bad) return fail(400, bad); }
     if (op !== 'create' && (!Number.isSafeInteger(body.version) || body.version < 1)) return fail(400, 'record version required');
     const stmt = op === 'create'
-      ? env.DB.prepare('INSERT OR IGNORE INTO app_records (app, collection, id, value, version, updated_at) SELECT ?1, ?2, ?3, ?4, 1, ?5 WHERE (SELECT COUNT(*) FROM app_records WHERE app = ?1 AND collection = ?2) < 1000').bind(meta.id, 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(meta.id, 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(meta.id, collection, id, body.version);
+      ? env.DB.prepare('INSERT OR IGNORE INTO app_records (app, collection, id, value, version, updated_at) SELECT ?1, ?2, ?3, ?4, 1, ?5 WHERE (SELECT COUNT(*) FROM app_records WHERE app = ?1 AND collection = ?2) < 1000').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();
     return result.meta.changes ? json({ ok: true, id, version: op === 'create' ? 1 : body.version + 1 }) : fail(409, 'record changed, already exists, or collection full; reload');
   } catch (error) {
+    if (/booking capacity|capacity below|slot has active/.test(error.message)) return fail(409, error.message);
     if (error instanceof SyntaxError || error.message === 'body too large') return fail(400, error.message);
     return fail(503, 'app database unavailable; apply studio migrations');
   }

package/worker/booking-store.mjs

@@ -0,0 +1,79 @@
+import { linkConfig, hasStripeKey } from './shop-links.mjs';
+/** Capacity belongs to the studio database. Checkout expiry is a provider fact,
+ * never an inference from a browser return or the local clock. */
+export const BOOKINGS_MIGRATION_FILE = '0025_bookings.sql';
+export const BOOKINGS_MIGRATION = `
+CREATE TABLE shop_bookings (
+ id TEXT PRIMARY KEY, app TEXT NOT NULL, collection TEXT NOT NULL,
+ slots TEXT NOT NULL, slot TEXT NOT NULL, quantity INTEGER NOT NULL CHECK(quantity > 0),
+ order_id TEXT NOT NULL UNIQUE, state TEXT NOT NULL DEFAULT 'held'
+ CHECK(state IN ('pending','held','confirmed','released')),
+ version INTEGER NOT NULL DEFAULT 1, updated_at INTEGER NOT NULL
+);
+CREATE INDEX shop_bookings_capacity ON shop_bookings(app, slots, slot, state);
+CREATE TRIGGER booking_capacity_insert BEFORE INSERT ON shop_bookings WHEN NEW.state != 'pending' 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 state IN ('held','confirmed'))
+ );
+END;
+CREATE TRIGGER booking_capacity_move BEFORE UPDATE OF slot 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_slot_update BEFORE UPDATE OF value ON app_records
+WHEN EXISTS (SELECT 1 FROM shop_bookings WHERE app=OLD.app AND slots=OLD.collection AND slot=OLD.id AND state IN ('held','confirmed')) BEGIN
+ SELECT RAISE(ABORT,'capacity below existing bookings') WHERE json_type(NEW.value,'$.capacity') IS NOT 'integer' OR json_extract(NEW.value,'$.capacity') <
+  (SELECT SUM(quantity) FROM shop_bookings WHERE app=OLD.app AND slots=OLD.collection AND slot=OLD.id AND state IN ('held','confirmed'))
+;
+END;
+CREATE TRIGGER booking_slot_delete BEFORE DELETE ON app_records
+WHEN EXISTS (SELECT 1 FROM shop_bookings WHERE app=OLD.app AND slots=OLD.collection AND slot=OLD.id AND state IN ('held','confirmed')) BEGIN
+ SELECT RAISE(ABORT,'slot has active bookings');
+END;
+CREATE TRIGGER booking_order_state AFTER UPDATE OF status ON shop_orders BEGIN
+ UPDATE shop_bookings SET state=CASE WHEN NEW.status='paid' THEN 'confirmed' ELSE 'released' END,
+ version=version+1, updated_at=NEW.updated_at
+ WHERE order_id=NEW.id AND ((state IN ('pending','held') AND NEW.status IN ('paid','expired','failed')) OR (state IN ('pending','held','confirmed') AND NEW.status IN ('refunded','lost')));
+END;
+${['INSERT', 'UPDATE'].map(op => `CREATE TRIGGER booking_record_${op.toLowerCase()} AFTER ${op} ON shop_bookings BEGIN
+ INSERT INTO app_records(app,collection,id,value,version,updated_at)
+ VALUES(NEW.app,NEW.collection,NEW.id,json_object('slot',NEW.slot,'quantity',NEW.quantity,'state',NEW.state),NEW.version,NEW.updated_at)
+ ON CONFLICT(app,collection,id) DO UPDATE SET value=excluded.value,version=excluded.version,updated_at=excluded.updated_at;
+ INSERT OR IGNORE INTO studio_events(id,type,data,at)
+ SELECT 'booking:' || NEW.id || ':' || NEW.version,'booking.' || ${op === 'INSERT' ? "NEW.state" : "CASE WHEN OLD.slot!=NEW.slot THEN 'moved' ELSE NEW.state END"},
+ json_object('booking',NEW.id,'app',NEW.app,'collection',NEW.collection,'slot',NEW.slot,'state',NEW.state,'quantity',NEW.quantity,'order',NEW.order_id,'version',NEW.version),NEW.updated_at
+ WHERE EXISTS(SELECT 1 FROM function_subscriptions WHERE type='booking.' || ${op === 'INSERT' ? "NEW.state" : "CASE WHEN OLD.slot!=NEW.slot THEN 'moved' ELSE NEW.state END"});
+END;`).join('\n')}
+DROP TRIGGER IF EXISTS shop_orders_function_paid;
+CREATE TRIGGER shop_orders_function_paid AFTER UPDATE ON shop_orders
+WHEN EXISTS (SELECT 1 FROM function_subscriptions WHERE type='order.paid')
+ AND OLD.paid_at IS NULL AND NEW.paid_at IS NOT NULL
+ AND NOT EXISTS (SELECT 1 FROM purchase_orders WHERE id=NEW.id) BEGIN
+ INSERT OR IGNORE INTO studio_events(id,type,data,at)
+ VALUES('shop_orders:' || NEW.id || ':paid','order.paid',
+ json_object('order',NEW.id,'source','shop_orders','amount',NEW.amount,'currency',NEW.currency,'mode',NEW.mode,
+ 'app',NEW.game,'reference',(SELECT value FROM meta WHERE key='shop-reference:' || NEW.id),
+ 'lines',json((SELECT json_group_array(json_object('item',item,'quantity',quantity,'amount',amount,'total',total)) FROM shop_order_lines WHERE order_id=NEW.id))),NEW.paid_at);
+END;
+`;
+
+export function bookingStatement(env, { id, app, collection, slots, slot, quantity, order, pending = false, now = Date.now() }) {
+  return env.DB.prepare(`INSERT INTO shop_bookings(id,app,collection,slots,slot,quantity,order_id,updated_at,state)
+    SELECT ?1,?2,?3,?4,?5,?6,?7,?8,?9 WHERE EXISTS(SELECT 1 FROM shop_orders WHERE id=?7)`).bind(id, app, collection, slots, slot, quantity, order, now, pending ? 'pending' : 'held');
+}
+
+/** Staff movement uses the same version contract as app records. */
+export async function moveBooking(env, { app, collection, id, slot, version }) {
+  const target=linkConfig(env)?.slots?.find(l=>l.app===app&&l.collection===collection&&l.slot===slot);
+  if(!hasStripeKey(env) && target && !target.paused)throw new Error('booking capacity: ask the owner’s AI to pause the target slot and expire open links before moving; then sync confirmed seat counts');
+  const result = await env.DB.prepare(`UPDATE shop_bookings SET slot=?4,version=version+1,updated_at=?6
+    WHERE app=?1 AND collection=?2 AND id=?3 AND version=?5 AND state IN ('held','confirmed')`)
+    .bind(app, collection, id, slot, version, Date.now()).run();
+  return result.meta.changes > 0;
+}

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.50.6","sha256":"8aabf4298c649e24766b5dbd5836625be78a4c69c1005c221d93d4c9e4e45b3e"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.51.0","sha256":"5a8e0df9f204fbe4978d618b507fe5ae0c5005ef4f106ac4b78dfac5f6c02b7b"});

package/worker/event-resources.mjs

@@ -17,7 +17,7 @@ export async function readableFeed(env,cat,caller,name) {
     if(!app||!app.records?.collections?.[feed.collection])return false;
     if(caller.owner)return true;
     if(launchOf(app,await settingsOf(env,{fresh:true}),env)!=='public')return false;
-    return Object.entries(app.roles??{}).some(([role,decl])=>decl.can.includes('read:'+feed.collection)&&(!decl.signIn||caller.roles?.[app.id]?.includes(role)));
+    return Object.entries(app.roles??{}).some(([role,decl])=>decl.can.includes('read:'+feed.collection)&&(!decl.signIn||(caller.roles?.[app.id]?.includes(role)||caller.roles?.['*']?.includes(role))));
   }
   // Non-record events have no app read capability; they remain owner-only.
   return caller.owner===true;
@@ -56,12 +56,14 @@ export async function pushEvents(env,cat,origin) {
 }
 
 /** One existing Lobby object per OAuth connection: streams never live in a Worker isolate. */
+const streamCaller=(env,connection)=>connection.startsWith('public:')?Promise.resolve({id:null,owner:false,client:null,connection}):currentCaller(env,{connection});
 export class EventStreams {
   constructor(env,ctx){this.env=env;this.ctx=ctx;this.stream=null;this.tail=Promise.resolve();}
-  close(stream){stream.cancelled=true;stream.resume?.();try{stream.controller.close();}catch{}if(this.stream===stream)this.stream=null;}
+  close(stream){stream.cancelled=true;stream.resume?.();try{stream.controller.close();}catch{}if(this.stream===stream){this.stream=null;this.ctx.waitUntil(this.env.DB.prepare('DELETE FROM mcp_kv WHERE key=?1').bind('tools-stream:'+stream.connection).run().catch(()=>{}));}}
   background(input){this.ctx.waitUntil(this.wake(input).catch(error=>{if(this.stream)this.close(this.stream);console.error('Event stream delivery failed',error);}));}
   async fetch(request) {
     const input=await request.json();
+    if(input.op==='tools') {await this.wake(input);return new Response(null,{status:204});}
     if(input.op==='stream') {
       // A reconnect replaces the previous GET, including a half-open socket.
       if(this.stream)this.close(this.stream);
@@ -73,6 +75,10 @@ export class EventStreams {
       const stream={...input,after,name,controller:null,cancelled:false,resume:null};
       const body=new ReadableStream({start:controller=>{stream.controller=controller;controller.enqueue(new TextEncoder().encode(': connected\n\n'));},pull:()=>{const resume=stream.resume;stream.resume=null;resume?.();},cancel:()=>this.close(stream)});
       this.stream=stream;
+      const caller=await streamCaller(this.env,connection).catch(()=>null);
+      if(!caller){this.close(stream);return new Response('Unauthorized',{status:401});}
+      stream.toolSignature=await this.toolSignature(input.tools??[],caller);
+      await this.env.DB.prepare('INSERT INTO mcp_kv(key,value) VALUES(?1,?2) ON CONFLICT(key) DO UPDATE SET value=excluded.value').bind('tools-stream:'+connection,JSON.stringify({connection})).run();
       // Replay and later wakes share one ordered pump. Backpressure must not
       // hold up the writer's request or a function handler.
       this.background(input);
@@ -81,11 +87,16 @@ export class EventStreams {
     this.background(input);return new Response(null,{status:204});
   }
   wake(input){const work=this.tail.then(()=>this.deliver(input));this.tail=work.catch(()=>{});return work;}
+  async toolSignature(tools,caller) {const visible=[];for(const tool of tools)if(await allowed(tool.audience,caller,this.env))visible.push(tool);return JSON.stringify(visible);}
   async deliver(input) {
     const stream=this.stream;if(!stream)return;
     let caller;
-    try{caller=await currentCaller(this.env,{connection:input.connection});}
+    try{caller=await streamCaller(this.env,input.connection);}
     catch{this.close(stream);return;}
+    if(input.tools){
+      const signature=await this.toolSignature(input.tools,caller);
+      if(stream.toolSignature!==signature){stream.toolSignature=signature;stream.controller.enqueue(new TextEncoder().encode('event: message\ndata: '+JSON.stringify({jsonrpc:'2.0',method:'notifications/tools/list_changed'})+'\n\n'));}
+    }
     const rows=(await this.env.DB.prepare("SELECT value FROM mcp_kv WHERE key LIKE ?1").bind('event-sub:'+caller.connection+':%').all()).results;
     const subscriptions=[];
     for(const row of rows){const sub=JSON.parse(row.value);if(await readableFeed(this.env,input.cat,caller,sub.name))subscriptions.push(sub);}
@@ -114,3 +125,19 @@ export class EventStreams {
     }
   }
 }
+
+/** Refresh active streams whenever this Worker observes a new tool catalogue. */
+export async function pushToolList(env,cat,tools,origin) {
+  if(!env.LOBBY)return;
+  const publicShape=tools.map(({name,description,inputSchema,audience,kind})=>({name,description,inputSchema,audience,kind}));
+  const signature=JSON.stringify(publicShape);
+  const previous=await env.DB.prepare("SELECT value FROM mcp_kv WHERE key='tools-catalogue'").first();
+  if(previous?.value===signature)return;
+  await env.DB.prepare("INSERT INTO mcp_kv(key,value) VALUES('tools-catalogue',?1) ON CONFLICT(key) DO UPDATE SET value=excluded.value").bind(signature).run();
+  let after='';
+  for(;;){
+    const rows=(await env.DB.prepare("SELECT key,value FROM mcp_kv WHERE key LIKE 'tools-stream:%' AND key>?1 ORDER BY key LIMIT 100").bind(after).all()).results;
+    for(const row of rows){const connection=JSON.parse(row.value).connection;await eventHub(env,connection).fetch('https://events/__studio_events',{method:'POST',body:JSON.stringify({op:'tools',connection,cat,tools:publicShape,origin})});}
+    if(rows.length<100)break;after=rows.at(-1).key;
+  }
+}

package/worker/functions.mjs

@@ -74,8 +74,11 @@ export async function runFunctions(env, cat, origin, {definitions, now = Date.no
         if (!claimed.meta.changes) continue;
         let failure=null;
         try {
-          const event=Object.freeze({id:row.event,type:row.type,at:row.at,data:JSON.parse(row.data),attempt:row.attempts+1});
-          await fn.handler(event,services(env,cat,origin,{id:'studio-function',owner:true,client:null},'function:'+fn.name,fn));
+          const stored=JSON.parse(row.data);
+          const isolated=env.HOMIE_LOCAL_TEST_SECRET && /^([a-z][a-z0-9-]*):check:([a-zA-Z0-9-]+)$/.exec(stored?.app??'');
+          const event=Object.freeze({id:row.event,type:row.type,at:row.at,data:isolated?{...stored,app:isolated[1]}:stored,attempt:row.attempts+1});
+          const testScope=isolated?isolated[2]:null;
+          await fn.handler(event,services(env,cat,origin,{id:'studio-function',owner:true,client:null,...(testScope?{testScope}:{})},'function:'+fn.name+(testScope?':check:'+testScope:''),fn));
         } catch(error) {failure=fn.webhook?webhookFailure(error):functionError(error,env);}
         const finished=now();
         await env.DB.batch([