@bongos/core 1.19.589 → 1.19.591

package/modules/lifecycle/routes/goals.js

@@ -49,6 +49,14 @@ const goalConflicts = require('../goal-conflicts');
 const { isGoalOwner, authorizeGoalManagement } = require('../goal-authz');
 
 const VALID_GOAL_STATUSES = ['open', 'achieved', 'archived'];
+
+// ARCHIVE_DISPOSITION_MAX — how many unfinished tasks one archive call will
+// disposition (BV1.R14). A ceiling rather than an unbounded read because the
+// whole plan is validated in memory and applied in ONE transaction, and a goal
+// holding thousands of open tasks is a data problem to fix before archiving, not
+// a payload to stream. Sized well above anything real: the largest bucket on the
+// live instance is a per-version catch-all at ~53 (ADR 0250 §7).
+const ARCHIVE_DISPOSITION_MAX = 500;
 const VALID_MEMBERSHIP_KINDS = ['lead', 'member'];
 const METIC_PLUS = ['metic', 'archon'];
 const RESOLVE_ACTIONS = ['sequence', 'flag_release', 'rescope'];
@@ -63,7 +71,7 @@ const JOIN_REQUEST_RESPONSE_ACTIONS = ['approve', 'deny']; // an owner/manager/A
 // proceed; a false result means "not a member" → the route should 403. This is the
 // membership half of the wall; the protected-module rank check is enforced per-route
 // (scope is never self-granted).
-const { authorizeCreateJoinRequest, authorizeGoalCreate, authorizeGoalTaskCreate, authorizeInvitationAccept, authorizeInvitationResponse, authorizeJoinRequestResponse, authorizeMembershipKindChange, authorizeOwnershipTransfer, authorizeRescindInvitation, authorizeWithdrawJoinRequest, decorateGoalScope, isMemberOrArchon, protectedScopeAdmissionBlock } = require('./goal-route-authz.js');
+const { authorizeCreateJoinRequest, authorizeGoalCreate, authorizeGoalTaskCreate, authorizeInvitationAccept, authorizeInvitationResponse, authorizeJoinRequestResponse, authorizeMembershipKindChange, authorizeOwnershipTransfer, authorizeRescindInvitation, authorizeWithdrawJoinRequest, decorateGoalScope, goalNotOpenRefusal, isMemberOrArchon, planGoalArchiveDispositions, protectedScopeAdmissionBlock } = require('./goal-route-authz.js');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('lifecycle');
 module.exports = function buildGoalsRouter() {
@@ -1075,6 +1083,17 @@ module.exports = function buildGoalsRouter() {
   // skill reaches for once a goal is achieved (ADR 0086 §6 / BV1.R64).
   // rank: metic+archon — a goal member (Metic+) or an Archon dispositions the goal.
   router.post('/goals/:id/archive', auth.requireBuilder, auth.requirePermission('goal.archive'), async (req, res) => {
+    // ADR 0118 / R12: every write route that reads a body declares it, so an
+    // unknown field is REJECTED rather than silently ignored — a typo'd
+    // `disposition` (singular) must not read as "no disposition given" and take
+    // the refusal branch, which is exactly the shape that trains a caller to
+    // believe the map was applied. `dispositions` is a dynamic-key map (task id →
+    // verb) so the schema bounds its TYPE here and its CONTENTS are validated by
+    // planGoalArchiveDispositions, which refuses every malformed entry by name.
+    if (validateOrRespond(req, res, {
+      reason: { type: 'string', maxLength: 2000 },
+      dispositions: { type: 'object' },
+    })) return;
     const id = parseId(req, res, { code: 'bad_goal_id' });
     if (id === null) return;
     try {
@@ -1100,17 +1119,96 @@ module.exports = function buildGoalsRouter() {
       // "not without saying what happens to these", not a silent discard.
       //
       // A goal holding nothing open stays a single call, unchanged.
-      const held = await db.openTasksInGoal(id);
-      if (held.total > 0) {
-        return res.fail('goal_holds_open_tasks', {
+      //
+      // BV1.R14 (task 1003601) is the second half: the caller comes back with a
+      // `dispositions` map saying what happens to each open task, and the archive
+      // APPLIES it. R10 shipped the refusal one task ahead of its own remedy, so
+      // between the two every archive of a goal holding work was impossible —
+      // which is also why the ADR 0264 goal cut could not start until this landed.
+      //
+      // The decision is the pure planGoalArchiveDispositions (the sibling of
+      // authorizeGoalCreate / authorizeVersionCreate): the route gathers the
+      // facts, that decides, the route renders the verdict verbatim.
+      //
+      // THE CAP MATTERS HERE AND NOT IN R10. `openTasksInGoal` defaults to 50 rows
+      // (with the true count in `.total`), which is right for a refusal that only
+      // has to show the caller what is in the way. This call must plan over EVERY
+      // open task — a plan built from a truncated list would validate as complete,
+      // and the transaction's final re-count would then roll the whole archive back
+      // with a confusing "still holds N" on a caller who dispositioned everything
+      // they were shown. So: read wide when a disposition is being applied, and
+      // refuse above the ceiling with a code that says what to do.
+      const wantsDisposition = req.body?.dispositions != null;
+      const held = await db.openTasksInGoal(id, wantsDisposition ? { cap: ARCHIVE_DISPOSITION_MAX } : undefined);
+      if (wantsDisposition && held.total > ARCHIVE_DISPOSITION_MAX) {
+        return res.fail('too_many_open_tasks', {
           status: 409,
-          message: `Goal #${id} still holds ${held.total} unfinished task(s). Ship or abandon them, or move them to another goal, before archiving it.`,
-          details: { total: held.total, shown: held.tasks.length, tasks: held.tasks },
+          message: `Goal #${id} holds ${held.total} unfinished tasks — more than the ${ARCHIVE_DISPOSITION_MAX} this call dispositions at once. Move or abandon some first, then archive.`,
+          details: { total: held.total, max: ARCHIVE_DISPOSITION_MAX },
         });
       }
-      const updated = await db.setGoalStatus({ goalId: id, status: 'archived' });
-      return res.json({ ok: true, goal: updated });
+      const reason = typeof req.body?.reason === 'string' ? req.body.reason.slice(0, 2000) : '';
+      const plan = planGoalArchiveDispositions({
+        goalId: id, openTasks: held.tasks, dispositions: req.body?.dispositions ?? null, reason,
+      });
+      if (!plan.ok) return res.status(plan.status).json(plan.body);
+
+      // A goal holding nothing open never had a plan to apply — keep it the one
+      // untouched call it has always been, rather than routing it through a
+      // transaction that would do nothing.
+      if (plan.plan.length === 0) {
+        const updated = await db.setGoalStatus({ goalId: id, status: 'archived' });
+        return res.json({ ok: true, goal: updated, applied: [] });
+      }
+
+      // Move targets are resolved HERE, before the write, so a bad target is a
+      // 400 about the caller's request rather than a rollback mid-archive. The
+      // open test is goalNotOpenRefusal — the ONE definition of "this goal takes
+      // no new work" (BV1.R05) — never a second spelling of the status list.
+      const targets = [...new Set(plan.plan.filter((p) => p.verb === 'move').map((p) => p.toGoalId))];
+      for (const t of targets) {
+        const dest = await db.getGoal(t);
+        if (!dest) {
+          return res.fail('bad_disposition', { status: 400, message: `Move target goal #${t} does not exist.`, details: { goal_id: String(t) } });
+        }
+        const notOpen = goalNotOpenRefusal(dest);
+        if (notOpen) {
+          return res.fail('bad_disposition', {
+            status: 409,
+            message: `Move target goal #${t} is '${dest.status}' — a task cannot be moved into a closed goal.`,
+            details: { goal_id: String(t), goal_status: dest.status },
+          });
+        }
+      }
+
+      const result = await db.archiveGoalWithDispositions({ goalId: id, plan: plan.plan, reason });
+      return res.json({ ok: true, goal: result.goal, applied: result.applied });
     } catch (err) {
+      // An actively-claimed task must not be abandoned out from under whoever is
+      // working it — the same refusal POST /tasks/:id/abandon makes, surfaced with
+      // the task named so the caller knows which claim to chase.
+      if (err && err.code === 'TASK_HAS_ACTIVE_CLAIM') {
+        return res.fail('task_has_active_claim', {
+          status: 409,
+          message: `Task #${err.taskId} has an active claim — release it before archiving this goal.`,
+          details: { task_id: err.taskId, task_title: err.taskTitle },
+        });
+      }
+      if (err && (err.code === 'MOVE_TARGET_NOT_FOUND' || err.code === 'MOVE_TARGET_NOT_OPEN')) {
+        return res.fail('bad_disposition', {
+          status: 409,
+          message: `Move target goal #${err.toGoalId} changed while the archive was running — nothing was applied. Re-read and retry.`,
+          details: { goal_id: err.toGoalId, goal_status: err.targetStatus ?? null },
+        });
+      }
+      if (err && err.code === 'DISPOSITION_INCOMPLETE_AFTER_APPLY') {
+        return res.fail('goal_holds_open_tasks', {
+          status: 409,
+          message: `Goal #${id} still held ${err.remaining} unfinished task(s) after the dispositions were applied — nothing was changed. Re-read the goal and retry.`,
+          details: { remaining: err.remaining },
+        });
+      }
+      if (err && err.code === 'GOAL_NOT_FOUND') return res.fail('goal_not_found', 404);
       log.error('[gds] POST /goals/:id/archive', err);
       return res.fail('archive_failed', { status: 500, message: 'internal error' });
     }

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.589",
+  "version": "1.19.591",
   "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/gds-literal-scan.js

@@ -69,6 +69,13 @@ const GDS_RULE_FILES = new Set([
   'scripts/gds/fitness-ratchets.js',      // the gate: names the metric and carries the builder-facing hint
   'tests/fitness_gds_ratchet.mjs',        // its test, which must write the literal to prove the gate fires
   'config/fitness-baselines.json',        // the baseline's own _comment explains what is counted
+  // The RESTRAINT half of the same rename (task 1003697, criterion C5). It fails
+  // the build when the old name is ERASED from the frozen record, so it has to
+  // name both the literal and the version ids it pins — the same reason this
+  // file is exempt. A gate that cannot state its own rule cannot explain itself.
+  'scripts/gds/rename-history-check.js',
+  'tests/rename_history_restraint.mjs',
+  'config/rename-history-baseline.json',
 ]);
 
 // A version id is a row key, not vocabulary. Stripped before matching so it is

package/scripts/gds/rename-history-check.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+'use strict';
+// rename-history-check.js — the RESTRAINT half of the GDS→Bongos rename
+// (criterion C5 of goal 1000073, "history is intact and the alias still
+// answers"; task 1003697).
+//
+// WHY THIS EXISTS, AND WHY IT IS THE MIRROR OF THE RATCHET. Its sibling
+// gds-literal-scan.js + the `legacy_gds_literals` ratchet fail the build when
+// the old name COMES BACK. This module fails the build when the old name is
+// erased from somewhere it must stay. The goal's rule needs both halves:
+//
+//     rename what the project says about itself GOING FORWARD;
+//     leave what it recorded about its PAST.
+//
+// A ratchet alone rewards deletion — the cheapest way to lower a literal count
+// is to sweep the record clean, which is precisely the failure this guards.
+//
+// WHY IT LANDS BEFORE CRITERION C3. C3 renames scripts/gds/ → scripts/bongos/
+// with a codemod across ~1,000 referencing files. The goal calls C3 "the risky
+// criterion" and says C5 is "verified THROUGHOUT the goal, not at the end" —
+// which is not possible without a test. This is that test, built first so the
+// risky pass has something to be verified against.
+//
+// THE FOUR PROPERTIES, and the concrete damage each one prevents:
+//
+//   1. FROZEN FILENAMES — every migration filename, core and module-owned.
+//      schema_migrations is keyed by the filename STEM, so a renamed applied
+//      migration reads as unapplied and RE-RUNS. This is an outage, not an
+//      aesthetic. Two stems in this repo literally carry the old name and sit
+//      directly in a codemod's path:
+//        migrations/019_rename_pms_v3_to_gds_v3.sql
+//        modules/economy/migrations/economy_001_fix_gds_shipper_description.sql
+//      They are the reason this check is a pinned list rather than a pattern.
+//
+//   2. FROZEN LITERAL FLOORS — per-file minimum occurrence counts under the
+//      frozen record (docs/adr, docs/session-logs, docs/audits, limitations).
+//      A FLOOR, not a ceiling: the count may rise as new records are written,
+//      never fall. An ADR rewritten to today's vocabulary destroys the evidence
+//      that the words ever changed, and a per-file floor catches that even
+//      while new files push the directory total up.
+//
+//   3. VERSION ID FLOORS — GDS-V3 / GDS-V4 are row KEYS in the versions table,
+//      not vocabulary. gds-literal-scan.js deliberately strips them before
+//      counting so they stay legal anywhere; the corollary is that nothing else
+//      notices if a blanket find-replace rewrites them. This does.
+//
+//   4. ALIAS MOUNTS — '/api/gds' is a PERMANENT alias (src/bongos/api-prefix.js
+//      says never to remove it: shipped Dev Box binaries and live dev boxes
+//      call it and cannot be force-updated). Asserted against the real exported
+//      mount list. The DISPATCH half — that the alias is a live mount and so
+//      gets no corrective 404 hint — is already covered by
+//      tests/api_path_404.mjs and is deliberately not duplicated here.
+//
+// EVERY CHECKER IS PURE and takes its inputs explicitly, so the test can name
+// exactly the paths and counts under test without writing into the repo. That
+// is the gds-literal-scan.js precedent, and it is not tidiness: the unit lane
+// runs test files in parallel, and a test that edits the tree corrupts whatever
+// suite happens to be scanning it.
+//
+// Usage:
+//   node scripts/gds/rename-history-check.js            # verify against the baseline
+//   node scripts/gds/rename-history-check.js --json
+//   node scripts/gds/rename-history-check.js --write    # re-pin the baseline (see below)
+//
+// RE-PINNING. --write is legitimate ONLY when the record genuinely grew — a new
+// migration, a new ADR. It is never the fix for a failing check: if a floor
+// dropped, something erased history, and lowering the floor hides it.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { countInText, GDS_RULE_FILES } = require('./gds-literal-scan.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const BASELINE_PATH = path.join(ROOT, 'config', 'rename-history-baseline.json');
+
+// The frozen record. Matched against the repo-relative path at any depth, so an
+// instance's own docs/ and a module-owned migrations/ fall under the same rule
+// as the core's. Kept in step with GDS_EXCLUDED_PATHS in gds-literal-scan.js —
+// the same set of paths, read the opposite way: excluded from the ratchet
+// BECAUSE they are pinned here.
+const FROZEN_RECORD_PATHS = [
+  /(^|\/)docs\/adr\//,
+  /(^|\/)docs\/session-logs\//,
+  /(^|\/)docs\/audits\//,
+  /(^|\/)limitations\//,
+];
+
+// Any path segment named migrations/ — core and module-owned alike.
+const MIGRATION_PATH_RE = /(^|\/)migrations\/[^/]+\.sql$/;
+
+// Version ids that must survive as row keys. Deliberately a literal list and
+// not a pattern: the point is that THESE specific keys still resolve.
+const PINNED_VERSION_IDS = ['GDS-V3', 'GDS-V4'];
+
+// Mounts the server must keep answering on.
+const REQUIRED_ALIAS_MOUNTS = ['/api/gds'];
+
+function isFrozenRecordPath(relPath) {
+  return FROZEN_RECORD_PATHS.some((re) => re.test(relPath));
+}
+
+function isMigrationPath(relPath) {
+  return MIGRATION_PATH_RE.test(relPath);
+}
+
+// ---------- the four checkers (pure) ----------
+
+// checkFrozenFilenames — every pinned migration filename must still exist under
+// exactly that path. A rename shows up as a miss, which is the whole point:
+// schema_migrations keys on the stem, so a rename is a silent re-run.
+function checkFrozenFilenames({ present, pinned }) {
+  const have = new Set(present);
+  const missing = pinned.filter((p) => !have.has(p));
+  return { ok: missing.length === 0, missing };
+}
+
+// checkFrozenLiteralFloors — a per-file FLOOR on occurrences of the old name in
+// the frozen record. A file that vanished counts as zero, so deleting a record
+// fails exactly as loudly as rewriting one.
+function checkFrozenLiteralFloors({ counts, floors }) {
+  const dropped = [];
+  for (const [relPath, floor] of Object.entries(floors)) {
+    const now = Object.prototype.hasOwnProperty.call(counts, relPath) ? counts[relPath] : 0;
+    if (now < floor) dropped.push({ path: relPath, was: floor, now });
+  }
+  return { ok: dropped.length === 0, dropped };
+}
+
+// checkVersionIdFloors — the version ids are row keys; they may be referenced
+// more often over time, never fewer.
+function checkVersionIdFloors({ counts, floors }) {
+  const dropped = [];
+  for (const [id, floor] of Object.entries(floors)) {
+    const now = counts[id] || 0;
+    if (now < floor) dropped.push({ id, was: floor, now });
+  }
+  return { ok: dropped.length === 0, dropped };
+}
+
+// checkAliasMounts — the permanent alias must still be in the mount list.
+function checkAliasMounts({ mounts, required }) {
+  const have = new Set(mounts);
+  const missing = required.filter((m) => !have.has(m));
+  return { ok: missing.length === 0, missing };
+}
+
+// runAll — the four checkers over one set of gathered inputs. Returns every
+// failure rather than short-circuiting: a codemod that broke one property
+// usually broke several, and reporting them one release at a time is useless.
+function runAll({ observed, baseline }) {
+  const results = {
+    frozenFilenames: checkFrozenFilenames({
+      present: observed.migrationFiles,
+      pinned: baseline.migrationFiles,
+    }),
+    frozenLiteralFloors: checkFrozenLiteralFloors({
+      counts: observed.frozenLiteralCounts,
+      floors: baseline.frozenLiteralFloors,
+    }),
+    versionIdFloors: checkVersionIdFloors({
+      counts: observed.versionIdCounts,
+      floors: baseline.versionIdFloors,
+    }),
+    aliasMounts: checkAliasMounts({
+      mounts: observed.aliasMounts,
+      required: REQUIRED_ALIAS_MOUNTS,
+    }),
+  };
+  return { ok: Object.values(results).every((r) => r.ok), results };
+}
+
+// ---------- collectors (touch the repo; kept out of the checkers) ----------
+
+function trackedFiles() {
+  const out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+function readRepoFile(relPath) {
+  return fs.readFileSync(path.join(ROOT, relPath), 'utf8');
+}
+
+// Compiled ONCE, not per file. observe() reads every tracked file in the repo,
+// so a `new RegExp` inside that loop is thousands of needless compilations on
+// every unit-gate run. Reuse is safe: String.prototype.match with a global
+// regex ignores lastIndex and returns all matches, so the shared objects carry
+// no state between files.
+const VERSION_ID_RES = PINNED_VERSION_IDS.map((id) => [
+  id,
+  new RegExp(id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'),
+]);
+
+// observe — everything the checkers compare against, gathered once.
+// `files` and `readFile` are injectable for the same reason gds-literal-scan.js
+// makes them injectable: so a test can exercise the real aggregation without
+// writing to a tree other suites are reading in parallel.
+function observe({ files = null, readFile = null, aliasMounts = null } = {}) {
+  const read = readFile || readRepoFile;
+  const all = files || trackedFiles();
+
+  const migrationFiles = all.filter(isMigrationPath).sort();
+
+  const frozenLiteralCounts = {};
+  const versionIdCounts = {};
+  for (const id of PINNED_VERSION_IDS) versionIdCounts[id] = 0;
+
+  for (const relPath of all) {
+    let text;
+    try {
+      text = read(relPath);
+    } catch {
+      continue;
+    }
+    if (text.includes(String.fromCharCode(0))) continue; // binary (a NUL byte)
+
+    if (isFrozenRecordPath(relPath)) {
+      const n = countInText(text);
+      if (n) frozenLiteralCounts[relPath] = n;
+    }
+    // The files that STATE the rule are not part of the record they protect.
+    // This module and its test name the version ids as fixtures; counting those
+    // would pin a floor to test data, so editing a test could later red the
+    // build as if history had been erased. Same exemption, same reason, as
+    // GDS_RULE_FILES in the ratchet.
+    if (!GDS_RULE_FILES.has(relPath)) {
+      for (const [id, re] of VERSION_ID_RES) {
+        versionIdCounts[id] += (text.match(re) || []).length;
+      }
+    }
+  }
+
+  let mounts = aliasMounts;
+  if (!mounts) {
+    // Read the real exported mount list rather than grepping for the string —
+    // a comment mentioning the alias must not satisfy the check.
+    mounts = require('../../src/bongos/api-prefix.js').ALL_API_PREFIXES;
+  }
+
+  return { migrationFiles, frozenLiteralCounts, versionIdCounts, aliasMounts: mounts };
+}
+
+function loadBaseline() {
+  return JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf8'));
+}
+
+function baselineFrom(observed) {
+  return {
+    _comment: [
+      'Pinned by scripts/gds/rename-history-check.js (task 1003697, criterion C5 of goal 1000073).',
+      'These are FLOORS on the historical record, the mirror of the legacy_gds_literals ratchet.',
+      'migrationFiles: every migration filename must keep existing verbatim — schema_migrations',
+      'is keyed by the filename stem, so a rename reads as unapplied and RE-RUNS the migration.',
+      'frozenLiteralFloors / versionIdFloors: counts may RISE as the record grows, never fall.',
+      'Re-pin with --write only when the record genuinely grew. A dropped floor means something',
+      'erased history; lowering it hides the erasure instead of fixing it.',
+    ],
+    migrationFiles: observed.migrationFiles,
+    frozenLiteralFloors: observed.frozenLiteralCounts,
+    versionIdFloors: observed.versionIdCounts,
+  };
+}
+
+// ---------- CLI ----------
+
+// describe — the failure report. Names the damage, not just the diff, because
+// the reader is a builder mid-codemod who needs to know what to restore.
+function describe(report) {
+  const lines = [];
+  const { results } = report;
+  if (results.frozenFilenames.missing.length) {
+    lines.push(`frozen filenames MISSING (${results.frozenFilenames.missing.length}) — a renamed applied migration RE-RUNS:`);
+    for (const p of results.frozenFilenames.missing.slice(0, 20)) lines.push(`    ${p}`);
+  }
+  if (results.frozenLiteralFloors.dropped.length) {
+    lines.push(`frozen record ERASED in ${results.frozenLiteralFloors.dropped.length} file(s) — history was rewritten:`);
+    for (const d of results.frozenLiteralFloors.dropped.slice(0, 20)) {
+      lines.push(`    ${d.path}  ${d.was} → ${d.now}`);
+    }
+  }
+  if (results.versionIdFloors.dropped.length) {
+    lines.push('version ids REWRITTEN — these are row keys, not vocabulary:');
+    for (const d of results.versionIdFloors.dropped) lines.push(`    ${d.id}  ${d.was} → ${d.now}`);
+  }
+  if (results.aliasMounts.missing.length) {
+    lines.push(`alias mount REMOVED: ${results.aliasMounts.missing.join(', ')} — shipped clients call it and cannot be updated (src/bongos/api-prefix.js)`);
+  }
+  return lines;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const observed = observe();
+
+  if (argv.includes('--write')) {
+    // Print what re-pinning would ERASE before doing it. --write is legitimate
+    // when the record grew, and is the wrong move when a floor dropped — so the
+    // one thing it must never do is lower a floor silently. Everything under
+    // "removes" below is exactly what the check would have caught.
+    let prior = null;
+    try {
+      prior = loadBaseline();
+    } catch {
+      prior = null;
+    }
+    if (prior) {
+      const lost = describe(runAll({ observed, baseline: prior }));
+      if (lost.length) {
+        console.log('re-pinning would LOWER the record — read this before committing:\n');
+        for (const line of lost) console.log(`  ${line}`);
+        console.log('\nIf that was not deliberate, restore what was renamed or erased instead.\n');
+      }
+    }
+
+    fs.writeFileSync(BASELINE_PATH, `${JSON.stringify(baselineFrom(observed), null, 2)}\n`);
+    console.log(`re-pinned ${path.relative(ROOT, BASELINE_PATH)}`);
+    const priorMigrations = prior ? prior.migrationFiles.length : 0;
+    const priorFrozen = prior ? Object.keys(prior.frozenLiteralFloors).length : 0;
+    console.log(`  ${observed.migrationFiles.length} migration filename(s)  (was ${priorMigrations})`);
+    console.log(`  ${Object.keys(observed.frozenLiteralCounts).length} frozen-record file(s)  (was ${priorFrozen})`);
+    console.log(`  version ids: ${Object.entries(observed.versionIdCounts).map(([k, v]) => `${k}=${v}`).join(' ')}`);
+    return;
+  }
+
+  const baseline = loadBaseline();
+  const report = runAll({ observed, baseline });
+
+  if (argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exitCode = report.ok ? 0 : 1;
+    return;
+  }
+
+  if (report.ok) {
+    console.log('rename restraint: OK — history intact, alias still mounted');
+    console.log(`  ${baseline.migrationFiles.length} migration filename(s) unchanged`);
+    console.log(`  ${Object.keys(baseline.frozenLiteralFloors).length} frozen-record file(s) at or above their floor`);
+    console.log(`  version ids: ${Object.entries(observed.versionIdCounts).map(([k, v]) => `${k}=${v}`).join(' ')}`);
+    console.log(`  mounts: ${observed.aliasMounts.join(' ')}`);
+    return;
+  }
+
+  console.error('rename restraint: FAILED — the record changed where it must not\n');
+  for (const line of describe(report)) console.error(`  ${line}`);
+  console.error('\nThis is not fixed by re-pinning the baseline. Restore what was renamed or erased.');
+  process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  FROZEN_RECORD_PATHS,
+  MIGRATION_PATH_RE,
+  PINNED_VERSION_IDS,
+  REQUIRED_ALIAS_MOUNTS,
+  isFrozenRecordPath,
+  isMigrationPath,
+  checkFrozenFilenames,
+  checkFrozenLiteralFloors,
+  checkVersionIdFloors,
+  checkAliasMounts,
+  runAll,
+  observe,
+  baselineFrom,
+  loadBaseline,
+  describe,
+  BASELINE_PATH,
+};

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.589'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.591'; // 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');