@homie-rocks/studio 0.52.0 → 0.54.0

package/worker/index.mjs

@@ -1,3 +1,4 @@
+import {trackBackground,requestDatabase,databaseBinding,MUTATIONS} from './request-db.mjs';
 import {appGraphicsFallback} from './app-graphics.mjs';
 import {JOIN_AREA_FRAME_JS} from './join-area.mjs';
 import {loadShopLinks} from './shop-links.mjs';
@@ -123,7 +124,7 @@ import { cookieValues, count, countVisit, counter, isQa, onlyOf, ownerAllowed, p
 import { ownerRoutes } from './stats-page.mjs';
 import { playerRoutes, players as playerAccounts } from './players.mjs';
 import {
-  accessOf, accountSub, gatePage, holders, isOwner, joinHolders, launchOf, regateArgs, officeRoutes, publicCatalogue, redeemInvite, sameOrigin, seatsFor, settingsOf, ticketAllows,
+  appRoleSession, appAssetTicket, accessOf, accountSub, gatePage, holders, isOwner, joinHolders, launchOf, regateArgs, officeRoutes, publicCatalogue, redeemInvite, sameOrigin, seatsFor, settingsOf, ticketAllows,
   ticketFor, ticketSub, usePlayers, verifyControl,
 } from './office.mjs';
 
@@ -154,7 +155,7 @@ export { mergeSaves } from './saves.mjs';
 const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const POST_SLUG = /^[a-z0-9][a-z0-9-]{0,79}$/;
 /** A game's own files, framed by its play page: never x-frame-options DENY. */
-const GAME_FILES = /^\/[a-z0-9][a-z0-9-]{0,39}\/__game(?:\/|$)/;
+const GAME_FILES = /^\/[a-z0-9][a-z0-9-]{0,39}\/(?:__game|__assets)(?:\/|$)/;
 const MEDIA_FILE = /\.(mp4|webm|m4v|mov|mp3|m4a|aac|ogg|opus|wav|flac)$/i;
 /** A browser's room key (random, kept in the play page's own storage) and a play ticket, as they may appear in an address. */
 const BROWSER_KEY = /^[A-Za-z0-9_-]{16,43}$/;
@@ -168,13 +169,15 @@ const json = (body, status = 200, extra = {}) => new Response(`${JSON.stringify(
 const catalogueCache = new WeakMap();
 async function catalogue(env, origin) {
   try {
+    const cached=catalogueCache.get(env.ASSETS);
+    if(cached?.origin===origin && env.HOMIE_PREVIEW!=='1' && env.HOMIE_DEV!=='1')return cached.value;
     const res = await env.ASSETS.fetch(new Request(`${origin}/games.json`));
     if (!res.ok) return { studio: { name: env.STUDIO_NAME || 'Studio' }, games: [] };
     const tag = res.headers.get('etag');
     const hit = catalogueCache.get(env.ASSETS);
     if (tag && hit?.tag === tag && hit.origin === origin) { await res.body?.cancel(); return hit.value; }
     const value = await res.json();
-    if (tag) catalogueCache.set(env.ASSETS, { tag, origin, value });
+    catalogueCache.set(env.ASSETS, { tag, origin, value });
     return value;
   } catch { return { studio: { name: env.STUDIO_NAME || 'Studio' }, games: [] }; }
 }
@@ -539,7 +542,14 @@ async function gameDocument(request, env, url, game, meta, cat, { agent = null }
   };
   let html = await res.text();
   const fallback = meta?.kind === 'app' ? `<script>addEventListener('DOMContentLoaded',()=>(${appGraphicsFallback.toString()})(${JSON.stringify(meta.words?.fallback ?? 'This device cannot display the 3D scene. Use the text controls to continue.').replace(/</g, '\\u003c')}));</script>` : '';
-  const head = `<script>${JOIN_AREA_FRAME_JS}</script>` + (meta.kind==='app'?`<script>${APP_STORAGE_JS}</script>`:'') + fallback + `${embedded ? `<script>${EMBED_GAME_JS}</script>` : ''}<script>window.HOMIE_NET=${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script>`;
+  let assetBase='';
+  const assetLaunch=meta.kind==='app'?launchOf(meta,await settingsOf(env,{fresh:true}),env):'public';
+  if(meta.kind==='app'&&!url.pathname.includes('/__assets/')&&assetLaunch!=='public') {
+    const ticket=await appAssetTicket(env,game,undefined,{request,meta,launch:assetLaunch});
+    if(!ticket)return new Response('Sign in again to load this private app.',{status:403,headers:{'cache-control':'no-store'}});
+    assetBase=`<base href="/${game}/__assets/${ticket}/">`;
+  }
+  const head = assetBase + `<script>${JOIN_AREA_FRAME_JS}</script>` + (meta.kind==='app'?`<script>${APP_STORAGE_JS}</script>`:'') + fallback + `${embedded ? `<script>${EMBED_GAME_JS}</script>` : ''}<script>window.HOMIE_NET=${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script>`;
   html = /<head[^>]*>/i.test(html) ? html.replace(/<head([^>]*)>/i, `<head$1>${head}`) : head + html;
   return new Response(html, {
     headers: {
@@ -615,16 +625,10 @@ function finish(res, path) {
   return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
 }
 
-// Repeat after migration: an older isolate may recreate these during a rolling deploy.
-async function removeReferralLeftovers(env) {
-  if(env.DB)await env.DB.prepare("DELETE FROM meta WHERE key GLOB 'referral_*' OR key GLOB 'referral-*'").run();
-}
-
 export default {
   async scheduled(event, env, ctx) {
     env=await loadShopLinks(env);
     const maintenance=(async () => {
-      await removeReferralLeftovers(env);
       const cat = await catalogue(env, 'https://studio.invalid');
       await notifyTools(env,cat,cat.studio?.url??'https://studio.invalid').catch(error=>console.warn('Tool catalogue refresh:',error.message));
       await reconcileOrders(env, shopOf(cat));
@@ -634,18 +638,19 @@ export default {
     await maintenance;
   },
   async fetch(request, env, ctx) {
+    const staticPath=new URL(request.url).pathname;
+    if(['GET','HEAD'].includes(request.method)&&staticPath==='/_homie/site.js')return finish(await route(request,env,ctx),staticPath);
     env=await loadShopLinks(env,new URL(request.url).origin);
-    await removeReferralLeftovers(env);
+    env={...env,DB:requestDatabase(env.DB,request)};
     const url = new URL(request.url);
-    await (await import('./functions.mjs')).syncFunctions(env);
+    if(env.HOMIE_CONCEPT==='1' && url.pathname==='/robots.txt')return new Response('User-agent: *\nDisallow: /\n',{headers:{'content-type':'text/plain','x-robots-tag':'noindex, nofollow'}});
+    if(env.HOMIE_CONCEPT==='1' && url.pathname==='/.well-known/homie-studio.json')return json({ok:false,error:'concept-unlisted'},404,{'x-robots-tag':'noindex, nofollow'});
     const dispatch=()=>import('./functions.mjs').then(m=>m.runFunctions(env,()=>catalogue(env,url.origin),url.origin));
     // Some routes reconcile shop state in waitUntil after returning their page.
     // Keep dispatch behind those writes too, preserving the runtime context's
     // methods and OAuth verification symbols through the proxy.
-    const requestCtx=ctx?.waitUntil?new Proxy(ctx,{get(target,key){
-      if(key==='waitUntil')return work=>ctx.waitUntil(Promise.resolve(work).finally(dispatch));
-      const value=Reflect.get(target,key,target);return typeof value==='function'?value.bind(target):value;
-    }}):ctx;
+    const background=trackBackground(ctx,()=>env.DB?.[MUTATIONS]?dispatch():undefined);
+    const requestCtx=background.context;
     // A standalone copy's Lobby call (worker/standalone.mjs): every answer to it can be read by the app's page, an
     // unknown game's 404 and a failure included, so the app can say why it plays offline. No other address is opened.
     const appRecords = isAppOrigin(request) && /^\/[^/]+\/api\/app\/records\//.test(url.pathname);
@@ -658,18 +663,36 @@ export default {
       res = json({ ok: false, error: 'failed' }, 500);
     } finally {
       // Refresh after the route has populated the catalogue cache.
-      if(env.DB&&env.LOBBY&&ctx?.waitUntil)ctx.waitUntil(catalogue(env,url.origin).then(cat=>notifyTools(env,cat,url.origin)).catch(()=>{}));
+      if(env.DB&&env.LOBBY&&ctx?.waitUntil) {
+        const binding=databaseBinding(env.DB),mutation=url.pathname.startsWith('/_studio/')&&env.DB[MUTATIONS];
+        if(!toolCatalogues.has(binding)||mutation) {
+          toolCatalogues.add(binding);
+          ctx.waitUntil(catalogue(env,url.origin).then(cat=>notifyTools(env,cat,url.origin)).catch(()=>toolCatalogues.delete(binding)));
+        }
+      }
       // A route can commit a write and then fail. Its outbox still needs delivery.
       if(env.DB) {
-        const delivery=dispatch();
+        const delivery=background.finish();
         if(ctx?.waitUntil)ctx.waitUntil(delivery);else await delivery;
       }
     }
+    if(env.HOMIE_CONCEPT==='1' && res.status!==101) {
+      const headers=new Headers(res.headers);headers.set('x-robots-tag','noindex, nofollow');
+      let body=res.body;
+      if(/text\/html/i.test(headers.get('content-type')??'')) {
+        const html=await res.text(),banner='<aside role="status" style="position:fixed;z-index:2147483647;top:0;left:0;right:0;text-align:center;background:#ffda44;color:#171717;padding:6px;font:bold 14px system-ui;pointer-events:none">TEST / CONCEPT</aside>';
+        body=/<body[^>]*>/i.test(html)?html.replace(/<body[^>]*>/i,m=>m+banner):banner+html;
+        headers.delete('content-length');
+      }
+      res=new Response(body,{status:res.status,headers});
+    }
     if (appLobby || appRecords) return appCors(request, res);
     return res;
   },
 };
 
+// Refresh once per isolate/binding, and again after studio mutations. No shared pending I/O.
+const toolCatalogues=new WeakSet();
 async function notifyTools(env,cat,origin) {
   if(!env.DB||!env.LOBBY)return;
   const [{pushToolList},{builtins}]=await Promise.all([import('./event-resources.mjs'),import('./mcp-tools.mjs')]);
@@ -842,7 +865,7 @@ async function route(request, env, ctx) {
     if (own.ok) return own;
     const cat = await getCat();
     const method = request.method;
-    if (path === '/robots.txt') return discoveryResponse(robotsTxt(cat, url.origin, { preview: env.HOMIE_PREVIEW === '1' }), 'text/plain', { method });
+    if (path === '/robots.txt') return discoveryResponse(robotsTxt(cat, url.origin, { preview: env.HOMIE_PREVIEW === '1' || env.HOMIE_CONCEPT === '1' }), 'text/plain', { method });
     const all = await getAll();
     if (path === '/sitemap.xml') return discoveryResponse(sitemapXml(cat, url.origin, { all }), 'application/xml', { method });
     const full = path === '/llms-full.txt';
@@ -927,14 +950,21 @@ async function route(request, env, ctx) {
     return postPage(cat, post, { origin: url.origin });
   }
 
+  if(parts[0]==='games' && parts.length>2) {
+    const all=await getAll(),app=(all.games??[]).find(g=>g.id===parts[1]&&g.kind==='app');
+    if(app && launchOf(app,await settingsOf(env,{fresh:true}),env)!=='public')return json({ok:false,error:'not-found'},404);
+  }
   const game = parts[0];
   if (game && GAME_ID.test(game)) {
     const all = await getAll();
     const meta = (all.games ?? []).find((g) => g.id === game);
     if (!meta) return fallback(request, env, url, getCat);
     if (parts.length === 1 && !path.endsWith('/')) return Response.redirect(`${url.origin}/${game}/`, 301);
-    const cat = await getCat();
     let sub = parts.slice(1).join('/');
+    // Game bundles were already public assets; only the document carries access context.
+    // Apps retain their session/role checks even for individual asset files.
+    if(read&&meta.kind!=='app'&&sub.startsWith('__game/')&&!['__game/','__game/index.html'].includes(sub))return gameAsset(request,env,url,game,sub.slice('__game/'.length));
+    const cat = await getCat();
     if (meta.kind === 'app' && /^open(?:\/(embed|preview))?$/.test(sub)) sub = sub.replace(/^open/, 'play');
     if (sub === '__restart') {
       if (env.HOMIE_PREVIEW !== '1' || request.method !== 'POST' || !hostedGame(game)) return new Response('not found', { status: 404 });
@@ -949,15 +979,32 @@ async function route(request, env, ctx) {
     const launch = launchOf(meta, settings, env);
     const max = seatsFor(meta, settings);
     if (meta.kind === 'app') {
-      if (launch !== 'public' && !(await accessOf(request, env, game, launch)).ok) return json({ ok: false, error: 'not-found' }, 404);
+      const asset=/^__assets\/([^/]+)\/(.+)$/.exec(sub);
+      if(asset) {
+        if(!(await appAssetTicket(env,game,asset[1],{request,meta,launch})))return json({ok:false,error:'not-found'},404);
+        const response=asset[2]==='index.html'?await gameDocument(request,env,url,game,meta,cat):await gameAsset(request,env,url,game,asset[2]);
+        response.headers.set('cache-control','private, no-store');
+        response.headers.set('referrer-policy','no-referrer');
+        return response;
+      }
+      const frameTicket = ['__game','__game/','__game/index.html','__net','__watch'].includes(sub) && await ticketAllows(env, await ticketSub(env,game,url.searchParams.get('t')), launch);
+      if (launch !== 'public' && !frameTicket && !(await accessOf(request, env, game, launch)).ok && (await (await import('./local-test.mjs')).localSession(request,env))?.app!==game) return json({ ok: false, error: 'not-found' }, 404);
+      if(launch==='public') {
+        const web=await (await import('./app-web.mjs')).appWeb(request,env,meta,url,sub,()=>gameDocument(request,env,url,game,meta,cat));
+        if(web)return web;
+      }
+      const apiSession=async response=>{
+        const access=await appAccess(request,env,meta,url);
+        return access.ok?appRoleSession(response,request,env,meta,launch):response;
+      };
       if(sub==='api/app/live') {
         if(request.method!=='GET')return new Response('GET required',{status:405});
         const {appHub}=await import('./app-streams.mjs');
-        return appHub(env,meta.id).fetch('https://app/__app_records',{method:'POST',body:JSON.stringify({op:'open',meta,url:request.url,headers:Object.fromEntries(request.headers),collections:url.searchParams.getAll('collection')})});
+        return apiSession(await appHub(env,meta.id).fetch('https://app/__app_records',{method:'POST',body:JSON.stringify({op:'open',meta,url:request.url,headers:Object.fromEntries(request.headers),collections:url.searchParams.getAll('collection')})}));
       }
-      if(sub==='api/app/tools')return (await import('./app-tools.mjs')).appToolsRoute(request,env,meta,url,cat,await studioTools());
+      if(sub==='api/app/tools')return apiSession(await (await import('./app-tools.mjs')).appToolsRoute(request,env,meta,url,cat,await studioTools()));
       const api = await appRecordsRoute(request, env, meta, url, sub);
-      if (api) return api;
+      if (api) return sub.startsWith('api/app/records/')?apiSession(api):api;
       if (['play', 'tv', 'watch'].includes(sub)) {
         let a;
         try { a = await appAccess(request, env, meta, url); } catch { return json({ ok: false, error: 'app roles unavailable; apply studio migrations' }, 503); }
@@ -965,7 +1012,7 @@ async function route(request, env, ctx) {
           if (a.status === 401) return Response.redirect(`${url.origin}/account/?next=${encodeURIComponent(url.pathname + url.search)}`, 302);
           return json({ ok: false, error: a.error }, a.status);
         }
-        if(!meta.room)return recordsPage(meta,url,cat,await availableShellShop(env,cat,game),Boolean(await (await import('./local-test.mjs')).localSession(request,env)));
+        if(!meta.room)return appRoleSession(recordsPage(meta,url,cat,await availableShellShop(env,cat,game),Boolean(await (await import('./local-test.mjs')).localSession(request,env)),launch!=='public'?await appAssetTicket(env,game,undefined,{request,meta,launch}):null),request,env,meta,launch);
       }
     }
     const lobby = () => env.LOBBY.get(env.LOBBY.idFromName(game));
@@ -1110,11 +1157,11 @@ async function route(request, env, ctx) {
         const sh = await availableShellShop(env, cat, game, { kids: pol.kids });
         let shopQr = null;
         if (sh && !local) try { shopQr = qrSvg(`${url.origin}/shop/?game=${encodeURIComponent(game)}`, { title: `Shop: ${meta.name ?? game}` }); } catch { shopQr = null; }
-        return playPage(cat, meta, { test: Boolean(await (await import('./local-test.mjs')).localSession(request,env)), origin: url.origin, screen: true, joinUrl, qr, local, room, ticket, owner: d.owner, launch, server, shop: sh ? { ...sh, qr: shopQr, url: `${url.origin}/shop/?game=${game}` } : null });
+        return appRoleSession(playPage(cat, meta, { test: Boolean(await (await import('./local-test.mjs')).localSession(request,env)), origin: url.origin, screen: true, joinUrl, qr, local, room, ticket, owner: d.owner, launch, server, shop: sh ? { ...sh, qr: shopQr, url: `${url.origin}/shop/?game=${game}` } : null }),request,env,meta,launch);
       }
       await countVisit(request, env, ctx, game, 'play');
       shareDaily(cat, url, ctx);
-      const page=playPage(cat, meta, { test: Boolean(await (await import('./local-test.mjs')).localSession(request,env)), origin: url.origin, embed, preview: env.HOMIE_EMBED_PREVIEW === '1', ticket: embed ? null : ticket, owner: !embed && d.owner, launch, server, ...(embed ? {} : await chatWho(env, game, srv, d.acct)), shop: await availableShellShop(env, cat, game, { kids: pol.kids }) });
+      const page=await appRoleSession(playPage(cat, meta, { test: Boolean(await (await import('./local-test.mjs')).localSession(request,env)), origin: url.origin, embed, preview: env.HOMIE_EMBED_PREVIEW === '1', ticket: embed ? null : ticket, owner: !embed && d.owner, launch, server, ...(embed ? {} : await chatWho(env, game, srv, d.acct)), shop: await availableShellShop(env, cat, game, { kids: pol.kids }) }),request,env,meta,launch);
       for(const cookie of recordsGuest?.cookies??[])page.headers.append('set-cookie',cookie);return page;
     }
     if (sub === 'watch') {

package/worker/local-test.mjs

@@ -1,6 +1,8 @@
 /** Only dev supplies this secret. Neither a loopback URL nor a role parameter grants authority. */
 const local = (request, env) => env.HOMIE_LOCAL_TEST_SECRET && ['localhost','127.0.0.1','[::1]'].includes(new URL(request.url).hostname);
 export async function localCaller(request, env) {
+  const remote=await remoteSession(request,env);
+  if(remote)return {id:`check-${remote.app}-${remote.role}`,owner:false,client:null,localTest:true,remoteTest:true,roles:{[remote.app]:[remote.role]},testApp:remote.app,testScope:remote.scope};
   if (!local(request, env) || request.headers.get('authorization') !== `Bearer ${env.HOMIE_LOCAL_TEST_SECRET}`) return null;
   const session=await localSession(request,env);
   // A supplied but invalid signed session must never fall back to owner.
@@ -9,6 +11,7 @@ export async function localCaller(request, env) {
   return {id:'local-test-owner',owner:true,client:null};
 }
 export async function localSession(request, env) {
+  const remote=await remoteSession(request,env);if(remote)return remote;
   if (!local(request, env)) return null;
   const token = /(?:^|;\s*)homie_test=([^;]+)/.exec(request.headers.get('cookie') ?? '')?.[1];
   if (!token) return null;
@@ -21,3 +24,10 @@ export async function localSession(request, env) {
     return /^[a-z][a-z0-9-]*$/.test(session.app) && /^[a-z][a-z0-9-]*$/.test(session.role) && (!session.scope || /^[a-zA-Z0-9-]+$/.test(session.scope)) ? session : null;
   } catch { return null; }
 }
+
+async function remoteSession(request,env) {
+ const token=/(?:^|;\s*)homie_check=([^;]+)/.exec(request.headers.get('cookie')??'')?.[1];
+ if(!token)return null;
+ const session=await (await import('./office.mjs')).checkSessionTicket(env,null,token);
+ return session?.origin===new URL(request.url).origin?{...session,remoteTest:true}:null;
+}

package/worker/mcp-events.mjs

@@ -41,9 +41,9 @@ export async function pollEvents(env,cat,caller,params,now=Date.now()){
   const rows=(await env.DB.prepare(`SELECT seq,id,type,data,at FROM studio_events
     WHERE type=?1 AND seq>?2 AND seq<=?3 AND scope IS ?7
       AND (?4 IS NULL OR (json_extract(data,'$.app')=?4 AND json_extract(data,'$.collection')=?5))
-    ORDER BY seq LIMIT ?6`).bind(feed.event,start.after,start.through,feed.event==='record.changed'?(env.HOMIE_LOCAL_TEST_SECRET&&caller.localTest&&caller.testScope?`${feed.app}:check:${caller.testScope}`:feed.app):null,feed.collection??null,max+1,feed.event==='record.changed'?null:caller.testScope??null).all()).results;
+    ORDER BY seq LIMIT ?6`).bind(feed.event,start.after,start.through,feed.event==='record.changed'?((env.HOMIE_LOCAL_TEST_SECRET||caller.remoteTest)&&caller.localTest&&caller.testScope?`${feed.app}:check:${caller.testScope}`:feed.app):null,feed.collection??null,max+1,feed.event==='record.changed'?null:caller.testScope??null).all()).results;
   const hasMore=rows.length>max,page=rows.slice(0,max);
-  const events=page.map(row=>{const data=JSON.parse(row.data);if(env.HOMIE_LOCAL_TEST_SECRET&&caller.localTest&&caller.testScope&&feed.event==='record.changed')data.app=feed.app;return occurrence(params.name,{...row,data},cursorOf(params.name,row.seq));});
+  const events=page.map(row=>{const data=JSON.parse(row.data);if((env.HOMIE_LOCAL_TEST_SECRET||caller.remoteTest)&&caller.localTest&&caller.testScope&&feed.event==='record.changed')data.app=feed.app;return occurrence(params.name,{...row,data},cursorOf(params.name,row.seq));});
   const after=hasMore?page.at(-1).seq:start.through;
   return {events,cursor:cursorOf(params.name,after),truncated:start.truncated,hasMore,nextPollMs:5000};
 }

package/worker/mcp-tools.mjs

@@ -1,3 +1,4 @@
+import {bookingInputSchema,normalizeBookingArgs} from './booking-options.mjs';
 import {bookingHolds} from './booking-holds.mjs';
 import {toolDatabase} from './tool-database.mjs';
 import { selling } from './extensions.mjs';
@@ -16,7 +17,7 @@ export async function allowed(audience, caller, env) {
   if (audience === 'studio-staff') return caller.owner === true || Boolean(await env.DB.prepare("SELECT player FROM app_roles WHERE app='*' AND role='staff' AND player=?1").bind(caller.id).first());
   if (audience === 'owner') return caller.owner === true;
   if (audience && typeof audience === 'object' && audience.app && audience.role) {
-    if(env.HOMIE_LOCAL_TEST_SECRET && caller.localTest)return caller.owner || Boolean(caller.roles?.[audience.app]?.includes(audience.role));
+    if((env.HOMIE_LOCAL_TEST_SECRET || caller.remoteTest) && caller.localTest)return caller.owner || Boolean(caller.roles?.[audience.app]?.includes(audience.role));
     return caller.owner || Boolean(await env.DB.prepare("SELECT player FROM app_roles WHERE app IN (?1,'*') AND role=?2 AND player=?3").bind(audience.app,audience.role,caller.id).first());
   }
   return false;
@@ -38,9 +39,11 @@ export async function currentCaller(env, props) {
 }
 export function services(env, cat, origin, caller, namespace, definition = {}) {
   const records = async ({app,role,collection,id,operation='read',data,version}) => {
+    if(operation!=='read'&&!id)throw Object.assign(new Error('Put id at the top level of the arguments, alongside app and collection (1–64 letters, digits, underscore or hyphen).'),{name:'StudioOperationError'});
+    if(caller.remoteTest&&app!==caller.testApp)throw new Error('Test session belongs to another app');
     const meta = cat.games.find(g=>g.id===app && g.kind==='app');
     if (!meta || !/^[a-z][a-z0-9-]{0,39}$/.test(collection) || (id!==undefined && !/^[A-Za-z0-9_-]{1,64}$/.test(id))) throw Object.assign(new Error('Unknown app or collection; collection names start with a lowercase letter and use lowercase letters, digits and hyphens (1–40). Record id: 1–64 letters, digits, underscore or hyphen.'),{name:'StudioOperationError'});
-    if (!caller.owner && launchOf(meta,await settingsOf(env,{fresh:true}),env)!=='public') throw new Error('app is private');
+    if (!caller.owner && !caller.remoteTest && launchOf(meta,await settingsOf(env,{fresh:true}),env)!=='public') throw new Error('app is private');
     if(!role) {
       const candidates=[];
       for(const [name,declared] of Object.entries(meta.roles??{})) {
@@ -90,6 +93,13 @@ export function services(env, cat, origin, caller, namespace, definition = {}) {
 export function builtins(env,cat,origin) {
   const tool=(name,description,audience,inputSchema,handler)=>({name,description,audience,inputSchema,handler});
   const tools=[
+    tool('studio_check_session','Owner: create a short-lived app-role test session with isolated records. Never grants global owner access.','owner',object({app:str,role:str,scope:{type:'string',pattern:'^check-[a-zA-Z0-9-]{1,64}$'}},['app','role','scope']),async(args,ctx)=>{
+      if(!ctx.caller.owner)throw new Error('Owner required');
+      const meta=cat.games.find(g=>g.id===args.app&&g.kind==='app');
+      if(!meta?.roles?.[args.role])throw new Error('Name a declared app role');
+      const token=await (await import('./office.mjs')).checkSessionTicket(env,{...args,origin});
+      return {token,expiresIn:900};
+    }),
     tool('studio_events_clear','Owner: permanently clear retained events and deliveries through a sequence number. Newer events remain.','owner',object({through:{type:'integer',minimum:0}},['through']),async({through},ctx)=>{
       if(!ctx.caller.owner)throw new Error('Owner only');
       if(!Number.isSafeInteger(through)||through<0)throw new Error('Invalid event cursor');
@@ -166,6 +176,14 @@ export function builtins(env,cat,origin) {
       const collections=new Set(Object.values(roles).flatMap(r=>r.can.map(cap=>cap.split(':')[1])));
       return {app,roles,collections:Object.fromEntries(Object.entries(meta.records?.collections??{}).filter(([name])=>collections.has(name)))};
     }),
+    tool('studio_book','Reserve a declared booking slot. Accepts slot/time, resource/preferredResource, and addons/addOns as an array or quantity object. Supply a stable id, future expiresAt and a private token for an anonymous booking. Payment is separate.','public',bookingInputSchema,async(input,ctx)=>{
+      const args=normalizeBookingArgs(input),meta=cat.games.find(g=>g.id===args.app&&g.kind==='app'),spec=meta?.records?.collections?.[args.collection]?.booking;
+      if(!spec)throw Object.assign(new Error('Unknown booking collection'),{name:'StudioOperationError'});
+      const minutes=Number.isSafeInteger(spec.holdMinutes)&&spec.holdMinutes>0?Math.min(spec.holdMinutes,1440):15;
+      if(!Number.isSafeInteger(args.expiresAt)||args.expiresAt<=Date.now()||args.expiresAt>Date.now()+minutes*60000)throw Object.assign(new Error(`Hold expiry must be within ${minutes} minutes`),{name:'StudioOperationError'});
+      await ctx.records({app:args.app,collection:spec.slots,id:args.slot});
+      return ctx.bookings.hold(args);
+    }),
     tool('app_records','List, read, create, update or delete app records with the app role and record version.','public',object({app:str,role:str,collection:{type:'string',pattern:'^[a-z][a-z0-9-]{0,39}$'},id:{type:'string',pattern:'^[A-Za-z0-9_-]{1,64}$',description:'1–64 letters, digits, underscore or hyphen'},operation:{enum:['read','create','update','delete']},data:{type:'object',propertyNames:{pattern:'^[a-z][a-z0-9_]*$'},description:'Field names start with a lowercase letter and use lowercase letters, digits and underscore; discover fields with app_schema.'},version:{type:'integer',minimum:1}},['app','collection']), (args,ctx)=>ctx.records(args)),
   ];
   for(const [name,path,description] of [

package/worker/office.mjs

@@ -1,3 +1,4 @@
+import {databaseBinding, ORIGINAL_DB} from './request-db.mjs';
 import { selling } from './extensions.mjs';
 import { purchaseOrderIfPresent } from './shop.mjs';
 import { toolIdentity } from './tool-identity.mjs';
@@ -170,6 +171,7 @@ export async function accountSub(request, env) {
 
 /** The owner: the signed-in owner's browser session, or (with player accounts) the owner's own account. */
 export async function isOwner(request, env) {
+  if(toolIdentity(request)?.owner)return true;
   if ((await ownerAllowed(request, env, { kinds: ['session'] })) === 'session') return true;
   try { return players?.isOwner ? (await players.isOwner(request, env)) === true : false; } catch { return false; }
 }
@@ -181,17 +183,17 @@ const settingsCache = new WeakMap();
 /** Every game's live settings (D1 office_games), read at most every 5 s per Worker instance. Empty before migration 0005. */
 export async function settingsOf(env, { fresh = false } = {}) {
   if (!env?.DB || env.HOMIE_PREVIEW === '1') return new Map();
-  const hit = settingsCache.get(env.DB);
-  if (!fresh && hit && Date.now() - hit.at < 5000) return hit.map;
+  const hit = settingsCache.get(databaseBinding(env.DB));
+  if (!env.DB[ORIGINAL_DB] && !fresh && hit && Date.now() - hit.at < 5000) return hit.map;
   let map = new Map();
   try {
     const { results } = await env.DB.prepare('SELECT game, launch, max_players, updated_at FROM office_games LIMIT 500').all();
     map = new Map((results ?? []).map((r) => [r.game, r]));
   } catch { map = new Map(); }
-  settingsCache.set(env.DB, { at: Date.now(), map });
+  settingsCache.set(databaseBinding(env.DB), { at: Date.now(), map });
   return map;
 }
-const forgetSettings = (env) => { if (env?.DB) settingsCache.delete(env.DB); };
+const forgetSettings = (env) => { if (env?.DB) settingsCache.delete(databaseBinding(env.DB)); };
 
 /** A game's launch state: the owner's (D1), else its game.json `launch`, else public. A Preview enforces none. */
 export function launchOf(meta, settings, env) {
@@ -221,7 +223,7 @@ function hexBytes(hex) { const out = new Uint8Array(hex.length / 2); for (let i
 /** The studio's office secret (a random 32 bytes in D1 meta, made on first use), as an HMAC key; null without D1. */
 async function officeKey(env) {
   if (!env?.DB) return null;
-  if (keys.has(env.DB)) return keys.get(env.DB);
+  if (keys.has(databaseBinding(env.DB))) return keys.get(databaseBinding(env.DB));
   let hex = null;
   try {
     hex = (await env.DB.prepare("SELECT value FROM meta WHERE key = 'office_key'").first())?.value ?? null;
@@ -232,7 +234,7 @@ async function officeKey(env) {
   } catch { hex = null; }
   if (!/^[a-f0-9]{64}$/.test(String(hex))) return null;
   const key = await crypto.subtle.importKey('raw', hexBytes(hex), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
-  keys.set(env.DB, key);
+  keys.set(databaseBinding(env.DB), key);
   return key;
 }
 async function mac(key, text) { return b64url(new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(text)))); }
@@ -330,6 +332,8 @@ async function inviteOpen(env, id) {
  */
 export async function accessOf(request, env, game, launch) {
   if (launch === 'public') return { ok: true, sub: null, owner: false };
+  const caller=toolIdentity(request);
+  if(caller?.localTest&&(env.HOMIE_LOCAL_TEST_SECRET||caller.remoteTest)&&caller.testApp===game)return {ok:true,sub:null,owner:false};
   if (await isOwner(request, env)) return { ok: true, sub: 'o', owner: true };
   if (launch === 'invite') {
     const pass = await passOf(request, env, game);
@@ -1377,3 +1381,101 @@ export async function officeRoutes(request, env, url, { catalogueOf }) {
   }
   return null;
 }
+
+/** Encrypted, HMAC-authenticated asset capability. Session hashes never enter URLs in plaintext.
+ * Every use checks revocation, grants and role-link rotation in one D1 statement.
+ */
+export async function appAssetTicket(env, app, ticket, {request,meta,launch=meta?.launch??'public',expectedRole,purpose='asset',renew=false}={}) {
+  const key=await officeKey(env),issuing=ticket===undefined,denied=issuing?null:false;
+  if(!key||!meta)return denied;
+  const decode=text=>Uint8Array.from(atob(text.replaceAll('-','+').replaceAll('_','/')),c=>c.charCodeAt(0));
+  const cipher=await crypto.subtle.importKey('raw',decode(await mac(key,'app-assets-encryption-v1')),'AES-GCM',false,['encrypt','decrypt']);
+  let data;
+  if(issuing) {
+    if(!request)return null;
+    const url=new URL(request.url),{appRole}=await import('./app-format.mjs');
+    const role=appRole(meta,url),rights=meta.roles?.[role];if(!rights)return null;
+    const owner=cookieValues(request,OWNER_COOKIE)[0],player=cookieValues(request,'studio_player')[0],pass=cookieValues(request,passCookie(app))[0],caller=toolIdentity(request);
+    data={purpose,exp:Date.now()+5*60_000,role,rights:await sha256(JSON.stringify(rights)),hash:null,pass:pass?await sha256(pass):null,connection:null,person:null};
+    if(owner||player){data.kind=owner?'owner':'player';data.hash=await sha256(owner??player);}
+    else if(caller){
+      if(caller.localTest&&(env.HOMIE_LOCAL_TEST_SECRET||caller.remoteTest)&&caller.roles?.[app]?.includes(role)){data.kind='test';data.testApp=caller.testApp??app;}
+      else {data.kind='tool';data.connection=caller.connection??null;data.person=caller.id??null;if(data.person?.startsWith('office-'))data.hash=data.person.slice(7);}
+    } else if(launch==='invite'&&!rights.signIn&&pass){data.kind='pass';}
+    else {
+      const session=await (await import('./local-test.mjs')).localSession(request,env);
+      if(session?.app!==app||session.role!==role)return null;
+      data.kind='test';data.testApp=app;data.exp=Math.min(data.exp,session.expires??data.exp);
+    }
+  } else {
+    try {
+      const [iv,payload,signature,...extra]=ticket.split('.');
+      if(extra.length||!signature||!same(await mac(key,`app-assets|${app}|${iv}|${payload}`),signature))return false;
+      data=JSON.parse(new TextDecoder().decode(await crypto.subtle.decrypt({name:'AES-GCM',iv:decode(iv)},cipher,decode(payload))));
+    }catch{return false;}
+  }
+  if(data.kind==='test') {
+    const session=request&&await (await import('./local-test.mjs')).localSession(request,env);
+    if(!issuing&&(!session||session.app!==app||session.role!==data.role||(session.scope??null)!==data.testScope))return denied;
+    if(issuing)data.testScope=session?.scope??toolIdentity(request)?.testScope??null;
+  }
+  if(data.purpose!==purpose||(purpose==='handoff'&&!['owner','player'].includes(data.kind)))return denied;
+  if(expectedRole&&data.role!==expectedRole)return denied;
+  if(!Number.isSafeInteger(data.exp)||data.exp<=Date.now()||data.exp>Date.now()+5*60_000||!meta.roles?.[data.role]||data.rights!==await sha256(JSON.stringify(meta.roles[data.role])))return denied;
+  const state=await env.DB.prepare(`SELECT
+    (SELECT token FROM app_role_links WHERE app=?1 AND role=?2) link,
+    EXISTS(SELECT 1 FROM stats_keys WHERE hash=?3 AND kind='session' AND expires_at>?4) owner,
+    EXISTS(SELECT 1 FROM office_passes p JOIN office_invites i ON i.id=p.invite WHERE p.hash=?5 AND p.game=?1 AND p.expires_at>?4 AND i.revoked=0) pass,
+    (SELECT p.id FROM players p WHERE p.id=(SELECT player FROM player_sessions WHERE hash=?3 AND kind='session' AND expires_at>?4)) player,
+    EXISTS(SELECT 1 FROM players p WHERE p.owner=1 AND (p.id=(SELECT player FROM player_sessions WHERE hash=?3 AND kind='session' AND expires_at>?4) OR p.id=?6)) playerOwner,
+    EXISTS(SELECT 1 FROM app_roles WHERE app IN (?1,'*') AND role=?2 AND player IN (?6,(SELECT player FROM player_sessions WHERE hash=?3 AND kind='session' AND expires_at>?4))) granted,
+    EXISTS(SELECT 1 FROM mcp_connections WHERE id=?7 AND person=?6 AND revoked=0) connected
+  `).bind(app,data.role,data.hash??null,Date.now(),data.pass??null,data.person??null,data.connection??null).first();
+  if(issuing&&purpose==='asset'&&launch==='invite'&&!meta.roles[data.role].signIn&&state.pass)data.kind='pass';
+  const gate=state.owner||state.playerOwner||launch==='public'||launch==='invite'&&state.pass;
+  const roleAllowed=!meta.roles[data.role].signIn||state.owner||state.playerOwner||state.granted;
+  const authorized=data.kind==='owner'?state.owner:data.kind==='pass'?launch==='invite'&&!meta.roles[data.role].signIn&&state.pass:data.kind==='player'?state.player&&gate&&roleAllowed:data.kind==='tool'?state.connected&&gate&&roleAllowed:data.kind==='test'?data.testApp===app:false;
+  if(!authorized)return denied;
+  const link=state.link?await sha256(state.link):null;
+  if(!issuing) {
+    if(data.link!==link)return denied;
+    if(!renew||purpose!=='handoff')return true;
+    data.exp=Date.now()+5*60_000;
+  }
+  data.link=link;
+  const iv=crypto.getRandomValues(new Uint8Array(12)),ivText=b64url(iv);
+  const payload=b64url(new Uint8Array(await crypto.subtle.encrypt({name:'AES-GCM',iv},cipher,new TextEncoder().encode(JSON.stringify(data)))));
+  return `${ivText}.${payload}.${await mac(key,`app-assets|${app}|${ivText}|${payload}`)}`;
+}
+
+/** Owner-issued test role, scoped to one app/record namespace; never an owner credential. */
+export async function checkSessionTicket(env, data, token) {
+ const key=await officeKey(env);if(!key)return null;
+ if(token===undefined) {
+  const payload=b64url(new TextEncoder().encode(JSON.stringify({...data,expires:Date.now()+15*60_000})));
+  return payload+'.'+await mac(key,'check-session|'+payload);
+ }
+ try {
+  const [payload,signature,...extra]=token.split('.');
+  if(extra.length||!signature||!same(await mac(key,'check-session|'+payload),signature))return null;
+  const session=JSON.parse(atob(payload.replaceAll('-','+').replaceAll('_','/')));
+  if(session.expires<=Date.now()||!Number.isSafeInteger(session.expires)||!/^check-[a-zA-Z0-9-]{1,64}$/.test(session.scope)||!GAME_ID.test(session.app)||!/^[a-z][a-z0-9-]{0,39}$/.test(session.role))return null;
+  return session;
+ }catch{return null;}
+}
+
+/** Same-origin role handoff for opening another screen, never the long-lived role URL secret. */
+export async function appRoleSession(response,request,env,meta,launch) {
+ if(meta.kind!=='app')return response;
+ const {appRole}=await import('./app-format.mjs'),role=appRole(meta,new URL(request.url));
+ if(!meta.roles?.[role]?.signIn)return response;
+ const handoff=cookieValues(request,`studio_app_${meta.id}_${role}`)[0];
+ const ticket=(handoff&&await appAssetTicket(env,meta.id,handoff,{request,meta,launch,purpose:'handoff',expectedRole:role,renew:true}))||await appAssetTicket(env,meta.id,undefined,{request,meta,launch,purpose:'handoff'});
+ if(ticket) {
+  response=new Response(response.body,{status:response.status,statusText:response.statusText,headers:response.headers});
+  // LAN dev uses HTTP: a Secure cookie is discarded before the shell removes access.
+  const secure=new URL(request.url).protocol==='https:'?'; Secure':'';
+  response.headers.append('set-cookie',`studio_app_${meta.id}_${role}=${ticket}; Path=/${meta.id}/; Max-Age=300; HttpOnly${secure}; SameSite=Strict`);
+ }
+ return response;
+}

package/worker/operational-schema.mjs

@@ -0,0 +1,30 @@
+export const OPERATIONAL_MIGRATION_FILE='0031_request_and_tool_notifications.sql';
+export const OPERATIONAL_MIGRATION=`
+-- Removed features are cleaned once, never on the request path.
+DELETE FROM meta WHERE key GLOB 'referral_*' OR key GLOB 'referral-*';
+INSERT OR IGNORE INTO meta(key,value) VALUES('tool-data-revision','0');
+${['INSERT','UPDATE','DELETE'].map(op=>`CREATE TRIGGER tool_data_live_${op.toLowerCase()} AFTER ${op} ON tool_data BEGIN
+ UPDATE meta SET value=CAST(value AS INTEGER)+1 WHERE key='tool-data-revision';
+END;`).join('\n')}
+`;
+
+export const CACHE_MIGRATION_FILE='0032_metadata_revisions.sql';
+export const CACHE_MIGRATION=`
+INSERT OR IGNORE INTO meta(key,value) VALUES('metadata-revision','0');
+${['office_games','servers','chat_rules'].flatMap(table=>['INSERT','UPDATE','DELETE'].map(op=>`CREATE TRIGGER ${table}_revision_${op.toLowerCase()} AFTER ${op} ON ${table} BEGIN
+ UPDATE meta SET value=CAST(value AS INTEGER)+1 WHERE key='metadata-revision';
+END;`)).join('\n')}
+`;
+export const TOOL_NAMESPACE_MIGRATION_FILE='0033_tool_namespace_revisions.sql';
+export const TOOL_NAMESPACE_MIGRATION=`
+DROP TRIGGER tool_data_live_insert;
+DROP TRIGGER tool_data_live_update;
+DROP TRIGGER tool_data_live_delete;
+DELETE FROM meta WHERE key='tool-data-revision';
+CREATE TABLE tool_data_revisions(namespace TEXT PRIMARY KEY,revision INTEGER NOT NULL);
+CREATE TABLE app_tool_namespaces(app TEXT NOT NULL,namespace TEXT NOT NULL,PRIMARY KEY(app,namespace));
+${['INSERT','UPDATE','DELETE'].map(op=>{const row=op==='DELETE'?'OLD':'NEW';return `CREATE TRIGGER tool_data_namespace_${op.toLowerCase()} AFTER ${op} ON tool_data BEGIN
+ INSERT INTO tool_data_revisions VALUES(${row}.namespace,1) ON CONFLICT(namespace) DO UPDATE SET revision=revision+1;
+ ${op==='UPDATE'?`INSERT INTO tool_data_revisions SELECT OLD.namespace,1 WHERE OLD.namespace!=NEW.namespace ON CONFLICT(namespace) DO UPDATE SET revision=revision+1;`:''}
+END;`;}).join('\n')}
+`;

package/worker/pages.mjs

@@ -494,7 +494,13 @@ const SHELL_JS = String.raw`${BUILD_RETRY_JS}(function () {
     ui.querySelector('[data-room-code]').textContent = labelOf(room) + (boot.embed ? ' \u00b7 Site' : '');
     ui.querySelector('[data-room-label]').textContent = labelOf(room);
     ui.querySelector('[data-room-link]').textContent = LOCAL ? 'Deploy to share: this preview address works on this computer only.' : link.replace(/^https?:\/\//, '');
-    ui.querySelector('[data-bigscreen]').href = '/' + boot.game + '/tv?room=' + encodeURIComponent(room);
+    var tv = new URL('/' + boot.game + '/tv', location.origin);
+    tv.searchParams.set('room', room);
+    if (boot.kind === 'app') {
+      var context = new URLSearchParams(location.search);
+      ['role'].forEach(function (key) { if (context.has(key)) tv.searchParams.set(key, context.get(key)); });
+    }
+    ui.querySelector('[data-bigscreen]').href = tv.pathname + tv.search;
     toggle.addEventListener('click', function (e) { e.stopPropagation(); open(sheet.hidden); });
     ui.querySelector('[data-invite]').addEventListener('click', function () {
       var data = { title: boot.name, text: (boot.appWords ? boot.appWords.open : 'Play') + ' ' + boot.name + ' with me: join my room.', url: link };

package/worker/records-page.mjs

@@ -5,10 +5,10 @@ import {SHOP_SHELL_JS, SHOP_SHELL_CSS} from './shop-page.mjs';
 import {RECORDS_PREFS_JS} from './records-prefs.mjs';
 import {APP_SHELL_JS} from './app-shell.mjs';
 /** A records-only app has no room simulation. The shell owns one frame and its authenticated records bridge. */
-export function recordsPage(meta,url,cat={},shop=null,test=false) {
+export function recordsPage(meta,url,cat={},shop=null,test=false,assetTicket=null) {
  const params=new URLSearchParams(url.search);params.delete('access');params.set('pf','1');params.set('role',appRole(meta,url));if(!params.has('surface'))params.set('surface',url.pathname.endsWith('/tv')?'wall':'phone');
  const tags=Object.entries(playerProperties(cat,meta,{origin:url.origin})).map(([name,content])=>`<meta name="${esc(name)}" content="${esc(content)}">`).join('');
  const boot={kind:'app',test,game:meta.id,screen:url.pathname.endsWith('/tv'),shop};
- const source=`/${meta.id}/__game/?${params}`;
+ const source=assetTicket?`/${meta.id}/__assets/${assetTicket}/index.html?${params}`:`/${meta.id}/__game/?${params}`;
  return new Response(`<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(meta.name)}</title>${tags}<style>${SHOP_SHELL_CSS}html,body{margin:0;height:100%;background:#10151c;color:white;font:18px system-ui}iframe{border:0;width:100%;height:100%;display:block}[data-arrive]{position:fixed;inset:0;display:grid;place-items:center;background:#10151c}[data-arrive][hidden]{display:none;opacity:0;visibility:hidden}</style></head><body><div data-arrive>Opening ${esc(meta.name)}…</div><iframe class="game" title="${esc(meta.name)}" sandbox="allow-scripts allow-forms allow-modals allow-popups allow-downloads" allow="autoplay *; fullscreen *; web-share *"></iframe><script>window.__HOMIE_APP=${JSON.stringify(boot).replace(/</g,'\\u003c')};window.__HOMIE_PLAY=window.__HOMIE_APP;window.__shell={room:new URLSearchParams(location.search).get('room')||'main',link:{state:'connecting'},arrival:{phase:'loading'}};</script><script>${APP_SHELL_JS}</script><script>${RECORDS_PREFS_JS}</script><script>${SHOP_SHELL_JS}</script><script>const frame=document.querySelector('iframe');frame.addEventListener('load',()=>{if(!frame.getAttribute('src'))return;requestAnimationFrame(()=>requestAnimationFrame(()=>{document.querySelector('[data-arrive]').hidden=true;window.__shell.link.state='online';window.__shell.arrival.phase='done';}));});frame.src=${JSON.stringify(source).replace(/</g,'\\u003c')};</script></body></html>`,{headers:{'content-type':'text/html;charset=utf-8','cache-control':'no-store, no-transform','x-frame-options':'SAMEORIGIN'}});
 }

package/worker/request-db.mjs

@@ -0,0 +1,53 @@
+export const ORIGINAL_DB=Symbol('original database');
+export const MUTATIONS=Symbol('request mutations');
+export const databaseBinding=db=>db?.[ORIGINAL_DB]??db;
+const metadata=new WeakMap();
+const metadataQueries=new Set(['SELECT game, launch, max_players, updated_at FROM office_games LIMIT 500','SELECT * FROM servers LIMIT 2000','SELECT game, server, rules, updated_at FROM chat_rules LIMIT 1000']);
+/** Cache only completed metadata, stamped by a trigger-maintained revision. Pending
+ * D1 operations belong to one request; unrelated metadata tables are never loaded.
+ */
+export function requestDatabase(DB, request, state={mutated:false}, binding=databaseBinding(DB)) {
+ if(!DB)return DB;
+ let revision,records;
+ const url=new URL(request.url),match=request.method==='GET'&&/^\/([a-z0-9][a-z0-9-]{0,39})\/api\/app\/records\/([a-z][a-z0-9-]{0,39})(?:\/([A-Za-z0-9_-]{1,64}))?$/.exec(url.pathname);
+ const recordQuery=match&&(match[3]?'SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 AND id = ?3':'SELECT id, value, version, updated_at FROM app_records WHERE app = ?1 AND collection = ?2 ORDER BY updated_at, id');
+ const stamp=()=>revision??=(async()=>{
+  const query=DB.prepare("SELECT value FROM meta WHERE key='metadata-revision'");
+  if(recordQuery){const result=await DB.batch([query,DB.prepare(recordQuery).bind(...match.slice(1).filter(x=>x!==undefined))]);records=result[1];return result[0].results?.[0]?.value??null;}
+  return (await query.first())?.value??null;
+ })();
+ const writing=sql=>{if(!/^\s*(SELECT|PRAGMA|EXPLAIN)\b/i.test(sql)){if(/\bapp_records\b/.test(sql)){records=null;revision=null;}if(/\b(office_games|servers|chat_rules)\b/.test(sql)){revision=null;metadata.delete(binding);}if(!/\bstats_daily\b/.test(sql))state.mutated=true;}};
+ const prepare=(sql,args=[])=>{
+  const original=()=>{const stmt=DB.prepare(sql);return args.length?stmt.bind(...args):stmt;};
+  const read=async()=>{
+   if(sql===recordQuery&&JSON.stringify(args)===JSON.stringify(match.slice(1).filter(x=>x!==undefined))){await stamp();return records;}
+   if(!metadataQueries.has(sql))return original().all();
+   const version=await stamp();let cache=metadata.get(binding);
+   if(!cache||cache.version!==version){cache={version,rows:new Map()};metadata.set(binding,cache);}
+   if(version!==null&&cache.rows.has(sql))return cache.rows.get(sql);
+   const result=await original().all();if(version!==null)cache.rows.set(sql,result);return result;
+  };
+  return {bind:(...args)=>prepare(sql,args),first:async column=>{writing(sql);if(!metadataQueries.has(sql)&&sql!==recordQuery)return original().first(column);const row=(await read()).results?.[0]??null;return column&&row?row[column]:row;},all:()=>{writing(sql);return read();},run:()=>{writing(sql);return original().run();},raw:(...args)=>{writing(sql);return original().raw(...args);},_original:original,_sql:sql};
+ };
+ const methods={[ORIGINAL_DB]:binding,get [MUTATIONS](){return state.mutated;},prepare,batch:statements=>{for(const s of statements)writing(s._sql??'UPDATE');return DB.batch(statements.map(s=>s._original?.()??s));},exec:(sql,...args)=>{writing(sql);return DB.exec(sql,...args);},withSession:(...args)=>requestDatabase(DB.withSession(...args),request,state,binding)};
+ return new Proxy(methods,{get(target,key){if(key in target)return target[key];const value=DB[key];return typeof value==='function'?value.bind(DB):value;}});
+}
+
+/** A background task may register more work while it settles. */
+export async function drainPending(pending) {
+ for(let done=0;done<pending.length;){const end=pending.length;await Promise.allSettled(pending.slice(done,end));done=end;}
+}
+
+/** Keep the runtime context intact and also deliver writes registered after the
+ * response's original drain finished (for example from response-stream work). */
+export function trackBackground(ctx,deliver) {
+ const pending=[];let finished=false;
+ const context=ctx?.waitUntil?new Proxy(ctx,{get(target,key){
+  if(key==='waitUntil')return work=>{
+   const task=Promise.resolve(work);pending.push(task);ctx.waitUntil(task);
+   if(finished)ctx.waitUntil(Promise.allSettled([task]).then(deliver));
+  };
+  const value=Reflect.get(target,key,target);return typeof value==='function'?value.bind(target):value;
+ }}):ctx;
+ return {context,async finish(){await drainPending(pending);finished=true;await deliver();}};
+}