ruvnet-brain 4.3.28 → 4.3.30

package/scripts/release.mjs

@@ -1,30 +1,38 @@
 #!/usr/bin/env node
-// scripts/release.mjs — the DEFINITION OF DONE. The only path to the word "shipped."
+// scripts/release.mjs — the ONLY publisher, plus a local preview of the CI qualification gate.
 //
 // WHY (2026-07-17, Stuart): "You should be able to take the applied knowledge and build it into a set
 // of criteria that you always use, not a bunch of suggestions you choose to ignore." Every failure
 // this session was an ASSUMPTION that survived because the check was a suggestion, not a gate. This
-// script turns the checklist into a gate: it runs the criteria in order, STOPS on the first failure,
-// and only prints "SHIPPED" when every channel a user touches is proven current and working. There is
-// no "I think it's fine" — there is pass or fail.
+// script turns the checklist into a gate: it runs the criteria in order and STOPS on the first
+// failure. There is no "I think it's fine" — there is pass or fail.
 //
-// Check-only mode evaluates source. Publish mode consumes a CI-sealed package and receipt, then
-// performs only the staged transaction and public verification. It never rebuilds or retests the
-// source: the immutable artifact is the evidence boundary.
+// WHAT EACH MODE ACTUALLY DOES (rewritten 2026-09-26, consolidation/single-source — the previous
+// header called check-only "the DEFINITION OF DONE" and claimed it alone decided "shipped"; that was
+// never true and duplicated a second, drifting gate list alongside CI's real one). Publishing a
+// release — creating the GitHub Release, moving the npm dist-tag — happens ONLY inside the
+// reviewer-protected `protected-release.yml` workflow, against an exact-SHA CI-sealed candidate;
+// `--publish` mode is that workflow's publisher (it validates the protected-invocation receipt before
+// doing anything and refuses outside it), never rebuilds or retests source, and treats the immutable
+// artifact as the evidence boundary. `--check` mode is a read-only LOCAL PREVIEW for a human on a dev
+// branch: it runs the exact same release-qualification gate CI enforces
+// (`scripts/release-qualification.mjs` + `scripts/release-qualification-contract.mjs`, invoked the
+// same way `canonical-qa.yml`/`ci.yml` invoke it) plus the one-publisher check
+// (`scripts/release-authority.mjs`). There is exactly ONE definition of "release-qualified" — the one
+// CI enforces — and this is a preview of it, not a second, independent one.
 //
 // Usage:
-//   node scripts/release.mjs --check          # run every gate READ-ONLY (no publish) — the pre-flight
-//   node scripts/release.mjs --publish        # publish the exact CI-sealed artifact
+//   node scripts/release.mjs --check          # preview the SAME qualification gate CI enforces
+//   node scripts/release.mjs --publish        # the protected workflow's publisher; not for manual use
 //   node scripts/release.mjs                   # same as --check
 //
 // The gates, in order (fail fast):
-//   A. version single-source-of-truth agrees (sync-version --check)
-//   B. full test suite green (npm test — the 60/60)
-//   C. narrative + unit gates (vitest) incl. the tag/entity-aware "What's new" check
+//   A. version single-source-of-truth agrees (sync-version --check) + one protected publisher
+//   B. release qualification — scripts/release-qualification.mjs, invoked exactly as CI invokes it
 //   D. [--publish only] stage and promote the exact package plus signed RVF bundle
-//   E. [--check only] verify current public channels; publish verifies them inside transaction finalization
 
 import path from 'node:path';
+import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { spawnSync, execFileSync } from 'node:child_process';
 import fs from 'node:fs';
@@ -500,71 +508,22 @@ if (!PUBLISH) {
   runOrDie('version sync', process.execPath, ['scripts/sync-version.mjs', '--check']);
   runOrDie('one protected publisher', process.execPath, ['scripts/release-authority.mjs']);
 
-// WIRED-CHECK — refuses to ship a module with zero callers.
+// RELEASE QUALIFICATION — ONE definition of "release-qualified", the one CI enforces.
 //
-// Added 2026-07-22 after this project shipped built-tested-unwired code SEVEN times in one session
-// (capability-registry, capability-audit, lesson-gate's five triggers, anticipate.sh,
-// advocacy-outcomes, lesson-promote's demotion, continuation-gate's global path). Every one had
-// passing tests, because a test imports the module directly — the one caller that proves nothing
-// about whether the product uses it. Every one was found by a human running grep, hours later.
-//
-// Seven repetitions of one mistake is not a discipline problem; discipline is what failed. So it
-// becomes a gate, on the ship path, where this repo's gates run 8/8 against prose's 0/6.
-  runOrDie('wired (no orphan modules)', process.execPath, ['scripts/wired-check.mjs', '--check']);
-
-// THE NORTH-STAR PROMOTION VECTOR — strict/check-only releases may not average one broken or
-// unknown invariant into a pass. The separately authorized stabilization class makes no 95 claim;
-// it retains every safety, test, artifact, publication, and post-publication gate below while the
-// promotion program remains open. Derive this only from the already-validated sealed receipt, never
-// from a free-standing environment toggle.
-  if (protectedReleaseMode === 'strict') {
-    runOrDie('release vector (all critical invariants PASS)', process.execPath, ['scripts/release-vector.mjs']);
-
-  // The Top-100 corpus spans naive through expert prompts and grades semantic clauses, citations,
-  // abstention, and latency. A manual-only benchmark is a report; a strict release-path benchmark
-  // is a guarantee. The benchmark itself fails closed unless all 100 canonical questions run.
-    runOrDie('Top-100 source-grounded recall contract', process.execPath, ['scripts/top100-benchmark.mjs', '--no-write']);
-  } else {
-    console.log(c.y('  strict >=95 promotion gates: NOT CLAIMED (sealed stabilization; scoreClaimed:false)'));
-  }
-
-// A2. Stable Spine restart classifier (ADR-023, red-team finding 18): diff the boot-frozen SHELL
-// (hooks.json, hook-shim, MCP server, .mcp.json, skills/, commands/) against the previous release
-// tag and SAY OUT LOUD whether this release needs a restart. The classification is computed, never
-// remembered — the same shellDiff logic runs client-side in update-apply.mjs at every flip, so the
-// user-facing nag stays honest even if this print is ignored. Informational at ship time; the
-// releasing human sees exactly which shell files changed.
-  step('A2', 'Stable Spine — does this release change the boot-frozen shell? (requiresRestart classifier)');
+// Rewritten 2026-09-26 (consolidation/single-source). Before this change, check-only mode ran its
+// OWN separate gate list (npm test, vitest tests/unit, release-vector.mjs, top100-benchmark.mjs,
+// wired-check.mjs, a Stable-Spine restart print, and a live verify-channels.mjs walk) that had
+// drifted from — and duplicated — the actual contract CI enforces in
+// scripts/release-qualification-contract.mjs. Two lists of "what counts as qualified" is exactly how
+// a local PASS stops meaning what CI's PASS means. There is now one contract; this runs it locally,
+// read-only, the same way canonical-qa.yml's `qualify-development` job runs it on every push/PR.
+  step('B', 'release qualification — the same gate CI enforces (release-qualification.mjs)');
   {
-  const { execFileSync } = await import('node:child_process');
-  const SHELL = ['plugin/hooks/hooks.json', 'plugin/scripts/hook-shim.mjs', 'plugin/mcp/server.mjs', 'plugin/.mcp.json', 'plugin/skills', 'plugin/commands'];
-  let prevTag = '';
-  try { prevTag = execFileSync('git', ['describe', '--tags', '--abbrev=0'], { encoding: 'utf8' }).trim(); } catch { /* no tags yet */ }
-  if (!prevTag) {
-    console.log(c.dim('  no previous release tag — classifier has no baseline (first spine release: requiresRestart=true by definition)'));
-  } else {
-    let changed = [];
-    try {
-      const out = execFileSync('git', ['diff', '--name-only', `${prevTag}..HEAD`, '--', ...SHELL], { encoding: 'utf8' }).trim();
-      changed = out ? out.split('\n') : [];
-    } catch { /* diff failure = unknown; say so, never guess green */ changed = ['(diff failed — treat as changed)']; }
-    if (changed.length) {
-      console.log(`  ${c.y('requiresRestart: TRUE')} — shell changed vs ${prevTag}:`);
-      for (const f of changed) console.log(`    · ${f}`);
-      console.log(c.dim('  users get ONE honest restart notice (session-start reads active.json.shellChanged); everything else is live.'));
-    } else {
-      console.log(`  ${c.g('requiresRestart: false')} — no shell change vs ${prevTag}; this release goes fully live with zero restarts.`);
-    }
+    const reportDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-brain-release-qualification-'));
+    const reportPath = path.join(reportDir, 'source-qualification.json');
+    runOrDie('release qualification (source)', process.execPath,
+      ['scripts/release-qualification.mjs', '--suite', 'source', '--report', reportPath]);
   }
-  }
-
-// B. the full brain test suite (the 60/60)
-  step('B', 'full test suite (npm test)');
-  runOrDie('npm test', 'npm', ['test']);
-
-// C. unit gates — narrative-version (tag/entity aware), claims, etc.
-  step('C', 'unit gates (vitest) — narrative version, claims, guards');
-  runOrDie('vitest unit', 'npx', ['vitest', 'run', 'tests/unit']);
 }
 
 // D. One remotely durable, staged release transaction (ADR-062 / DDD-0015). GitHub remains a draft
@@ -634,13 +593,6 @@ if (PUBLISH) {
   step('D', 'remote staged release transaction — SKIPPED (check-only; pass --publish to publish)');
 }
 
-// Check-only diagnoses the currently public channels. During publication, transaction finalization
-// performs this walk once, then creates and verifies the publication receipt before convergence.
-if (!PUBLISH) {
-  step('E', 'verify-channels — the live walk of every user path');
-  runOrDie('verify-channels', process.execPath, ['scripts/verify-channels.mjs']);
-}
-
 if (PUBLISH) {
   console.log(`\n${c.y(c.b('PUBLISHED, NOT VERIFIED'))}`);
 } else {

package/scripts/retrieval-canary.mjs

@@ -594,7 +594,7 @@ export function validateRetrievalCanaryReceipt(receipt, { plan, requireAcceptanc
 }
 
 export async function runRetrievalCanaries({ plan, sourceSha, artifactSha256, candidateArchiveSha256,
-  search, citationResolver, concurrency = 3 } = {}) {
+  search, citationResolver, concurrency = 3, searchTimeoutMs = null } = {}) {
   validateRetrievalCanaryPlan(plan);
   if (!HEX40.test(String(sourceSha || '')) || !HEX64.test(String(artifactSha256 || ''))
     || !HEX64.test(String(candidateArchiveSha256 || '')) || sourceSha !== plan.candidate.sourceSha
@@ -609,7 +609,8 @@ export async function runRetrievalCanaries({ plan, sourceSha, artifactSha256, ca
     for (let index = next++; index < plan.cases.length; index = next++) {
       const canary = plan.cases[index];
       try {
-        const rows = resultRows(await search({ query: canary.query, k: 10 }));
+        const rows = resultRows(await search({ query: canary.query, k: 10,
+          ...(Number.isFinite(searchTimeoutMs) && searchTimeoutMs > 0 ? { timeoutMs: searchTimeoutMs } : {}) }));
         const top = rows.slice(0, 10);
         const rank = top.findIndex((row) => String(row?.repo || '').toLowerCase() === canary.expected.repo
           && expectedSources(canary.expected).some((source) => row?.path === source.path));

package/scripts/review-model-defaults.mjs

@@ -0,0 +1,26 @@
+// scripts/review-model-defaults.mjs — single source for the model IDs this repo SELECTS to run its
+// own release-review and dual/tri-host deliberation pipelines (single-source contract B7, see
+// scripts/single-source-check.mjs). Every value below is copied verbatim from wherever it used to be
+// hard-coded — no ID has changed, so importing these constants changes no behavior.
+//
+// Two independent generations exist because they were pinned on different dates for different gates;
+// they are NOT the same fact and are kept as two separate exports rather than merged into one.
+
+// ── Legacy release-review pair (ADR-072 completion gate + public verification aggregate). ─────────
+// Pinned identically, and independently, in three files before this consolidation:
+// adr-072-completion.mjs (REQUIRED_REVIEWERS), independent-review-receipt.mjs
+// (ALLOWED_INDEPENDENT_REVIEWERS) and public-verification-aggregate.mjs (REQUIRED_REVIEW_MODELS).
+export const CLAUDE_FABLE_5_ID = 'claude-fable-5';
+export const GPT_5_6_SOL_ID = 'gpt-5.6-sol';
+export const LEGACY_REVIEW_MODEL_IDS = Object.freeze([CLAUDE_FABLE_5_ID, GPT_5_6_SOL_ID]);
+export const LEGACY_REVIEWER_IDENTITIES = Object.freeze([
+  Object.freeze({ identity: CLAUDE_FABLE_5_ID, model: CLAUDE_FABLE_5_ID, provider: 'firstParty' }),
+  Object.freeze({ identity: GPT_5_6_SOL_ID, model: GPT_5_6_SOL_ID, provider: 'openai' }),
+]);
+
+// ── Native subscription-CLI dual/tri-host pair, verified against the live hosts 2026-09-10/13. ─────
+// Pinned identically, and independently, in three files before this consolidation:
+// dual-host-deliberation.mjs (TOP_SUBSCRIPTION_MODELS), oracle/producer-hosts.mjs (PRODUCER_MODELS)
+// and trismart.mjs's --dry-run summary.
+export const DUAL_HOST_MODEL_IDS = Object.freeze({ claude: 'claude-fable-5-1', codex: 'gpt-6-astra' });
+export const TRI_HOST_MODEL_IDS = Object.freeze({ ...DUAL_HOST_MODEL_IDS, grok: 'grok-4.6' });

package/scripts/route-cheap.mjs

@@ -39,10 +39,23 @@ export const PRICING = {
   'deepseek/deepseek-v4-flash': { in: 0.077, out: 0.154 }, // verified 2026-07-12 OpenRouter /models live; successor to deepseek-chat (which resolves to legacy V3)
   'x-ai/grok-4.5': { in: 2.0, out: 6.0 }, // verified 2026-07-12 OpenRouter /models live; mid-priced frontier-adjacent
 };
+// Named handles for the Claude tier ids below, so every OTHER file that needs one of these ids
+// imports it by NAME instead of retyping the literal a second time (single-source contract B7 —
+// calibrate-router.mjs, dispatch-receipt.mjs, router-utilization.mjs and metaharness-receipts.mjs
+// all used to hard-code their own copies of these same strings).
+export const CLAUDE_MODEL_IDS = Object.freeze({
+  haiku: 'claude-haiku-4.5',
+  sonnet: 'claude-sonnet-5',
+  opus: 'claude-opus-4.8',
+  fable: 'claude-fable-5',
+  opus5: 'claude-opus-5',
+  opus5Fast: 'claude-opus-5-fast',
+});
+
 // Frontier = the most capable model you'd otherwise reach for. Fable 5 leads the Claude 5 family
 // (2× Opus 4.8 per token — see CLAUDE_TIERS below), so it is the honest "instead of" baseline: every
 // $ the cascade saves is measured against what Fable 5 would have cost on the same tokens.
-export const FRONTIER = { name: 'claude-fable-5', in: 10.0, out: 50.0 };
+export const FRONTIER = { name: CLAUDE_MODEL_IDS.fable, in: 10.0, out: 50.0 };
 
 // Claude tiers — $/Mtok, verified live from the OpenRouter /models API 2026-07-13.
 // These are NOT routed through here (Claude Code's own Agent/Task tool spawns them). They are priced
@@ -51,10 +64,10 @@ export const FRONTIER = { name: 'claude-fable-5', in: 10.0, out: 50.0 };
 // whole router looked unused. It WAS unused; it was also unmeasurable. Both had to be fixed.
 // The spread is the whole argument: fable-5 costs 10x haiku-4.5 for identical mechanical work.
 export const CLAUDE_TIERS = {
-  'claude-haiku-4.5': { in: 1.0, out: 5.0 },
-  'claude-sonnet-5': { in: 2.0, out: 10.0 },
-  'claude-opus-4.8': { in: 5.0, out: 25.0 },
-  'claude-fable-5': { in: 10.0, out: 50.0 },
+  [CLAUDE_MODEL_IDS.haiku]: { in: 1.0, out: 5.0 },
+  [CLAUDE_MODEL_IDS.sonnet]: { in: 2.0, out: 10.0 },
+  [CLAUDE_MODEL_IDS.opus]: { in: 5.0, out: 25.0 },
+  [CLAUDE_MODEL_IDS.fable]: { in: 10.0, out: 50.0 },
   // OPUS 5 ADDED 2026-08-08, and its absence was silently costing every receipt.
   //
   // dispatch-receipt refuses to price an unknown model ("refusing to invent savings"), which is the
@@ -67,8 +80,8 @@ export const CLAUDE_TIERS = {
   // standing rule — never recalled, never inferred from the 4.8 row:
   //     anthropic/claude-opus-5        in $5.00/Mtok  out $25.00/Mtok
   //     anthropic/claude-opus-5-fast   in $10.00/Mtok out $50.00/Mtok
-  'claude-opus-5': { in: 5.0, out: 25.0 },
-  'claude-opus-5-fast': { in: 10.0, out: 50.0 },
+  [CLAUDE_MODEL_IDS.opus5]: { in: 5.0, out: 25.0 },
+  [CLAUDE_MODEL_IDS.opus5Fast]: { in: 10.0, out: 50.0 },
 };
 
 /** Price lookup across both tables. Unknown model → null (never invent a savings number). */

package/scripts/router-utilization.mjs

@@ -20,7 +20,7 @@
 // Usage: node scripts/router-utilization.mjs [--json]
 
 import fs from 'node:fs';
-import { FRONTIER, priceOf, receiptsPath } from './route-cheap.mjs';
+import { CLAUDE_MODEL_IDS, FRONTIER, priceOf, receiptsPath } from './route-cheap.mjs';
 
 // Band = a human-legible grouping over the continuous complexity/cost axis (ADR-149: "tier_label is
 // metadata, not control flow"). The four bands mirror router-optimizer.mjs. Known models are mapped
@@ -28,15 +28,15 @@ import { FRONTIER, priceOf, receiptsPath } from './route-cheap.mjs';
 const BAND_BY_MODEL = {
   'agent-booster': 'mechanical',
   'inclusionai/ling-2.6-flash': 'cheap',
-  'claude-haiku-4.5': 'cheap',
+  [CLAUDE_MODEL_IDS.haiku]: 'cheap',
   'deepseek/deepseek-chat': 'cheap',
   'deepseek/deepseek-v4-flash': 'cheap',
   'meta-llama/llama-3.3-70b-instruct': 'mid',
   'openai/gpt-4.1': 'mid',
   'x-ai/grok-4.5': 'mid',
-  'claude-sonnet-5': 'mid',
-  'claude-opus-4.8': 'frontier',
-  'claude-fable-5': 'frontier',
+  [CLAUDE_MODEL_IDS.sonnet]: 'mid',
+  [CLAUDE_MODEL_IDS.opus]: 'frontier',
+  [CLAUDE_MODEL_IDS.fable]: 'frontier',
 };
 export const BAND_ORDER = ['mechanical', 'cheap', 'mid', 'frontier'];
 const BAND_LABEL = { mechanical: 'Mechanical', cheap: 'Cheap', mid: 'Mid', frontier: 'Frontier' };

package/scripts/rvf-generation.mjs

@@ -11,6 +11,29 @@ import path from 'node:path';
 import { getVersion, getVersionTag } from './version.mjs';
 
 export const RVF_GENERATIONS_FILE = 'RVF-GENERATIONS.json';
+export const RUNTIME_LEDGER_KIND = 'ruvnet-brain-runtime-generation-ledger';
+
+// S4 (ONE PROVENANCE RECORD) — RECONCILING THE TWO "schemaVersion 2" MEANINGS.
+//
+// Two independent writers had drifted into calling different shapes "schemaVersion 2":
+//   "Schema A" — THIS module's writeRvfGeneration wrote schemaVersion 1, no `kind`, no
+//     `sourceSnapshot`, one store touched per call (the dev-time incremental refresh ledger).
+//   "Schema B" — scripts/build-bundle.mjs's projectStoreViews independently writes
+//     `{ schemaVersion: 2, kind: 'ruvnet-brain-runtime-generation-ledger', brainVersion,
+//     releaseTag, sourceSnapshot, stores }` (the release-time ledger) — and
+//     plugin/scripts/coverage-integrity.mjs's release validation ALREADY requires exactly this
+//     shape (`schemaVersion !== 2` / `kind !== 'ruvnet-brain-runtime-generation-ledger'` are hard
+//     failures there, confirmed by reading it directly) for the tree an installed brain carries.
+// Schema B is the one kept: it is a strict superset (Schema A's per-store row shape is a subset
+// of Schema B's), and it is what the release-time validator already enforces on every installed
+// tree. Schema A is retired: writeRvfGeneration below now emits Schema B's envelope, carrying
+// `sourceSnapshot` forward from whatever the ledger already had (null until a release build sets
+// it — build-bundle.mjs's own construction is untouched and still wins at release time; this
+// module's schemaVersion bump changes nothing downstream, since nothing reads the dev-time
+// ledger's schemaVersion — verified against every consumer: validateSelectedRvfGenerations/
+// verifyRvfGenerations below check individual fields, never schemaVersion; build-bundle.mjs
+// reads the dev-time ledger via readRvfGenerations only to look up per-store rows by name, then
+// constructs ITS OWN new ledger object from scratch).
 
 export function canonicalRvfStores(dir) {
   return fs.readdirSync(dir)
@@ -42,7 +65,8 @@ export function sha256File(file) {
 export function readRvfGenerations(dir) {
   const file = path.join(dir, RVF_GENERATIONS_FILE);
   if (!fs.existsSync(file)) {
-    return { schemaVersion: 1, brainVersion: getVersion(), releaseTag: getVersionTag(), stores: {} };
+    return { schemaVersion: 2, kind: RUNTIME_LEDGER_KIND, brainVersion: getVersion(),
+      releaseTag: getVersionTag(), sourceSnapshot: null, stores: {} };
   }
   const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
   parsed.stores ||= {};
@@ -56,15 +80,22 @@ export function writeRvfGeneration({
   model,
   dimensions,
   sourceCommit = null,
+  sourceRepo = null,
+  sourceDescribe = null,
   builtUtc = new Date().toISOString(),
   previousDir = dir,
 }) {
   const rvfPath = path.join(dir, rvfFile);
   if (!fs.existsSync(rvfPath)) throw new Error(`cannot stamp missing RVF: ${rvfPath}`);
   const manifest = readRvfGenerations(previousDir);
-  manifest.schemaVersion = 1;
+  manifest.schemaVersion = 2;
+  manifest.kind = RUNTIME_LEDGER_KIND;
   manifest.brainVersion = getVersion();
   manifest.releaseTag = getVersionTag();
+  // Carried forward, never invented here: this is the git sha of the CODE checkout that
+  // assembles a release (build-bundle.mjs's projectStoreViews sets it fresh at release time).
+  // The dev-time incremental refresh this function serves does not know that value yet.
+  manifest.sourceSnapshot = manifest.sourceSnapshot ?? null;
   manifest.stores[store] = {
     file: rvfFile,
     sha256: sha256File(rvfPath),
@@ -72,12 +103,47 @@ export function writeRvfGeneration({
     model,
     dimensions,
     sourceCommit,
+    // S4 (ONE PROVENANCE RECORD): the repo identity a SOURCE.json entry needs, carried alongside
+    // the byte identity this ledger has always recorded, so SOURCE.json can be projected entirely
+    // FROM this ledger (projectSourceStore below) rather than a caller's own second copy of the
+    // same facts. Optional and omitted (not written as null) so a caller that does not pass them
+    // gets a ledger row with no dangling nulls.
+    ...(sourceRepo !== null ? { sourceRepo } : {}),
+    ...(sourceDescribe !== null ? { sourceDescribe } : {}),
     builtUtc,
   };
   fs.writeFileSync(path.join(dir, RVF_GENERATIONS_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
   return manifest.stores[store];
 }
 
+/**
+ * Project ONE SOURCE.json store entry from its ledger row — the ONE place identity fields
+ * (sourceRepo, sourceCommit, sourceDescribe, builtUtc) are read FROM the ledger rather than
+ * independently recomputed by a caller (S4: ONE PROVENANCE RECORD).
+ *
+ * Deliberately minimal: it projects ONLY the identity fields the ledger itself carries.
+ * `updater` supplies every NON-identity field a caller's SOURCE.json shape wants
+ * (canonicalManifestUrl, canonicalBundleUrl, selfUpdate, builder, updateManaged, origin, …) —
+ * spread first so identity fields read from `generation` always win, the same adapter pattern
+ * scripts/build-bundle.mjs's projectStoreViews already uses for the release-time case ("only its
+ * non-identity updater fields are borrowed per store; sourceCommit/builtUtc are always bound from
+ * the selected generation record, never independently trusted from the updater's own copy"). This
+ * function does not default those non-identity fields itself: a public-bundle store and a private
+ * overlay store want genuinely different shapes (a private store has no selfUpdate command at
+ * all, since forge-update.mjs never fetches it) — each caller states what IT needs.
+ */
+export function projectSourceStore(name, generation, updater = {}) {
+  if (!generation) throw new Error(`projectSourceStore: no ledger generation record for ${name}`);
+  return {
+    ...updater,
+    kbName: updater.kbName || name,
+    sourceRepo: generation.sourceRepo ?? updater.sourceRepo ?? null,
+    sourceCommit: generation.sourceCommit ?? null,
+    sourceDescribe: generation.sourceDescribe ?? updater.sourceDescribe ?? null,
+    builtUtc: generation.builtUtc,
+  };
+}
+
 export function verifyRvfGenerations(dir, {
   version = getVersion(),
   releaseTag = getVersionTag(),