@bongos/core 1.19.681 → 1.19.682

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.681",
-  "core_contract": "1.19.681",
-  "source_commit": "e31ae913044e78d0b2b8202995eb551dad418a9e",
+  "core_version": "1.19.682",
+  "core_contract": "1.19.682",
+  "source_commit": "b499e76b5b34ee8e7e753b7b89a3f6e1e8874224",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T02:05:45.659Z",
+  "built_at": "2026-09-12T16:22:24.694Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 476,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2624,
-  "tree_sha256": "f249c4df05688bdb744709b348940982241ccc686471029262564d9b79bdd140",
+  "tree_sha256": "a8aca2d995556a722b4debefe87ae388610d584d4954da4285b7dbf0a642eef4",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -322,7 +322,7 @@
     {
       "path": ".gitattributes",
       "mode": "0000644",
-      "sha256": "72bc38b553e34bc652f0b5b5b2ab24999b4b11c2d6fc3699489e157fd0127a11"
+      "sha256": "38bf33dd14a7bff6545f961c4f30172ac850f6a0578900a3c10295c4fc0f27e9"
     },
     {
       "path": "CLAUDE.md",
@@ -2797,7 +2797,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "244cffb195592c644ad06262ed1a0f610e7744fd62e634a35c5cddd954c9def6"
+      "sha256": "1f62636e946a5b5bbf9b546d2e532b704db15ca21c3a9d0e71f5a8b17cde150b"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5642,7 +5642,7 @@
     {
       "path": "modules/lifecycle/conflict-resolve.js",
       "mode": "0000644",
-      "sha256": "1a281a4233b3805550a05ed6bd38b163ab18db658d48675f055b90d2ba722a16"
+      "sha256": "3e20f4965d1d83d17f8e777201bd7e4fd7857843295180542914de16ae51e936"
     },
     {
       "path": "modules/lifecycle/criterion-suggest.js",
@@ -7777,12 +7777,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "fd92e4204b64289d8404adb924c9142b47c10b0a6c73d709583cbbad01cd6e0a"
+      "sha256": "db81ab75a6e749de67b91e13f3605d79a58a90b2e57c83332f535d48273dabcb"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "242ae038fbdb23f8d375f04e794c87100df9df4c250b93942ca4eaed82017ca3"
+      "sha256": "f4d50516d2a3a9ee031a89735502c1c8ec01789eeb4dfa3fd20da07713679279"
     },
     {
       "path": "public-docs/index.html",
@@ -8282,7 +8282,7 @@
     {
       "path": "scripts/gds/gen-api-client.js",
       "mode": "0000644",
-      "sha256": "d363c76caf379a051faea40a2497db8bbba18effd68e9cd9922e9445638c57c5"
+      "sha256": "2d8b35709e19b339bc55c57237f2add36fa6bdeb83a9b036faa902b0c4b8e3f9"
     },
     {
       "path": "scripts/gds/gen-api-docs.js",
@@ -8332,7 +8332,7 @@
     {
       "path": "scripts/gds/git-merge-regen.js",
       "mode": "0000644",
-      "sha256": "9896dc201aaa7186838fe4dcecf5226fdb0736b1b7094a98649e2f8fcbfc4d1a"
+      "sha256": "9d65420d85f20d10dba3af63c45d8dd0425ee11dd3d5cfa14d3019abf7354aed"
     },
     {
       "path": "scripts/gds/go-live.js",
@@ -8372,7 +8372,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "1d63c1485820ad2e81e97979402eabd3829e86503f4c06318a251dc3a6874047"
+      "sha256": "b0971625852fca93ca474d2f9e31e3601397f1b9efbef3241a0b0c47f17d925f"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -9112,7 +9112,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "642d0ade55c203d6b07478a07d3c21c26fa4635dc8a92e4fe989434e635abbbb"
+      "sha256": "4f30ee3036846f449f6fc8143da32b3767376352743d373c39ace2f50f66e913"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9142,7 +9142,7 @@
     {
       "path": "scripts/gds/worktree.js",
       "mode": "0000644",
-      "sha256": "56549d4c288f55699ceb1fea10f4f65756a9114b4628b3f2b6c44fed0ec6ab26"
+      "sha256": "849cd462b9c50866ca1582ed2156fb68ac76699c8270796d1daf6942c09713dc"
     },
     {
       "path": "scripts/hall-preview/README.md",
@@ -9542,7 +9542,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b06c931aa58a7997f7733e13d2850d290540647c4a7d243cc07d27c20d5b812e"
+      "sha256": "9f875091ba63a70601a61a1d486f5b561026167aa524bd371e457c9a93c2635c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10212,7 +10212,7 @@
     {
       "path": "tests/conflict_resolve.mjs",
       "mode": "0000644",
-      "sha256": "e36410c3288ec8c38c22bd5fd285d7abc6e0cadc4433ce87028bb7f9c7d54806"
+      "sha256": "da8182c4235c7735bdee351cfa7dc1146f7ded33b9d594dc0ba498a3b5206d83"
     },
     {
       "path": "tests/connections_api.mjs",
@@ -10642,7 +10642,7 @@
     {
       "path": "tests/git_merge_regen.mjs",
       "mode": "0000644",
-      "sha256": "52f02bc7f0da86b29d4b39da78a34f9677f7bdd93e24a4e5365ffb1af64fc413"
+      "sha256": "a55ae255245a53429cc7948e35ea0515bf58307f826d605d6ffd52cc60196ef8"
     },
     {
       "path": "tests/github_push_ancestry.mjs",
@@ -12987,7 +12987,7 @@
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "106735a9ab28b4a23e2f25269030d982798da3fa39e31d40a1ec78277ac971bc"
+      "sha256": "492b9dc7efdd6f63b81f1662d5fdc9a7541b7f8ccc6c0ec77a456ad3f574ee74"
     },
     {
       "path": "tests/upgrade_persist_pin.mjs",

package/.gitattributes

@@ -112,6 +112,34 @@ src/bongos/routes/CLAUDE.md   merge=otb-regen
 docs/copy-registry.json    merge=otb-regen
 docs/copy-inventory.md     merge=otb-regen text eol=lf
 
+# Generated API contract + client (task 1003537). gen-api-docs.js writes the first
+# three of these wholesale from a scan of the route files; gen-api-client.js writes the
+# six client files wholesale from that spec. Nothing is hand-authored in any of the
+# nine, so they are the same whole-file shape as docs/session-log-index.md above — and
+# any branch that adds or changes a route regenerates all nine differently and conflicts
+# on ordinary text. Measured on task 1002334: main took 41 commits in 3 hours and four
+# consecutive merge -> regenerate -> reship cycles each lost the race to a fresh conflict
+# in exactly these files, with a PASSING grade the whole time. REGENERABLE in
+# git-merge-regen.js carries the matching rules, and tests/git_merge_regen.mjs pins the
+# two lists as one set.
+#
+# EVERY PATH IS LISTED EXPLICITLY -- deliberately no `clients/bongos-client/*` glob, for
+# two independent reasons. The lockstep test compares these tokens against REGENERABLE as
+# literal path strings, and the driver is handed git's %P, so a glob would match nothing
+# on either side. And clients/bongos-client/examples/hello-world.mjs is HAND-WRITTEN (the
+# generator owns only the six files below): a glob that captured it would route it through
+# a driver that has no rule for it, forcing a conflict git would otherwise merge cleanly --
+# the same trap the leading slash on /CLAUDE.md above exists to avoid.
+docs/api/openapi.json         merge=otb-regen
+docs/api-reference.md         merge=otb-regen
+docs/routes-permissions.md    merge=otb-regen
+clients/bongos-client/index.mjs               merge=otb-regen
+clients/bongos-client/index.cjs               merge=otb-regen
+clients/bongos-client/bongos-client.global.js merge=otb-regen
+clients/bongos-client/index.d.ts              merge=otb-regen
+clients/bongos-client/package.json            merge=otb-regen
+clients/bongos-client/README.md               merge=otb-regen
+
 # Append-only index tables (task 1385 / ADR 0082). docs/adr/README.md is a
 # hand-maintained ADR index whose ONLY recurring conflict is two branches each
 # appending a new row — there is no generator to regen it from, so `otb-regen`

package/docs/module-api-changelog.md

@@ -1821,5 +1821,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.679 with no explicit bump. run 34665216511. (task 1002620)
   1.19.681 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.680 with no explicit bump. run 34666648354. (task 1002620)
+  1.19.682 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.681 with no explicit bump. run 34704993368. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/conflict-resolve.js

@@ -311,6 +311,19 @@ const GENERATOR_SCRIPTS = [
   // burned the attempt cap, and announceStrand flagged the task needs_rebase
   // (PR #536 / task 1003544).
   'scripts/gds/copy-inventory.js',
+  // task 1003537: the generated API contract + client. gen-api-docs.js writes
+  // docs/api/openapi.json + docs/api-reference.md + docs/routes-permissions.md from a
+  // scan of the route files; gen-api-client.js then writes the six
+  // clients/bongos-client files FROM that spec. Both are `--check` gates on the merge
+  // ref, so the same trap copy-inventory.js fell into applies verbatim: covered by the
+  // merge driver, regenerated by nobody, and the resulting staleness reported as
+  // `no_regen_diff` — "a real check failure" — rather than as drift.
+  //
+  // ORDER IS LOAD-BEARING: gen-api-client.js reads docs/api/openapi.json off disk, so
+  // it must run AFTER gen-api-docs.js has rewritten it for the merged tree. This list
+  // is walked in order, one await at a time, which is what makes that safe.
+  'scripts/gds/gen-api-docs.js',
+  'scripts/gds/gen-api-client.js',
 ];
 
 // Run the CLONE's generator scripts in WRITE mode against the merged working tree.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.681",
+  "version": "1.19.682",
   "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/gen-api-client.js

@@ -487,8 +487,13 @@ function renderReadme(spec, ops) {
   ].join('\n');
 }
 
-function build() {
-  const spec = JSON.parse(fs.readFileSync(SPEC_PATH, 'utf8'));
+// injectedSpec (task 1003537): the otb-regen merge driver regenerates this client
+// DURING a merge, when docs/api/openapi.json on disk may be the conflicted file git has
+// just written markers into — JSON.parse would throw on it. Passing a spec built in
+// memory keeps the heal working and keeps the client consistent with the api-reference.md
+// the same merge resolves. Omitted everywhere else, so the CLI path is unchanged.
+function build(injectedSpec) {
+  const spec = injectedSpec || JSON.parse(fs.readFileSync(SPEC_PATH, 'utf8'));
   const ops = buildModel(spec);
   const esm = renderClientJs(spec, ops);
   return {

package/scripts/gds/git-merge-regen.js

@@ -54,9 +54,40 @@ const G = require('./gen-repo-map');
 const FM = require('./gen-file-map');
 const SI = require('./gen-session-index');
 const CI = require('./copy-inventory');
+// gen-api-docs / gen-api-client are required LAZILY, inside the two rules that use them —
+// deliberately NOT here (task 1003537). gen-api-docs pulls src/bongos/routes/_helpers.js
+// for its LIMITS caps, and ship.js requires this module, so an eager require put a server
+// route file into the boot of every `bongos` subcommand. tests/module_api_lazy.mjs catches
+// exactly that. require() is cached, so the merge path pays the load once and the CLI
+// path never pays it at all.
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
+// The generated API contract (task 1003537). gen-api-docs.js writes all three of these
+// wholesale from a scan of the route files, so one build() call answers whichever of
+// them git hands us.
+const API_DOC_FILES = new Set([
+  'docs/api/openapi.json',
+  'docs/api-reference.md',
+  'docs/routes-permissions.md',
+]);
+
+// The generated client (task 1003537), written wholesale from the spec by
+// gen-api-client.js. These six names mirror the keys of its build().files; the
+// lockstep is asserted in tests/git_merge_regen.mjs rather than derived here, because
+// deriving it would mean running the generator at require time. NOTE what is absent:
+// clients/bongos-client/examples/hello-world.mjs is hand-written and must stay out of
+// this set, or the driver would force a conflict on a file git can merge by itself.
+const API_CLIENT_DIR = 'clients/bongos-client';
+const API_CLIENT_FILES = new Set([
+  'index.mjs',
+  'index.cjs',
+  'bongos-client.global.js',
+  'index.d.ts',
+  'package.json',
+  'README.md',
+].map((n) => `${API_CLIENT_DIR}/${n}`));
+
 // The files this driver knows how to regenerate. docs/repo-map.md and
 // docs/session-log-index.md are whole-file; each NESTED_DIRS CLAUDE.md is
 // hand-written prose with one generated block; docs/file-map.md is hand-written
@@ -73,6 +104,10 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..');
 // that each add a session-log file regenerate that block differently and ALWAYS conflict
 // there, and nothing healed it: the driver did not know the file, and `merge=union` would be
 // wrong for prose. Same shape as docs/file-map.md (3-way-merge the prose, re-render the block).
+// task 1003537: the two API sets above are spread in whole — every one of those nine files
+// is generated end to end, so they take the docs/repo-map.md path (ignore all three merge
+// sides, rebuild). They are named up there rather than inline here because the rules below
+// test set membership, and tests/git_merge_regen.mjs cross-checks them against .gitattributes.
 const REGENERABLE = new Set([
   'CLAUDE.md',
   'docs/repo-map.md',
@@ -81,6 +116,8 @@ const REGENERABLE = new Set([
   'docs/copy-inventory.md',
   'docs/copy-registry.json',
   ...G.NESTED_DIRS.map((d) => `${d}/CLAUDE.md`),
+  ...API_DOC_FILES,
+  ...API_CLIENT_FILES,
 ]);
 
 // A line that begins with a git conflict marker. If any survives our resolution,
@@ -137,6 +174,33 @@ function regenerateResolved(relpath, { base = '', ours = '', theirs = '' } = {})
     return { content: CI.renderReport(CI.buildRegistry()), ok: true };
   }
 
+  // The generated API contract (task 1003537): gen-api-docs.js writes openapi.json,
+  // api-reference.md and routes-permissions.md wholesale from a scan of the route files
+  // — nothing hand-authored in any of them — so like docs/repo-map.md below they ignore
+  // all three merge sides and rebuild. One build() yields all three; take the one asked
+  // for. This is the rule that ends the task-1002334 stall, where four merge → reship
+  // cycles each lost the race to a fresh textual conflict in exactly these files.
+  if (API_DOC_FILES.has(relpath)) {
+    const AD = require('./gen-api-docs'); // lazy — see the require block up top
+    const f = AD.build().files.find((x) => x.rel === relpath);
+    return { content: f.content, ok: true };
+  }
+
+  // The generated client (task 1003537): gen-api-client.js renders all six files from
+  // the spec, so it heals the same way. Hand it a FRESHLY BUILT spec instead of letting
+  // build() read docs/api/openapi.json off disk — mid-merge that file is very often the
+  // one git has just written conflict markers into, and JSON.parse would throw on them
+  // (an uncaught throw here exits non-zero, which git reads as "unresolved", so the
+  // failure would be a silent fallback to a textual conflict on the very files this
+  // rule exists to heal). Rebuilding also keeps the client consistent with the
+  // api-reference.md the same merge is healing.
+  if (API_CLIENT_FILES.has(relpath)) {
+    const AD = require('./gen-api-docs');   // lazy — see the require block up top
+    const AC = require('./gen-api-client'); // lazy — same reason
+    const { files } = AC.build(AD.buildOpenapi(AD.extractModel()));
+    return { content: files[relpath.slice(API_CLIENT_DIR.length + 1)], ok: true };
+  }
+
   // The ROOT CLAUDE.md (task 1001431): hand-written prose carrying ONE generated block, the
   // §13 session-log snippet. 3-way-merge the prose, then re-render the snippet from the
   // session-log files on disk. Must be handled BEFORE the nested-CLAUDE.md fallthrough below,

package/scripts/gds/init.js

@@ -943,7 +943,7 @@ async function main(argv) {
       console.error(`init: could not derive the core version from ${path.basename(tgz)} — expected a tarball named ${upgrade.ARTIFACT}-<version>.tgz (produced by \`node scripts/gds/package-core.js\`).`);
       return 1;
     }
-    const vendorRel = path.join('vendor', `${upgrade.ARTIFACT}-${version}.tgz`);
+    const vendorRel = upgrade.vendorRelFor(version);
     coreDep = `file:${vendorRel}`;
     vendorPlan = { tgz, version, vendorRel };
   }

package/scripts/gds/upgrade.js

@@ -34,6 +34,16 @@ const { writeNpmrc, hasNpmToken, resolveNpmToken } = require('./npmrc'); // ADR
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
+// WHERE THE VENDORED TARBALL SITS, as a package.json `file:` specifier — and the reason
+// this is not a path.join(). The same string is spent two ways: it is joined onto an
+// absolute dir for an fs check (path.join normalises a forward slash on every platform,
+// so that direction is free), and it is WRITTEN INTO package.json as `file:<vendorRel>`.
+// npm specifiers are POSIX. A path.join() here emits `file:vendor\\bongos-core-x.y.z.tgz`
+// on a Windows builder's machine, and that pin is then COMMITTED to the instance repo —
+// where the provisioner runs `npm ci` on Linux and reads a literal backslash in the
+// filename. One copy, POSIX by construction, so a scaffold cannot be platform-stamped
+// by the box that happened to run the scaffolder (task 1003839).
+function vendorRelFor(version) { return path.posix.join('vendor', `${ARTIFACT}-${version}.tgz`); }
 
 // ---- pure helpers (no I/O side effects beyond the injected fs) --------------
 
@@ -245,7 +255,7 @@ function vendorTarball({ instanceDir, fromTgz, targetVersion }, fsImpl = fs) {
   if (fsImpl.existsSync(fromManifest)) {
     fsImpl.copyFileSync(fromManifest, path.join(vendorDir, `${ARTIFACT}-${targetVersion}.manifest.json`));
   }
-  return path.join('vendor', destName);
+  return path.posix.join('vendor', destName);
 }
 
 // Lightweight module-compat pre-check reusing module.js against the TARGET core version. Best-effort:
@@ -940,10 +950,10 @@ async function runUpgrade(opts, deps = {}) {
     if (!dryRun) { writeNpmrc(instanceDir, { fsImpl, overwrite: false, log }); snapshot = { prevPin, prevVersion: fromVersion }; }
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${dryRun ? ' + write an env-fed .npmrc' : ''}${prevPin ? `  (was ${prevPin})` : ''}`);
   } else {
-    let vendorRel = opts.pinPath || (opts.from ? null : path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`));
+    let vendorRel = opts.pinPath || (opts.from ? null : vendorRelFor(targetVersion));
     if (opts.from) {
       if (!fsImpl.existsSync(opts.from)) return { ok: false, error: `--from tarball not found: ${opts.from}` };
-      if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = path.join('vendor', `${ARTIFACT}-${targetVersion}.tgz`); }
+      if (dryRun) { log(`  [dry-run] would vendor ${opts.from} → vendor/${ARTIFACT}-${targetVersion}.tgz`); vendorRel = vendorRelFor(targetVersion); }
       else vendorRel = vendorTarball({ instanceDir, fromTgz: path.resolve(opts.from), targetVersion }, fsImpl);
     }
     if (!fsImpl.existsSync(path.join(instanceDir, vendorRel)) && !dryRun) {
@@ -1225,7 +1235,7 @@ module.exports = {
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
   vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity, resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth, deriveVersionUrl, pollServedVersion,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
-  CORE_PKG, ARTIFACT,
+  CORE_PKG, ARTIFACT, vendorRelFor,
 };
 
 if (require.main === module) {

package/scripts/gds/worktree.js

@@ -31,6 +31,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
+const { registerMergeDriver, MERGE_DRIVER_NAME } = require('./install-git-hooks');
 
 // -- pure helpers (exported for tests/worktree_helper.mjs) --------------------
 
@@ -145,6 +146,25 @@ function cmdAdd(root, argv) {
     process.exit(1);
   }
 
+  // Register the otb-regen merge driver (task 1003537). .gitattributes routes the
+  // generated files through it, but git honours that ONLY where merge.otb-regen.driver is
+  // configured — which install-git-hooks.js does per CLONE, on /builder-setup. A builder
+  // who never ran the installer got a silent TEXTUAL merge of files no textual merge can
+  // resolve: measured on task 1002334, a scripts/gds/CLAUDE.md symbol block matching
+  // neither generator, clean enough that nothing flagged it until fitness ran in CI.
+  // Worktree-per-claim is the default path to a new tree, so doing it here is what closes
+  // that gap for a clone whose owner never ran setup. git config is shared with every
+  // linked worktree, so registering against the main root covers this tree and all later
+  // ones. Idempotent, and best-effort on purpose: failing to register only restores the
+  // pre-existing fallback-to-conflict behaviour, which must never fail `worktree add`.
+  const driver = registerMergeDriver(root);
+  if (driver.ok) {
+    console.log(`  merge driver '${MERGE_DRIVER_NAME}' registered (generated files auto-regenerate on merge)`);
+  } else {
+    console.log(`  ⚠ could not register the '${MERGE_DRIVER_NAME}' merge driver: ${driver.error}`);
+    console.log('    (generated files will merge textually here; ship.js still self-heals the same set)');
+  }
+
   if (needsJunction({ wtPath, repoRoot: root, platform: process.platform })) {
     const target = path.join(root, 'node_modules');
     if (!fs.existsSync(target)) {

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.681'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.682'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/conflict_resolve.mjs

@@ -562,6 +562,19 @@ test('1003546 every REGENERABLE artifact has a producer, and every producer is i
     [CI.REGISTRY_REL, 'scripts/gds/copy-inventory.js'],
     [CI.REPORT_REL, 'scripts/gds/copy-inventory.js'],
     ...G.NESTED_DIRS.map((d) => [`${d}/CLAUDE.md`, 'scripts/gds/gen-repo-map.js']),
+    // task 1003537 — the generated API contract + client joined REGENERABLE. Mapped by
+    // PATH PREFIX rather than by calling the generators: this suite deliberately sets
+    // *_INSTANCE_ROOT (see the env-hardening case above), which repoints their docs root
+    // at a fake server checkout, so a build() here reads a file that does not exist.
+    // Nothing is lost by not running them — drift between REGENERABLE and what they
+    // actually write is pinned by tests/git_merge_regen.mjs case 11, and a future entry
+    // under either prefix is picked up here automatically.
+    ...[...regen.REGENERABLE]
+      .filter((p) => p.startsWith('docs/api/') || p === 'docs/api-reference.md' || p === 'docs/routes-permissions.md')
+      .map((p) => [p, 'scripts/gds/gen-api-docs.js']),
+    ...[...regen.REGENERABLE]
+      .filter((p) => p.startsWith('clients/bongos-client/'))
+      .map((p) => [p, 'scripts/gds/gen-api-client.js']),
   ]);
 
   for (const p of regen.REGENERABLE) {

package/tests/git_merge_regen.mjs

@@ -28,6 +28,12 @@
 //      the merge's OWNER must regenerate afterwards (conflict-resolve.js step 7b).
 //      Needs a real clone (the driver's __dirname must BE the merging tree), so it
 //      skips where the environment cannot host that.
+//  11. The generated API contract + client (task 1003537) — docs/api/openapi.json,
+//      docs/api-reference.md, docs/routes-permissions.md and the six
+//      clients/bongos-client files regenerate clean from the merged tree, the client
+//      heals even when the on-disk spec is the conflicted file, and the driver's file
+//      list still matches what gen-api-client actually writes. Also pins the ABSENCE of
+//      clients/bongos-client/examples/hello-world.mjs, which is hand-written.
 //
 // Run:  node tests/git_merge_regen.mjs
 
@@ -46,6 +52,8 @@ const regen = require('../scripts/gds/git-merge-regen.js');
 const G = require('../scripts/gds/gen-repo-map.js');
 const CI = require('../scripts/gds/copy-inventory.js');
 const SI = require('../scripts/gds/gen-session-index.js'); // task 1001431 — the root CLAUDE.md's §13 snippet
+const AD = require('../scripts/gds/gen-api-docs.js');   // task 1003537 — the generated API contract
+const AC = require('../scripts/gds/gen-api-client.js'); // task 1003537 — the generated client
 
 const MARKERS = /^(<{7}|={7}|>{7})/m;
 
@@ -438,4 +446,56 @@ function withBlockBody(src, body) {
   }
 }
 
+// ── 11) the generated API contract + client (task 1003537) ─────────────────────
+// gen-api-docs.js and gen-api-client.js write nine fully generated files that used to
+// merge textually, so any branch touching a route conflicted with every concurrent land
+// (task 1002334: four merge → reship cycles, each beaten by a fresh conflict). They heal
+// like docs/repo-map.md — all three merge sides ignored, rebuilt from the merged tree.
+{
+  const conflicted = (a, b) => `<<<<<<< ours\n${a}\n=======\n${b}\n>>>>>>> theirs\n`;
+
+  // (a) the three doc artifacts rebuild to exactly what the generator would write.
+  const fresh = new Map(AD.build().files.map((f) => [f.rel, f.content]));
+  for (const rel of ['docs/api/openapi.json', 'docs/api-reference.md', 'docs/routes-permissions.md']) {
+    const r = regen.regenerateResolved(rel, {
+      base: 'base\n', ours: conflicted('{"a":1}', '{"b":2}'), theirs: 'nonsense\n',
+    });
+    assert.equal(r.ok, true, `${rel} heal must succeed`);
+    assert.ok(!MARKERS.test(r.content), `${rel} heal must leave no conflict markers`);
+    assert.equal(r.content, fresh.get(rel), `${rel} heal must equal a fresh generation`);
+  }
+
+  // (b) the six client files do too. The driver rebuilds the spec in memory rather than
+  // reading docs/api/openapi.json, so this must hold no matter what is on disk.
+  const freshClient = AC.build().files;
+  for (const [name, content] of Object.entries(freshClient)) {
+    const rel = `clients/bongos-client/${name}`;
+    const r = regen.regenerateResolved(rel, {
+      base: 'base\n', ours: conflicted('one', 'two'), theirs: 'nonsense\n',
+    });
+    assert.equal(r.ok, true, `${rel} heal must succeed`);
+    assert.ok(!MARKERS.test(r.content), `${rel} heal must leave no conflict markers`);
+    assert.equal(r.content, content, `${rel} heal must equal a fresh generation`);
+  }
+
+  // (c) LOCKSTEP: the driver's hardcoded client list must be exactly what the generator
+  // writes. Without this, a seventh generated client file would be added to
+  // gen-api-client.js and silently fall back to a textual merge — the original defect.
+  const declared = [...regen.REGENERABLE]
+    .filter((f) => f.startsWith('clients/bongos-client/'))
+    .map((f) => f.slice('clients/bongos-client/'.length))
+    .sort();
+  assert.deepEqual(declared, Object.keys(freshClient).sort(),
+    'REGENERABLE\'s clients/bongos-client entries must match gen-api-client build().files exactly');
+
+  // (d) the hand-written example must stay OUT. A `clients/bongos-client/*` glob would
+  // have swept it in, and the driver has no rule for it — so git would be forced into a
+  // conflict on a file it can merge by itself (the /CLAUDE.md leading-slash trap again).
+  assert.ok(!regen.REGENERABLE.has('clients/bongos-client/examples/hello-world.mjs'),
+    'the hand-written example must never be routed through the regenerating driver');
+  assert.equal(regen.regenerateResolved('clients/bongos-client/examples/hello-world.mjs',
+    { base: 'a\n', ours: 'b\n', theirs: 'c\n' }).content, null,
+    'a non-generated path under the client dir must not resolve');
+}
+
 console.log('git_merge_regen: all assertions passed');

package/tests/upgrade.mjs

@@ -88,11 +88,51 @@ t('vendorTarball: copies the .tgz + side-car manifest under the canonical name',
   writeFileSync(join(src, 'bongos-core-1.15.0.manifest.json'), '{"v":1}');
   const dir = scratchConsumer();
   const rel = u.vendorTarball({ instanceDir: dir, fromTgz: join(src, 'bongos-core-1.15.0.tgz'), targetVersion: '1.15.0' });
-  assert.equal(rel, join('vendor', 'bongos-core-1.15.0.tgz'));
+  // POSIX outright, not join(): this return value is written into package.json as a
+  // `file:` specifier, so the separator is part of the contract, not of the platform
+  assert.equal(rel, 'vendor/bongos-core-1.15.0.tgz');
   assert.equal(readFileSync(join(dir, rel), 'utf8'), 'TGZBYTES');
   assert.ok(existsSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json')), 'manifest copied too');
 });
 
+// The pin is a POSIX specifier on EVERY platform (task 1003839). `bongos init
+// --vendor-core` and `bongos upgrade` both write `file:<vendorRel>` into an
+// instance's package.json, and that package.json is COMMITTED — so a scaffold cut
+// on a Windows laptop was shipping `file:vendor\\bongos-core-x.y.z.tgz` to a Linux
+// provisioner running `npm ci`, which reads the backslash as part of the filename.
+//
+// Two halves, because neither alone can see the bug from CI. The STATIC half reads
+// the sources and so fails on any platform; the BEHAVIOURAL half below it is silent on
+// Linux (path.join already yields a forward slash there) and loud on Windows. The
+// static half runs FIRST for exactly that reason: on Windows a regression trips the
+// behavioural assertions and would abort the case before the platform-independent
+// ones ever ran, hiding whether CI could have caught it.
+t('the vendored core pin is POSIX on every platform, and no call site rebuilds it', () => {
+  // one place decides the separator, and that place spells it posix
+  const upgradeSrc = readFileSync(new URL('../scripts/gds/upgrade.js', import.meta.url), 'utf8');
+  assert.match(upgradeSrc, /function vendorRelFor\([^)]*\)\s*{\s*return path\.posix\.join\(/,
+    'vendorRelFor must build the pin with path.posix.join — it is an npm specifier, not a filesystem path');
+  for (const rel of ['scripts/gds/upgrade.js', 'scripts/gds/init.js']) {
+    const code = readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+    assert.doesNotMatch(code, /path\.join\(\s*['"]vendor['"]\s*,/,
+      `${rel} must build the pin with vendorRelFor(), not path.join('vendor', …)`);
+  }
+
+  // and the string it produces, end to end
+  assert.equal(u.vendorRelFor('1.17.0'), 'vendor/bongos-core-1.17.0.tgz');
+  assert.doesNotMatch(u.vendorRelFor('1.17.0'), /\\/, 'a package.json file: specifier carries no backslash');
+  // still a usable path: join() normalises a forward-slash relative on Windows too,
+  // so POSIX costs the fs side nothing
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, u.vendorRelFor('1.17.0')), 'TGZ');
+  assert.ok(existsSync(join(dir, u.vendorRelFor('1.17.0'))), 'the POSIX rel still resolves on disk');
+  // and the pin that reaches package.json is that string, verbatim
+  u.writePin(dir, u.vendorRelFor('1.17.0'));
+  assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies[u.CORE_PKG],
+    'file:vendor/bongos-core-1.17.0.tgz');
+});
+
 // ---- 3. step shims issue the right argv ------------------------------------
 t('npmInstall / runMigrate / restartService: correct commands', () => {
   const calls = [];