@bongos/core 1.19.410 → 1.19.412

package/docs/modules-contract.md

@@ -54,6 +54,8 @@ A module's `module.json` declares `"coreVersion": "^1.4.0"` (a semver range). Th
 
 **Current `CORE_VERSION`:** `1.8.0`
 
+> The table below is a hand-maintained summary of the MINOR bumps only, and it lags. The authoritative, complete release ledger — every version, including the CI carrier patches — is [`docs/module-api-changelog.md`](module-api-changelog.md) ([ADR 0203](adr/<redacted>.md) moved it out of `src/module-api.js`); the live value is the `const CORE_VERSION` literal in `src/module-api.js`.
+
 | Bump | What it added |
 |---|---|
 | 1.0.0 | Initial doorway: auth gates, pool accessor, config/branding, seams. |

package/docs/recipes/core-release-pipeline.md

@@ -72,7 +72,7 @@ Three steps. The first two are ordinary claimed work; only the publish (2c) is o
 
 ### 2a. Bump `CORE_VERSION` — the step with no automation behind it
 
-`CORE_VERSION` lives in [`src/module-api.js`](../../src/module-api.js) and is bumped **by hand, inside a claimed task**, with a changelog line in the same file. It is never auto-bumped: the version's provenance stays in git history + changelog ([ADR 0137](../adr/<redacted>.md) §2).
+`CORE_VERSION` lives in [`src/module-api.js`](../../src/module-api.js) and is bumped **by hand, inside a claimed task**, with an entry appended to the release ledger [`docs/module-api-changelog.md`](../module-api-changelog.md) in the same commit. (The ledger used to be a comment block inside `module-api.js`; appending to it there on every CI release grew the file past the oversized-file fitness ratchet and broke `unit` on `main` — [ADR 0203](../adr/<redacted>.md).) The version's provenance stays in git history + ledger ([ADR 0137](../adr/<redacted>.md) §2).
 
 Semver here is not decoration — it decides **who receives the change automatically** ([ADR 0136](../adr/<redacted>.md)):
 
@@ -82,7 +82,7 @@ Semver here is not decoration — it decides **who receives the change automatic
 | **minor** — an added export / additive surface | ❌ **invisible to them** | ✅ |
 | **major** — never automatic for anyone | ❌ | ❌ |
 
-The practical trap: a **MINOR is silently withheld from every patch-only instance**, which is the default channel. If a fix must reach the fleet, it belongs behind a *patch* bump — so an additive export shipped alongside a needed fix will strand that fix. The changelog convention is to justify the level explicitly ("the doorway surface is byte-identical to X, so despite the volume this is → PATCH").
+The practical trap: a **MINOR is silently withheld from every patch-only instance**, which is the default channel. If a fix must reach the fleet, it belongs behind a *patch* bump — so an additive export shipped alongside a needed fix will strand that fix. The ledger convention is to justify the level explicitly ("the doorway surface is byte-identical to X, so despite the volume this is → PATCH").
 
 **A bump is mandatory even for a one-file fix.** `bongos upgrade` refuses an equal version, and npm rejects a duplicate — a natural guard, and the reason "carrier bumps" exist to sweep up commits that landed with no bump behind them.
 
@@ -99,7 +99,7 @@ node scripts/gds/package-core.js --ref main --self-verify
 
 ### 2c. Publish — automatic on merge
 
-**Every merge to `main` publishes** ([ADR 0161](../adr/<redacted>.md), superseding ADR 0137's manual gate): once the required `unit` check succeeds on a main push, the `publish` workflow auto-bumps a **patch** if nobody bumped (via `scripts/gds/bump-version.js`, changelog line included), builds through the fail-closed no-leak gate with `--self-verify`, publishes, and tags `core-v<version>`. A **minor/major is still a human in-task bump** — CI never makes that call, because it decides what patch-channel subscribers receive unattended.
+**Every merge to `main` publishes** ([ADR 0161](../adr/<redacted>.md), superseding ADR 0137's manual gate): once the required `unit` check succeeds on a main push, the `publish` workflow auto-bumps a **patch** if nobody bumped (via `scripts/gds/bump-version.js`, which writes the literal AND appends the ledger entry to [`docs/module-api-changelog.md`](../module-api-changelog.md) — ADR 0203; the carrier commit stages both), builds through the fail-closed no-leak gate with `--self-verify`, publishes, and tags `core-v<version>`. A **minor/major is still a human in-task bump** — CI never makes that call, because it decides what patch-channel subscribers receive unattended.
 
 The lane is armed by the owner via the `PUBLISH_ON_MERGE=1` repo variable + two secrets (`NPM_TOKEN`, `RELEASE_PUSH_TOKEN`); while disarmed it no-ops loudly. Manual fallback, same command CI runs:
 

package/docs/recipes/private-npm-distribution.md

@@ -55,7 +55,7 @@ npm publish ./clients/bongos-client               # real (publishConfig makes it
 
 The steps below remain as the **manual fallback** (lane disarmed, npm outage, or a deliberate out-of-band release):
 
-1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and add a one-line changelog entry in the same file. This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + changelog.
+1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and append an entry to the release ledger [`docs/module-api-changelog.md`](../module-api-changelog.md) in the same commit ([ADR 0203](../adr/<redacted>.md) moved that ledger out of `module-api.js`). This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + ledger.
 2. **Publish** (owner, from a clean checkout of the released commit):
    ```sh
    node scripts/gds/package-core.js --publish        # DRY-RUN: runs the fail-closed no-leak gate, previews @bongos/core@<version>

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.410",
+  "version": "1.19.412",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.410",
+      "version": "1.19.412",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.410",
+  "version": "1.19.412",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/bump-version.js

@@ -4,10 +4,19 @@
 //
 // WHY THIS EXISTS. ADR 0161 makes every merge to main publishable: when a merge
 // lands without a human version bump, CI bumps a PATCH itself so the release
-// has a unique version. The bump edits src/module-api.js in the two places the
-// repo's version discipline lives — the `const CORE_VERSION` literal and the
-// changelog comment block above it — because a bare literal change with no
-// changelog line is exactly the drift the discipline exists to prevent.
+// has a unique version. The bump writes the two places the repo's version
+// discipline lives — the `const CORE_VERSION` literal in src/module-api.js and
+// the release ledger in docs/module-api-changelog.md — because a bare literal
+// change with no changelog line is exactly the drift the discipline prevents.
+//
+// WHERE THE LEDGER LIVES (ADR 0203). It used to be a comment block directly
+// above the literal, in src/module-api.js. Appending two lines there on EVERY
+// release grew that file past the 1500-line oversized-file fitness ratchet, and
+// because this lane pushes straight to main it broke the very `unit` gate it
+// rides behind — for main and for every open PR at once. The ledger is now a
+// markdown file, which `git ls-files '*.js'` never counts, so it can grow
+// forever. The INSERTION CONTRACT is unchanged: entries stay oldest-first and
+// each new one goes immediately above the divider that closes the ledger.
 //
 // POLICY (deliberately narrow): this script only ever bumps PATCH. A MINOR or
 // MAJOR is a statement about the doorway surface that only a human (or a far
@@ -19,7 +28,7 @@
 //
 // Usage:
 //   node scripts/gds/bump-version.js                # dry-run: print the plan
-//   node scripts/gds/bump-version.js --apply        # rewrite src/module-api.js
+//   node scripts/gds/bump-version.js --apply        # rewrite both files
 //   node scripts/gds/bump-version.js --apply --note "run 123456"  # extra provenance
 // stdout (both modes): one JSON line { from, to, applied } for CI to capture.
 
@@ -29,35 +38,45 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const TARGET = path.join(__dirname, '..', '..', 'src', 'module-api.js');
+// The release ledger (ADR 0203) — markdown, so the .js line ratchet never counts it.
+const CHANGELOG = path.join(__dirname, '..', '..', 'docs', 'module-api-changelog.md');
 const CONST_RE = /^const CORE_VERSION = '(\d+)\.(\d+)\.(\d+)';.*$/m;
-// The changelog block's closing divider sits immediately above the const line.
-const DIVIDER = '// ---------------------------------------------------------------------------';
+// The ledger's closing divider — the last line inside its fenced block, and the
+// insertion anchor each new entry goes immediately above. Same 75-dash rule the
+// comment block used, minus the `// ` that made it a JS comment.
+const DIVIDER = '---------------------------------------------------------------------------';
 
-// Pure transform: (source text, optional note) -> { from, to, text }.
+// Pure transform: (module-api source, { note, changelog }) -> { from, to, text,
+// changelogText }. Pass the ledger's current text as `changelog` to get the
+// entry appended too; omit it to bump the literal alone (the unit tests do).
 // Throws with a precise message on any shape it does not recognize — a silent
 // mis-edit of the version literal is the worst possible failure mode here.
-function bumpPatch(src, { note = '' } = {}) {
+function bumpPatch(src, { note = '', changelog = null } = {}) {
   const m = src.match(CONST_RE);
   if (!m) throw new Error(`bump-version: could not find the CORE_VERSION literal in ${TARGET} (expected: const CORE_VERSION = 'x.y.z';)`);
   const [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])];
   const from = `${major}.${minor}.${patch}`;
   const to = `${major}.${minor}.${patch + 1}`;
 
-  // 1. The changelog entry — inserted just above the divider that closes the
-  //    changelog block, matching the existing two-line entry style.
-  const constLineStart = src.search(CONST_RE);
-  const dividerStart = src.lastIndexOf(DIVIDER, constLineStart);
-  if (dividerStart === -1) throw new Error('bump-version: could not find the changelog closing divider above CORE_VERSION');
-  const noteSuffix = note ? ` ${note}.` : '';
-  const entry =
-    `//   ${to} — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges\n` +
-    `//         landed since ${from} with no explicit bump.${noteSuffix} (task 1002620)\n`;
+  // 1. The literal — same line shape deploy-divergence greps for.
+  const newConstLine = `const CORE_VERSION = '${to}'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md`;
+  const text = src.replace(CONST_RE, newConstLine);
 
-  // 2. The literal — same line shape deploy-divergence greps for.
-  const newConstLine = `const CORE_VERSION = '${to}'; // CI auto-patch carrier (ADR 0161); see changelog above`;
+  // 2. The ledger entry — inserted just above the divider that closes the
+  //    ledger, keeping the historic two-line entry style byte-for-byte (the
+  //    old `//   ` / `//         ` comment prefixes minus the `// ` marker).
+  let changelogText = null;
+  if (changelog !== null) {
+    const dividerStart = changelog.lastIndexOf(DIVIDER);
+    if (dividerStart === -1) throw new Error(`bump-version: could not find the changelog closing divider in ${CHANGELOG} — the ledger's insertion anchor is gone (ADR 0203)`);
+    const noteSuffix = note ? ` ${note}.` : '';
+    const entry =
+      `  ${to} — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges\n` +
+      `        landed since ${from} with no explicit bump.${noteSuffix} (task 1002620)\n`;
+    changelogText = changelog.slice(0, dividerStart) + entry + changelog.slice(dividerStart);
+  }
 
-  const text = src.slice(0, dividerStart) + entry + src.slice(dividerStart).replace(CONST_RE, newConstLine);
-  return { from, to, text };
+  return { from, to, text, changelogText };
 }
 
 function main() {
@@ -65,10 +84,19 @@ function main() {
   const noteIdx = process.argv.indexOf('--note');
   const note = noteIdx !== -1 ? (process.argv[noteIdx + 1] || '') : '';
 
+  // Read and transform BOTH files before writing EITHER: a half-applied bump
+  // (literal moved, ledger silent) is precisely the drift this script exists
+  // to prevent, and it would be committed and pushed to main before anyone saw it.
   const src = fs.readFileSync(TARGET, 'utf8');
-  const { from, to, text } = bumpPatch(src, { note });
-  if (apply) fs.writeFileSync(TARGET, text);
-  else console.error(`bump-version: would bump ${from} → ${to} (dry-run; pass --apply to write)`);
+  const changelog = fs.readFileSync(CHANGELOG, 'utf8');
+  const { from, to, text, changelogText } = bumpPatch(src, { note, changelog });
+  if (changelogText === null) throw new Error('bump-version: the ledger was not rewritten — refusing to write a versionless release');
+  if (apply) {
+    fs.writeFileSync(TARGET, text);
+    fs.writeFileSync(CHANGELOG, changelogText);
+  } else {
+    console.error(`bump-version: would bump ${from} → ${to} in ${TARGET} + ${CHANGELOG} (dry-run; pass --apply to write)`);
+  }
   console.log(JSON.stringify({ from, to, applied: apply }));
 }
 

package/scripts/gds/deploy-divergence.js

@@ -246,7 +246,7 @@ function report(r, { quiet = false } = {}) {
       ? ` (${u.countWithMerges} counting merges)` : '';
     say(`  ⚠ UNRELEASED — ${u.count} work commit${u.count === 1 ? '' : 's'}${merges} on ${r.mainRef} since the last CORE_VERSION bump.`);
     say('    No instance can take these at ANY pin: no published version contains them.');
-    say(`    Fix: bump CORE_VERSION in src/module-api.js (+ a changelog line) and land it.`);
+    say(`    Fix: bump CORE_VERSION in src/module-api.js (+ an entry in docs/module-api-changelog.md) and land it.`);
   }
   if (r.behind) {
     say(`  ⚠ UNDEPLOYED — live is ${r.live.coreVersion}, main declares ${r.onMain}.`);

package/scripts/gds/publish-manifest.js

@@ -104,6 +104,12 @@ const PUBLISH_ALLOWLIST = [
   'docs/api/openapi.json',           // the generated OpenAPI 3.1 spec served at /docs/openapi.json
   'docs/api-reference.md',           // the markdown API reference
   'docs/modules-contract.md',
+  // The doorway's release ledger (ADR 0203). It USED TO ship inside
+  // src/module-api.js as a comment block, so an instance that installs
+  // @bongos/core has always received it; omitting it here would silently drop
+  // the history from the package at the next release. A module author checking
+  // what a `coreVersion` floor actually buys them reads exactly this file.
+  'docs/module-api-changelog.md',
   'docs/branding-contract.md',
   'docs/branding-fill-prompt.md',
   // RUNTIME DATA that happens to live under docs/, not documentation (ADR 0178).

package/src/bongos/module-scope-map.js

@@ -52,7 +52,12 @@ const MODULE_GLOBS = {
     'src/bongos/repo-info.js', 'src/bongos/api-path-404.js', 'src/bongos/serve-internal.js',
     'src/bongos/module-scope-map.js', 'src/bongos/hierarchy-config.js',
     'src/instance-config.js', 'src/branding.js', 'src/modules.js',
-    'src/module-api.js', 'src/module-loader/',
+    // The doorway and its release ledger travel together: since ADR 0203 the
+    // CORE_VERSION changelog is a separate markdown file, so a kernel-scoped
+    // goal authoring a version bump touches BOTH. Enumerated like copy-desk's
+    // docs/ artifacts below — without it, scopeSubset() denies the ledger as
+    // out_of_scope and a hand-cut MINOR/MAJOR cannot be authored at all.
+    'src/module-api.js', 'docs/module-api-changelog.md', 'src/module-loader/',
     // security-the-PROPERTY: the threat-model (/security/adr) + Archon-only
     // exploit-detail engagement-doc store (/security/docs). Stays kernel when the
     // red-team FEATURE carved to modules/security/ (BV1.R79 / 02-module-map §5).