@bongos/core 1.19.646 → 1.19.648

package/scripts/gds/box-sync.js

@@ -15,6 +15,18 @@
 //
 // Usage:  node scripts/gds/box-sync.js            # re-fetch now
 //         node scripts/gds/box-sync.js --dry-run  # print what it WOULD run
+//         node scripts/gds/box-sync.js --widen <dir>    # keep <dir> across ticks
+//         node scripts/gds/box-sync.js --unwiden <dir>  # stop keeping it
+//         node scripts/gds/box-sync.js --widen-list     # what is kept, and what is ignored
+//
+// WHY --widen EXISTS (task 1003087 / idea 1000793). `git sparse-checkout add`
+// does not survive: the */10 cron re-applies the SERVER-computed set and deletes
+// the addition, sometimes MID-COMMAND — a live test suite died with
+// MODULE_NOT_FOUND that read exactly like a code bug. --widen records the
+// directory server-side instead, so every fetch (the cron included) returns it
+// in the set and it stops being deleted. It is capped, and it can never widen
+// past what your RANK already reaches — a request outside it is stored but
+// reported as ignored rather than silently applied.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -36,7 +48,78 @@ function resolveFetchScript(opts = {}) {
   try { return fs.existsSync(p) ? p : null; } catch { return null; }
 }
 
+// valueAfter(argv, flag) — the argument following a flag, or null. Kept tiny and
+// pure so the arg handling is testable without spawning anything.
+function valueAfter(argv, flag) {
+  const i = argv.indexOf(flag);
+  if (i < 0) return null;
+  const v = argv[i + 1];
+  return typeof v === 'string' && v && !v.startsWith('--') ? v : null;
+}
+
+// formatWidenReport — PURE. The lines to print for a /box/widen body. Reports
+// IGNORED entries loudly: a widen the server accepted into storage but will not
+// apply (because it is outside your rank scope) looks identical to a working one
+// unless it is said out loud, and a silently-inert widen is exactly the class of
+// bug this whole task is about.
+function formatWidenReport(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return ['widen: could not read your widen set.'];
+  }
+  const kept = Array.isArray(body.widen_paths) ? body.widen_paths : [];
+  const ignored = Array.isArray(body.ignored) ? body.ignored : [];
+  const out = [];
+  out.push(kept.length
+    ? `widen: keeping ${kept.length} path(s) across ticks: ${kept.join(', ')}`
+    : 'widen: nothing kept — the fetch set is whatever your claim scope says.');
+  if (ignored.length) {
+    out.push(`widen: IGNORED (outside your rank scope, stored but not applied): ${ignored.join(', ')}`);
+  }
+  return out;
+}
+
+// The --widen family. Talks to the control plane, so it works off a box too —
+// unlike the fetch itself, the widen set is server state you can inspect and
+// edit from anywhere.
+async function runWiden(argv) {
+  const { apiCall } = require('./cli-lib');
+  const add = valueAfter(argv, '--widen');
+  const remove = valueAfter(argv, '--unwiden');
+  const clear = argv.includes('--widen-clear');
+  const listOnly = !add && !remove && !clear;
+
+  const r = listOnly
+    ? await apiCall('GET', '/api/gds/box/widen')
+    : await apiCall('POST', '/api/gds/box/widen', {
+      ...(add ? { add: [add] } : {}),
+      ...(remove ? { remove: [remove] } : {}),
+      ...(clear ? { clear: true } : {}),
+    });
+
+  if (!r || (r.status !== 200 && r.status !== 201)) {
+    const code = r && r.data && r.data.error ? r.data.error : `HTTP ${r ? r.status : '?'}`;
+    if (code === 'no_box') {
+      console.error('widen: you have no dev box — there is nothing to widen. Provision one first.');
+    } else if (code === 'bad_widen_path') {
+      const bad = r.data && r.data.rejected ? r.data.rejected.join(', ') : '';
+      console.error(`widen: refused ${bad} — give a repo-relative DIRECTORY (no leading /, no "..").`);
+    } else {
+      console.error(`widen: failed (${code}).`);
+    }
+    return 1;
+  }
+  for (const line of formatWidenReport(r.data)) console.log(line);
+  if (!listOnly) console.log('widen: run `box-sync` (no flags) to apply it to the checkout now.');
+  return 0;
+}
+
 function main(argv = process.argv.slice(2)) {
+  // The widen family is server state, not a fetch — handled before the on-a-box
+  // check, so it works from a laptop too.
+  if (argv.some((a) => a === '--widen' || a === '--unwiden' || a === '--widen-list' || a === '--widen-clear')) {
+    runWiden(argv).then((code) => process.exit(code), () => process.exit(1));
+    return;
+  }
   const dryRun = argv.includes('--dry-run') || argv.includes('-n');
   const script = resolveFetchScript();
   if (!script) {
@@ -130,4 +213,4 @@ async function reportScope() {
 
 if (require.main === module) main();
 
-module.exports = { resolveFetchScript, FETCH_SCRIPT, formatScopeReport };
+module.exports = { resolveFetchScript, FETCH_SCRIPT, formatScopeReport, formatWidenReport, valueAfter };

package/scripts/gds/ship-flow.js

@@ -659,6 +659,58 @@ async function shipMain() {
   });
 }
 
+// persistRegradeSummary — store a re-grade's corrected --summary on the task row
+// (task 1003817). A re-grade has no claim, so it cannot reach claim-resolve, the
+// only writer of tasks.value_summary before this; PATCH /tasks/:id is the route
+// it uses instead.
+//
+// WHY PATCH AND NOT publish-branch, which already RECEIVES value_summary and
+// could have persisted it with a one-line change: publish-branch is only called
+// when pushVia() === 'server'. A laptop land goes through ciLandLocal (gh), and
+// --no-merge / --db-only / --allow-empty never land at all — so persisting there
+// would have fixed one path of four and left the defect standing on the rest. It
+// would also have made publish-branch a SECOND writer racing claim-resolve on
+// the normal ship path, which sends the same field. Writing from here keeps one
+// writer per ship: the claim on a first ship, this on a re-grade.
+//
+// Three deliberate postures:
+//   - OMITTED --summary writes NOTHING. The stored value is the fallback the
+//     grader was already handed, so a re-grade that omits the flag must leave
+//     the row exactly as it was — the COALESCE/NULLIF posture every other
+//     value_summary write in db-ship.js keeps. This is acceptance 2.
+//   - UNCHANGED text writes nothing either, so a no-op edit mints no audit_log row.
+//   - A FAILURE is LOUD BUT NON-BLOCKING. The grade is the expensive step and it
+//     has not run yet; discarding a re-grade over a summary that did not persist
+//     would trade the cheap problem for the costly one. The builder is told
+//     plainly that the row still holds the old sentence, so nothing is silent.
+//     An older pinned core that has not learned the field is named as exactly
+//     that rather than reported as a generic error — the same forward-compat
+//     posture the resolve call in shipMain documents at length (task 1003767),
+//     because @cloudbongos/cli ships separately from the core and an instance
+//     pins its own core version.
+async function persistRegradeSummary({ taskId, summaryArg, task }) {
+  const next = (summaryArg || '').trim();
+  if (!next) return { written: false, reason: 'omitted' };
+  if (next === (task.value_summary || '').trim()) return { written: false, reason: 'unchanged' };
+  let r;
+  try {
+    r = await (await cliClient()).tasks.patchTasksId({ id: taskId, body: { value_summary: next } });
+  } catch (err) {
+    console.error(`  ⚠ value_summary NOT stored (${err && err.message ? err.message : 'request failed'}) — task #${taskId} keeps its previous summary. The grade below is unaffected.`);
+    return { written: false, reason: 'error' };
+  }
+  if (!r.ok) {
+    if (isUnknownFieldRejection(r.status, r.data, 'value_summary')) {
+      console.error(`  ⚠ value_summary NOT stored: this instance's core predates PATCH /tasks/:id accepting the field. Upgrade the core, or edit the summary in the hall. The grade below is unaffected.`);
+    } else {
+      console.error(`  ⚠ value_summary NOT stored (${apiErrorLine(r.data, r.status)}) — task #${taskId} keeps its previous summary. The grade below is unaffected.`);
+    }
+    return { written: false, reason: 'refused' };
+  }
+  console.log(`  value_summary updated on task #${taskId} — the hall, /status and the ship broadcast now read the corrected sentence.`);
+  return { written: true };
+}
+
 // ---------- Re-grade flow (#678) ----------
 //
 // `node scripts/gds/ship.js <id> --regrade` closes the task-595-regrade-gap
@@ -676,6 +728,7 @@ async function shipMain() {
 //   - grade: gradeAndRecord → POST /tasks/:id/grade (rank-open; applyGrade
 //     promotes completed→confirmed + awards credits on pass, idempotent)
 //   - on pass: the normal confirmed→shipped merge + sync tail runs.
+
 async function regradeMain() {
   await requireSession();
   const args = process.argv.slice(2);
@@ -764,16 +817,14 @@ async function regradeMain() {
   // task's stored value_summary so the merge commit + Discord #ship-news post
   // carry meaningful text even when --summary is omitted.
   //
-  // AND IT NEVER REACHES THE TASK ROW — task 1003702's acceptance 3 asked this
-  // question; the answer is a real, separate defect, filed as task 1003817.
-  // `summary` from here feeds the grader prompt, the merge commit message and
-  // the PR title/body, and NOTHING writes it back to tasks.value_summary. All
-  // three candidate write paths were read and ruled out: publish-branch accepts
-  // value_summary but uses it only for PR text; PATCH /tasks/:id does not accept
-  // the field at all; the claim-resolve route is the sole writer and a re-grade
-  // has no claim (which is why claimLike is synthesized above). Fixing it needs
-  // a server route change, so it is deliberately NOT folded into this CLI fix.
-  // tests/ship_cannot_lie.mjs pins both halves of that so the answer cannot rot.
+  // AND IT NOW REACHES THE TASK ROW TOO — task 1003817. It did not before: this
+  // `summary` fed the grader prompt, the merge commit message and the PR
+  // title/body and stopped there, so a builder who re-graded with a CORRECTED
+  // --summary saw it applied everywhere except the place that is the record —
+  // the hall, /status and the Discord #ship-news line all kept the first ship's
+  // sentence forever. persistRegradeSummary (below the preflight) is the write;
+  // PATCH /tasks/:id is the route it uses, and `value_summary` was added to that
+  // schema by this same task. tests/ship_cannot_lie.mjs pins the wiring.
   const summary = summaryArg || task.value_summary || '';
 
   // The grader helpers want a claim-like object for touches[] (preflight's
@@ -804,6 +855,14 @@ async function regradeMain() {
     process.exit(1);
   }
 
+  // ---- Persist a corrected --summary to the task row (task 1003817) ----
+  // Placed HERE deliberately: after the guards that can still abort the re-grade
+  // (so a refused run writes nothing), and BEFORE the grade — which is the order
+  // the normal ship already has, where claim-resolve stores value_summary and
+  // the panel runs afterwards. The row, the grader prompt, the merge commit and
+  // the PR then all carry the same sentence.
+  await persistRegradeSummary({ taskId, summaryArg, task });
+
   // ---- Delta-aware prior-round context (task 1002662) ----
   // The prior grade's findings + the builder's response + the interim fix diff
   // ride to the panel so an already-answered finding can't re-veto on

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.646'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.648'; // 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/box_access.mjs

@@ -414,5 +414,160 @@ t('1003227 config/ is a cone-mode DIRECTORY entry (a file path aborts the whole
   }
 });
 
+// ---------------------------------------------------------------------------
+// task 1003087 / idea 1000793 — builder widening that SURVIVES the */10 tick
+//
+// The bug: the cron re-applies the server-computed sparse set, so a builder's
+// own `git sparse-checkout add` is deleted — sometimes mid-command (a live suite
+// died with MODULE_NOT_FOUND that read exactly like a code bug). The widen set is
+// therefore recorded server-side and unioned in HERE, on the same path the cron
+// asks every tick. These pin the two halves that matter: it actually widens, and
+// it cannot be used to climb past the rank scope.
+// ---------------------------------------------------------------------------
+
+console.log('\nnormalizeWidenPath — a repo-relative directory, or nothing:');
+
+t('accepts a plain repo-relative dir and strips the noise around it', () => {
+  assert.equal(access.normalizeWidenPath('docs'), 'docs');
+  assert.equal(access.normalizeWidenPath('  docs  '), 'docs');
+  assert.equal(access.normalizeWidenPath('./docs/'), 'docs');
+  assert.equal(access.normalizeWidenPath('docs//adr'), 'docs/adr');
+});
+
+t('folds a Windows separator rather than judging the path on it', () => {
+  const BS = String.fromCharCode(92);
+  assert.equal(access.normalizeWidenPath(`modules${BS}game`), 'modules/game');
+});
+
+t('REFUSES traversal, absolute paths and drive letters outright', () => {
+  // Refused, never "cleaned up into something that still works" — this string
+  // reaches `git sparse-checkout set` on a real box.
+  for (const bad of ['../etc', 'a/../../b', '/etc/passwd', 'C:/Windows', '..', '.', '']) {
+    assert.equal(access.normalizeWidenPath(bad), null, `${JSON.stringify(bad)} must be refused`);
+  }
+});
+
+t('refuses a non-string, an over-long path, and odd characters', () => {
+  assert.equal(access.normalizeWidenPath(null), null);
+  assert.equal(access.normalizeWidenPath(42), null);
+  assert.equal(access.normalizeWidenPath({}), null);
+  assert.equal(access.normalizeWidenPath('a'.repeat(500)), null);
+  assert.equal(access.normalizeWidenPath('modules/ga me'), null);
+  assert.equal(access.normalizeWidenPath('modules/rm -rf'), null);
+});
+
+console.log('\nadmissibleWidenPaths — rank is the ceiling, and it is the whole point:');
+
+t('a Metic (full rank scope) may widen anywhere', () => {
+  assert.deepEqual(access.admissibleWidenPaths(['modules/game'], 'metic'), ['modules/game']);
+  assert.deepEqual(access.admissibleWidenPaths(['migrations'], 'archon'), ['migrations']);
+});
+
+t('a Xenos may NOT widen past the starter surface — that would be rank escalation', () => {
+  // The security property of this feature stated as a test: if an arbitrary widen
+  // were honored, a convenience flag would hand a starter-scoped builder the whole
+  // repo, which is the rank gate defeated rather than a checkout preference.
+  assert.deepEqual(access.admissibleWidenPaths(['modules/game'], 'xenos'), []);
+  assert.deepEqual(access.admissibleWidenPaths(['migrations'], 'xenos'), []);
+  assert.deepEqual(access.admissibleWidenPaths(['modules/lifecycle'], 'thetes'), []);
+});
+
+t('a Xenos MAY widen INSIDE starter — a task box is narrower than their rank allows', () => {
+  // Not a null grant: task scope is BASE union modules, which is narrower than
+  // starter, so this is the room to climb back to what rank already permitted.
+  assert.deepEqual(access.admissibleWidenPaths(['docs/adr'], 'xenos'), ['docs/adr']);
+  assert.deepEqual(access.admissibleWidenPaths(['src/world'], 'xenos'), ['src/world']);
+});
+
+t('normalizes, dedupes and sorts, and drops the invalid without failing the rest', () => {
+  const got = access.admissibleWidenPaths(['./docs/', 'docs', '../etc', 'art'], 'metic');
+  assert.deepEqual(got, ['art', 'docs'], 'one invalid entry must not discard the valid ones');
+});
+
+t('is capped, so a widen set can never become a second scope system', () => {
+  const many = Array.from({ length: access.MAX_WIDEN_PATHS + 20 }, (_, i) => `docs/d${i}`);
+  assert.equal(access.admissibleWidenPaths(many, 'metic').length, access.MAX_WIDEN_PATHS);
+});
+
+t('a missing / non-array widen set is simply no widening', () => {
+  for (const v of [undefined, null, 'docs', 42, {}]) {
+    assert.deepEqual(access.admissibleWidenPaths(v, 'metic'), []);
+  }
+});
+
+console.log('\nwithWidenPaths — union into the computed set, without redundancy:');
+
+t('adds a dir the set does not already cover', () => {
+  assert.deepEqual(access.withWidenPaths(['src/bongos'], ['docs']), ['src/bongos', 'docs']);
+});
+
+t('skips a dir an ANCESTOR already covers — cone mode pulls the whole subtree', () => {
+  assert.deepEqual(access.withWidenPaths(['scripts'], ['scripts/gds']), ['scripts'],
+    'adding scripts/gds under scripts is noise in the git command and in the scope readout');
+});
+
+t('passes a null sparse set (the full clone) straight through', () => {
+  assert.equal(access.withWidenPaths(null, ['docs']), null,
+    'a full clone already holds everything — there is nothing to widen INTO');
+});
+
+t('an empty widen set returns the computed set untouched', () => {
+  const base = ['src/bongos', 'scripts'];
+  assert.deepEqual(access.withWidenPaths(base, []), base);
+});
+
+console.log('\ndecideSourceAccess — the widen reaches the spec the box actually fetches:');
+
+t('a task-scoped box gets its widen unioned into the sparse set', () => {
+  const d = access.decideSourceAccess({
+    rank: 'metic', status: 'active', scopeKeys: [], hasActiveClaims: false,
+    moduleScopeMap: {}, widenPaths: ['modules/game'],
+  });
+  assert.equal(d.allowed, true);
+  assert.ok(d.spec.sparsePaths.includes('modules/game'),
+    'the widen must reach the SPEC — this is the value the cron writes into sparse-checkout');
+});
+
+t('an out-of-scope widen never reaches the spec for a starter-scoped builder', () => {
+  const d = access.decideSourceAccess({
+    rank: 'xenos', status: 'active', scopeKeys: [], hasActiveClaims: false,
+    moduleScopeMap: {}, widenPaths: ['modules/game'],
+  });
+  assert.ok(!d.spec.sparsePaths.includes('modules/game'));
+});
+
+t('no widenPaths leaves every scope byte-identical to before the feature', () => {
+  const withArg = access.decideSourceAccess({
+    rank: 'metic', status: 'active', scopeKeys: [], hasActiveClaims: false, moduleScopeMap: {}, widenPaths: [],
+  });
+  const without = access.decideSourceAccess({
+    rank: 'metic', status: 'active', scopeKeys: [], hasActiveClaims: false, moduleScopeMap: {},
+  });
+  assert.deepEqual(withArg.spec, without.spec, 'a box that asked for nothing must fetch exactly what it always did');
+});
+
+t('a full-clone builder is unaffected — sparsePaths stays null', () => {
+  const d = access.decideSourceAccess({ rank: 'metic', status: 'active', widenPaths: ['docs'] });
+  assert.equal(d.spec.sparsePaths, null);
+  assert.equal(d.spec.mode, 'full');
+});
+
+t('widening cannot resurrect access for an inactive or below-floor builder', () => {
+  // The widen set is read from the box row, so it must not become a way around
+  // the ALLOW/DENY gate that runs before any scope is computed.
+  const inactive = access.decideSourceAccess({ rank: 'metic', status: 'inactive', widenPaths: ['docs'] });
+  assert.equal(inactive.allowed, false);
+  assert.equal(inactive.reason, 'BUILDER_INACTIVE');
+  assert.equal(inactive.spec, undefined);
+});
+
+t('every admitted widen path is still a DIRECTORY — cone mode aborts on a file', () => {
+  for (const p of access.admissibleWidenPaths(['docs/adr', 'src/world'], 'metic')) {
+    assert.ok(!p.endsWith('/'), `${p} must not carry a trailing slash`);
+    const last = p.split('/').pop();
+    assert.ok(!/\.[a-z0-9]+$/i.test(last), `${p} looks like a FILE — cone mode would abort the set`);
+  }
+});
+
 console.log(`\nbox_access.mjs: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/box_sync_scope_report.mjs

@@ -18,6 +18,8 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 const { formatScopeReport } = require('../scripts/gds/box-sync.js');
+// task 1003087 — the widen read-out lives in the same module.
+const sync = require('../scripts/gds/box-sync.js');
 
 let passed = 0;
 let failed = 0;
@@ -77,5 +79,48 @@ t('an unknown scope value is reported verbatim rather than swallowed', () => {
   assert.match(joined({ scope: 'something-new', sparse_paths: [] }), /something-new/);
 });
 
+// ---------------------------------------------------------------------------
+// task 1003087 — the --widen read-out
+//
+// The whole feature exists because a widen that silently stops applying is
+// indistinguishable from one that works. So the report must say when the server
+// stored a path it will NOT apply (outside the caller's rank scope) — otherwise
+// this fix reintroduces its own bug one layer up.
+// ---------------------------------------------------------------------------
+
+const widenLines = (body) => sync.formatWidenReport(body).join('\n');
+
+t('an empty widen set says so plainly rather than printing nothing', () => {
+  assert.match(widenLines({ widen_paths: [], ignored: [] }), /nothing kept/i);
+});
+
+t('a kept set names the paths and the count', () => {
+  const out = widenLines({ widen_paths: ['docs', 'modules/game'], ignored: [] });
+  assert.match(out, /2 path/);
+  assert.match(out, /docs/);
+  assert.match(out, /modules\/game/);
+});
+
+t('an IGNORED path is called out loudly, not folded into the kept list', () => {
+  const out = widenLines({ widen_paths: ['docs', 'modules/game'], ignored: ['modules/game'] });
+  assert.match(out, /IGNORED/);
+  assert.match(out, /rank scope/i,
+    'the reason must be named — "stored but not applied" with no why is the silent failure again');
+});
+
+t('a garbage / missing body degrades to one honest line rather than throwing', () => {
+  for (const bad of [null, undefined, 'nope', 42, []]) {
+    assert.match(widenLines(bad), /could not read/i);
+  }
+});
+
+t('valueAfter reads the argument after a flag, and refuses the next flag as a value', () => {
+  assert.equal(sync.valueAfter(['--widen', 'docs'], '--widen'), 'docs');
+  assert.equal(sync.valueAfter(['--widen', '--dry-run'], '--widen'), null,
+    'consuming the next FLAG as a path would silently widen to something nobody typed');
+  assert.equal(sync.valueAfter(['--widen'], '--widen'), null);
+  assert.equal(sync.valueAfter([], '--widen'), null);
+});
+
 console.log(`\nbox_sync_scope_report.mjs: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/home_bounded_reads.mjs

@@ -99,16 +99,25 @@ await test('the limit is OPT-IN — the Work Board and /builder-start are untouc
 await test('every db.* the claimable handler calls actually exists', () => {
   // The bug this catches, caught the hard way: an earlier cut pushed the limit into the
   // db layer, was reverted, and left the route calling `db.listClaimableTasksPaged` — a
-  // function that no longer existed. Every assertion in this file is source text, and
-  // source text cannot see a missing symbol; a neighbouring suite found it instead.
+  // function that no longer existed. Every OTHER assertion in this file is source text,
+  // and source text cannot see a missing symbol; a neighbouring suite found it instead.
+  //
+  // So this one is not source text: it REQUIRES the facade and reads the real key. It
+  // used to grep db.js's module.exports block for each name, which was a proxy for
+  // exactly this and stopped being a valid one at task 1003817 — db.js now SPREADS
+  // db-tasks.js's exports instead of re-listing them, so `listClaimableTasks` is a live
+  // key that appears nowhere in the block's text. Requiring is safe here: the lifecycle
+  // db family is pool-lazy (tests/lifecycle_facade_surface.mjs relies on the same thing).
   const from = ROUTE.indexOf("router.get('/tasks/claimable'");
   const body = ROUTE.slice(from, ROUTE.indexOf('res.json({ claimable', from));
   const called = [...new Set([...body.matchAll(/\bdb\.([A-Za-z0-9_]+)\s*\(/g)].map((m) => m[1]))];
   assert.ok(called.length > 0, 'the handler calls the db layer');
-  const dbExports = read('modules/lifecycle/db.js');
-  const block = dbExports.slice(dbExports.lastIndexOf('module.exports'));
+  const db = require(path.join(ROOT, 'modules', 'lifecycle', 'db.js'));
   for (const fn of called) {
-    assert.ok(new RegExp(`\\b${fn}\\b`).test(block), `db.js must export ${fn} — the route calls it`);
+    assert.ok(
+      typeof db[fn] === 'function',
+      `db.js must export ${fn} — the route calls it, and this is the runtime check, not a text match`
+    );
   }
 });
 

package/tests/lifecycle_facade_surface.mjs

@@ -0,0 +1,112 @@
+// tests/lifecycle_facade_surface.mjs
+//
+// The lifecycle facade's TASK surface, pinned (task 1003817).
+//
+// WHY THIS FILE EXISTS. modules/lifecycle/db.js used to re-export db-tasks.js by
+// hand: 31 names destructured at the top purely so module.exports could list
+// them again, with no internal caller for a single one. Two hand-maintained
+// copies of one list is real duplication, and the `duplicate_window_count`
+// ratchet counted it — the two runs were 29 identical normalized lines, one
+// under the 30-line window, so task 1003750 adding `updateTaskPriority` to both
+// tipped it over and cost an owner-decided baseline raise (59 -> 60). The reason
+// recorded in config/fitness-baselines.json told whoever added the NEXT
+// db-tasks function to fix the facade instead of raising it again. Task 1003817
+// added `updateTaskValueSummary`, so this is that fix: db.js now spreads
+// db-tasks.js's exports minus an explicit omit list.
+//
+// A SPREAD IS CHEAPER TO MAINTAIN AND EASIER TO GET WRONG. Nothing stops it from
+// silently WIDENING the module's public surface (publishing an internal that was
+// deliberately withheld) or NARROWING it (a rename in db-tasks.js quietly
+// dropping a name every route calls, which is a runtime `undefined is not a
+// function` in an async Express handler — ADR 0091 §2 records exactly that
+// outage for `LIVE_RANK_LADDER`, where it hung the request until Cloudflare
+// 524'd). The old twin list at least failed loudly at require time. So the
+// safety the list used to provide is re-established here, as an assertion rather
+// than as boilerplate: db.js's task surface must be db-tasks.js's exports minus
+// TASK_FACADE_OMIT, exactly — no more, no fewer.
+//
+// No live DB: requiring the lifecycle db family is pool-lazy.
+//
+// Run:  node tests/lifecycle_facade_surface.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..');
+const require = createRequire(import.meta.url);
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`  ok  ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  FAIL ${name}`);
+    console.error('    ', err.message);
+    failed++;
+  }
+}
+
+const db = require(join(repoRoot, 'modules', 'lifecycle', 'db.js'));
+const dbTasks = require(join(repoRoot, 'modules', 'lifecycle', 'db-tasks.js'));
+const dbSrc = readFileSync(join(repoRoot, 'modules', 'lifecycle', 'db.js'), 'utf8');
+
+// The omit list is read from the SOURCE, not re-typed here — a test that hardcodes
+// the same two names cannot notice a third being added without a reason.
+function omitListFromSource(src) {
+  const block = src.match(/const TASK_FACADE_OMIT = new Set\(\[([\s\S]*?)\]\)/);
+  assert.ok(block, 'db.js must declare TASK_FACADE_OMIT so the withheld names are a named decision');
+  return block[1]
+    .split('\n')
+    .map((l) => l.replace(/\/\/.*/, '').trim())
+    .filter(Boolean)
+    .map((l) => l.replace(/^'|',?$/g, ''));
+}
+
+await test('db.js re-exports every db-tasks export except the named omissions', () => {
+  const omit = new Set(omitListFromSource(dbSrc));
+  const expected = Object.keys(dbTasks).filter((k) => !omit.has(k)).sort();
+  const actual = expected.filter((k) => Object.prototype.hasOwnProperty.call(db, k));
+  const missing = expected.filter((k) => !Object.prototype.hasOwnProperty.call(db, k));
+  assert.deepEqual(missing, [], `db.js dropped task surface: ${missing.join(', ')} — a route calling one of these gets undefined at runtime, not an error at require`);
+  assert.equal(actual.length, expected.length);
+});
+
+await test('and publishes NONE of the omitted internals', () => {
+  const omit = omitListFromSource(dbSrc);
+  assert.ok(omit.length > 0, 'the omit list is not empty — a bare spread would widen the surface');
+  for (const name of omit) {
+    assert.ok(
+      Object.prototype.hasOwnProperty.call(dbTasks, name),
+      `${name} is omitted from a surface it is not on — stale entry, remove it`
+    );
+    assert.ok(
+      !Object.prototype.hasOwnProperty.call(db, name),
+      `${name} is on the omit list but reachable through db.js — the spread widened the facade`
+    );
+  }
+});
+
+await test('the spread is what wires it, and the twin name list is gone', () => {
+  assert.match(dbSrc, /\.\.\.dbTasksFacade,/, 'module.exports spreads the filtered db-tasks surface');
+  assert.match(
+    dbSrc,
+    /const dbTasksFacade = Object\.fromEntries\(\s*Object\.entries\(dbTasks\)\.filter\(\(\[name\]\) => !TASK_FACADE_OMIT\.has\(name\)\)/,
+    'the filter is the omit list, not an inline literal'
+  );
+  // The regression this replaces: a `const { … } = require('./db-tasks.js')`
+  // destructure whose only purpose was to feed module.exports.
+  assert.ok(
+    !/const \{[\s\S]*?\} = require\('\.\/db-tasks\.js'\)/.test(dbSrc),
+    'db-tasks.js must not be hand-destructured again — that is the duplication this task removed'
+  );
+});
+
+console.log(`\nlifecycle_facade_surface: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/migration_allocation.mjs

@@ -205,6 +205,7 @@ function shouldReserveMigrationNumber(task) {
         [() => db.updateTaskDescription(1, 'edited body'), 'description'], // task 1002647
         [() => db.updateTaskTitle(1, 'corrected title'), 'title'], // task 1002792
         [() => db.updateTaskPriority(1, 2), 'priority'], // task 1003750
+        [() => db.updateTaskValueSummary(1, 'corrected summary'), 'value_summary'], // task 1003817
       ];
       for (const [call, column] of setters) {
         const before = seen.length;
@@ -255,6 +256,33 @@ function shouldReserveMigrationNumber(task) {
     assert.ok(guardAt > 0 && firstWriteAt > 0 && guardAt < firstWriteAt, 'the priority bounds check must run before the first write, not after');
   });
 
+  // task 1003817: value_summary was the FOURTH write-once field, and the one
+  // that is the public record — the hall, /status and the Discord #ship-news
+  // line all read it. It had exactly one writer, the claim-resolve route, so
+  // `ship.js --regrade --summary` (no claim, by definition) could correct it in
+  // the PR and the merge commit and leave the record holding the first ship's
+  // sentence forever.
+  await test('PATCH /tasks/:id accepts value_summary so a re-graded summary reaches the record (task 1003817)', () => {
+    assert.ok(
+      /value_summary: \{ type: 'string', minLength: 1, maxLength: LIMITS\.VALUE_SUMMARY \}/.test(routesSrc),
+      'the PATCH schema must declare value_summary with the shared limit — rewritable, never blankable'
+    );
+    assert.ok(/const hasValueSummary = Object\.prototype\.hasOwnProperty\.call\(body, 'value_summary'\)/.test(routesSrc), 'value_summary is gated like every other field');
+    assert.ok(/if \(!hasParent &&[^)]*!hasValueSummary\b/.test(routesSrc), 'a value_summary-only PATCH is a supported request');
+    assert.ok(/db\.updateTaskValueSummary\(id, body\.value_summary\.trim\(\)\)/.test(routesSrc), 'the write goes through the allowlisted setter');
+    assert.ok(
+      /async function updateTaskValueSummary/.test(dbSrc) && /updateTaskValueSummary,/.test(dbSrc),
+      'the lifecycle db family must define it and re-export it (the ADR 0093 facade contract)'
+    );
+    // minLength 1 refuses "" but not "   ", and the write trims — so the
+    // whitespace guard is what actually keeps the record un-blankable. It must
+    // sit above the first write, like the priority bounds check above.
+    const blankGuardAt = routesSrc.indexOf("res.fail('bad_value_summary'");
+    const firstWriteAt2 = routesSrc.indexOf('await db.updateTaskKind(');
+    assert.ok(blankGuardAt > 0, 'a whitespace-only value_summary is refused, not trimmed into a blank record');
+    assert.ok(blankGuardAt < firstWriteAt2, 'and that refusal runs before the first write');
+  });
+
   await test('PATCH /tasks/:id accepts needs_migration so a wrong flag is correctable', () => {
     assert.ok(
       /needs_migration: \{ type: 'boolean' \}/.test(routesSrc),

package/tests/patch_gate_ordering.mjs

@@ -49,6 +49,10 @@ const REFUSALS = [
   // task 1003750: priority joined the PATCH surface; its bounds check is a
   // validation refusal like the rest, so it must settle before the first write.
   "'bad_priority'",
+  // task 1003817: value_summary joined the PATCH surface. Its refusal is the
+  // blank guard — minLength 1 stops "" but not "   ", and the write trims — so
+  // it must settle before the first write like every other validation.
+  "'bad_value_summary'",
   'badKind(res)',
   "'bad_discipline'",
 ];