@homie-rocks/studio 0.32.0 → 0.33.0

package/worker/players.mjs

@@ -30,7 +30,7 @@ import { cookieValue } from './stats.mjs';
 import { adoptStatements, bumpPlayerStats, dropPlayerData, fall, fallenList, getSave, listSaves, playerData, readPlayerStats, SAVE_LIMITS, savesSummary, wipeSaves, writeSaves } from './saves.mjs';
 import { bytesToB64url, randomToken, sha256Hex, verifyAssertion, verifyRegistration } from './webauthn.mjs';
 import { ACCOUNT_JS, accountPage } from './account-page.mjs';
-import { forgetPlayerShop, livePurchases, shopDataOf } from './shop-store.mjs';
+import { adoptShopStatements, migrated as shopMigrated, forgetPlayerShop, livePurchases, shopDataOf } from './shop-store.mjs';
 import { forgetPlayerHistory, playerHistory } from './lounge-store.mjs';
 
 export const PLAYERS_MIGRATION_FILE = '0004_players.sql';
@@ -234,9 +234,9 @@ async function sessionOf(request, env, url = new URL(request.url)) {
 }
 
 /** A guest for a request with no player yet (the first save). Refused past the address's or the day's limit. */
-async function newGuest(request, env, url) {
+async function newGuest(request, env, url, addressLimit = PLAYER_LIMITS.newPlayersPerHour, counter = 'new') {
   const ip = addressOf(request);
-  if (limited(`new:${ip}`, PLAYER_LIMITS.newPlayersPerHour, HOUR)) return { error: fail(429, 'rate', 'too many new players from this address; try again later') };
+  if (limited(`${counter}:${ip}`, addressLimit, HOUR)) return { error: fail(429, 'rate', 'too many new players from this address; try again later') };
   const capped = await dailyCapReached(env);
   if (capped) return { error: fail(503, 'busy', 'this studio has taken all the new players it takes in one day; try again tomorrow') };
   const id = newPlayerId();
@@ -258,8 +258,10 @@ async function dailyCapReached(env) {
 }
 
 /** Guests nobody has used for guestIdleDays are forgotten (a few at a time), with everything they kept. */
-async function pruneGuests(env) {
-  const old = (await env.DB.prepare('SELECT id FROM players WHERE guest = 1 AND seen_at < ?1 LIMIT 25').bind(Date.now() - PLAYER_LIMITS.guestIdleDays * DAY).all()).results ?? [];
+export async function pruneGuests(env) {
+  const now = Date.now();
+  const ownership = await shopMigrated(env, { complete: false }) ? "AND NOT EXISTS (SELECT 1 FROM entitlements e WHERE e.player = players.id AND e.state = 'active' AND (e.ends_at IS NULL OR e.ends_at > ?2))" : 'AND ?2 > 0';
+  const old = (await env.DB.prepare(`SELECT id FROM players WHERE guest = 1 AND seen_at < ?1 ${ownership} LIMIT 25`).bind(now - PLAYER_LIMITS.guestIdleDays * DAY, now).all()).results ?? [];
   for (const { id } of old) await removePlayer(env, id);
   await env.DB.prepare('DELETE FROM player_challenges WHERE expires_at < ?1').bind(Date.now()).run();
   await env.DB.prepare('DELETE FROM player_sessions WHERE expires_at < ?1').bind(Date.now()).run();
@@ -383,6 +385,8 @@ export const players = Object.freeze({
   async of(request, env) {
     try { const s = await sessionOf(request, env); return s ? { id: s.player.id, name: s.player.name, guest: s.player.guest, owner: s.player.owner } : null; } catch { return null; }
   },
+  /** Shop guest creation uses the studio's new-guest address rate and the daily player limit. */
+  async shopGuest(request, env, url, addressLimit) { return newGuest(request, env, url, addressLimit, 'shop-new'); },
   /** True when the request carries the session of an account its owner marked (`homie-studio players owner`). */
   async isOwner(request, env) { return Boolean((await players.of(request, env))?.owner); },
   /** A short-lived pass naming a player (for a room to recognise them): 'pp_…'. */
@@ -689,7 +693,7 @@ async function apiRoute(request, env, ctx, url, parts, { catalogueOf, read, f })
       // A guest signing in to their account: what only the guest had moves over, then the guest is gone.
       if (current.player.guest) {
         adopted = await adoptStatements(env, current.player.id, key.player);
-        writes.push(...adopted.statements,
+        writes.push(...adopted.statements, ...(await adoptShopStatements(env, current.player.id, key.player)),
           env.DB.prepare('DELETE FROM player_sessions WHERE player = ?1').bind(current.player.id),
           env.DB.prepare('DELETE FROM player_challenges WHERE player = ?1').bind(current.player.id),
           env.DB.prepare('DELETE FROM players WHERE id = ?1 AND guest = 1').bind(current.player.id));

package/worker/referrals.mjs

@@ -20,7 +20,7 @@ import { isVisit } from './stats.mjs';
 
 const DAY = 86_400_000;
 export const VIA_COOKIE = 'studio_via';
-const HOST = /^(?=.{3,80}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
+const HOST = /^(?=.{3,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
 export const STATEMENT_KIND = 'homie-referral-statement';
 
 const b64url = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
@@ -120,13 +120,14 @@ export async function arrivalCookie(request, env, url, shop) {
   if (/(?:^|;\s*)(?:studio_player|studio_via)=/.test(cookies)) return null;
   const at = Math.floor(Date.now() / 1000);
   const value = `${via}.${at}.${await macOf(env, `${via}.${at}`)}`;
-  return `${VIA_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${shop.referrals.windowDays * 86400}${url.protocol === 'https:' ? '; Secure' : ''}`;
+  // Persistent integer lifetime; browsers may apply their own cookie retention policy.
+  return `${VIA_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${Math.min(2147483647, Math.max(1, Math.round((shop.referrals.windowDays ?? 24855) * 86400)))}${url.protocol === 'https:' ? '; Secure' : ''}`;
 }
 
 /** The arrival this request's browser carries ({ via, at }), checked, or null. */
 export async function arrivalOf(request, env) {
   const raw = /(?:^|;\s*)studio_via=([^;]+)/.exec(request.headers.get('cookie') ?? '')?.[1];
-  const m = /^([a-z0-9.-]{3,80})\.(\d{9,11})\.([A-Za-z0-9_-]{22})$/.exec(raw ?? '');
+  const m = /^([a-z0-9.-]{3,253})\.(\d{9,11})\.([A-Za-z0-9_-]{22})$/.exec(raw ?? '');
   if (!m || !hostOf(m[1])) return null;
   try { if (m[3] !== await macOf(env, `${m[1]}.${m[2]}`)) return null; } catch { return null; }
   return { via: m[1], at: Number(m[2]) * 1000 };
@@ -183,14 +184,14 @@ export async function manifestReferrals(env, origin, shop, studio) {
 export async function lineFor(env, order, shop, { touchAt = null, now = Date.now() } = {}) {
   const terms = shop?.referrals;
   if (!terms || !order.via || !(terms.rate > 0)) return [];
-  if (touchAt !== null && now - touchAt > terms.windowDays * DAY) return [];
-  let so = 0;
-  try { so = Number((await env.DB.prepare("SELECT COALESCE(SUM(l.share), 0) AS n FROM referral_lines l JOIN shop_orders o ON o.id = l.order_id WHERE o.player = ?1 AND l.via = ?2 AND l.state != 'void'").bind(order.player, order.via).first())?.n) || 0; } catch { so = 0; }
-  const share = Math.max(0, Math.min(Math.round(Number(order.amount) * terms.rate), terms.capPerPlayer - so));
+  if (touchAt !== null && terms.windowDays !== null && now - touchAt > Math.round(terms.windowDays * DAY)) return [];
+  const share = Math.round(Number(order.amount) * terms.rate);
+  if (!Number.isSafeInteger(share)) throw new RangeError('Referral share exceeds safe integer arithmetic; lower the studio rate or amount.');
   if (share <= 0) return [];
   const period = new Date(now).toISOString().slice(0, 7);
-  return [env.DB.prepare("INSERT INTO referral_lines (order_id, via, net, rate, share, currency, state, period, hold_until, settled_ref, created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'pending', ?7, ?8, NULL, ?9) ON CONFLICT(order_id) DO NOTHING")
-    .bind(order.id, order.via, Number(order.amount), terms.rate, share, order.currency, period, now + terms.holdDays * DAY, now)];
+  // Compute remaining room in the INSERT itself: simultaneous paid orders share one exact cap.
+  return [env.DB.prepare("INSERT INTO referral_lines (order_id, via, net, rate, share, currency, state, period, hold_until, settled_ref, created_at) SELECT ?1, ?2, ?3, ?4, CASE WHEN ?10 IS NULL THEN ?5 ELSE MAX(0, MIN(?5, ?10 - used)) END, ?6, 'pending', ?7, ?8, NULL, ?9 FROM (SELECT COALESCE(SUM(l.share), 0) AS used FROM referral_lines l JOIN shop_orders o ON o.id = l.order_id WHERE ?10 IS NOT NULL AND o.player = ?11 AND l.via = ?2 AND l.state != 'void') WHERE ?10 IS NULL OR used < ?10 ON CONFLICT(order_id) DO NOTHING")
+    .bind(order.id, order.via, Number(order.amount), terms.rate, share, order.currency, period, now + Math.round((terms.holdDays ?? 0) * DAY), now, terms.capPerPlayer, order.player)];
 }
 
 /** A refund or a lost dispute: a held line is void; a settled one becomes a clawback that nets off the next statement. */
@@ -208,26 +209,82 @@ async function orderHash(seller, orderId) {
 }
 
 /**
- * The seller's books per referrer: { via, currency, pending, owed, clawback, lines } (lines not yet settled, and
- * clawbacks), newest first. `period` (YYYY-MM) limits lines to sales up to the end of that month.
+ * The seller's books page by referrer and currency; totals and counts include every open line.
+ * `period` (YYYY-MM) limits lines to sales up to the end of that month. Lines have their own cursor.
  */
-export async function booksOf(env, { period = null, now = Date.now() } = {}) {
-  let rows = [];
-  try {
-    rows = (await env.DB.prepare("SELECT l.*, o.item, o.paid_at FROM referral_lines l JOIN shop_orders o ON o.id = l.order_id WHERE l.state IN ('pending', 'owed', 'clawback', 'void') ORDER BY l.created_at DESC LIMIT 2000").all()).results ?? [];
-  } catch { return []; }
-  const by = new Map();
-  for (const r of rows) {
-    if (period && r.period > period) continue;
-    const b = by.get(r.via) ?? { via: r.via, currency: r.currency, pending: 0, owed: 0, clawback: 0, lines: [] };
-    const state = lineState(r, now);
-    if (state === 'pending') b.pending += Number(r.share);
-    if (state === 'owed') b.owed += Number(r.share);
-    if (state === 'clawback') b.clawback += Number(r.share);
-    b.lines.push({ order: r.order_id, item: r.item, net: Number(r.net), rate: Number(r.rate), share: Number(r.share), state, period: r.period, date: new Date(Number(r.paid_at ?? r.created_at)).toISOString().slice(0, 10), holdUntil: Number(r.hold_until) });
-    by.set(r.via, b);
+const readCursor = (cursor) => { try { const value = JSON.parse(cursor); return Array.isArray(value) && value.every((part) => typeof part === 'string' || (typeof part === 'number' && Number.isFinite(part))) ? value : []; } catch { return []; } };
+const openLines = "state IN ('pending', 'owed', 'clawback', 'void')";
+
+export async function booksOf(env, { period = null, now = Date.now(), cursor = '', pageSize = 100, edition = null } = {}) {
+  const parts = readCursor(cursor);
+  const [via = '', currency = ''] = parts.length === 2 && parts.every((x) => typeof x === 'string') ? parts : [];
+  // The index starts at the next referrer; each referrer's rows are aggregated once in a full traversal.
+  const rows = (await env.DB.prepare(`SELECT via, currency, COUNT(*) AS lineCount,
+    SUM(CASE WHEN state = 'pending' AND hold_until > ?2 THEN share ELSE 0 END) AS pending,
+    SUM(CASE WHEN state = 'owed' OR (state = 'pending' AND hold_until <= ?2) THEN share ELSE 0 END) AS owed,
+    SUM(CASE WHEN state = 'clawback' THEN share ELSE 0 END) AS clawback
+    FROM ${edition ? 'referral_edition_lines' : 'referral_lines'} WHERE ${edition ? 'edition = ?6 AND' : ''} (via, currency) > (?3, ?4) AND ${openLines} AND (?1 IS NULL OR period <= ?1)
+    GROUP BY via, currency ORDER BY via, currency LIMIT ?5`).bind(...[period, now, via, currency, pageSize + 1, ...(edition ? [edition] : [])]).all()).results ?? [];
+  const more = rows.length > pageSize;
+  if (more) rows.pop();
+  const books = rows.map((r) => ({ ...r, due: r.owed - r.clawback }));
+  return { books, nextCursor: more ? JSON.stringify([rows.at(-1).via, rows.at(-1).currency]) : null };
+}
+
+/** Lines inside one book, without repeating its totals. The covering prefix makes a full read linear. */
+export async function linesOf(env, { via, currency, period = null, now = Date.now(), cursor = '', pageSize = 100, edition = null }) {
+  const rows = (await env.DB.prepare(`SELECT l.*${edition ? '' : ', o.item, o.paid_at'} FROM ${edition ? 'referral_edition_lines l' : 'referral_lines l LEFT JOIN shop_orders o ON o.id = l.order_id'}
+    WHERE ${edition ? 'l.edition = ?6 AND' : ''} l.via = ?1 AND l.currency = ?2 AND l.order_id > ?3 AND l.${openLines} AND (?4 IS NULL OR l.period <= ?4)
+    ORDER BY l.order_id LIMIT ?5`).bind(...[via, currency, cursor, period, pageSize + 1, ...(edition ? [edition] : [])]).all()).results ?? [];
+  const more = rows.length > pageSize;
+  if (more) rows.pop();
+  return { lines: rows.map((r) => ({ order: r.order_id, item: r.item ?? '', net: Number(r.net), rate: Number(r.rate), share: Number(r.share), state: lineState(r, now), period: r.period, date: new Date(Number(r.paid_at ?? r.created_at)).toISOString().slice(0, 10), holdUntil: Number(r.hold_until) })), nextCursor: more ? rows.at(-1).order_id : null };
+}
+
+/** One statement per referrer, continued by line pages; totals occur only on its first page. */
+export async function statementPage(env, origin, terms, period, cursor = '', { snapshot = true } = {}) {
+  let edition, after = '', via, currency, lineCursor = '';
+  if (cursor) {
+    const parts = readCursor(cursor);
+    if (parts.length !== 5 || !parts.every((x) => typeof x === 'string')) return { statements: [], nextCursor: null, error: 'cursor' };
+    [edition, after, via, currency, lineCursor] = parts;
+    if ((snapshot ? !/^[a-f0-9-]{36}$/.test(edition) : !/^\d{13}$/.test(edition)) || (via && hostOf(via) !== via) || (currency && !/^[a-z]{3}$/.test(currency)) || lineCursor.length > 256) return { statements: [], nextCursor: null, error: 'cursor' };
+  } else if (snapshot) {
+    edition = crypto.randomUUID();
+    await env.DB.batch([
+      env.DB.prepare('INSERT INTO referral_editions (id, period, issued) VALUES (?1, ?2, ?3)').bind(edition, period, Date.now()),
+      env.DB.prepare(`INSERT INTO referral_edition_lines SELECT ?1, l.order_id, l.via, l.currency, l.net, l.rate, l.share, l.state, l.period, l.hold_until, l.created_at, o.item, o.paid_at FROM referral_lines l LEFT JOIN shop_orders o ON o.id = l.order_id WHERE l.${openLines} AND l.period <= ?2`).bind(edition, period),
+    ]);
   }
-  return [...by.values()].map((b) => ({ ...b, due: b.owed - b.clawback }));
+  if (!snapshot && !edition) edition = String(Date.now());
+  const sourceEdition = snapshot ? edition : null;
+  const saved = snapshot ? await env.DB.prepare('SELECT issued FROM referral_editions WHERE id = ?1 AND period = ?2').bind(edition, period).first() : { issued: Number(edition) };
+  if (!saved || !Number.isSafeInteger(saved.issued)) return { statements: [], nextCursor: null, error: 'cursor' };
+  const issued = saved.issued;
+  let book;
+  if (!via) {
+    const page = await booksOf(env, { period, cursor: after, pageSize: 1, now: issued, edition: sourceEdition });
+    book = page.books[0];
+    if (!book) {
+      if (snapshot) await env.DB.batch([
+        env.DB.prepare('DELETE FROM referral_edition_lines WHERE edition = ?1').bind(edition),
+        env.DB.prepare('DELETE FROM referral_editions WHERE id = ?1').bind(edition),
+      ]);
+      return { statements: [], nextCursor: null };
+    }
+    via = book.via; currency = book.currency;
+  } else {
+    // A continuation must name a real line in this immutable edition, never a caller-selected host.
+    if (!lineCursor || !(snapshot ? await env.DB.prepare('SELECT 1 FROM referral_edition_lines WHERE edition = ?1 AND via = ?2 AND currency = ?3 AND order_id = ?4').bind(edition, via, currency, lineCursor).first() : await env.DB.prepare('SELECT 1 FROM referral_lines WHERE via = ?1 AND currency = ?2 AND order_id = ?3').bind(via, currency, lineCursor).first())) return { statements: [], nextCursor: null, error: 'cursor' };
+    book = { via, currency };
+  }
+  const page = await linesOf(env, { via, currency, period, cursor: lineCursor, now: issued, edition: sourceEdition });
+  book.lines = page.lines;
+  book.page = { cursor: lineCursor, nextCursor: page.nextCursor, issued };
+  const envelope = await statementFor(env, origin, book, period, terms);
+  // A following empty summary page terminates the walk, avoiding a second aggregate of this book.
+  const nextCursor = page.nextCursor ? JSON.stringify([edition, after, via, currency, page.nextCursor]) : JSON.stringify([edition, JSON.stringify([via, currency]), '', '', '']);
+  return { statements: [envelope], nextCursor };
 }
 
 /** One referrer's signed statement for a period (no player, name or email in it: order hashes only). */
@@ -238,28 +295,36 @@ export async function statementFor(env, origin, book, period, terms) {
   const statement = {
     seller, referrer: book.via, period, currency: book.currency, issued: new Date().toISOString(),
     terms: terms ? { rate: terms.rate, holdDays: terms.holdDays, minimumInvoice: terms.minimumInvoice, basis: 'pre-tax' } : null,
-    totals: { pending: book.pending, owed: book.owed, clawback: book.clawback, due: book.due },
+    ...(book.due !== undefined ? { totals: { pending: book.pending, owed: book.owed, clawback: book.clawback, due: book.due }, lineCount: book.lineCount } : {}),
     lines,
+    page: book.page ?? { cursor: '', nextCursor: null },
     note: 'Invoice the seller for "due" from your own Stripe (or the way its terms accept). Nothing moves through Homie.',
   };
   return signStatement(env, statement);
 }
 
 /** The owner marks what was paid (an invoice paid by card, a PayPal transfer): those owed lines are settled. */
-export async function settle(env, via, ref, { now = Date.now() } = {}) {
+export async function settle(env, via, ref, { now = Date.now(), currency } = {}) {
   const h = hostOf(via);
+  if (!/^[a-z]{3}$/.test(currency ?? '')) return { ok: false, error: 'currency', message: 'Name the currency to mark paid.' };
   if (!h) return { ok: false, error: 'bad-request', message: 'via is the referrer\'s host' };
   const note = String(ref ?? '').replace(/[^\w .:#/-]/g, '').slice(0, 80) || 'paid';
   await env.DB.batch([
-    env.DB.prepare("UPDATE referral_lines SET state = 'settled', settled_ref = ?2 WHERE via = ?1 AND state = 'pending' AND hold_until <= ?3").bind(h, note, now),
-    env.DB.prepare("UPDATE referral_lines SET state = 'settled-clawback', settled_ref = ?2 WHERE via = ?1 AND state = 'clawback'").bind(h, note),
+    env.DB.prepare("UPDATE referral_lines SET state = 'settled', settled_ref = ?2 WHERE via = ?1 AND currency = ?4 AND (state = 'owed' OR (state = 'pending' AND hold_until <= ?3))").bind(h, note, now, currency),
+    env.DB.prepare("UPDATE referral_lines SET state = 'settled-clawback', settled_ref = ?2 WHERE via = ?1 AND currency = ?3 AND state = 'clawback'").bind(h, note, currency),
   ]);
   return { ok: true, via: h, ref: note };
 }
 
 /* ------------------------------------------------------------------ as a referrer */
 
-const received = [];
+const received = new Map();
+const positiveSetting = (value, fallback) => {
+  if (value === undefined || value === null) return fallback;
+  if (!['string', 'number'].includes(typeof value) || !/^[1-9][0-9]*$/.test(String(value)) || !Number.isSafeInteger(Number(value))) throw new Error('use a positive whole decimal number');
+  return Number(value);
+};
+export function resetReferralLimits() { received.clear(); }
 /**
  * POST /api/referrals/statement: a seller's signed statement to this studio. It must name this site as the referrer,
  * and its signature must check against the key in the SELLER's own manifest (fetched now, over https). Kept per
@@ -270,12 +335,23 @@ export async function receiveStatement(request, env, url, { fetcher = fetch } =
   if (request.method !== 'POST') return json({ ok: false, error: 'method' }, 405);
   // A statement makes this Worker read the seller's manifest: a few a minute is all a real seller sends.
   const now = Date.now();
-  while (received.length && received[0] < now - 60_000) received.shift();
-  if (received.length >= 30) return json({ ok: false, error: 'rate', message: 'too many statements; try again in a minute' }, 429);
-  received.push(now);
-  if (Number(request.headers.get('content-length') ?? 0) > 65_536) return json({ ok: false, error: 'too-large' }, 413);
+  const address = request.headers.get('cf-connecting-ip') || 'local';
+  const attempts = (received.get(address) ?? []).filter((at) => at > now - 60000);
+  let rate, globalRate, maxBytes;
+  try {
+    rate = positiveSetting(env.REFERRAL_STATEMENTS_PER_MINUTE, 30);
+    globalRate = positiveSetting(env.REFERRAL_STATEMENTS_GLOBAL_PER_MINUTE, 30);
+    maxBytes = positiveSetting(env.REFERRAL_STATEMENT_BYTES, 65536);
+  } catch { return json({ ok: false, error: 'settings', message: 'REFERRAL_STATEMENTS_PER_MINUTE, REFERRAL_STATEMENTS_GLOBAL_PER_MINUTE and REFERRAL_STATEMENT_BYTES must be positive whole decimal numbers.' }, 503); }
+  const global = (received.get('*') ?? []).filter((at) => at > now - 60000);
+  if (global.length >= globalRate) return json({ ok: false, error: 'rate', message: 'The studio referral rate limit was reached; try again in a minute.' }, 429);
+  global.push(now); received.set('*', global);
+  if (attempts.length >= rate) return json({ ok: false, error: 'rate', message: 'The studio referral address rate limit was reached; try again in a minute.' }, 429);
+  attempts.push(now); received.set(address, attempts);
+  if (received.size > 10000) received.delete([...received.keys()].find((key) => key !== '*'));
+  if (Number(request.headers.get('content-length') ?? 0) > maxBytes) return json({ ok: false, error: 'too-large', message: 'The studio can raise REFERRAL_STATEMENT_BYTES for larger signed statements.' }, 413);
   const text = await request.text();
-  if (text.length > 65_536) return json({ ok: false, error: 'too-large' }, 413);
+  if (new TextEncoder().encode(text).length > maxBytes) return json({ ok: false, error: 'too-large', message: 'The studio can raise REFERRAL_STATEMENT_BYTES for larger signed statements.' }, 413);
   let env0 = null;
   try { env0 = JSON.parse(text); } catch { return json({ ok: false, error: 'json' }, 400); }
   const s = env0?.statement;
@@ -283,7 +359,9 @@ export async function receiveStatement(request, env, url, { fetcher = fetch } =
   if (hostOf(s.referrer) !== hostOf(url.hostname)) return json({ ok: false, error: 'not-ours', message: 'this statement names another referrer' }, 400);
   let seller = null;
   try { const u = new URL(String(s.seller)); seller = u.protocol === 'https:' && hostOf(u.hostname) ? u.origin : null; } catch { seller = null; }
+  if (!/^[a-z]{3}$/.test(s.currency ?? '')) return json({ ok: false, error: 'currency' }, 400);
   if (!seller || !/^\d{4}-\d{2}$/.test(String(s.period ?? ''))) return json({ ok: false, error: 'bad-statement' }, 400);
+  if (typeof (s.page?.cursor ?? '') !== 'string' || String(s.page?.cursor ?? '').length > 256 || (s.page?.nextCursor != null && (typeof s.page.nextCursor !== 'string' || s.page.nextCursor.length > 256))) return json({ ok: false, error: 'cursor' }, 400);
   let x = null;
   try {
     const res = await fetcher(`${seller}/.well-known/homie-studio.json`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(5000) });
@@ -292,12 +370,32 @@ export async function receiveStatement(request, env, url, { fetcher = fetch } =
   if (!x || x !== env0.key || !(await verifyStatement(env0, x))) return json({ ok: false, error: 'signature', message: 'the signature does not match the key in the seller\'s own manifest' }, 401);
   const t = s.totals ?? {};
   try {
-    await env.DB.prepare('INSERT INTO referral_statements (seller, period, owed, pending, currency, body, received_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) ON CONFLICT(seller, period) DO UPDATE SET owed = excluded.owed, pending = excluded.pending, currency = excluded.currency, body = excluded.body, received_at = excluded.received_at')
-      .bind(seller, s.period, Math.max(0, Math.floor(Number(t.due ?? t.owed) || 0)), Math.max(0, Math.floor(Number(t.pending) || 0)), String(s.currency ?? 'usd').slice(0, 3), text.slice(0, 65_536), Date.now()).run();
-  } catch { return json({ ok: false, error: 'not-migrated', message: 'this studio has no referral tables yet (migration 0008)' }, 503); }
+    const prefix = `referral-page:${seller}|${s.period}|${s.currency}|`;
+    const cursor = s.page?.cursor ?? '';
+    const prior = await env.DB.prepare('SELECT body FROM referral_statements WHERE seller = ?1 AND period = ?2 AND currency = ?3').bind(seller, s.period, s.currency).first();
+    const previous = prior ? JSON.parse(prior.body).statement : null;
+    const storedPage = await metaGet(env, prefix + cursor);
+    if (storedPage && JSON.parse(storedPage).sig === env0.sig) return json({ ok: true, duplicate: true });
+    if (cursor && (!previous || previous.page?.nextCursor !== cursor || previous.page?.issued !== s.page?.issued)) return json({ ok: false, error: 'page-order' }, 409);
+    const writes = [];
+    // A fresh first page replaces the previous edition, including all its old continuations.
+    if (!cursor) writes.push(env.DB.prepare('DELETE FROM meta WHERE key >= ?1 AND key < ?2').bind(prefix, prefix + '\uffff'));
+    writes.push(env.DB.prepare('INSERT INTO meta (key, value) VALUES (?1, ?2) ON CONFLICT(key) DO UPDATE SET value = excluded.value').bind(prefix + cursor, text));
+    if (!cursor) writes.push(env.DB.prepare('INSERT INTO referral_statements (seller, period, owed, pending, currency, body, received_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) ON CONFLICT(seller, period, currency) DO UPDATE SET owed = excluded.owed, pending = excluded.pending, currency = excluded.currency, body = excluded.body, received_at = excluded.received_at')
+      .bind(seller, s.period, Number(t.due ?? t.owed) || 0, Number(t.pending) || 0, String(s.currency ?? 'usd'), text, Date.now()));
+    else writes.push(env.DB.prepare('UPDATE referral_statements SET body = ?3, received_at = ?4 WHERE seller = ?1 AND period = ?2 AND currency = ?5').bind(seller, s.period, text, Date.now(), s.currency));
+    await env.DB.batch(writes);
+  } catch { return json({ ok: false, error: 'not-migrated', message: 'this studio needs referral migrations 0008_studio_shop.sql and 0011_shop_statements.sql' }, 503); }
   return json({ ok: true, seller, period: s.period });
 }
 
+/** Stored signed pages, one bounded document at a time, with a continuation cursor. */
+export async function receivedPages(env, seller, period, cursor = '') {
+  const prefix = `referral-page:${seller}|${period}|`;
+  const rows = (await env.DB.prepare('SELECT key, value FROM meta WHERE key >= ?1 AND key < ?2 AND key > ?3 ORDER BY key LIMIT 2').bind(prefix, prefix + '\uffff', cursor).all()).results ?? [];
+  return { ok: true, statements: rows.length ? [JSON.parse(rows[0].value)] : [], nextCursor: rows.length > 1 ? rows[0].key : null };
+}
+
 /** The statements other studios sent this one: what each says it owes. */
 export async function statementsIn(env) {
   try {
@@ -307,22 +405,59 @@ export async function statementsIn(env) {
 }
 
 /** Send each referrer its statement for `period` (to the address in its own manifest). */
-export async function sendStatements(env, origin, shop, period, { fetcher = fetch } = {}) {
-  const books = await booksOf(env, { period });
-  const sent = [];
-  for (const book of books) {
-    const env0 = await statementFor(env, origin, book, period, shop?.referrals);
-    let to = null;
-    try {
-      const m = await (await fetcher(`https://${book.via}/.well-known/homie-studio.json`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(5000) })).json();
-      const st = String(m?.referrals?.statements ?? '');
-      to = st.startsWith(`https://${book.via}/`) ? st : null;
-    } catch { to = null; }
-    if (!to) { sent.push({ via: book.via, ok: false, why: 'no statement address in its manifest' }); continue; }
-    try {
-      const res = await fetcher(to, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(env0), signal: AbortSignal.timeout(8000) });
-      sent.push({ via: book.via, ok: res.ok, status: res.status, due: book.due });
-    } catch (error) { sent.push({ via: book.via, ok: false, why: String(error?.message ?? error).slice(0, 80) }); }
+export async function sendStatements(env, origin, shop, period, { fetcher = fetch, cursor = '' } = {}) {
+  // The server owns progress. A caller cursor can neither skip a page nor select a destination.
+  const key = `referral-send:${origin}|${period}`;
+  await metaPutOnce(env, key, JSON.stringify({ cursor: '', attempts: 0 }));
+  const raw = await metaGet(env, key);
+  let state = JSON.parse(raw);
+  if (state.done) state = { cursor: '', attempts: 0 };
+  if (state.nextAt > Date.now()) return { sent: [], nextCursor: 'resume', retryAfter: (state.nextAt - Date.now()) / 1000 };
+  const locked = JSON.stringify({ ...state, nextAt: Date.now() + 30000 });
+  const claim = await env.DB.prepare('UPDATE meta SET value = ?3 WHERE key = ?1 AND value = ?2').bind(key, raw, locked).run();
+  if (!claim.meta?.changes) return { sent: [], nextCursor: 'resume', retryAfter: 2.1 };
+  const save = async (value) => env.DB.prepare('UPDATE meta SET value = ?2 WHERE key = ?1').bind(key, JSON.stringify(value)).run();
+  const page = state.page ?? await statementPage(env, origin, shop?.referrals, period, state.cursor);
+  const envelope = page.statements[0];
+  if (!envelope) { await save({ done: true, failures: state.failures ?? [] }); return { sent: [], nextCursor: null, failures: state.failures ?? [] }; }
+  // Save the exact signed page BEFORE delivery: timeouts and process termination replay identical bytes.
+  state.page = page;
+  await save({ ...state, nextAt: Date.now() + 30000 });
+  const via = envelope.statement.referrer;
+  let result;
+  try {
+    const manifestResponse = await fetcher(`https://${via}/.well-known/homie-studio.json`, { redirect: 'manual', signal: AbortSignal.timeout(5000) });
+    if (!manifestResponse.ok) throw new Error(`Manifest answered ${manifestResponse.status}`);
+    const manifest = await manifestResponse.json();
+    const to = new URL(String(manifest?.referrals?.statements ?? ''));
+    if (to.protocol !== 'https:' || to.host !== via || to.username || to.password) throw new Error('no statement address in its manifest');
+    const res = await fetcher(to.href, { method: 'POST', redirect: 'manual', headers: { 'content-type': 'application/json' }, body: JSON.stringify(envelope), signal: AbortSignal.timeout(8000) });
+    result = { via, ok: res.ok, status: res.status };
+  } catch (error) { result = { via, ok: false, why: String(error?.message ?? error).slice(0, 80) }; }
+  if (!result.ok && state.attempts < 3) {
+    const retryAfter = result.status === 429 ? 60 : 2 ** (state.attempts + 1);
+    await save({ ...state, attempts: state.attempts + 1, nextAt: Date.now() + retryAfter * 1000 });
+    return { sent: [], nextCursor: 'resume', retryAfter };
+  }
+  let next = page.nextCursor;
+  if (!result.ok) {
+    // Skip this referrer's remaining pages after a persistent failure; the next referrer still runs.
+    const [edition] = readCursor(next);
+    next = JSON.stringify([edition, JSON.stringify([via, envelope.statement.currency]), '', '', '']);
   }
-  return sent;
+  const retryAfter = 2.1;
+  await save({ cursor: next, attempts: 0, failures: [...(state.failures ?? []), ...(!result.ok ? [result] : [])], nextAt: Date.now() + retryAfter * 1000, done: next === null });
+  return { sent: [result], nextCursor: next === null ? null : 'resume', retryAfter };
+}
+
+export async function statementFailures(env) {
+  const rows = (await env.DB.prepare("SELECT value FROM meta WHERE key >= 'referral-send:' AND key < 'referral-send;' ORDER BY key LIMIT 100").all()).results ?? [];
+  return rows.flatMap((r) => JSON.parse(r.value).failures ?? []);
+}
+
+/** A default Send resumes an unfinished period even if the calendar month changed while closed. */
+export async function pendingStatementPeriod(env, origin) {
+  const prefix = `referral-send:${origin}|`;
+  const row = await env.DB.prepare("SELECT key FROM meta WHERE key >= ?1 AND key < ?2 AND COALESCE(json_extract(value, '$.done'), 0) = 0 ORDER BY key LIMIT 1").bind(prefix, prefix + '\uffff').first();
+  return row ? row.key.slice(prefix.length) : null;
 }

package/worker/room-store.mjs

@@ -0,0 +1,54 @@
+/**
+ * A whole server-hosted room in SQLite. A small room updates one row; a large one uses pieces in the same synchronous
+ * transaction. No index besides the integer primary key: the default is one row written per second, not two.
+ * The boot row outlives a save being replayed, so two restores of that save can never reuse an epoch.
+ */
+export function roomStore(storage) {
+  const sql = storage.sql;
+  sql.exec('CREATE TABLE IF NOT EXISTS save (id INTEGER PRIMARY KEY, data BLOB NOT NULL)');
+  sql.exec('CREATE TABLE IF NOT EXISTS boots (id INTEGER PRIMARY KEY, data TEXT NOT NULL)');
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const pieceBytes = 1_000_000;
+  return {
+    read() {
+      if (this.boots()?.retired === true) return null;
+      const total = sql.exec('SELECT SUM(length(data)) AS bytes FROM save').toArray()[0]?.bytes ?? 0;
+      if (total > 16_000_000) throw new Error('save exceeds 16 MB');
+      const rows = sql.exec('SELECT id, data FROM save ORDER BY id').toArray();
+      if (!rows.length) return null;
+      if (rows.some((r, i) => r.id !== i) || rows.reduce((n, r) => n + r.data.byteLength, 0) > 16_000_000) throw new Error('save pieces missing or save exceeds 16 MB');
+      const pieces = rows.map((r) => new Uint8Array(r.data));
+      const bytes = new Uint8Array(pieces.reduce((n, p) => n + p.length, 0));
+      let at = 0;
+      for (const p of pieces) { bytes.set(p, at); at += p.length; }
+      const value = JSON.parse(decoder.decode(bytes));
+      if (typeof value.host === 'string') {
+        const hostText = value.host;
+        value.host = JSON.parse(hostText);
+        Object.defineProperty(value, 'hostText', { value: hostText });
+      }
+      return value;
+    },
+    write(value) {
+      const bytes = encoder.encode(JSON.stringify(value));
+      if (bytes.length > 16_000_000) throw new Error('save exceeds 16 MB');
+      storage.transactionSync(() => {
+        let id = 0;
+        for (let at = 0; at < bytes.length; at += pieceBytes) sql.exec('INSERT INTO save (id, data) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data', id++, bytes.slice(at, at + pieceBytes));
+        sql.exec('DELETE FROM save WHERE id >= ?', id);
+      });
+    },
+    boots() { return JSON.parse(sql.exec('SELECT data FROM boots WHERE id = 1').toArray()[0]?.data ?? 'null'); },
+    boot(value) { sql.exec('INSERT INTO boots (id, data) VALUES (1, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data', JSON.stringify(value)); },
+    retire() { this.boot({ retired: true }); },
+    clear() { storage.transactionSync(() => { sql.exec('DELETE FROM save'); sql.exec('DELETE FROM boots'); }); },
+  };
+}
+
+/** A repeatable delay spreads rooms that shared a failing isolate over thirty seconds. */
+export function restoreDelay(id) {
+  let h = 2166136261;
+  for (const c of id) h = Math.imul(h ^ c.charCodeAt(0), 16777619) >>> 0;
+  return h % 30_001;
+}