Brain-tier dependency closure: commit-stable lockfile for the opt-in manifest

Context

Follow-up of #16364 (the two-path install tier, PR #16389). The tier split prunes the Brain set from package-lock.json, so npm install --no-save better-sqlite3@12.11.1 … resolves the Brain transitive closure against live registry state — the same Git SHA can install different Brain graphs on different days. The three roots are exact-pinned in package.brain.json (that much landed in #16364); the ~108-entry closure (@huggingface/transformers, sharp, onnxruntime, prebuild-install chain, …) still floats.

Live latest-open sweep 2026-08-02 (20 newest): no equivalent found.

The Problem

Before the split, every dependency resolved through one committed lock: SHA → identical graph, which is what Vega's plane-rebuild receipts and CI reproducibility stand on. Post-split that invariant covers only the base tier. The Brain tier's closure floats — bounded (stable libraries) but real, and exactly the class that turns a plane receipt into a non-reproduction.

The Fix (shape, open to the implementer)

Give the Brain tier a commit-stable closure consumed by every arming path (installBrain.mjs, ai/deploy/Dockerfile, harness pack staging). Candidate shapes:

1. A second lockfile (package-lock.brain.json) generated by composing package.json + package.brain.json in a scratch manifest and refreshing it on Brain-set changes — the installer then installs from the frozen graph (e.g. materialize the composed manifest+lock in a temp overlay and npm ci it into root node_modules, or extract the resolved closure and npm install --no-save the exact list).
2. A recorded-exact snapshot: the installer resolves once and commits the full exact specifier list it installed (weaker: pins versions installed then, not resolution now).
3. Something npm-native the implementer defends.

Guard rails: the generation path must not use npm install --package-lock-only against the repo lock (whole-file reformat churn — the #16364 lesson); the refresh belongs in a lint/CI check that fails when package.brain.json and its lock disagree.

Acceptance Criteria

• The same Git SHA installs the identical Brain graph on two clean machines (receipt: two fresh installs, identical npm ls closure hashes).
• installBrain.mjs and ai/deploy/Dockerfile consume the same frozen closure.
• A mechanical check fails CI when package.brain.json and the committed closure drift.
• Docs (GETTING_STARTED.md Brain-path note + the installer JSDoc) name the determinism contract.

Related

• #16364 — the tier (parent)
• #16204 — the census (evidence base)

Origin Session ID: 69b4b2b4-9f78-40aa-a653-6bd93ddde065

Retrieval Hint: query_raw_memories("brain lockfile deterministic closure install tier float")