@homie-rocks/studio 0.32.1 → 0.33.0

package/worker/shop.mjs

@@ -3,15 +3,15 @@
  * The studio is the seller; homie.rocks never sees, holds or moves its money, and Homie takes no cut.
  *
  *   GET  /api/shop               the items, each with how THIS player may get it (shop-rules.mjs wayFor); on a kids
- *                                server or a kids studio, nothing; until set up, { open: false, missing: [...] }
+ *                                server or studio, the studio policy applies; until set up, { open: false, missing: [...] }
  *   POST /api/shop/age           the neutral age question, once per account: a year of birth, kept only as a band
- *   POST /api/shop/buy           an adult account buys one item: an order row, then Stripe's own hosted Checkout page
- *   POST /api/shop/parent        13-17: a one-time link a parent opens on their own device (/shop/parent/<token>)
- *   POST /api/shop/hook          Stripe's webhook, signature checked; the ONLY writer of paid, refunded, disputed
+ *   POST /api/shop/buy           a permitted buyer buys one item: an order row, then Stripe's own hosted Checkout page
+ *   POST /api/shop/parent        studio parent policy: a one-time link a parent opens on their own device (/shop/parent/<token>)
+ *   POST /api/shop/hook          Stripe's webhook, signature checked; verified Stripe events record paid, refunded, disputed
  *   POST /api/shop/used          the game says an item was used (equipped, played): it leaves the self-serve refund
  *   POST /api/shop/refund        the player's own refund of an unused item within the studio's refund days
  *   GET  /api/player/owns        what the signed-in player owns (the keys the game reads; a beginner or kids server
- *                                hides anything with a play advantage)
+ *                                follows the studio advantage settings)
  *   GET  /api/shop/mine          the player's orders and what they own (the account page)
  *   GET  /shop/  /shop/thanks  /shop/refunds/  /shop/parent/<token>   the pages (worker/shop-page.mjs)
  *   POST /api/referrals/statement   another studio's signed referral statement to this one (worker/referrals.mjs)
@@ -33,24 +33,24 @@
  */
 import { players } from './players.mjs';
 import { serversOf } from './servers.mjs';
-import { CAP_CEILING, audienceOf, bandOf, checkShop, defaultTaxCode, money, wayFor } from './shop-rules.mjs';
+import { ENTITLEMENT_KEY, checkoutMessage, amountError, amountStep, parseAmount, currencyScale, audienceOf, bandOf, checkShop, defaultTaxCode, money, wayFor } from './shop-rules.mjs';
 import {
-  bandOfPlayer, forgetPlayerShop, grantStatements, migrated, newOrderId, orderById, orderByPayment, orderBySession, orderView, ownsOf, restoreStatement, revokeStatement,
+  bandOfPlayer, forgetPlayerShop, grantStatements, migrationNeeded, migrated, newOrderId, orderById, orderByPayment, orderBySession, orderView, playerOrderStatus, ownsOf, restoreStatement, revokeStatement,
   setBand, shopDataOf, spentThisMonth,
 } from './shop-store.mjs';
-import { KEY_SHAPE, StripeError, WEBHOOK_SECRET_SHAPE, createCheckoutSession, createRefund, dashboardLink, isApprovalRequired, isMissingProduct, modeOf, productIdOf, verifyWebhook } from './stripe.mjs';
-import { arrivalOf, booksOf, lineFor, receiveStatement, referrerOk, sendStatements, settle, statementFor, statementsIn, voidLineStatements } from './referrals.mjs';
+import { KEY_SHAPE, stripeCall, StripeError, WEBHOOK_SECRET_SHAPE, createCheckoutSession, createRefund, expireCheckoutSession, dashboardLink, isApprovalRequired, isMissingProduct, modeOf, productIdOf, verifyWebhook } from './stripe.mjs';
+import { pendingStatementPeriod, statementFailures, arrivalOf, booksOf, linesOf, statementPage, lineFor, receiveStatement, receivedPages, referrerOk, sendStatements, settle, statementsIn, voidLineStatements } from './referrals.mjs';
 import { SHOP_JS, officeShopPage, parentPage, refundsPage, shopPage, thanksPage } from './shop-page.mjs';
 import { notFoundPage } from './site.mjs';
 
-export { forgetPlayerShop, officeShopPage, shopDataOf };
+export { linesOf, forgetPlayerShop, officeShopPage, receivedPages, shopDataOf };
 
 const DAY = 86_400_000;
 const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const SERVER_ID = /^(?:public|[a-z0-9][a-z0-9-]{1,19})$/;
 const TOKEN = /^[A-Za-z0-9_-]{43}$/;
-/** In-memory, per Worker instance: buys and parent links a minute per player. Never stored. */
-const BUYS_PER_MINUTE = 6;
+/** In-memory, per Worker instance: purchase attempts a minute per account and address. Never stored. */
+const addressOf = (request) => request.headers.get('cf-connecting-ip') || 'local';
 
 const json = (body, status = 200, headers = {}) => new Response(`${JSON.stringify(body)}\n`, {
   status, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store, private', 'x-content-type-options': 'nosniff', ...headers },
@@ -58,16 +58,18 @@ const json = (body, status = 200, headers = {}) => new Response(`${JSON.stringif
 const fail = (status, error, message, extra = {}) => json({ ok: false, error, message, ...extra }, status);
 
 const buckets = new Map();
+const accountBuckets = new Map();
 function limited(key, max, windowMs, now = Date.now()) {
-  const list = (buckets.get(key) ?? []).filter((t) => t > now - windowMs);
-  if (list.length >= max) { buckets.set(key, list); return true; }
+  const counts = key.includes(':account:') ? accountBuckets : buckets;
+  const list = (counts.get(key) ?? []).filter((t) => t > now - windowMs);
+  if (list.length >= max) { counts.set(key, list); return true; }
   list.push(now);
-  buckets.set(key, list);
-  if (buckets.size > 10_000) buckets.clear();
+  counts.set(key, list);
+  if (counts.size > 10_000) counts.delete(counts.keys().next().value);
   return false;
 }
 /** For tests: forget every count. */
-export function resetShopLimits() { buckets.clear(); }
+export function resetShopLimits() { buckets.clear(); accountBuckets.clear(); }
 
 const sha256Hex = async (text) => [...new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)))].map((b) => b.toString(16).padStart(2, '0')).join('');
 function randomToken() {
@@ -90,16 +92,22 @@ async function bodyOf(request, max = 4096) {
 
 /* ------------------------------------------------------------------ the shop and whether it is open */
 
+const sizes = new WeakMap();
+function requestSize(shop) {
+  if (sizes.has(shop)) return sizes.get(shop);
+  const size = (shop?.items ?? []).reduce((size, item) => (item.gives ?? []).reduce((n, key) => Math.max(n, JSON.stringify(key).length), Math.max(size, JSON.stringify(item.id).length)), 0) * 6 + 4096;
+  sizes.set(shop, size);
+  return size;
+}
 const shopCache = new WeakMap();
 /**
- * The studio's shop, as the build wrote it into games.json and checked again here (the kids rules are in the code,
- * so a hand-edited build cannot sell what the kit refuses). null when the studio has no shop.json.
+ * The studio's shop, checked against its chosen settings and provider requirements at build and request time. null when the studio has no shop.json.
  */
 export function shopOf(cat) {
   if (!cat?.shop) return null;
   if (shopCache.has(cat)) return shopCache.get(cat);
   const games = (cat.games ?? []).map((g) => g.id);
-  const r = checkShop(cat.shop, { games: games.length ? games : null, audience: audienceOf(cat.studio) });
+  const r = checkShop(cat.shop, { games: games.length ? games : null, audience: audienceOf(cat.studio), studioName: cat.studio?.name });
   const shop = r.ok ? r.shop : { ...r.shop, open: false, broken: r.errors.slice(0, 5) };
   shopCache.set(cat, shop);
   return shop;
@@ -117,22 +125,23 @@ export async function readiness(env, shop) {
   if (/^sk_live_/.test(key)) missing.push('restricted-key');
   else if (!KEY_SHAPE.test(key)) missing.push('stripe-key');
   if (!WEBHOOK_SECRET_SHAPE.test(String(env?.STRIPE_WEBHOOK_SECRET ?? ''))) missing.push('webhook-secret');
+  let migration = null;
   if (!env?.DB || env.HOMIE_PREVIEW === '1') missing.push('database');
-  else if (!(await migrated(env))) missing.push('migration');
-  return { ready: missing.length === 0, missing, mode: KEY_SHAPE.test(key) ? modeOf(key) : null };
+  else if ((migration = await migrationNeeded(env))) missing.push('migration');
+  return { ready: missing.length === 0, missing, migration, mode: KEY_SHAPE.test(key) ? modeOf(key) : null };
 }
 
 export const MISSING_WORDS = Object.freeze({
   'shop.json': 'This studio has no shop.json: nothing is for sale (homie-studio shop init writes one).',
-  'kids-studio': 'This studio is made for children (studio.json "audience": "kids"): it sells nothing in its games.',
-  'shop.json-refused': 'shop.json breaks the kit\'s rules (homie-studio shop check says which), so nothing is sold.',
+  'kids-studio': 'This studio is made for children (studio.json "audience": "kids"): its policy.kidsStudio setting closes the shop.',
+  'shop.json-refused': 'shop.json conflicts with the studio settings or payment requirements (homie-studio shop check says which), so nothing is sold.',
   'till-off': 'shop.json says "till": "off".',
   items: 'shop.json has no items.',
   'restricted-key': 'The Worker has a full secret key: the shop takes only a restricted key (homie-studio shop connect).',
   'stripe-key': 'The Worker has no Stripe key yet (homie-studio shop connect: the owner pastes a restricted key into a page on their own computer).',
   'webhook-secret': 'The Worker has no webhook signing secret yet (the same page takes it).',
   database: 'This Worker has no database (a Preview never sells).',
-  migration: 'The shop\'s tables are not in the studio\'s D1 yet: npm run deploy applies migration 0008_studio_shop.sql.',
+  migration: 'The shop\'s tables are not in the studio\'s D1 yet: npm run deploy applies migrations 0008_studio_shop.sql, 0010_shop_reservations.sql and 0011_shop_statements.sql.',
 });
 
 /** The server a request names (the play shell says which), with its kids and beginner flags. */
@@ -159,16 +168,18 @@ async function accountOf(request, env) {
 }
 
 /** Each item with how this player may get it, and the words for it. */
-async function itemsView(env, shop, { game, kids, beginner, player, open }) {
-  const band = player && !player.guest ? await bandOfPlayer(env, player.id) : null;
+async function itemsView(env, shop, { game, kids, beginner, player, open, cursor = 0, item = null, purchasing = false }) {
+  const band = player ? await bandOfPlayer(env, player.id) : null;
   const owns = player ? await ownsOf(env, player.id) : [];
-  const spent = player && !player.guest ? await spentThisMonth(env, player.id) : 0;
-  const items = itemsFor(shop, game).map((it) => {
+  const spent = !purchasing && player && open && shop.capPerPlayerMonth !== null ? await spentThisMonth(env, player.id) : 0;
+  const selected = item ? [item] : itemsFor(shop, game);
+  const page = item ? selected : selected.slice(cursor, cursor + 100);
+  const items = page.map((it) => {
     const owned = it.gives.length > 0 && it.gives.every((k) => owns.some((o) => o.key === k && o.item === it.id));
-    const way = wayFor(it, { open, kids, beginner, player, band, owned, spent, cap: shop.capPerPlayerMonth ?? CAP_CEILING });
-    return { id: it.id, kind: it.kind, name: it.name, blurb: it.blurb ?? null, price: it.price, ...(it.kind === 'tip' ? { min: it.min, max: it.max } : {}), shown: it.kind === 'tip' ? `${money(it.min, shop.currency)} or more` : money(it.price, shop.currency), gives: it.gives, ...(it.badge ? { badge: it.badge } : {}), ...(it.days ? { days: it.days } : {}), ...(it.ends ? { ends: it.ends } : {}), ...(it.game ? { game: it.game } : {}), way };
+    const way = wayFor(it, { open, kids, beginner, player, band, owned, spent, cap: purchasing ? null : shop.capPerPlayerMonth, policy: shop.policy });
+    return { id: it.id, kind: it.kind, name: it.name, blurb: it.blurb ?? null, price: it.price, ...(it.kind === 'tip' ? { min: it.min, max: it.max } : {}), shown: it.kind === 'tip' ? `${money(it.min, shop.currency)} or more` : money(it.price, shop.currency), gives: it.gives, ...(it.badge ? { badge: it.badge } : {}), ...(it.days ? { days: it.days } : {}), ...(it.ends ? { ends: it.ends } : {}), ...(it.game ? { game: it.game } : {}), way, ...(way === 'cap' ? { retryWay: wayFor(it, { open, kids, beginner, player, band, owned, cap: null, policy: shop.policy }) } : {}) };
   }).filter((i) => i.way !== 'beginner' && i.way !== 'kids');
-  return { band, owns, spent, items };
+  return { band, owns, spent, items, nextCursor: !item && cursor + 100 < selected.length ? String(cursor + 100) : null };
 }
 
 /* ------------------------------------------------------------------ routes */
@@ -184,11 +195,11 @@ export async function shopRoutes(request, env, ctx, url, { catalogueOf }) {
   if (path === '/shop') return Response.redirect(`${url.origin}/shop/${url.search}`, 301);
   const cat = await catalogueOf();
   const shop = shopOf(cat);
-  // A kids studio has no shop at all: no page, no list, nothing to buy.
+  // The studio's protective policy closes kids studios.
   if (!shop || shop.audience === 'kids') {
     if (path === '/api/player/owns') return json({ ok: true, owns: [], open: false });
     if (path.startsWith('/api/')) return json({ ok: true, open: false, items: [], missing: [shop ? 'kids-studio' : 'shop.json'] });
-    // No shop.json: /shop/ is the studio's own to use (a page in site/pages, say). A kids studio's is never a shop.
+    // No shop.json: /shop/ is the studio's own to use (a page in site/pages, say). The policy can close a kids studio's shop.
     return shop ? notFoundPage('This studio sells nothing.', cat) : null;
   }
   const ready = await readiness(env, shop);
@@ -199,18 +210,18 @@ export async function shopRoutes(request, env, ctx, url, { catalogueOf }) {
     if (path === '/api/player/owns' && read) return await ownsRoute(request, env, url, cat, shop);
     if (path === '/api/shop/mine' && read) return await mineRoute(request, env, shop);
     if (path === '/api/shop/order' && read) return await orderRoute(request, env, url);
-    if (path === '/api/shop/age' && request.method === 'POST') return await ageRoute(request, env);
-    if (path === '/api/shop/buy' && request.method === 'POST') return await buyRoute(request, env, url, cat, shop, ready);
+    if (path === '/api/shop/age' && request.method === 'POST') return await ageRoute(request, env, shop);
+    if (path === '/api/shop/buy' && request.method === 'POST') return await buyRoute(request, env, url, cat, shop, ready, ctx);
     if (path === '/api/shop/parent' && request.method === 'POST') return await parentLinkRoute(request, env, url, cat, shop, ready);
-    if (path === '/api/shop/used' && request.method === 'POST') return await usedRoute(request, env);
+    if (path === '/api/shop/used' && request.method === 'POST') return await usedRoute(request, env, shop);
     if (path === '/api/shop/refund' && request.method === 'POST') return await selfRefundRoute(request, env, shop, ready);
     if (path === '/shop/' && read) return shopPage(cat, shop, { origin: url.origin, game: GAME_ID.test(url.searchParams.get('game') ?? '') ? url.searchParams.get('game') : null, item: url.searchParams.get('item'), open: ready.ready, mode: ready.mode });
     if (path === '/shop/thanks' && read) return thanksPage(cat, shop, { session: /^cs_[A-Za-z0-9_]{1,200}$/.test(url.searchParams.get('session_id') ?? '') ? url.searchParams.get('session_id') : null, game: GAME_ID.test(url.searchParams.get('game') ?? '') ? url.searchParams.get('game') : null });
     if ((path === '/shop/refunds/' || path === '/shop/refunds') && read) return refundsPage(cat, shop);
     const parent = /^\/shop\/parent\/([A-Za-z0-9_-]{43})$/.exec(path);
-    if (parent) return await parentRoute(request, env, url, cat, shop, ready, parent[1]);
+    if (parent) return await parentRoute(request, env, url, cat, shop, ready, parent[1], ctx);
   } catch (error) {
-    if (/no such table/i.test(String(error?.message))) return fail(503, 'not-migrated', MISSING_WORDS.migration);
+    if (/no such table|no such column|has no column/i.test(String(error?.message))) return fail(503, 'not-migrated', MISSING_WORDS.migration);
     throw error;
   }
   return path.startsWith('/api/') ? fail(404, 'not-found', 'no such shop route') : notFoundPage('Nothing here.', cat);
@@ -219,16 +230,16 @@ export async function shopRoutes(request, env, ctx, url, { catalogueOf }) {
 async function listRoute(request, env, url, cat, shop, ready) {
   const game = GAME_ID.test(url.searchParams.get('game') ?? '') ? url.searchParams.get('game') : null;
   const facts = await serverFacts(env, cat, game, url.searchParams.get('server'));
-  if (facts.kids) return json({ ok: true, open: false, kids: true, items: [] });
+  if (facts.kids && !shop.policy.kidsServer) return json({ ok: true, open: false, kids: true, items: [] });
   const player = await accountOf(request, env);
-  const v = await itemsView(env, shop, { game, ...facts, player, open: ready.ready });
-  // An account that said it is under 13 is a kids account from then on: no shop, nothing listed.
-  if (v.band === 'child') return json({ ok: true, open: false, kids: true, items: [] });
+  const v = await itemsView(env, shop, { game, ...facts, player, open: ready.ready, item: shop.items.find((i) => i.id === url.searchParams.get('item') && (!game || !i.game || i.game === game)) ?? null, cursor: /^\d+$/.test(url.searchParams.get('cursor') ?? '') ? Number(url.searchParams.get('cursor')) : 0 });
+  // The studio decides which known age bands see no shop.
+  if ((v.band === 'child' && shop.policy.children === 'deny') || (v.band === 'teen' && shop.policy.teens === 'deny')) return json({ ok: true, open: false, kids: true, items: [] });
   return json({
-    ok: true, open: ready.ready, ...(ready.ready ? {} : { missing: ready.missing }), mode: ready.mode,
-    currency: shop.currency, till: shop.till, refundDays: shop.refundDays, cap: shop.capPerPlayerMonth, spent: v.spent,
+    ok: true, open: ready.ready, ...(ready.ready ? {} : { missing: ready.missing, migration: ready.migration }), mode: ready.mode,
+    currency: shop.currency, currencyScale: currencyScale(shop.currency), amountStep: amountStep(shop.currency), policy: shop.policy, till: shop.till, refundDays: shop.refundDays, cap: shop.capPerPlayerMonth, spent: v.spent,
     player: player ? { signedIn: !player.guest, guest: player.guest, name: player.name, band: v.band } : null,
-    owns: v.owns.map((o) => o.key), items: v.items,
+    owns: v.owns.map((o) => o.key), items: v.items, nextCursor: v.nextCursor,
   });
 }
 
@@ -239,7 +250,7 @@ async function ownsRoute(request, env, url, cat, shop) {
   const game = GAME_ID.test(url.searchParams.get('game') ?? '') ? url.searchParams.get('game') : null;
   const facts = await serverFacts(env, cat, game, url.searchParams.get('server'));
   const advantage = new Set((shop.items ?? []).filter((i) => i.advantage).map((i) => i.id));
-  const owns = (await ownsOf(env, p.id)).filter((o) => !((facts.kids || facts.beginner) && advantage.has(o.item)));
+  const owns = (await ownsOf(env, p.id)).filter((o) => !(((facts.kids && !shop.policy.kidsAdvantages) || (facts.beginner && !shop.policy.beginnerAdvantages)) && advantage.has(o.item)));
   return json({ ok: true, open: Boolean(shop.open), owns: owns.map((o) => o.key), detail: owns.map((o) => ({ key: o.key, item: o.item, until: o.until })) });
 }
 
@@ -248,7 +259,7 @@ async function mineRoute(request, env, shop) {
   if (!p) return json({ ok: true, player: null, orders: [], owns: [] });
   const data = await shopDataOf(env, p.id);
   const names = new Map((shop.items ?? []).map((i) => [i.id, i.name]));
-  return json({ ok: true, currency: shop.currency, refundDays: shop.refundDays, ageBand: data?.ageBand ?? null, orders: (data?.orders ?? []).map((o) => ({ ...o, name: names.get(o.item) ?? o.item, shown: money(o.amount, o.currency), refundable: refundableNow(o, data?.owns ?? [], shop) })).reverse(), owns: (data?.owns ?? []).map((o) => ({ key: o.key, item: o.item, until: o.until, used: o.used })), badges: (data?.owns ?? []).filter((o) => o.key.startsWith('badge:')).map((o) => (shop.items ?? []).find((i) => i.id === o.item)?.badge ?? o.key.slice(6)) });
+  return json({ ok: true, currency: shop.currency, refundDays: shop.refundDays, refundUsedItems: shop.policy.refundUsedItems, ageBand: data?.ageBand ?? null, orders: (data?.orders ?? []).map((o) => ({ ...o, name: names.get(o.item) ?? o.item, shown: money(o.amount, o.currency), refundable: refundableNow(o, data?.owns ?? [], shop) })).reverse(), owns: (data?.owns ?? []).map((o) => ({ key: o.key, item: o.item, until: o.until, used: o.used })), badges: (data?.owns ?? []).filter((o) => o.key.startsWith('badge:')).map((o) => (shop.items ?? []).find((i) => i.id === o.item)?.badge ?? o.key.slice(6)) });
 }
 
 /** The thanks page asks: is my order (of this session) paid yet? Only the buyer's own account sees it. */
@@ -258,22 +269,30 @@ async function orderRoute(request, env, url) {
   if (!p || !/^cs_[A-Za-z0-9_]{1,200}$/.test(session)) return json({ ok: true, status: null });
   const o = await orderBySession(env, session);
   if (!o || o.player !== p.id) return json({ ok: true, status: null });
-  return json({ ok: true, status: o.status, item: o.item, game: o.game ?? null });
+  return json({ ok: true, status: playerOrderStatus(o), item: o.item, game: o.game ?? null });
 }
 
 /** The neutral age question: a year of birth, once. Nothing hints which answer opens anything; no default. */
-async function ageRoute(request, env) {
-  const b = await bodyOf(request);
+async function ageRoute(request, env, shop) {
+  const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
-  const p = await players.of(request, env);
-  if (!p || p.guest) return fail(401, 'account', 'make an account first (a passkey)');
+  let p = await players.of(request, env);
+  let cookies = [];
+  const answer = bandOf(b.body.year, new Date(), shop.policy);
+  if (!answer) return fail(400, 'year', 'pick the year you were born');
+  if (!p && !shop.policy.requireAccount) {
+    const guest = await players.shopGuest(request, env, new URL(request.url), shop.guestBuyersPerAddressPerHour);
+    if (guest.error) return guest.error;
+    p = guest.session.player; cookies = guest.session.cookies;
+  }
+  if (!p || (p.guest && shop.policy.requireAccount)) return fail(401, 'account', 'The studio requires an account before its age question.');
   const before = await bandOfPlayer(env, p.id);
   if (before) return json({ ok: true, asked: true });
-  const band = bandOf(b.body.year);
-  if (!band) return fail(400, 'year', 'pick the year you were born');
-  await setBand(env, p.id, band);
+  await setBand(env, p.id, answer);
   // The answer itself is never said back: the shop's list shows what this account may do.
-  return json({ ok: true, asked: true });
+  const response = json({ ok: true, asked: true });
+  for (const cookie of cookies) response.headers.append('set-cookie', cookie);
+  return response;
 }
 
 export function sessionParams(shop, item, order, { origin, amount, player, game, parent = false, studio, product = null }) {
@@ -288,34 +307,90 @@ export function sessionParams(shop, item, order, { origin, amount, player, game,
       price_data: {
         currency: shop.currency, unit_amount: amount, tax_behavior: 'exclusive',
         // The catalog's Product (its name and tax code are Stripe's copy of shop.json's), or the item described inline.
-        ...(product ? { product } : { product_data: { name: item.name.slice(0, 120), ...(item.blurb ? { description: item.blurb.slice(0, 300) } : {}), ...(taxCode ? { tax_code: taxCode } : {}), metadata: { item: item.id } } }),
+        ...(product ? { product } : { product_data: { name: item.name, ...(item.blurb ? { description: item.blurb } : {}), ...(taxCode ? { tax_code: taxCode } : {}), metadata: { item: item.id.length <= 500 ? item.id : undefined } } }),
       },
     }],
     client_reference_id: player,
-    metadata: { homie: 'shop-v1', studio: String(studio ?? '').slice(0, 60), order: order.id, item: item.id, ...(game ? { game } : {}), ...(order.via ? { via: order.via } : {}), ...(parent ? { parent: '1' } : {}) },
-    payment_intent_data: { metadata: { order: order.id, item: item.id } },
+    // Stripe metadata values allow 500 characters; the order holds the complete item id.
+    // https://docs.stripe.com/metadata (fetched 2026-10-08).
+    metadata: { homie: 'shop-v1', studio: String(studio ?? '').length <= 500 ? String(studio ?? '') : undefined, order: order.id, item: item.id.length <= 500 ? item.id : undefined, ...(game ? { game } : {}), ...(order.via ? { via: order.via } : {}), ...(parent ? { parent: '1' } : {}) },
+    payment_intent_data: { metadata: { order: order.id, item: item.id.length <= 500 ? item.id : undefined } },
     success_url: `${origin}/shop/thanks?session_id={CHECKOUT_SESSION_ID}${back}`,
     cancel_url: `${origin}/shop/?cancelled=1${back}`,
-    expires_at: Math.floor(Date.now() / 1000) + 31 * 60,
+    // Stripe permits 30 minutes to 24 hours: https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-expires_at
+    expires_at: order.expiresAt ?? Math.floor((order.createdAt ?? Date.now()) / 1000) + 31 * 60,
     // The EU and UK immediate-delivery acknowledgement (Consumer Rights Directive Art 16(m)), beside the pay button.
-    custom_text: { submit: { message: `${parent ? 'This is for your child\'s account. ' : ''}Delivered at once to the player's account on ${String(studio ?? 'this studio').slice(0, 60)}. By paying you ask for it now, which ends the 14-day withdrawal right; an unused item can still be refunded within ${shop.refundDays} days.`.slice(0, 1200) } },
+    custom_text: { submit: { message: checkoutMessage(shop, String(studio ?? 'this studio'), parent) } },
     // The kit's own tills: Stripe Tax on (the studio is the seller), or Managed Payments (Stripe is the seller of record
     // and computes the tax itself, so automatic_tax and adaptive pricing must not be sent).
     ...(managed ? { managed_payments: { enabled: true } } : { automatic_tax: { enabled: true }, adaptive_pricing: { enabled: false } }),
   };
 }
 
+function logOrderError(env, order, error) {
+  const reason = String(error?.message ?? error).replaceAll(String(env.STRIPE_KEY || '\0'), '[redacted]');
+  console.warn('Shop reconciliation', { order, reason, status: error?.status ?? null, code: error?.code ?? null });
+}
+
+/** At most three reads in parallel, claimed before I/O. Old unresolved rows back off up to an hour.
+ * Stripe truth: https://docs.stripe.com/api/checkout/sessions/retrieve
+ * Missing sessions: https://docs.stripe.com/error-codes#resource-missing
+ * Payment time: https://docs.stripe.com/api/charges/object#charge_object-created
+ */
+export async function reconcileOrders(env, shop, player) {
+  const now = Date.now();
+  const rows = (await env.DB.prepare("SELECT * FROM shop_orders WHERE player = ?1 AND mode = ?2 AND session IS NOT NULL AND status IN ('started', 'processing') AND (expires_at IS NULL OR expires_at <= ?3 OR status = 'processing') AND updated_at <= ?3 - MIN(3600000, MAX(CASE WHEN status = 'processing' THEN 300000 ELSE 60000 END, CAST((?3 - created_at) / 24 AS INTEGER))) ORDER BY updated_at, id LIMIT 3")
+    .bind(player, modeOf(env.STRIPE_KEY), now).all()).results ?? [];
+  await Promise.all(rows.map(async (row) => {
+    const claim = await env.DB.prepare("UPDATE shop_orders SET updated_at = ?3 WHERE id = ?1 AND updated_at = ?2 AND status IN ('started', 'processing')").bind(row.id, row.updated_at, now).run();
+    if (!claim.meta?.changes) return;
+    try {
+      const session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(row.session)}`, { expand: ['payment_intent.latest_charge'] }, { timeout: 2000 });
+      if (!session || session.id !== row.session || (typeof session.livemode === 'boolean' && session.livemode !== (row.mode === 'live'))) throw new Error('Stripe session identity or mode mismatch');
+      const payment = session.payment_intent;
+      if (session.payment_status === 'paid' || session.payment_status === 'no_payment_required' || payment?.status === 'succeeded') {
+        const time = session.payment_status === 'no_payment_required' ? session.created : payment?.latest_charge?.created;
+        // Missing payment time remains unresolved; never charge an old payment to this month's allowance.
+        if (Number.isSafeInteger(time) && time > 0 && time * 1000 <= now) await paid(env, shop, session, time * 1000);
+      } else if (session.status === 'expired' || payment?.status === 'canceled' || (session.status === 'complete' && payment?.status === 'requires_payment_method' && payment.last_payment_error)) {
+        await env.DB.prepare("UPDATE shop_orders SET status = ?2, updated_at = ?3 WHERE id = ?1 AND status IN ('started', 'processing')").bind(row.id, session.status === 'expired' ? 'expired' : 'failed', now).run();
+      }
+    } catch (error) {
+      logOrderError(env, row.id, error);
+      // This key's account cannot see the session; a later verified payment still grants it.
+      if (error instanceof StripeError && error.status === 404 && error.code === 'resource_missing') {
+        await env.DB.prepare("UPDATE shop_orders SET status = 'missing', note = 'Stripe account has no such session; previous status: ' || status, updated_at = ?2 WHERE id = ?1 AND status IN ('started', 'processing')").bind(row.id, now).run();
+      } else {
+        // Keep the atomic claim, but retry failures after roughly a minute, regardless of row age.
+        const interval = Math.min(3600000, Math.max(row.status === 'processing' ? 300000 : 60000, Math.trunc((now - row.created_at) / 24)));
+        await env.DB.prepare("UPDATE shop_orders SET updated_at = ?3 WHERE id = ?1 AND updated_at = ?2 AND status IN ('started', 'processing')").bind(row.id, now, now - interval + 60000).run();
+      }
+    }
+  }).map((work, i) => work.catch((error) => logOrderError(env, rows[i].id, error))));
+}
+
 /** Make the order row, then Stripe's Checkout Session. Returns { order, url } or a refusal Response. */
 async function startCheckout(env, url, cat, shop, item, { player, game, via, amount, parent = false }) {
+  if (via && !Number.isSafeInteger(Math.round(amount * shop.referrals.rate))) return { error: fail(400, 'arithmetic', 'The referral share exceeds safe integer arithmetic; change the studio rate or amount.') };
   const order = { id: newOrderId(), player: player.id, via: via ?? null, amount, currency: shop.currency };
   const now = Date.now();
-  await env.DB.prepare("INSERT INTO shop_orders (id, player, item, game, amount, currency, till, mode, status, parent, via, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'started', ?9, ?10, ?11, ?11)")
-    .bind(order.id, player.id, item.id, game ?? item.game ?? null, amount, shop.currency, shop.till, modeOf(env.STRIPE_KEY), parent ? 1 : 0, order.via, now).run();
+  order.createdAt = now;
+  order.expiresAt = Math.floor(now / 1000) + 31 * 60;
+  // One SQL statement reserves the amount: concurrent requests cannot both spend the remaining cap.
+  const reserve = () => env.DB.prepare("INSERT INTO shop_orders (id, player, item, game, amount, currency, till, mode, status, parent, via, created_at, updated_at, expires_at) SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'started', ?9, ?10, ?11, ?11, ?14 WHERE ?5 = 0 OR ?12 IS NULL OR ?5 <= ?12 - (SELECT COALESCE(SUM(amount), 0) FROM shop_orders WHERE player = ?2 AND mode = ?8 AND ((status IN ('paid', 'disputed') AND paid_at >= ?13) OR (status IN ('started', 'processing') AND (session IS NOT NULL OR COALESCE(expires_at, created_at + 1860000) + 60000 > ?11))))")
+    .bind(order.id, player.id, item.id, game ?? item.game ?? null, amount, shop.currency, shop.till, modeOf(env.STRIPE_KEY), parent ? 1 : 0, order.via, now, shop.capPerPlayerMonth, Date.UTC(new Date(now).getUTCFullYear(), new Date(now).getUTCMonth(), 1), order.expiresAt * 1000).run();
+  let reserved = await reserve();
+  const reconciled = !reserved.meta?.changes;
+  if (!reserved.meta?.changes) {
+    await reconcileOrders(env, shop, player.id);
+    reserved = await reserve();
+  }
+  if (!reserved.meta?.changes) return { error: fail(403, 'cap', WAY_WORDS.cap, { way: 'cap' }) };
   let session = null;
   const mode = modeOf(env.STRIPE_KEY);
-  const product = Array.isArray(shop.catalog) && shop.catalog.includes(mode) ? productIdOf(cat.studio?.slug, item.id) : null;
-  const params = (p) => sessionParams(shop, item, order, { origin: url.origin, amount, player: player.id, game, parent, studio: cat.studio?.name, product: p });
   try {
+    const product = Array.isArray(shop.catalog) && shop.catalog.includes(mode) ? await productIdOf(cat.studio?.slug, item.id) : null;
+    const params = (p) => sessionParams(shop, item, order, { origin: url.origin, amount, player: player.id, game, parent, studio: cat.studio?.name, product: p });
     try {
       session = await createCheckoutSession(env, params(product), { idempotencyKey: `checkout-${order.id}` });
     } catch (error) {
@@ -324,16 +399,17 @@ async function startCheckout(env, url, cat, shop, item, { player, game, via, amo
       if (!product || !isMissingProduct(error)) throw error;
       session = await createCheckoutSession(env, params(null), { idempotencyKey: `checkout-${order.id}-inline` });
     }
+    if (typeof session?.id !== 'string' || typeof session?.url !== 'string' || !/^https:\/\//.test(session.url) && !/^http:\/\/(127\.0\.0\.1|localhost)/.test(session.url)) {
+      await env.DB.prepare("UPDATE shop_orders SET status = 'failed', updated_at = ?2 WHERE id = ?1").bind(order.id, Date.now()).run();
+      return { error: fail(502, 'stripe', 'Stripe answered without a checkout page. Nothing was charged.') };
+    }
+    await env.DB.prepare('UPDATE shop_orders SET session = ?2, updated_at = ?3 WHERE id = ?1').bind(order.id, session.id, Date.now()).run();
   } catch (error) {
     await env.DB.prepare("UPDATE shop_orders SET status = 'failed', note = ?2, updated_at = ?3 WHERE id = ?1").bind(order.id, String(error?.code ?? 'stripe').slice(0, 60), Date.now()).run();
     const why = error instanceof StripeError ? error.message : 'Stripe did not answer';
     return { error: fail(502, 'stripe', `Stripe could not open the checkout (${why}). Nothing was charged.`) };
   }
-  if (typeof session?.id !== 'string' || typeof session?.url !== 'string' || !/^https:\/\//.test(session.url) && !/^http:\/\/(127\.0\.0\.1|localhost)/.test(session.url)) {
-    return { error: fail(502, 'stripe', 'Stripe answered without a checkout page. Nothing was charged.') };
-  }
-  await env.DB.prepare('UPDATE shop_orders SET session = ?2, updated_at = ?3 WHERE id = ?1').bind(order.id, session.id, Date.now()).run();
-  return { order, url: session.url, session: session.id };
+  return { order, url: session.url, session: session.id, reconciled };
 }
 
 /** The referrer this buyer brought, if it still counts: their arrival, a new account since it, in the window, proven. */
@@ -341,60 +417,74 @@ async function viaFor(request, env, url, shop, player) {
   if (!shop.referrals || !(shop.referrals.rate > 0)) return null;
   const a = await arrivalOf(request, env);
   if (!a || a.via === url.hostname.replace(/^www\./, '')) return null;
-  if (Date.now() - a.at > shop.referrals.windowDays * DAY) return null;
+  if (shop.referrals.windowDays !== null && Date.now() - a.at > Math.round(shop.referrals.windowDays * DAY)) return null;
   // New players only: an account made before the arrival was already this studio's player.
   if (player.since !== null && player.since < a.at - 60_000) return null;
   return (await referrerOk(a.via)) ? a.via : null;
 }
 
 const WAY_WORDS = Object.freeze({
-  closed: 'The shop is not open yet.', kids: 'Nothing is sold on a kids server.', beginner: 'Not sold on a beginner server.',
+  closed: 'The shop is not open yet.', kids: 'The studio policy.kidsServer setting closes this shop on kids servers.', beginner: 'The studio server advantage settings hide this item here.',
   owned: 'You have it already.', 'make-an-account': 'Make an account first (a passkey), so what you buy stays yours on every device.',
   'age-question': 'One question first: the year you were born.', no: 'This shop sells nothing to this account.',
-  'ask-a-parent': 'A parent or guardian buys this for you: send them the link.', cap: 'That is this month\'s limit for this account here.',
+  'ask-a-parent': 'A parent or guardian buys this for you: send them the link.', cap: 'That reaches the studio capPerPlayerMonth setting for this account.',
   'not-yet': 'Not on sale yet.', over: 'No longer on sale.',
 });
 
-async function buyRoute(request, env, url, cat, shop, ready) {
-  const b = await bodyOf(request);
+function purchaseLimited(request, shop, player, kind) {
+  const account = player && limited(`${kind}:account:${player}`, shop.purchaseAttemptsPerMinute, 60_000);
+  const address = limited(`${kind}:address:${addressOf(request)}`, shop.purchaseAttemptsPerAddressPerMinute, 60_000);
+  return account || address;
+}
+
+async function buyRoute(request, env, url, cat, shop, ready, ctx) {
+  const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
-  if (!ready.ready) return fail(503, 'closed', 'The shop is not open yet.', { missing: ready.missing });
+  if (!ready.ready) return fail(503, 'closed', 'The shop is not open yet.', { missing: ready.missing, migration: ready.migration });
   const item = shop.items.find((i) => i.id === b.body.item);
   if (!item) return fail(404, 'item', 'no such item here');
   const game = GAME_ID.test(String(b.body.game ?? '')) ? String(b.body.game) : null;
   if (item.game && game && item.game !== game) return fail(400, 'item', 'that item belongs to another game');
   const facts = await serverFacts(env, cat, game, b.body.server);
-  const player = await accountOf(request, env);
-  if (player && limited(`buy:${player.id}`, BUYS_PER_MINUTE, 60_000)) return fail(429, 'rate', 'one moment: too many tries');
-  const v = await itemsView(env, shop, { game, ...facts, player, open: true });
+  let player = await accountOf(request, env);
+  if (purchaseLimited(request, shop, player?.id, 'buy')) return fail(429, 'rate', 'The studio purchase attempt rate limit was reached; try again in a minute.');
+  const v = await itemsView(env, shop, { game, ...facts, player, open: true, item, purchasing: true });
   const row = v.items.find((i) => i.id === item.id);
-  const way = facts.kids ? 'kids' : row?.way ?? (item.advantage && facts.beginner ? 'beginner' : 'closed');
+  const way = facts.kids && !shop.policy.kidsServer ? 'kids' : row?.way ?? (item.advantage && facts.beginner ? 'beginner' : 'closed');
   if (way !== 'checkout') return fail(403, way, WAY_WORDS[way] ?? 'Not now.', { way });
   let amount = item.price;
   if (item.kind === 'tip') {
-    amount = Math.floor(Number(b.body.amount));
-    if (!(amount >= item.min && amount <= item.max)) return fail(400, 'amount', `a tip is ${money(item.min, shop.currency)} to ${money(item.max, shop.currency)}`);
-    if (v.spent + amount > shop.capPerPlayerMonth) return fail(403, 'cap', WAY_WORDS.cap, { way: 'cap' });
+    amount = typeof b.body.amount === 'number' ? b.body.amount : NaN;
+    if (amountError(amount, shop.currency) || !(amount >= item.min && (item.max === null || amount <= item.max))) return fail(400, 'amount', amountError(amount, shop.currency) ?? `The studio tip range starts at ${money(item.min, shop.currency)}${item.max === null ? '' : ` and ends at ${money(item.max, shop.currency)}`}.`);
+  }
+  let cookies = [];
+  if (!player) {
+    const guest = await players.shopGuest(request, env, url, shop.guestBuyersPerAddressPerHour);
+    if (guest.error) return guest.error;
+    player = guest.session.player;
+    cookies = guest.session.cookies;
   }
   const via = await viaFor(request, env, url, shop, player);
   const r = await startCheckout(env, url, cat, shop, item, { player, game, via, amount });
-  if (r.error) return r.error;
-  return json({ ok: true, order: r.order.id, url: r.url });
+  const response = r.error ?? json({ ok: true, order: r.order.id, url: r.url });
+  if (!r.error && !r.reconciled && shop.capPerPlayerMonth !== null && ctx?.waitUntil) ctx.waitUntil(reconcileOrders(env, shop, player.id).catch((error) => logOrderError(env, r.order.id, error)));
+  for (const cookie of cookies) response.headers.append('set-cookie', cookie);
+  return response;
 }
 
 /** 13-17: a one-time link for a parent (7 days). The teen passes it on; nothing here pressures anyone. */
 async function parentLinkRoute(request, env, url, cat, shop, ready) {
-  const b = await bodyOf(request);
+  const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
-  if (!ready.ready) return fail(503, 'closed', 'The shop is not open yet.', { missing: ready.missing });
+  if (!ready.ready) return fail(503, 'closed', 'The shop is not open yet.', { missing: ready.missing, migration: ready.migration });
   const item = shop.items.find((i) => i.id === b.body.item);
-  if (!item || item.kind === 'tip') return fail(404, 'item', 'no such item here');
+  if (!item) return fail(404, 'item', 'no such item here');
   const game = GAME_ID.test(String(b.body.game ?? '')) ? String(b.body.game) : null;
   const facts = await serverFacts(env, cat, game, b.body.server);
   const player = await accountOf(request, env);
-  if (player && limited(`parent:${player.id}`, BUYS_PER_MINUTE, 60_000)) return fail(429, 'rate', 'one moment: too many tries');
-  const v = await itemsView(env, shop, { game, ...facts, player, open: true });
-  const way = facts.kids ? 'kids' : v.items.find((i) => i.id === item.id)?.way ?? 'closed';
+  if (purchaseLimited(request, shop, player?.id, 'parent')) return fail(429, 'rate', 'The studio purchase attempt rate limit was reached; try again in a minute.');
+  const v = await itemsView(env, shop, { game, ...facts, player, open: true, item, purchasing: true });
+  const way = facts.kids && !shop.policy.kidsServer ? 'kids' : v.items.find((i) => i.id === item.id)?.way ?? 'closed';
   if (way !== 'ask-a-parent') return fail(403, way, WAY_WORDS[way] ?? 'Not now.', { way });
   const token = randomToken();
   await env.DB.prepare('INSERT INTO shop_parent_links (hash, player, item, game, order_id, expires_at) VALUES (?1, ?2, ?3, ?4, NULL, ?5)').bind(await sha256Hex(token), player.id, item.id, game, Date.now() + 7 * DAY).run();
@@ -402,7 +492,7 @@ async function parentLinkRoute(request, env, url, cat, shop, ready) {
 }
 
 /** /shop/parent/<token>: what, for whom, the price; the parent pays in their own name on Stripe's page. */
-async function parentRoute(request, env, url, cat, shop, ready, token) {
+async function parentRoute(request, env, url, cat, shop, ready, token, ctx) {
   if (!TOKEN.test(token)) return notFoundPage('This link does not work.', cat);
   const row = await env.DB.prepare('SELECT * FROM shop_parent_links WHERE hash = ?1').bind(await sha256Hex(token)).first();
   const item = row ? shop.items.find((i) => i.id === row.item) : null;
@@ -417,51 +507,56 @@ async function parentRoute(request, env, url, cat, shop, ready, token) {
   try { form = await request.formData(); } catch { form = null; }
   if (String(form?.get('grownup') ?? '') !== 'yes') return parentPage(cat, shop, { item, name: kid.name, token, open: ready.ready, said: 'Tick the box to say you are their parent or guardian and an adult.' });
   if (!ready.ready) return parentPage(cat, shop, { item, name: kid.name, token, open: false });
-  if (limited(`parentpay:${row.player}`, BUYS_PER_MINUTE, 60_000)) return parentPage(cat, shop, { item, name: kid.name, token, open: true, said: 'One moment: too many tries.' });
+  if (purchaseLimited(request, shop, row.player, 'parentpay')) return parentPage(cat, shop, { item, name: kid.name, token, open: true, said: 'One moment: too many tries.' });
   const band = await bandOfPlayer(env, row.player);
-  const spent = await spentThisMonth(env, row.player);
-  if (band !== 'teen' || spent + item.price > shop.capPerPlayerMonth) return parentPage(cat, shop, { gone: true });
-  const r = await startCheckout(env, url, cat, shop, item, { player: { id: row.player }, game: row.game, via: null, amount: item.price, parent: true });
-  if (r.error) return parentPage(cat, shop, { item, name: kid.name, token, open: true, said: 'Stripe could not open the checkout just now. Nothing was charged; try again in a minute.' });
+  const owns = await ownsOf(env, row.player);
+  const owned = item.gives.length > 0 && item.gives.every((key) => owns.some((o) => o.key === key && o.item === item.id));
+  if (wayFor(item, { player: kid, band, owned, spent: 0, cap: null, policy: shop.policy }) !== 'ask-a-parent') return parentPage(cat, shop, { gone: true });
+  const amount = item.kind === 'tip' ? parseAmount(form?.get('amount'), currencyScale(shop.currency)) : item.price;
+  const invalidAmount = amountError(amount, shop.currency);
+  if (invalidAmount || (item.kind === 'tip' && (amount < item.min || (item.max !== null && amount > item.max)))) return parentPage(cat, shop, { item, name: kid.name, token, said: invalidAmount ?? 'This amount exceeds the studio tip range or monthly cap.' });
+  const r = await startCheckout(env, url, cat, shop, item, { player: { id: row.player }, game: row.game, via: null, amount, parent: true });
+  if (r.error) return parentPage(cat, shop, { item, name: kid.name, token, open: true, said: (await r.error.json()).message });
   await env.DB.prepare('UPDATE shop_parent_links SET order_id = ?2 WHERE hash = ?1').bind(await sha256Hex(token), r.order.id).run();
+  if (!r.reconciled && shop.capPerPlayerMonth !== null && ctx?.waitUntil) ctx.waitUntil(reconcileOrders(env, shop, row.player).catch((error) => logOrderError(env, r.order.id, error)));
   return Response.redirect(r.url, 303);
 }
 
 /** The game says the player used something (equipped a skin, played the pass): it is no longer refundable by the player. */
-async function usedRoute(request, env) {
-  const b = await bodyOf(request);
+async function usedRoute(request, env, shop) {
+  const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
   const p = await players.of(request, env);
   if (!p) return json({ ok: true, used: 0 });
   const key = String(b.body.key ?? '');
-  if (!/^[a-z0-9][a-z0-9_.:-]{0,63}$/.test(key)) return fail(400, 'key', 'name the key the game read');
+  if (!ENTITLEMENT_KEY.test(key)) return fail(400, 'key', 'name the key the game read');
   const r = await env.DB.prepare("UPDATE entitlements SET used_at = ?3 WHERE player = ?1 AND key = ?2 AND used_at IS NULL AND state = 'active'").bind(p.id, key, Date.now()).run();
   return json({ ok: true, used: Number(r?.meta?.changes ?? 0) });
 }
 
 function refundableNow(order, owns, shop, now = Date.now()) {
-  if (order.status !== 'paid' || order.paidAt === null) return false;
-  if (now - order.paidAt > shop.refundDays * DAY) return false;
-  return !owns.some((o) => o.item === order.item && o.used);
+  if (shop.refundDays === null || order.status !== 'paid' || order.paidAt === null) return false;
+  if (now - order.paidAt > Math.round(shop.refundDays * DAY)) return false;
+  return shop.policy.refundUsedItems || !owns.some((o) => o.item === order.item && o.used);
 }
 
 /** A player's own refund: an unused item, within the studio's refund days (fewer disputes, and the respected norm). */
 async function selfRefundRoute(request, env, shop, ready) {
-  const b = await bodyOf(request);
+  const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
   const p = await players.of(request, env);
-  if (!p || p.guest) return fail(401, 'account', 'sign in first');
+  if (!p) return fail(401, 'account', 'sign in first');
   const o = await orderById(env, b.body.order);
   if (!o || o.player !== p.id) return fail(404, 'order', 'no such order on this account');
   const used = await env.DB.prepare('SELECT COUNT(*) AS n FROM entitlements WHERE order_id = ?1 AND used_at IS NOT NULL').bind(o.id).first();
-  if (!refundableNow(orderView(o), Number(used?.n) ? [{ item: o.item, used: true }] : [], shop)) return fail(403, 'not-refundable', `Only an unused item, within ${shop.refundDays} days. Ask the studio for anything else.`);
-  if (!KEY_SHAPE.test(String(env.STRIPE_KEY ?? ''))) return fail(503, 'closed', MISSING_WORDS['stripe-key']);
+  if (!refundableNow(orderView(o), Number(used?.n) ? [{ item: o.item, used: true }] : [], shop)) return fail(403, 'not-refundable', shop.refundDays === null ? 'Ask the studio for a refund; it has not set a self-service refund window.' : `The studio allows self-service refunds for ${shop.policy.refundUsedItems ? 'items' : 'unused items'} within ${shop.refundDays} days. Ask the studio for anything else.`);
+  if (Number(o.amount) !== 0 && !KEY_SHAPE.test(String(env.STRIPE_KEY ?? ''))) return fail(503, 'closed', MISSING_WORDS['stripe-key']);
   const r = await refundOrder(env, o, { reason: 'requested_by_customer', by: 'player' });
   if (r.held) return json({ ok: false, held: true, error: 'held', message: 'The studio approves this refund in Stripe first. Your money comes back once they do, and the item leaves your account then.' }, 202);
   return json(r, r.ok ? 200 : 502);
 }
 
-/* ------------------------------------------------------------------ the webhook: the only writer of money states */
+/* ------------------------------------------------------------------ Stripe events and reconciliation share idempotent money transitions */
 
 async function hook(request, env, cat, shop, ready) {
   if (request.method !== 'POST') return fail(405, 'method', 'POST only');
@@ -479,11 +574,15 @@ async function hook(request, env, cat, shop, ready) {
   switch (ev.type) {
     case 'checkout.session.completed':
     case 'checkout.session.async_payment_succeeded':
-      did = obj.payment_status === 'paid' || obj.payment_status === 'no_payment_required' ? await paid(env, shop, obj) : 'waiting';
+      if (ev.type === 'checkout.session.async_payment_succeeded' || obj.payment_status === 'paid' || obj.payment_status === 'no_payment_required') did = await paid(env, shop, obj);
+      else {
+        await env.DB.prepare("UPDATE shop_orders SET status = 'processing', updated_at = ?2 WHERE session = ?1 AND status = 'started'").bind(String(obj.id ?? ''), Date.now()).run();
+        did = 'waiting';
+      }
       break;
     case 'checkout.session.async_payment_failed':
     case 'checkout.session.expired':
-      await env.DB.prepare('UPDATE shop_orders SET status = ?2, updated_at = ?3 WHERE session = ?1 AND status = \'started\'').bind(String(obj.id ?? ''), ev.type.endsWith('expired') ? 'expired' : 'failed', Date.now()).run();
+      await env.DB.prepare('UPDATE shop_orders SET status = ?2, updated_at = ?3 WHERE session = ?1 AND status IN (\'started\', \'processing\', \'missing\', \'released\')').bind(String(obj.id ?? ''), ev.type.endsWith('expired') ? 'expired' : 'failed', Date.now()).run();
       did = 'closed';
       break;
     case 'charge.refunded':
@@ -491,7 +590,11 @@ async function hook(request, env, cat, shop, ready) {
       break;
     case 'refund.created':
     case 'refund.updated':
-      if (obj.status === 'succeeded') did = await refunded(env, String(obj.payment_intent ?? ''), String(obj.id ?? ''));
+      // Individual refunds may be partial. charge.refunded supplies the cumulative full-refund truth.
+      if (obj.status === 'succeeded') {
+        const order = await orderByPayment(env, String(obj.payment_intent ?? ''));
+        if (order && Number(obj.amount) >= Number(order.total ?? order.amount)) did = await refunded(env, String(obj.payment_intent ?? ''), String(obj.id ?? ''));
+      }
       break;
     case 'charge.dispute.created':
       did = await disputed(env, String(obj.payment_intent ?? ''), String(obj.id ?? ''));
@@ -508,17 +611,17 @@ async function hook(request, env, cat, shop, ready) {
 }
 
 /** A paid checkout: the order is paid, its entitlements granted, a referral line written. Idempotent. */
-async function paid(env, shop, session) {
+async function paid(env, shop, session, paidAt = Date.now()) {
   const o = await orderBySession(env, session.id);
   if (!o) return 'unknown-order';
   // The session must be the one this order opened, for this player and this price.
   if (session.metadata?.order !== o.id || (session.client_reference_id && session.client_reference_id !== o.player)) return 'mismatch';
-  if (session.currency && session.currency === o.currency && Number.isFinite(Number(session.amount_subtotal)) && Number(session.amount_subtotal) !== Number(o.amount)) return 'mismatch';
-  if (o.status === 'paid' || o.status === 'refunded' || o.status === 'disputed') return 'already';
+  if (session.currency !== o.currency || !Number.isSafeInteger(session.amount_subtotal) || session.amount_subtotal !== Number(o.amount)) return 'mismatch';
+  if (o.paid_at !== null) return 'already';
   const item = shop.items.find((i) => i.id === o.item);
   const now = Date.now();
-  const res = await env.DB.prepare("UPDATE shop_orders SET status = 'paid', payment = ?2, tax = ?3, total = ?4, paid_at = ?5, updated_at = ?5 WHERE id = ?1 AND status IN ('started', 'failed', 'expired')")
-    .bind(o.id, typeof session.payment_intent === 'string' ? session.payment_intent : session.payment_intent?.id ?? null, Number.isFinite(Number(session.total_details?.amount_tax)) ? Number(session.total_details.amount_tax) : null, Number.isFinite(Number(session.amount_total)) ? Number(session.amount_total) : null, now).run();
+  const res = await env.DB.prepare("UPDATE shop_orders SET status = 'paid', payment = ?2, tax = ?3, total = ?4, paid_at = ?5, updated_at = ?6 WHERE id = ?1 AND paid_at IS NULL")
+    .bind(o.id, typeof session.payment_intent === 'string' ? session.payment_intent : session.payment_intent?.id ?? null, Number.isFinite(Number(session.total_details?.amount_tax)) ? Number(session.total_details.amount_tax) : null, Number.isFinite(Number(session.amount_total)) ? Number(session.amount_total) : null, paidAt, now).run();
   if (!Number(res?.meta?.changes ?? 1)) return 'already';
   const writes = [];
   if (o.player && item) writes.push(...grantStatements(env, o, item, now));
@@ -542,7 +645,7 @@ async function refunded(env, payment, refundId) {
   return 'refunded';
 }
 
-/** A dispute changes nothing until it is decided: the player keeps the item and their account (FTC v. Epic). */
+/** A dispute changes nothing until it is decided: the player keeps the item and their account. */
 async function disputed(env, payment, disputeId) {
   const o = payment ? await orderByPayment(env, payment) : null;
   if (!o) return 'unknown-order';
@@ -576,6 +679,11 @@ export const REFUND_HELD = 'Stripe is holding this refund until a person approve
 /** Refund one order in full with Stripe, then take back that one item. The webhook confirms the same (idempotent). */
 export async function refundOrder(env, o, { reason = 'requested_by_customer', by = 'owner' } = {}) {
   if (o.status !== 'paid') return { ok: false, error: 'state', message: o.status === 'disputed' ? 'This order is disputed: the card network decides it now (answer it in Stripe).' : `This order is ${o.status}, not paid.` };
+  if (Number(o.amount) === 0) {
+    const now = Date.now();
+    await env.DB.batch([env.DB.prepare("UPDATE shop_orders SET status = 'refunded', refunded_at = ?2, updated_at = ?2 WHERE id = ?1 AND status = 'paid'").bind(o.id, now), revokeStatement(env, o.id), ...voidLineStatements(env, o.id)]);
+    return { ok: true, order: o.id, amount: 0, currency: o.currency, status: 'succeeded', refund: null };
+  }
   if (!o.payment) return { ok: false, error: 'no-payment', message: 'Stripe has not said which payment this was yet; try again in a minute.' };
   let refund = null;
   try {
@@ -604,9 +712,31 @@ export function checkRefund(body) {
   const note = String(body.note ?? '').replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ').trim().slice(0, 140) || null;
   return { ok: true, action: { op: 'refund', order: body.order, reason, note } };
 }
+/** Explicit owner override of an unresolved reservation; the existing note records its actor and time. */
+export function checkRelease(body) {
+  const checked = checkRefund(body);
+  return checked.ok ? { ok: true, action: { op: 'shop-release', order: body.order } } : checked;
+}
+export async function performRelease(env, a) {
+  const row = await orderById(env, a.order);
+  if (!row || !['started', 'processing'].includes(row.status)) return { ok: false, error: 'state', message: 'Only an unresolved order can be released.' };
+  // https://docs.stripe.com/api/checkout/sessions/expire — only open sessions can expire.
+  if (row.session) {
+    try {
+      const session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(row.session)}`, null, { timeout: 2000 });
+      if (session?.id === row.session && session.status === 'open') await expireCheckoutSession(env, row.session, { timeout: 2000 });
+    } catch (error) { logOrderError(env, row.id, error); }
+  }
+  const at = Date.now();
+  const note = `Reservation released by ${a.by} at ${new Date(at).toISOString()}`;
+  const result = await env.DB.prepare("UPDATE shop_orders SET status = 'released', note = ?2 || '; previous status: ' || status, updated_at = ?3 WHERE id = ?1 AND status IN ('started', 'processing')").bind(a.order, note, at).run();
+  return result.meta?.changes ? { ok: true, order: a.order, by: a.by, at } : { ok: false, error: 'state', message: 'Only an unresolved order can be released.' };
+}
+
 export function checkSettle(body) {
-  if (!/^[a-z0-9.-]{3,80}$/.test(String(body.via ?? ''))) return { ok: false, error: 'bad-request', message: 'via is the referrer\'s host (as the shop page shows it)' };
-  return { ok: true, action: { op: 'shop-settle', via: String(body.via), ref: String(body.ref ?? '').slice(0, 80) } };
+  if (!/^[a-z0-9.-]{3,253}$/.test(String(body.via ?? ''))) return { ok: false, error: 'bad-request', message: 'via is the referrer\'s host (as the shop page shows it)' };
+  if (!/^[a-z]{3}$/.test(body.currency ?? '')) return { ok: false, error: 'currency', message: 'Choose the currency to mark paid.' };
+  return { ok: true, action: { op: 'shop-settle', currency: body.currency, via: String(body.via), ref: String(body.ref ?? '').slice(0, 80) } };
 }
 
 /** The refund in plain words, for the owner's confirm page and the AI's card. */
@@ -625,13 +755,13 @@ export async function performRefund(env, cat, a) {
 }
 
 /** Everything the office's shop page shows. Money is read from this studio's D1; Stripe's own pages are linked. */
-export async function shopOffice(env, cat, origin) {
+export async function shopOffice(env, cat, origin, cursor = '', itemCursor = 0, orderCursor = 0) {
   const shop = shopOf(cat);
   const ready = await readiness(env, shop);
   const mode = ready.mode ?? 'test';
   const out = {
-    ok: true, ready: ready.ready, missing: ready.missing.map((m) => ({ id: m, words: MISSING_WORDS[m] ?? m })), mode: ready.mode,
-    shop: shop ? { till: shop.till, currency: shop.currency, refundDays: shop.refundDays, cap: shop.capPerPlayerMonth, items: shop.items.map((i) => ({ id: i.id, kind: i.kind, name: i.name, price: i.price, shown: i.kind === 'tip' ? `${money(i.min, shop.currency)}+` : money(i.price, shop.currency), gives: i.gives, game: i.game ?? null })), referrals: shop.referrals, ...(shop.broken ? { broken: shop.broken } : {}) } : null,
+    ok: true, ready: ready.ready, missing: ready.missing.map((m) => ({ id: m, words: m === 'migration' ? `The shop needs ${ready.migration}; npm run deploy applies it.` : MISSING_WORDS[m] ?? m })), mode: ready.mode,
+    shop: shop ? { policy: shop.policy, purchaseAttemptsPerMinute: shop.purchaseAttemptsPerMinute, till: shop.till, currency: shop.currency, refundDays: shop.refundDays, cap: shop.capPerPlayerMonth, nextItemsCursor: itemCursor + 100 < shop.items.length ? String(itemCursor + 100) : null, items: shop.items.slice(itemCursor, itemCursor + 100).map((i) => ({ id: i.id, kind: i.kind, name: i.name, price: i.price, shown: i.kind === 'tip' ? `${money(i.min, shop.currency)}+` : money(i.price, shop.currency), gives: i.gives, game: i.game ?? null })), referrals: shop.referrals, ...(shop.broken ? { broken: shop.broken } : {}) } : null,
     stripe: {
       payments: dashboardLink(mode, 'payments'), refunds: dashboardLink(mode, 'refunds'), disputes: dashboardLink(mode, 'disputes'), payouts: dashboardLink(mode, 'payouts'),
       balance: dashboardLink(mode, 'balance'), tax: dashboardLink(mode, 'tax'), keys: dashboardLink(mode, 'keys'), webhooks: dashboardLink(mode, 'webhooks'),
@@ -644,14 +774,18 @@ export async function shopOffice(env, cat, origin) {
   const since = Date.now() - 30 * DAY;
   const t = await env.DB.prepare("SELECT SUM(CASE WHEN status IN ('paid', 'disputed') THEN amount ELSE 0 END) AS paid, SUM(CASE WHEN status IN ('paid', 'disputed') THEN 1 ELSE 0 END) AS sales, SUM(CASE WHEN status = 'refunded' THEN amount ELSE 0 END) AS refunded, SUM(CASE WHEN status = 'refunded' THEN 1 ELSE 0 END) AS refunds, SUM(CASE WHEN status = 'disputed' THEN 1 ELSE 0 END) AS disputes, SUM(CASE WHEN status = 'lost' THEN 1 ELSE 0 END) AS lost FROM shop_orders WHERE created_at >= ?1").bind(since).first();
   out.totals = { days: 30, currency: shop?.currency ?? 'usd', paid: Number(t?.paid) || 0, sales: Number(t?.sales) || 0, refunded: Number(t?.refunded) || 0, refunds: Number(t?.refunds) || 0, disputes: Number(t?.disputes) || 0, lost: Number(t?.lost) || 0 };
-  const rows = (await env.DB.prepare("SELECT o.*, p.name AS player_name FROM shop_orders o LEFT JOIN players p ON p.id = o.player WHERE o.status != 'started' OR o.created_at >= ?1 ORDER BY o.created_at DESC LIMIT 100").bind(Date.now() - DAY).all()).results ?? [];
+  const rows = (await env.DB.prepare("SELECT o.*, p.name AS player_name FROM shop_orders o LEFT JOIN players p ON p.id = o.player ORDER BY CASE WHEN o.status IN ('started', 'processing') THEN 0 ELSE 1 END, o.created_at DESC, o.id LIMIT 101 OFFSET ?1").bind(orderCursor).all()).results ?? [];
+  out.nextOrdersCursor = rows.length > 100 ? String(orderCursor + 100) : null;
+  if (rows.length > 100) rows.pop();
   const names = new Map((shop?.items ?? []).map((i) => [i.id, i.name]));
   out.orders = rows.map((r) => ({
-    ...orderView(r), name: names.get(r.item) ?? r.item, shown: money(r.amount, r.currency), player: r.player ? { id: r.player, name: r.player_name ?? null } : null,
+    ...orderView(r), note: r.note ?? null, name: names.get(r.item) ?? r.item, shown: money(r.amount, r.currency), player: r.player ? { id: r.player, name: r.player_name ?? null } : null,
     stripe: r.payment ? dashboardLink(r.mode, 'payment', r.payment) : null, dispute: r.dispute ? dashboardLink(r.mode, 'dispute', r.dispute) : null,
-    refundable: r.status === 'paid' && Boolean(r.payment),
+    releasable: ['started', 'processing'].includes(r.status),
+    refundable: r.status === 'paid' && (Number(r.amount) === 0 || Boolean(r.payment)),
   }));
-  out.referrals = { owe: await booksOf(env), owedToUs: await statementsIn(env), invoice: dashboardLink(mode, 'invoices') };
+  const { books, nextCursor } = await booksOf(env, { cursor });
+  out.referrals = { nextCursor, owe: books, failures: await statementFailures(env), owedToUs: await statementsIn(env), invoice: dashboardLink(mode, 'invoices') };
   return out;
 }
 
@@ -661,25 +795,23 @@ export async function ordersCsv(env) {
   const cell = (v) => { const s = v === null || v === undefined ? '' : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; };
   const head = ['order', 'created', 'paid', 'refunded', 'status', 'item', 'game', 'amount', 'tax', 'total', 'currency', 'till', 'mode', 'parent', 'via', 'stripe_payment', 'stripe_refund', 'stripe_dispute'];
   const iso = (t) => (t ? new Date(Number(t)).toISOString() : '');
-  const lines = rows.map((r) => [r.id, iso(r.created_at), iso(r.paid_at), iso(r.refunded_at), r.status, r.item, r.game, (Number(r.amount) / 100).toFixed(2), r.tax === null ? '' : (Number(r.tax) / 100).toFixed(2), r.total === null ? '' : (Number(r.total) / 100).toFixed(2), r.currency, r.till, r.mode, Number(r.parent) ? 'yes' : '', r.via, r.payment, r.refund, r.dispute].map(cell).join(','));
+  const lines = rows.map((r) => [r.id, iso(r.created_at), iso(r.paid_at), iso(r.refunded_at), r.status, r.item, r.game, (Number(r.amount) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.tax === null ? '' : (Number(r.tax) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.total === null ? '' : (Number(r.total) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.currency, r.till, r.mode, Number(r.parent) ? 'yes' : '', r.via, r.payment, r.refund, r.dispute].map(cell).join(','));
   return `${head.join(',')}\n${lines.join('\n')}${lines.length ? '\n' : ''}`;
 }
 
 /** The signed statements for a period (YYYY-MM, default last month): one per referrer this studio owes. */
-export async function statementsOut(env, cat, origin, period) {
+export async function statementsOut(env, cat, origin, period, cursor = '') {
   const shop = shopOf(cat);
   const p = /^\d{4}-\d{2}$/.test(String(period ?? '')) ? period : lastMonth();
-  const books = await booksOf(env, { period: p });
-  const out = [];
-  for (const b of books) out.push(await statementFor(env, origin, b, p, shop?.referrals));
-  return { ok: true, period: p, statements: out };
+  return { ok: true, period: p, ...(await statementPage(env, origin, shop?.referrals, p, cursor, { snapshot: false })) };
 }
-export async function statementsSend(env, cat, origin, period) {
+export async function statementsSend(env, cat, origin, period, cursor = '') {
   const shop = shopOf(cat);
-  const p = /^\d{4}-\d{2}$/.test(String(period ?? '')) ? period : lastMonth();
-  return { ok: true, period: p, sent: await sendStatements(env, origin, shop, p) };
+  const p = /^\d{4}-\d{2}$/.test(String(period ?? '')) ? period : (await pendingStatementPeriod(env, origin)) ?? lastMonth();
+  const { sent, nextCursor, retryAfter, failures } = await sendStatements(env, origin, shop, p, { cursor });
+  return { ok: true, period: p, nextCursor, sent, retryAfter, failures };
 }
-export const settleReferrer = (env, a) => settle(env, a.via, a.ref);
+export const settleReferrer = (env, a) => settle(env, a.via, a.ref, { currency: a.currency });
 
 function lastMonth(now = new Date()) {
   const d = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
@@ -688,22 +820,22 @@ function lastMonth(now = new Date()) {
 
 /* ------------------------------------------------------------------ for the rest of the Worker */
 
-/** The play shell's boot facts: is there a shop to show in this game (never on a kids server or a kids studio). */
+/** The play shell's boot facts: is there a shop to show under this studio's policy. */
 export function shellShop(cat, game, { kids = false } = {}) {
   const shop = shopOf(cat);
-  if (!shop || shop.audience === 'kids' || kids || shop.till === 'off') return null;
+  if (!shop || shop.audience === 'kids' || (kids && !shop.policy.kidsServer) || shop.till === 'off') return null;
   const items = itemsFor(shop, game);
-  return items.length ? { items: items.length, currency: shop.currency } : null;
+  return items.length ? { items: items.length, currency: shop.currency, policy: shop.policy } : null;
 }
 
-/** The badge (a supporter's) a signed-in player shows in rooms; none on a kids server. Verified here, never by a hello. */
+/** The badge (a supporter's) a signed-in player shows in rooms; kids visibility follows studio policy. Verified here, never by a hello. */
 export async function roomBadge(env, cat, player, { kids = false } = {}) {
   const shop = shopOf(cat);
-  if (!shop || kids || !/^pl_[A-Za-z0-9_-]{22}$/.test(String(player ?? ''))) return null;
+  if (!shop || (kids && !shop.policy.kidsServer) || !/^pl_[A-Za-z0-9_-]{22}$/.test(String(player ?? ''))) return null;
   try {
     const owns = await ownsOf(env, player);
     const b = owns.find((o) => o.key.startsWith('badge:'));
     if (!b) return null;
-    return shop.items.find((i) => i.id === b.item)?.badge ?? b.key.slice(6, 22);
+    return shop.items.find((i) => i.id === b.item)?.badge ?? b.key.slice(6);
   } catch { return null; }
 }