@assembly-js/app-foundation 0.0.47 → 0.0.48

package/CHANGELOG.md

@@ -5,18 +5,21 @@ lists what that version means for an app that already exists, one kind per bulle
 
 - `[fix]` — fixed on install; the app's code doesn't change.
 - `[behavior]` — the app behaves differently on install with no code change; its owner should know.
-- `[action: <id>]` — the app's own code must change; `<id>` names the `fixes.json` entry that
-  detects the gap and tells the update agent how to close it.
+- `[action]` — the app's own code must change. A release with an `[action]` bullet ships a
+  `bin/check-*.mjs` script that detects the gap and prints how to close it.
 - `[new]` — something the app can adopt; nothing changes until it does.
 - `[guidance]` — changes what the build agent is taught for future work, not existing code.
 
 A foundation update reads the sections between an app's version and the target: owner-facing copy
-from every bullet except `[guidance]`, agent work from the `fixes.json` entries those `[action]`
-bullets name. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
+from every bullet except `[guidance]`, agent work from the check scripts those `[action]`
+bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
+
+## 0.0.48
+- [guidance] Builds now warn when an app lacks the retry screen for platform outages, calls the child-row batch detached from the database, or imports a PDF library on the server that breaks after publishing, with the exact steps to fix each; nothing in an existing app changes until its code is updated.
 
 ## 0.0.47
 - [new] Apps can read the text of uploaded PDFs with a built-in parser that keeps working after publishing.
-- [action: server-pdf-text-extraction] PDF uploads that parsed in the preview but failed after publishing now parse correctly; apps that read PDFs with their own parser switch to the built-in one.
+- [action] PDF uploads that parsed in the preview but failed after publishing now parse correctly; apps that read PDFs with their own parser switch to the built-in one.
 - [guidance] Tell the build agent why PDF and similar libraries break after deploy (they look up worker scripts and native bindings by their own path), to use the built-in PDF text helper, and to preview PDFs in a new tab or on a canvas rather than in an iframe.
 
 ## 0.0.46
@@ -32,14 +35,14 @@ bullets name. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's o
 - [guidance] The build agent's SDK method tables are now generated from the SDK instead of hand-written.
 
 ## 0.0.42
-- [action: package-proxy] Sign-in and cross-site request protection now come from the package instead of code the app owns, and are checked by sending real requests through the app.
+- [action] Sign-in and cross-site request protection now come from the package instead of code the app owns, and are checked by sending real requests through the app.
 
 ## 0.0.41
 - [guidance] Tell the build agent where an owner updates an API key that has expired or been rejected (App secrets in the builder chat, then republish), instead of sending them to support.
 
 ## 0.0.40
 - [behavior] Confirm each viewer's session with the platform instead of trusting the token alone, cached briefly per server. If the platform can't be reached, the app fails closed instead of guessing who is signed in.
-- [action: identity-outage-states] Show a retry screen when the platform can't confirm the viewer instead of an error page, and stop a failing app from renewing its session over and over.
+- [action] Show a retry screen when the platform can't confirm the viewer instead of an error page, and stop a failing app from renewing its session over and over.
 
 ## 0.0.39
 - [fix] Let an app keep a scheduled job it already runs more often than every 30 minutes: the cron check now warns about that schedule instead of failing the build.
@@ -49,7 +52,7 @@ bullets name. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's o
 
 ## 0.0.37
 - [fix] Fix saves of records with nested rows (a proposal's packages, a retainer's allowances) failing with a 500 and leaving the parent without its children.
-- [action: inlined-child-rows-batch] Apps that copied the child-row helper into their own code carry the same bug and need the package's helper instead.
+- [action] Apps that copied the child-row helper into their own code carry the same bug and need the package's helper instead.
 
 ## 0.0.36
 - [fix] Accept notification category ids with underscores (`past_due`), so a build no longer fails on the id the user asked for.
@@ -114,13 +117,13 @@ bullets name. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's o
 
 ## 0.0.22
 - [new] Ship vNext content: origin bootstrap and a cookie-outcome log line.
-- [action: paint-beacon] The builder preview now tells a page that rendered from one that only loaded, which needs the paint beacon in the app.
+- [action] The builder preview now tells a page that rendered from one that only loaded, which needs the paint beacon in the app.
 
 ## 0.0.21
 - [new] Add Slack error-code and channel-list helpers, and a tripwire against an accidental `useServerAction` fetch loop, ahead of connector GA.
 
 ## 0.0.20
-- [action: next-config-wrapper] The live preview no longer hangs on networks that block its dev connection, which needs the app's Next config split into the platform wrapper and the app's own settings.
+- [action] The live preview no longer hangs on networks that block its dev connection, which needs the app's Next config split into the platform wrapper and the app's own settings.
 
 ## 0.0.19
 - [guidance] Align the connector action catalog's signatures with the vendored scripts' actual behavior.

package/bin/check-child-rows-batch.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Fails the build when app code calls drizzle's batch detached from `db`.
+// Dependency-free on purpose: it runs inside the generated app's sandbox
+// before any deps beyond Node exist.
+//
+// Apps that copied the child-row replace helper before foundation 0.0.37 call
+// `const batch = db.batch …; await batch([...])`. drizzle's batch reads
+// this.session, so detached it throws and every save that writes nested rows
+// 500s, leaving the parent without its children. The package's
+// replaceChildRows is the fix; the minimal alternative is `batch.call(db, …)`.
+//
+// An app with no such call (including every app that never copied the helper)
+// passes, so there is no generation marker to check.
+//
+// A hit is a warning on an ordinary turn and fails the build with --strict
+// (the update acceptance) or when ASSEMBLY_TURN_BASELINE_SHA says this turn
+// changed the offending file.
+import { readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, relative } from 'node:path';
+
+const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict');
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+
+const SOURCE_FILE = /\.(?:ts|tsx|mts|js|jsx|mjs)$/;
+const SKIPPED_DIRS = new Set(['node_modules', '.next', '.git', '.assembly']);
+// A bare `batch([` — not `db.batch([` or `foo_batch([`, which keep their receiver.
+const DETACHED_BATCH = /(^|[^.\w])batch\(\[/;
+
+const hits = scan(ROOT);
+if (hits.length === 0) process.exit(0);
+
+const wasChanged = changedThisTurn();
+const fatal = STRICT || hits.some((hit) => wasChanged(hit.file));
+const out = fatal ? console.error : console.warn;
+out('');
+out(
+  fatal
+    ? 'check-child-rows-batch: drizzle batch is called detached from db:'
+    : 'check-child-rows-batch: drizzle batch is called detached from db (pre-existing; this build is not failed for it):',
+);
+out('');
+for (const { file, line } of hits) out(`  - ${file}:${line}`);
+out('');
+out("drizzle's batch reads this.session, so in a deployed app every save that writes nested rows");
+out('fails with a 500 and leaves the parent without its children. Either:');
+out('');
+out("  - delete the app's copy of the child-row helper and import the package's:");
+out("      import { replaceChildRows } from '@assembly-js/app-foundation/server';");
+out('    Its signature is the one the copy was made from, so call sites keep their arguments; or');
+out('  - if the copy has drifted and cannot be swapped cleanly, change only the call to');
+out('      await batch.call(db, [first, ...rest]);');
+out('');
+out('Do not change what the helper writes or the order it writes in.');
+if (fatal) process.exit(1);
+
+function scan(dir) {
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRS.has(entry.name)) found.push(...scan(path));
+    } else if (entry.isFile() && SOURCE_FILE.test(entry.name)) {
+      const file = relative(ROOT, path);
+      readFileSync(path, 'utf8')
+        .split('\n')
+        .forEach((text, i) => {
+          // Whole-line comments only: a block-comment strip would eat string literals.
+          if (!/^\s*(\/\/|\*|\/\*)/.test(text) && DETACHED_BATCH.test(text)) {
+            found.push({ file, line: i + 1 });
+          }
+        });
+    }
+  }
+  return found;
+}
+
+// Returns a predicate over repo-relative paths changed since the turn baseline.
+function changedThisTurn() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return () => false;
+  const changed = new Set();
+  const listings = [
+    { args: ['diff', '--name-only', `${baseline}..HEAD`], parse: (line) => line },
+    // Porcelain rows are "XY path", or "XY old -> new" for a rename.
+    { args: ['status', '--porcelain', '--untracked-files=all'], parse: (line) => line.slice(3).split(' -> ').pop() },
+  ];
+  for (const { args, parse } of listings) {
+    const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    // Unknown history: treat every file as changed rather than let a broken app through.
+    if (result.status !== 0) return () => true;
+    for (const line of result.stdout.split('\n')) {
+      const file = parse(line).trim();
+      if (file) changed.add(file);
+    }
+  }
+  return (file) => changed.has(file);
+}

package/bin/check-identity-outage-states.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Checks that the app handles the platform being unable to confirm the viewer.
+// Dependency-free on purpose: it runs inside the generated app's sandbox
+// before any deps beyond Node exist.
+//
+// Since foundation 0.0.40, getSessionIdentity() throws AuthUnavailableError
+// when the platform can't be reached. The app must catch it in the root layout
+// and render a retry screen, and its client context must bound session renewal
+// with createRenewalGate — otherwise an outage fails every page and every
+// failed action renews the session without limit.
+//
+// An app whose root layout never calls getSessionIdentity predates identity
+// confirmation, so the contract never applied and this check exits 0.
+//
+// A gap is a warning on an ordinary turn (no agent there can act on an app
+// that was already behind) and fails the build with --strict (the update
+// acceptance) or when ASSEMBLY_TURN_BASELINE_SHA says this turn changed one of
+// the contract files.
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict');
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+
+const LAYOUT_FILE = 'app/layout.tsx';
+const CONTEXT_FILE = 'app/components/assembly-context.tsx';
+const RETRY_SCREEN_FILE = 'app/components/auth-unavailable.tsx';
+const RENEWAL_GATE_FILE = 'app/components/renewal-gate.ts';
+const CONTRACT_FILES = [LAYOUT_FILE, CONTEXT_FILE, RETRY_SCREEN_FILE, RENEWAL_GATE_FILE];
+
+const read = (file) => (existsSync(join(ROOT, file)) ? readFileSync(join(ROOT, file), 'utf8') : null);
+
+const layout = read(LAYOUT_FILE);
+if (layout === null || !/\bgetSessionIdentity\b/.test(layout)) {
+  process.exit(0); // pre-identity app: not this check's contract
+}
+
+const context = read(CONTEXT_FILE);
+const problems = [];
+if (read(RETRY_SCREEN_FILE) === null) problems.push(`${RETRY_SCREEN_FILE} is missing`);
+if (!/AuthUnavailableError/.test(layout)) {
+  problems.push(`${LAYOUT_FILE} does not handle AuthUnavailableError from getSessionIdentity()`);
+}
+if (read(RENEWAL_GATE_FILE) === null) problems.push(`${RENEWAL_GATE_FILE} is missing`);
+if (context !== null && !/createRenewalGate\s*\(/.test(context)) {
+  problems.push(`${CONTEXT_FILE} does not bound session renewal with createRenewalGate(`);
+}
+
+if (problems.length === 0) process.exit(0);
+
+const fatal = STRICT || contractChangedThisTurn();
+const out = fatal ? console.error : console.warn;
+out('');
+out(
+  fatal
+    ? 'check-identity-outage-states: the app does not handle the platform being unable to confirm the viewer:'
+    : 'check-identity-outage-states: the app does not handle the platform being unable to confirm the viewer (pre-existing; this build is not failed for it):',
+);
+out('');
+for (const problem of problems) out(`  - ${problem}`);
+out('');
+out('Since @assembly-js/app-foundation 0.0.40, getSessionIdentity() throws AuthUnavailableError when the');
+out('platform cannot be reached. Bring these app-owned files to the foundation shape:');
+out('');
+out(`1. Create ${RETRY_SCREEN_FILE}:`);
+out('');
+out("   'use client';");
+out('');
+out('   export default function AuthUnavailable() {');
+out('     return (');
+out('       <main className="flex min-h-screen flex-col items-center justify-center gap-3 px-4 text-center">');
+out('         <p className="text-sm text-muted-foreground">');
+out('           We couldn&apos;t load this right now. Please try again.');
+out('         </p>');
+out('         <button');
+out('           type="button"');
+out('           className="rounded-md border px-3 py-1.5 text-sm"');
+out('           onClick={() => window.location.reload()}');
+out('         >');
+out('           Try again');
+out('         </button>');
+out('       </main>');
+out('     );');
+out('   }');
+out('');
+out(`2. In ${LAYOUT_FILE}, import it (import AuthUnavailable from '@/app/components/auth-unavailable';)`);
+out('   and replace `const identity = await getSessionIdentity();` with:');
+out('');
+out('   let identity: Awaited<ReturnType<typeof getSessionIdentity>> = null;');
+out('   let authUnavailable = false;');
+out('   try {');
+out('     identity = await getSessionIdentity();');
+out('   } catch (err) {');
+out("     if (!(err instanceof Error && err.name === 'AuthUnavailableError')) throw err;");
+out('     authUnavailable = true;');
+out('   }');
+out('   if (authUnavailable) {');
+out('     return (');
+out("       <html lang=\"en\" style={{ colorScheme: 'light' }}>");
+out('         <body className="font-sans antialiased">');
+out('           <AuthUnavailable />');
+out('         </body>');
+out('       </html>');
+out('     );');
+out('   }');
+out('');
+out(`3. Create ${RENEWAL_GATE_FILE}:`);
+out('');
+out('   export function createRenewalGate(');
+out('     renew: () => Promise<boolean>,');
+out('     windowMs: number,');
+out('     now: () => number = Date.now,');
+out('   ): () => Promise<boolean> {');
+out('     let inFlight: Promise<boolean> | null = null;');
+out('     let lastStartedAt = Number.NEGATIVE_INFINITY;');
+out('     return () => {');
+out('       if (inFlight) return inFlight;');
+out('       if (now() - lastStartedAt < windowMs) return Promise.resolve(false);');
+out('       lastStartedAt = now();');
+out('       inFlight = renew().finally(() => {');
+out('         inFlight = null;');
+out('       });');
+out('       return inFlight;');
+out('     };');
+out('   }');
+out('');
+out(`   Then in ${CONTEXT_FILE} add \`import { createRenewalGate } from './renewal-gate';\`, define`);
+out('   `const renewOnce = createRenewalGate(reexchangeBearer, 30_000);` at module scope, and change the');
+out("   retry path's `await reexchangeBearer()` to `await renewOnce()`. Change nothing else in that file.");
+if (fatal) process.exit(1);
+
+function contractChangedThisTurn() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return false;
+  const listings = [
+    { args: ['diff', '--name-only', `${baseline}..HEAD`], parse: (line) => line },
+    // Porcelain rows are "XY path", or "XY old -> new" for a rename.
+    { args: ['status', '--porcelain', '--untracked-files=all'], parse: (line) => line.slice(3).split(' -> ').pop() },
+  ];
+  for (const { args, parse } of listings) {
+    const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    // Unknown history: treat as changed rather than let a broken app through.
+    if (result.status !== 0) return true;
+    const changed = result.stdout.split('\n').map((line) => parse(line).trim()).filter(Boolean);
+    if (changed.some((file) => CONTRACT_FILES.includes(file))) return true;
+  }
+  return false;
+}

package/bin/check-server-pdf-imports.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Fails the build when app code imports pdf-parse or pdfjs-dist on the server.
+// Dependency-free on purpose: it runs inside the generated app's sandbox
+// before any deps beyond Node exist.
+//
+// Since foundation 0.0.47, PDF text extraction uses the built-in
+// extractPdfText helper from @assembly-js/app-foundation/server. The old
+// libraries locate their worker script and canvas binding at runtime by paths
+// computed from their own location; the preview has the full node_modules so
+// they work there, but the deployed function only ships files reachable from
+// literal imports — every PDF parse fails after publishing with
+// "DOMMatrix is not defined" or "Setting up fake worker failed".
+//
+// An app with no such import passes, so there is no generation marker to check.
+//
+// A hit is a warning on an ordinary turn and fails the build with --strict
+// (the update acceptance) or when ASSEMBLY_TURN_BASELINE_SHA says this turn
+// changed the offending file.
+import { readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, relative } from 'node:path';
+
+const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict');
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+
+const SOURCE_FILE = /\.(?:ts|tsx|mts|js|jsx|mjs)$/;
+const SKIPPED_DIRS = new Set(['node_modules', '.next', '.git', '.assembly']);
+// Server-side imports of pdf-parse or pdfjs-dist (any subpath).
+const PDF_IMPORT = /(from|import\()\s*['"](pdf-parse|pdfjs-dist)\b/;
+// 'use client' files may legitimately import pdfjs-dist for browser-side
+// rendering (canvas, next/dynamic with ssr: false). The server-side breakage
+// this check guards against does not apply to client components.
+const USE_CLIENT = /^\s*['"]use client['"]/;
+
+const hits = scan(ROOT);
+if (hits.length === 0) process.exit(0);
+
+const wasChanged = changedThisTurn();
+const fatal = STRICT || hits.some((hit) => wasChanged(hit.file));
+const out = fatal ? console.error : console.warn;
+out('');
+out(
+  fatal
+    ? 'check-server-pdf-imports: server code imports pdf-parse or pdfjs-dist:'
+    : 'check-server-pdf-imports: server code imports pdf-parse or pdfjs-dist (pre-existing; this build is not failed for it):',
+);
+out('');
+for (const { file, line } of hits) out(`  - ${file}:${line}`);
+out('');
+out('Those libraries locate their worker script and canvas binding at runtime by paths');
+out('computed from their own location. The preview has the full node_modules so they');
+out('work there, but the deployed function only ships files reachable from literal');
+out('imports — every PDF parse fails after publishing.');
+out('');
+out("Replace each server-side use with the foundation's helper:");
+out("  import { extractPdfText } from '@assembly-js/app-foundation/server';");
+out('  const { text, pages } = await extractPdfText(bytes);');
+out('');
+out('Then remove the pdf-parse / pdfjs-dist / @napi-rs/canvas dependencies, any');
+out('GlobalWorkerOptions.workerSrc setup, and their entries in serverExternalPackages');
+out('in app.config.ts. Do not touch client-side PDF rendering code.');
+if (fatal) process.exit(1);
+
+function scan(dir) {
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRS.has(entry.name)) found.push(...scan(path));
+    } else if (entry.isFile() && SOURCE_FILE.test(entry.name)) {
+      const file = relative(ROOT, path);
+      const lines = readFileSync(path, 'utf8').split('\n');
+      if (lines.some((line) => USE_CLIENT.test(line))) continue;
+      lines.forEach((text, i) => {
+        if (!/^\s*(\/\/|\*|\/\*)/.test(text) && PDF_IMPORT.test(text)) {
+          found.push({ file, line: i + 1 });
+        }
+      });
+    }
+  }
+  return found;
+}
+
+function changedThisTurn() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return () => false;
+  const changed = new Set();
+  const listings = [
+    { args: ['diff', '--name-only', `${baseline}..HEAD`], parse: (line) => line },
+    { args: ['status', '--porcelain', '--untracked-files=all'], parse: (line) => line.slice(3).split(' -> ').pop() },
+  ];
+  for (const { args, parse } of listings) {
+    const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    if (result.status !== 0) return () => true;
+    for (const line of result.stdout.split('\n')) {
+      const file = parse(line).trim();
+      if (file) changed.add(file);
+    }
+  }
+  return (file) => changed.has(file);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -9,7 +9,6 @@
     "skills",
     "CLAUDE.md",
     "render-context.mjs",
-    "fixes.json",
     "CHANGELOG.md"
   ],
   "exports": {

package/fixes.json

@@ -1,78 +0,0 @@
-[
-  {
-    "id": "next-config-wrapper",
-    "version": "0.0.20",
-    "title": "Your app's live preview no longer hangs on networks that block its dev connection.",
-    "check": "Your app's Next config must be split so next.config.ts is the platform-owned wrapper and your own settings live in app.config.ts. The end state: next.config.ts contains exactly:\n\nimport { withAssemblyDev } from \"@assembly-js/app-foundation/next\";\nimport appConfig from \"./app.config\";\n\nexport default withAssemblyDev(appConfig);\n\nTo get there: create app.config.ts and move whatever next.config.ts currently exports (serverExternalPackages, experimental flags, redirects, headers, etc.) into it verbatim, keeping the export shape the app already used (e.g. `export default { ... }` or `export default appConfig satisfies NextConfig`). Then replace next.config.ts's contents with the wrapper above. If a sibling next.config.js or next.config.mjs exists, delete it — Next loads whichever config file it finds first, and a leftover unwrapped copy would silently run instead of the wrapper. Do not add new Next options while you're at it, and do not touch anything outside these two files — this fix is a relocation, not a config change.",
-    "detector": {
-      "absent": ["next.config.js", "next.config.mjs"],
-      "present": [
-        { "path": "next.config.ts", "contains": ["withAssemblyDev("] },
-        { "path": "app.config.ts" }
-      ]
-    }
-  },
-  {
-    "id": "paint-beacon",
-    "version": "0.0.22",
-    "title": "Your app's preview now accurately reports when a page has finished rendering, not just loaded.",
-    "check": "Your app is missing the post-paint beacon the builder preview uses to tell \"the page executed\" from \"the page actually rendered.\" Add the component exactly as the foundation ships it, at app/components/paint-beacon.tsx:\n\n'use client';\n\nimport { useEffect } from 'react';\nimport { installPaintBeacon } from '@assembly-js/app-foundation/client';\n\nexport default function PaintBeacon(): null {\n  useEffect(() => {\n    installPaintBeacon();\n  }, []);\n  return null;\n}\n\nRender it once, self-closing and prop-less, in the root layout's <body> (app/layout.tsx): import it as `import PaintBeacon from '@/app/components/paint-beacon';` and add `<PaintBeacon />` alongside the other foundation-owned providers already rendered there.\n\nThe beacon's POST must be routed before any CSRF or session-exchange handling, because sendBeacon is a headerless POST that 403s on the normal path. The platform sign-in proxy already does this, so proxy.ts's proxy export should be the package's:\n\nimport { createAssemblyProxy } from '@assembly-js/app-foundation/server';\n\nexport const proxy = createAssemblyProxy();\n\nIf proxy.ts has been rewritten away from that, restore that export (keep the file's `config` matcher as it is) rather than adding a beacon route by hand. Make sure @assembly-js/app-foundation is a declared dependency (it should already be installed). Do not post app.painted or hit /__assembly/painted yourself — the component already does both.",
-    "detector": {
-      "present": [
-        { "path": "app/components/paint-beacon.tsx" },
-        { "path": "app/layout.tsx", "contains": ["<PaintBeacon"] }
-      ],
-      "dependencies": ["@assembly-js/app-foundation"],
-      "checks": [{ "of": "@assembly-js/app-foundation", "script": "check-paint-beacon.mjs" }]
-    }
-  },
-  {
-    "id": "inlined-child-rows-batch",
-    "version": "0.0.37",
-    "title": "Saving a record with nested rows no longer fails and drops the rows.",
-    "check": "Your app has its own copy of the child-row replace helper, and that copy calls drizzle's batch detached from db (`const batch = db.batch …; await batch([...])`). drizzle's batch reads this.session, so in a deployed app every save that writes nested rows (a proposal's packages, a retainer's allowances) fails with a 500 and leaves the parent without its children.\n\nDelete the app's copy and import the package's helper instead: `import { replaceChildRows } from '@assembly-js/app-foundation/server';`. Its signature is the one the copy was made from, so call sites keep their arguments. If the copy has drifted from the original and can't be swapped cleanly, keep it and change only the call to `await batch.call(db, [first, ...rest]);`. Do not change what the helper writes or the order it writes in.",
-    "detector": {
-      "forbidden": [{ "id": "detached-db-batch", "pattern": "(^|[^.\\w])batch\\(\\[" }]
-    }
-  },
-  {
-    "id": "identity-outage-states",
-    "version": "0.0.40",
-    "title": "If Assembly can't confirm who is signed in, your app now shows a retry screen instead of an error.",
-    "check": "Since 0.0.40, getSessionIdentity() asks the platform who the viewer is and throws an AuthUnavailableError when the platform can't be reached. Your root layout calls it without a catch, so during an outage every page fails instead of showing a retry screen, and every failed action renews the session without a bound. Bring three app-owned files to the foundation's current shape:\n\n1. Create app/components/auth-unavailable.tsx:\n\n'use client';\n\nexport default function AuthUnavailable() {\n  return (\n    <main className=\"flex min-h-screen flex-col items-center justify-center gap-3 px-4 text-center\">\n      <p className=\"text-sm text-muted-foreground\">\n        We couldn&apos;t load this right now. Please try again.\n      </p>\n      <button\n        type=\"button\"\n        className=\"rounded-md border px-3 py-1.5 text-sm\"\n        onClick={() => window.location.reload()}\n      >\n        Try again\n      </button>\n    </main>\n  );\n}\n\n2. In app/layout.tsx, import it (`import AuthUnavailable from '@/app/components/auth-unavailable';`) and replace `const identity = await getSessionIdentity();` with:\n\nlet identity: Awaited<ReturnType<typeof getSessionIdentity>> = null;\nlet authUnavailable = false;\ntry {\n  identity = await getSessionIdentity();\n} catch (err) {\n  if (!(err instanceof Error && err.name === 'AuthUnavailableError')) throw err;\n  authUnavailable = true;\n}\nif (authUnavailable) {\n  return (\n    <html lang=\"en\" style={{ colorScheme: 'light' }}>\n      <body className=\"font-sans antialiased\">\n        <AuthUnavailable />\n      </body>\n    </html>\n  );\n}\n\nKeep everything else in the layout as it is.\n\n3. Create app/components/renewal-gate.ts:\n\nexport function createRenewalGate(\n  renew: () => Promise<boolean>,\n  windowMs: number,\n  now: () => number = Date.now,\n): () => Promise<boolean> {\n  let inFlight: Promise<boolean> | null = null;\n  let lastStartedAt = Number.NEGATIVE_INFINITY;\n  return () => {\n    if (inFlight) return inFlight;\n    if (now() - lastStartedAt < windowMs) return Promise.resolve(false);\n    lastStartedAt = now();\n    inFlight = renew().finally(() => {\n      inFlight = null;\n    });\n    return inFlight;\n  };\n}\n\nThen in app/components/assembly-context.tsx add `import { createRenewalGate } from './renewal-gate';`, define `const renewOnce = createRenewalGate(reexchangeBearer, 30_000);` at module scope, and change the retry path's `await reexchangeBearer()` to `await renewOnce()`. Change nothing else in that file.",
-    "detector": {
-      "present": [
-        { "path": "app/components/auth-unavailable.tsx" },
-        { "path": "app/layout.tsx", "contains": ["AuthUnavailableError"] },
-        { "path": "app/components/renewal-gate.ts" },
-        { "path": "app/components/assembly-context.tsx", "contains": ["createRenewalGate("] }
-      ]
-    }
-  },
-  {
-    "id": "package-proxy",
-    "version": "0.0.42",
-    "title": "Your app's sign-in and cross-site request protection now come from Assembly and are tested by it.",
-    "check": "Your app's sign-in proxy is still code the app owns. Since 0.0.42 the package provides all of it — the token exchange, the bearer cookie, the CSRF gate and the re-exchange pass-through — and proxy.ts only calls it:\n\nimport { createAssemblyProxy } from '@assembly-js/app-foundation/server';\n\nexport const proxy = createAssemblyProxy();\n\nReplace the proxy function in proxy.ts with that export and delete a root middleware.ts if one exists. Keep the file's `config` matcher, including any exclusions the app added for its own paths; `api/assembly-reexchange` must stay excluded. Carry over only what the app added on top of the foundation's proxy: request headers it set for its own pages go in `createAssemblyProxy({ onForward({ request, headers, session }) { headers.set(…) } })`. Do not keep, port or rewrite any token, cookie or CSRF handling. Verify with `node node_modules/@assembly-js/app-foundation/bin/check-proxy-csrf.mjs --strict`; if it fails, the fix is the file above, not a change to request handling.",
-    "detector": {
-      "absent": ["middleware.ts"],
-      "present": [{ "path": "proxy.ts", "contains": ["@assembly-js/app-foundation/server", "createAssemblyProxy("] }],
-      "dependencies": ["@assembly-js/app-foundation"],
-      "checks": [{ "of": "@assembly-js/app-foundation", "script": "check-proxy-csrf.mjs" }]
-    }
-  },
-  {
-    "id": "server-pdf-text-extraction",
-    "version": "0.0.47",
-    "title": "PDF uploads that parsed in the preview but failed after publishing now parse correctly.",
-    "check": "Your app reads PDF text on the server with pdf-parse or pdfjs-dist. Those libraries locate their worker script and the optional canvas binding at runtime by paths computed from their own location; the preview has the full node_modules so it works there, but the deployed function only ships the files reachable from literal imports, so every PDF parse fails after publishing with \"DOMMatrix is not defined\" or \"Setting up fake worker failed\".\n\nReplace each server-side use with the foundation's helper: `import { extractPdfText } from '@assembly-js/app-foundation/server';` then `const { text, pages } = await extractPdfText(bytes);` where `bytes` is the Buffer, Uint8Array or ArrayBuffer the code already has (read back from S3 or from the request). `text` is the whole document with pages separated by newlines and is empty for a scanned PDF with no text layer, so keep whatever fallback the app had for that case. Keep what the app does with the text unchanged.\n\nThen remove what only existed to support the old parser: the pdf-parse, pdfjs-dist and @napi-rs/canvas dependencies, any GlobalWorkerOptions.workerSrc setup, any static `import '@napi-rs/canvas'` or worker import, and their entries in serverExternalPackages in app.config.ts. Do not touch client-side PDF rendering code.",
-    "detector": {
-      "forbidden": [
-        {
-          "id": "server-pdf-parser-import",
-          "pattern": "(from|import\\()\\s*['\"](pdf-parse|pdfjs-dist/legacy/build/pdf(\\.mjs)?)['\"]"
-        }
-      ]
-    }
-  }
-]