latticesql 4.3.8 → 5.0.0

package/docs/api-reference.md

@@ -1122,10 +1122,41 @@ interface LatticeEntityDef {
 interface LatticeConfig {
   db: string;
   entities: Record<string, LatticeEntityDef>;
+  computed?: Record<string, ComputedTableDef>;
+}
+
+// Computed tables — config-defined, read-only SQL projections (the `computed:`
+// section). See computed-tables.md for the full guide, the GUI builder, and
+// the /api/computed-tables HTTP surface.
+interface ComputedTableDef {
+  base: string; // a declared entity or another computed table
+  description?: string;
+  fields: Record<string, ComputedFieldDef>; // projected in declaration order
 }
-```
 
-See [Configuration Guide](./configuration.md) for the complete YAML reference.
+type ComputedFieldDef =
+  | { kind: 'alias'; source: string }
+  | { kind: 'calc'; expr: string; type?: LatticeFieldType }
+  | {
+      kind: 'ai_classify';
+      input: string;
+      prompt: string;
+      labels: string[];
+      model?: 'default' | 'cheapest';
+    }
+  | { kind: 'ai_transform'; inputs: string[]; prompt: string; model?: 'default' | 'cheapest' }
+  | {
+      kind: 'aggregate';
+      via: string; // '<junctionTable>.<remoteRelation>'
+      fn: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'concat';
+      column?: string; // required for every fn except count
+    };
+```
+
+See [Configuration Guide](./configuration.md) for the complete YAML reference,
+and [Computed tables](./computed-tables.md) for the computed-table guide (field
+kinds, the GUI builder, AI-value refresh, and the `/api/computed-tables` HTTP
+routes).
 
 ---
 

package/docs/assistant.md

@@ -22,11 +22,36 @@ Every `ANTHROPIC_OAUTH_*` value (authorize/token URL, client id, scopes,
 redirect) can be overridden via the environment for a non-default deployment —
 see [`.env.example`](../.env.example).
 
+### Use an OpenAI-compatible model instead
+
+The assistant is not tied to Anthropic. On the first-run connect screen, choose
+**or connect an OpenAI-compatible model** to point it at any OpenAI-compatible
+`chat/completions` endpoint — OpenAI, Azure, OpenRouter, a local vLLM / Ollama /
+LM Studio server, your own gateway, or GitHub Copilot if you point it there. You
+supply three things: a **base URL** (up to `/v1`), an **API key** (sent as a
+Bearer token — leave blank for a keyless local server), and a **model** id
+(e.g. `gpt-4o`). Lattice ships **no** provider-specific auth or header
+impersonation; if your endpoint needs extra headers (an Azure `api-key`, a
+gateway token) they can be supplied alongside the config.
+
+Once connected it becomes the active backend and **every** assistant feature —
+chat, auto-linking / ingestion, computed-table fills, as-of detection, HTML
+authoring — runs on it. Switching backends and disconnecting are available via
+the API (`PUT /api/assistant/provider`, `DELETE
+/api/assistant/provider/openai-compat`); with nothing configured the assistant
+resolves a connected Claude subscription exactly as before. Image / PDF vision
+still uses a connected Claude subscription when one is available. Credentials are
+stored encrypted in the machine-local assistant credential store, never returned
+by any endpoint.
+
 ## Chat
 
-The rail runs a Claude tool-calling loop streamed over SSE. The model can list,
-read, **full-text search**, create, update, link, delete tables, and revert in
-the active database. **Every edit goes through the same audited, undoable
+The rail runs a Claude tool-calling loop. Sending a message returns immediately
+(the request is acknowledged, not held open); the turn runs in the background and
+its text streams to the browser over the multiplexed event WebSocket, so closing
+the panel, navigating away, or reloading never cancels an in-flight answer. The
+model can list, read, **full-text search**, create, update, link, delete tables,
+and revert in the active database. **Every edit goes through the same audited, undoable
 mutation path as a manual edit** — it appears in the activity feed and the
 version history and can be reverted.
 

package/docs/bugs/2026-07-05-db-source-import-then-wipe.md

@@ -0,0 +1,71 @@
+# Connecting a database imports every row, then silently wipes it
+
+**Date:** 2026-07-05
+**Area:** db-source connector connect route (`src/gui/db-sources-routes.ts`) + teardown (`src/connectors/teardown.ts`)
+
+## Symptom
+
+A user connected an external Postgres (≈20 tables, ~2,900 rows). Every table was
+created and every row was imported — and then, ~50 seconds later, **all of it
+disappeared**: the graph and object views showed "No objects with data yet", and
+the connection was gone from the Databases list. From the user's side it looked
+like nothing had ingested at all.
+
+## Root cause
+
+The connect handler ran the entire import inside one `try`:
+
+```
+defineLate(each table) → enableConnectorRls → syncConnector → publishImportSummary
+```
+
+and its `catch` responded to **any** throw — including one that happens _after_
+all the rows are already committed — by calling
+`disconnectConnector(mode: 'hard')`. That teardown soft-deletes every imported
+row (under one shared `deleted_at` timestamp) and hard-deletes the registry row.
+
+So the handler conflated two very different failures:
+
+1. **Pre-persistence** (bad creds, no reachable tables, a `defineLate`/RLS
+   failure) — nothing landed, so rolling back is correct.
+2. **Post-persistence** (a late/derived/transient step throws after thousands of
+   rows are committed) — the rollback **destroys a fully successful import**.
+
+The specific late throw is not even deterministic on a local SQLite workspace,
+which is the tell: the defect isn't any single operation, it's the _all-or-nothing
+rollback policy_. It also destroyed its own evidence — the only persisted error
+trace (the registry's `last_error`) was hard-deleted by the same teardown, so the
+failure surfaced as "nothing ingested" with no cause.
+
+## Fix
+
+Split the connect into two phases:
+
+- **Setup** (`defineLate` + RLS) keeps the hard rollback — a failure here means
+  nothing landed, so no phantom entry is left behind.
+- **Import** (`syncConnector`) no longer rolls back on failure. `syncConnector`'s
+  own catch has already stamped the registry row `status='error'` + `last_error`,
+  and `GET /api/db-sources` returns every status, so the connection stays visible
+  with its error, the imported rows stay live, the raw error is logged
+  server-side, and the user can **Refresh** to retry or **Disconnect** to remove.
+
+This is the intended loud-failure behavior: surface the error, keep the data.
+
+## Lessons
+
+- An "atomic connect" must not treat a post-commit failure the same as a
+  pre-commit one — discarding already-persisted user data to satisfy atomicity is
+  worse than a visible partial import.
+- A rollback that also deletes the error record makes the failure undiagnosable.
+  Log the raw error before any cleanup.
+
+## Regression tests
+
+`tests/integration/gui-db-sources-rollback.test.ts`:
+
+- An import failure keeps an errored connection (registry row survives with
+  `status='error'`, shows in `/api/db-sources`, creds/descriptor retained) instead
+  of wiping everything.
+- A **post-persistence** failure (rows imported for the first model, the second
+  model throws) keeps the already-imported rows **live** and the connection
+  present — the exact production data-loss path.

package/docs/bugs/2026-07-06-workspace-switch-stale-settings-takeover.md

@@ -0,0 +1,61 @@
+# Switching workspaces left the Settings / Version-history takeover showing the old workspace
+
+**Date:** 2026-07-06
+**Area:** GUI client — workspace switch routing (`src/gui/app/modules/search.ts`)
+**Severity:** stale/misleading data (a workspace-scoped panel kept showing the previous workspace)
+
+## Symptom
+
+With the **Settings** drawer open (Workspace tab — the workspace name, database
+connection, and data model), switching to a different workspace from the topbar
+dropdown updated the topbar (it now named the new workspace) but the Settings panel
+kept showing the **previous** workspace's data — the topbar named workspace B while the
+Workspace Settings display name still showed workspace A. The same happened for any open
+takeover: **Version history** kept showing the old workspace's history.
+
+## Root cause
+
+`reloadEverything()` is the single canonical workspace-switch path. To keep the user
+in the same section across a switch it computes a `switchTarget` hash from the current
+route and navigates there (or soft-re-renders if already on it). The mapping handled
+Analytics / Graph / Tables / Objects but had **no case for `#/settings/*`**, so a
+settings or version-history route fell through to the `#/folders` default.
+
+The Settings drawer and Version history are **takeover overlays** that the route
+dispatcher (re)renders from the hash: `#/settings/database → openSettingsDrawer('database')`,
+etc. By routing the switch to `#/folders`, `reloadEverything()` both (a) failed to
+re-invoke `openSettingsDrawer` for the new workspace and (b) never closed the drawer —
+so the overlay stayed on screen still populated with the previous workspace's
+`renderDatabaseSettings` / `renderHistory` output. The panel content is workspace-
+specific (name, DB connection, data model, history), so it read as another workspace's
+data leaking into the current view.
+
+## Fix
+
+Add a `#/settings/*` case to the `switchTarget` computation that **preserves the exact
+route** (`cur`). When the target equals the current hash, `reloadEverything()` takes its
+existing "already on target → `renderRoute({ soft: true })`" branch, which re-dispatches
+the settings route → `openSettingsDrawer(section)` → `selectDrawerTab` → re-renders the
+drawer body (`renderDatabaseSettings` / `renderLatticeSettings` / `renderUserConfig` /
+`renderHistory`) against the now-active new workspace. The takeover stays open and shows
+the new workspace's data. Version history (`#/settings/history`) is covered by the same
+prefix.
+
+## Lessons learned
+
+- A "keep the user in the same section on switch" mapping must account for **every**
+  routed surface, including overlay takeovers — not just the main content sections. A
+  route that isn't in the mapping silently falls to the default and strands whatever
+  overlay was open.
+- Overlays that render workspace-scoped data are a cross-workspace-leak risk on switch,
+  the same class as the Outputs-markdown leak: the switch path must refresh (or close)
+  every workspace-scoped surface, not only the ones rendered into `#content`.
+
+## Regression tests
+
+- `tests/unit/outputs-workspace-switch.test.ts` — "a switch while a Settings /
+  Version-history takeover is open re-renders it for the new workspace": drives the real
+  `reloadEverything()` in jsdom with `location.hash = '#/settings/database'` and asserts
+  the hash is **preserved** (not reset to `#/folders`) and `renderRoute({ soft: true })`
+  is called (which re-renders the drawer for the new workspace). Fails before the fix
+  (`#/folders`), passes after.

package/docs/bugs/2026-07-11-chat-active-context-w-routes.md

@@ -0,0 +1,63 @@
+# Chat lost the currently-open dashboard/record as context on the 5.0 Workspace routes
+
+- **Date:** 2026-07-11
+- **Area:** GUI chat context (`activeContext`) / client route detection
+- **Severity:** High (core "assistant knows what you're looking at" feature silently no-ops)
+
+## Symptom
+
+With a dashboard open, asking the assistant "why is this dashboard blank?" produced a reply
+asking the user to _open_ the dashboard they were already viewing (e.g. "I need to see the
+dashboard to diagnose the issue. Could you open it so I can investigate?"). The same class of
+failure applied to any open table record or file — the assistant never received the
+currently-open surface as context, so "this dashboard / this row / this file" resolved to
+nothing and the self-diagnosis (`investigate`) tool had no default target.
+
+## Root cause
+
+The client sends a `activeContext: { table, id }` hint with every chat message, computed by
+`activeElement()` in `src/gui/app/modules/boot-interstitial.ts`. Its dashboard branch matched
+**only** the retired route `#/analytics/<id>`. In the 5.0 single layout:
+
+- the canonical open-dashboard route is `#/w/dash/<id>` (see `renderRoute` in
+  `analytics-view.ts`), and
+- `normalizeLegacyHash` (`workspace-switch-progress.ts`) rewrites `#/analytics/<id>` →
+  `#/w/dash/<id>` on entry,
+
+so a user viewing a dashboard is **always** on `#/w/dash/<id>` — a hash `activeElement()`
+never recognized. It therefore returned `null`, the client POSTed `activeContext: null`, and
+the entire (correct) server chain went idle: `parseActiveContext` → `undefined`,
+`describeActiveView` emitted no note, `dispatch.activeDashboardId` was never set, and the
+`investigate` tool returned "No dashboard is open… have them open it." The same gap dropped
+open table records (`#/w/table/<name>/<rowId>`) and files (`#/w/file/<id>`) from chat context.
+
+The server side of the feature was fully built and correct — it was starved of the one input
+it needed because the client route detector was never migrated to the `#/w/…` scheme.
+
+## Fix
+
+Add a `#/w/(dash|table|file|md)/<first>[/<drill-in>…]` branch to `activeElement()` that mirrors
+`renderRoute`'s parser:
+
+- `dash` → `{ table: 'dashboards', id }`
+- `file` → `{ table: 'files', id }`
+- `table` / `md` → the deepest complete `table,id` pair (a bare collection yields `null`)
+
+The legacy `#/analytics/<id>` branch is retained for back-compat.
+
+## Lessons learned
+
+- When a route scheme is migrated (`#/analytics` / `#/fs` → `#/w/…`), audit **every** consumer
+  of the hash, not just the renderers. A route producer (`renderRoute`) and a route _reader_
+  (`activeElement`) drifted apart, and only the reader was missed — a silent no-op with no error.
+- Client-computed context that feeds the model needs a behavioral test at the client seam.
+  There was thorough coverage of the _server_ consuming a well-formed hint and of the
+  downstream tools once `activeDashboardId` was set, but nothing asserted the client actually
+  _produces_ the hint from the current route — so the regression slipped through green tests.
+
+## Regression tests
+
+- `tests/unit/gui-active-element-dashboard.test.ts` — jsdom test that evals the client segment
+  and asserts `activeElement()` returns the right `{ table, id }` for `#/w/dash/<id>` (incl.
+  percent-encoded ids), `#/w/file/<id>`, `#/w/table/<name>/<rowId>`, a drilled relation
+  (deepest pair), `null` for a bare collection, and the legacy `#/analytics/<id>` route.

package/docs/bugs/2026-07-11-connector-table-unknown-table.md

@@ -0,0 +1,55 @@
+# Clicking a post-open registered table 404s "Unknown table"
+
+- **Date:** 2026-07-11
+- **Area:** GUI row/read routes — table-name validation vs. the live registry
+- **Severity:** High (a table shown in the sidebar is unclickable — hard error)
+
+## Symptom
+
+After connecting a connector (e.g. a Gmail connector registering `gmail_labels`), the new
+table appears in the sidebar TABLES list, but clicking it returns `Unknown table: gmail_labels`
+and the collection never loads. A page reload does not help. The same applies to tables
+registered by a connected external database (db-source).
+
+## Root cause
+
+The sidebar list is built from the **live** table registry (`db.getRegisteredTableNames()`,
+via `entitiesSummary` / `registeredExtraTables`), but the row + read routes validated table
+names against `active.validTables` — a **snapshot** built once when the workspace opened
+(config tables ∪ registered non-internal tables at open time). A connector or db-source
+registers its tables via `db.defineLate` **after** the workspace opened, so those tables are
+in the live registry (hence listed) but absent from the snapshot (hence rejected). The list
+source and the validation source diverge.
+
+The gate appeared in several places — `tables-routes.ts` (row CRUD, the reported error),
+`read-routes.ts` (provenance graph/row + the rows-markdown listing) and `server.ts`
+(`/api/gui-meta`) — all using the bare `active.validTables.has(table)` snapshot check. Notably
+the schema-op paths (`computed-ops.ts`, `schema-ops.ts`, `schema-routes.ts`) **already** used
+the correct `validTables.has(x) || db.getRegisteredTableNames().includes(x)` idiom; the row/read
+gates were simply never migrated to it.
+
+## Fix
+
+Add one shared predicate `isRegisteredTable(active, table)` in `active-db.ts`: true if the
+table is in the `validTables` snapshot **or** in the live registry, with internal
+(`__lattice*` / `_lattice*`) tables always excluded so the security boundary is unchanged.
+Replace the bare `validTables.has` snapshot checks on the row/read/navigate gates
+(`tables-routes.ts`, `read-routes.ts` ×3, `server.ts` gui-meta) with it. Genuinely-unknown
+tables still 400/404 (they are in neither set).
+
+## Lessons learned
+
+- A "snapshot at open" set that a later runtime step (`defineLate`) can extend is a divergence
+  waiting to happen. When the same question ("is this a real table?") is answered against two
+  sources — a live registry for _listing_ and a snapshot for _validation_ — they will drift.
+  Answer it one way. Here the schema paths already had the right idiom; the fix is consistency.
+- When adding a gate, prefer a single named predicate over inlining `set.has(x)` at each call
+  site, so a policy change lands in one place instead of ~40.
+
+## Regression tests
+
+- `tests/unit/gui-registered-table.test.ts` — pins `isRegisteredTable`: accepts a snapshot
+  table, accepts a table registered after open (absent from the snapshot — the regressed case),
+  rejects a table in neither, and never exposes internal `__lattice*` / `_lattice*` tables even
+  when live-registered. The existing integration test that a genuinely-unknown table still
+  returns "Unknown table" continues to guard the reject path.

package/docs/bugs/2026-07-12-image-vision-byo-key-auth.md

@@ -0,0 +1,55 @@
+# Image descriptions never generate with a bring-your-own Claude API key
+
+- **Date:** 2026-07-12
+- **Area:** Ingest — image/PDF vision credential resolution
+- **Severity:** High for BYO-key users (image files ingest with no description; the file view shows "No source text.")
+
+## Symptom
+
+Opening an image file record shows a body of exactly "No source text." instead of the
+expected AI-generated description of the image. Chat and text enrichment work fine for the
+same user — only image (and scanned-PDF) descriptions are missing.
+
+## Root cause
+
+It is an ingest-side credential gap, not a render bug. Image vision (`extractImage`) and the
+scanned-PDF fallback resolve their Anthropic auth via `resolveClaudeAuth`, which is **narrower**
+than the resolver chat + text enrichment use (`resolveLlmProvider`): `resolveClaudeAuth` returns
+auth only for a managed env key or a connected Claude **subscription (OAuth)**, and never
+consults the **bring-your-own Claude API key** configured as an API provider pointed at an
+Anthropic host (`readOpenAiCompatConfig` + `isAnthropicEndpoint`).
+
+So for a BYO-key user: `resolveClaudeAuth` returns null → `extractImage` returns null → the file
+is written with `extracted_text=''` and `extraction_status='skipped'` (and, because the row is
+`skip`ped, LLM enrichment — the only writer of a `description` — never runs either). The record
+view faithfully reads `extracted_text` and, finding it empty, renders "No source text.".
+
+The render side was correct throughout; there was never an AI description sitting in a field the
+view ignored — the description was simply never generated.
+
+## Fix
+
+Add `resolveVisionAuth(db)` in `src/gui/ai/provider.ts` and use it at the two vision call sites
+(`ingest-routes.ts` `extractImage` + the PDF fallback) instead of `resolveClaudeAuth`. It unifies
+vision's credentials with the rest of the assistant — managed env key, connected subscription,
+**and** a BYO Claude API key on an Anthropic host — following the same managed → active-provider
+ordering as `resolveLlmProvider`. Living in `provider.ts` (which already imports
+`resolveClaudeAuth` + the config helpers) avoids an import cycle with `assistant-routes.ts`.
+
+Known limitation: `ClaudeAuth` carries no `baseURL`, so a BYO key against a **non-default**
+Anthropic host (a gateway) is not honored for vision — the common `api.anthropic.com` key works;
+a custom-host key falls through to a connected subscription, else no vision.
+
+## Lessons learned
+
+- Two credential resolvers for "the same" thing (chat vs. vision) drift. When a feature needs
+  Anthropic auth, it should resolve it through one shared path, not a hand-rolled narrower check.
+- "A key is present" is a trap: the key was present for chat and invisible to vision. Test the
+  credential resolver directly at the exact configuration state that reproduces the gap.
+
+## Regression tests
+
+- `tests/unit/llm-provider.test.ts` — with only a BYO Claude API key on an Anthropic endpoint
+  (no OAuth, not managed): `resolveClaudeAuth` returns null (the root cause) while
+  `resolveVisionAuth` returns the usable `{ apiKey }`. Plus: a non-Anthropic OpenAI-compatible
+  endpoint yields no vision auth, and nothing-configured stays null.

package/docs/bugs/2026-07-13-desktop-bulk-ingest-js-heap-oom.md

@@ -0,0 +1,104 @@
+# Desktop app crashes with a JS-heap OOM during bulk document ingest
+
+- **Date:** 2026-07-13
+- **Area:** Ingest — desktop runtime memory ceiling + extraction concurrency
+- **Severity:** Critical (the whole desktop app process aborts mid-batch; repeated, reproducible)
+
+## Symptom
+
+Ingesting a folder of large Office documents (~60 files, a few hundred MB total, individual
+spreadsheets/decks up to ~35 MB) crashes the desktop app partway through the batch. The
+macOS crash report shows `EXC_BREAKPOINT (SIGTRAP)` on the embedded runtime thread. Time to
+crash varies wildly with what is being ingested — from ~70 seconds after launch to many
+hours — and the same folder ingests fine through the CLI-launched GUI on the same machine.
+
+Symbolicating the crash frames against the runtime binary identifies the abort precisely:
+V8 `FatalProcessOutOfMemory` with the reason string **"Ineffective mark-compacts near heap
+limit"** — the JS old-space heap hit its configured maximum and consecutive full GCs could
+not reclaim anything. Notably, resident memory at death was only ~270 MB, which had
+previously been read as evidence this was _not_ an OOM; it is — the heap limit itself was
+tiny.
+
+## Root cause
+
+Two independent causes compound:
+
+1. **The compiled desktop runtime ships a conservative default V8 heap limit.** Nothing in
+   the desktop build passed `--v8-flags`, and the packaged runtime's default old-space
+   ceiling is a few hundred MB — vs ~4 GB for the CLI (`deno run`) default on the same
+   machine. This is why the crash class is desktop-only and why every prior "bulk-ingest
+   crash" investigation on the desktop kept finding memory-shaped failures. There is no
+   runtime escape hatch in the packaged app (no env-var flag pass-through), so the limit
+   must be baked in at build time.
+
+2. **Extraction transients are input-side, large, and were multiplied by concurrency.** The
+   folder-ingest pool runs 4 files at once and the browser upload path allows 3 more, and
+   each in-flight file can materialize:
+   - a full archive inflation of an Office/OpenDocument/EPUB file into memory
+     (`unzipSync` map, up to the 256 MB aggregate cap) plus full JS-string decodes of the
+     large XML parts;
+   - a pdf.js parse graph bounded only by a wall-clock timeout, not by memory;
+   - for scanned PDFs, a base64 copy of the whole file (~1.37×) inside the model request
+     body, which the SDK re-serializes and retains across 429/5xx retries — this leg had no
+     lock at all (only native image normalization was serialized);
+   - for browser uploads, the full request buffer (≤50 MB) retained by the handler for the
+     rest of its lifetime, alongside all of the above.
+
+   The 200 KB cap on _extracted text_ never bounded any of these input-side intermediates.
+   Count-based concurrency limits (4 + 3) cannot bound the heap when a single file's
+   transients run to hundreds of MB: concurrency × peak-transient is the number that has to
+   fit the heap, and it didn't.
+
+## Fix
+
+- **Bake a real heap ceiling into every desktop build.** All four `deno desktop` build
+  scripts now pass `--v8-flags=--max-old-space-size=4096` (matching the CLI default on a
+  16 GB machine and the ceiling CI already builds with). It is a ceiling, not a
+  reservation — the process still only commits what it allocates.
+- **Serialize heavy extraction.** New `src/gui/ai/extract-gate.ts`: files ≥ 8 MB on disk
+  acquire a process-wide single-slot lane around the whole extraction (`extractSource`),
+  covering archive inflation, PDF parsing, and the scanned-PDF vision call for every ingest
+  door (folder pool, browser upload, local-path ingest, chat attachments). Smaller files —
+  the long tail — keep the pool's full concurrency. Lock order with the existing native
+  image lock is strictly lane → native, so the two cannot deadlock; the lane releases in
+  `finally`, so a throwing extraction never poisons it.
+- **Release the upload buffer before extraction.** The browser-upload handler now hashes
+  and sizes the request bytes up front, keeps them only if an S3 push will need them, and
+  drops the reference before extraction begins — a large upload's in-memory copy no longer
+  coexists with the extraction transients.
+- **Log the effective heap limit at startup** (`[desktop] … (V8 heap limit N MB)`), so a
+  memory-starved build is visible at a glance instead of only as a mid-ingest crash.
+
+## Lessons learned
+
+- **Output caps don't bound input transients.** The extracted-text cap suggested extraction
+  memory was bounded; the actual heap cost lives in the intermediates (inflation maps,
+  parse graphs, base64 request bodies) that exist before any cap applies.
+- **A compiled runtime's V8 defaults are not the CLI's defaults — assert them, don't assume
+  them.** The startup heap-limit log and the build-script regression test exist so this
+  divergence can never be invisible again.
+- **Low resident memory does not rule out an OOM.** A process can die of heap exhaustion at
+  ~270 MB RSS when the configured limit is small. Symbolicate the abort reason before
+  classifying a crash.
+- **Per-stage locks don't compose into a memory budget.** Serializing one native step
+  (image normalization) still left every JS-heavy leg concurrent. The budget that matters
+  is concurrency × peak-per-file-transient across the whole pipeline.
+
+## Regression tests
+
+- `tests/unit/extract-gate.test.ts` — heavy extractions serialize (`maxActive === 1`),
+  small files stay concurrent and are never blocked behind the lane, and a rejected heavy
+  extraction releases the lane for the next waiter.
+- `tests/unit/desktop-heap-flags.test.ts` — every desktop build script carries
+  `--v8-flags=--max-old-space-size=4096`; fails loudly if the flag is ever dropped.
+- The upload-buffer release is a reference-lifetime change with no cheap deterministic
+  test (observing collectability mid-handler requires GC instrumentation); it is covered by
+  review and the end-to-end bulk-ingest verification.
+
+## Follow-ups (noted, not in this fix)
+
+- `autoImportStructured` (spreadsheet re-import on upload) runs outside the lane,
+  post-extraction, upload-only — worth folding under the lane if it ever shows up in a
+  heap profile.
+- pdf.js parsing remains timeout-bounded rather than memory-bounded; the lane serializes
+  big PDFs, which contains the risk, but a streaming/paged parse would bound it properly.