@bongos/core 1.19.647 → 1.19.649

package/src/module-loader/loader.js

@@ -20,6 +20,10 @@ const path = require('node:path');
 const { validateManifest } = require('./manifest-schema');
 const { satisfies } = require('./semver');
 const { resolveCoreRoot, resolveInstanceRoot } = require('../instance-config');
+// Required DIRECTLY, never through src/module-api.js: the doorway pulls in auth
+// and would re-form the eval-time cycle coreVersion() exists to avoid.
+// src/module-seams.js is pure (it requires nothing), so this is cycle-safe.
+const { verifyPortsSatisfied } = require('../module-seams');
 
 // Collapse roots that resolve to the SAME absolute path, preserving order.
 // Normalizes via path.resolve so a cwd that arrives with a trailing '.'/'//'
@@ -129,6 +133,39 @@ function discoveredRegistry(opts) {
   return out;
 }
 
+// The ENABLED slice of the discovered set, in discovery order. The one place the
+// `isEnabled` gate is spelled out, so verification and mounting can never disagree
+// about which modules are in play.
+function enabledModules({ isEnabled } = {}, opts) {
+  return discovered(opts).loaded.filter(({ key }) => typeof isEnabled !== 'function' || isEnabled(key));
+}
+
+// BOOT-TIME seam verification (BV1.R41), run over the ENABLED manifests before a
+// single module router is mounted. THROWS on an unsatisfiable set — a module that
+// consumes a port no enabled module provides, or a port claimed by two of them.
+//
+// Why it throws rather than warns: without it the failure surfaces as resolve()'s
+// runtime throw the first time the seam is used — an arbitrarily long time after
+// boot, on a request path, in a process that reported healthy. ADR 0150's "fail
+// loud, never boot half-wired" is the same argument: refuse at boot, name the
+// module and the port, and let the operator fix the module set.
+//
+// Only the ENABLED set is checked, deliberately. A disabled module's `consumes` is
+// not a wiring error — it is a module that isn't there.
+function verifyEnabledPorts(enabled) {
+  const { ok, errors } = verifyPortsSatisfied(enabled.map(({ key, manifest }) => ({
+    key,
+    provides: manifest.provides || [],
+    consumes: manifest.consumes || [],
+  })));
+  if (ok) return;
+  throw new Error([
+    '[module-loader] unsatisfiable module wiring — refusing to boot half-wired:',
+    ...errors.map((e) => `  - ${e}`),
+    'Fix the enabled module set (config/modules.json, or a <PREFIX>_MODULE_<KEY> env override) so every consumed port has exactly one provider.',
+  ].join('\n'));
+}
+
 // Mount each discovered + ENABLED module's route factories onto `router`. A
 // module declares contributes.routes:["box"] → factory at modules/<key>/routes/box.js
 // exporting a function returning an express Router. Auth model: audit is composed
@@ -136,10 +173,18 @@ function discoveredRegistry(opts) {
 // its required rank via api.requireBuilder / api.requireRank (public read routes
 // need no gate). The BV1.R44 fitness check enforces that every write route is
 // rank-gated. Returns the count mounted. No-op when nothing is discovered/enabled.
+//
+// Verifies the seam wiring FIRST (verifyEnabledPorts, above). This is the boot hook
+// the check belongs on because it is the one hook every server that mounts modules
+// runs — the live API, platform-server, and the test harness alike — so the
+// verification cannot be skipped by adding an entrypoint, the way a separately
+// called check could be. It runs before the first `require` of a module's route
+// factory, so a half-wired instance never gets as far as loading module code.
 function mountModuleRoutes(router, { isEnabled } = {}, opts) {
+  const enabled = enabledModules({ isEnabled }, opts);
+  verifyEnabledPorts(enabled);
   let mounted = 0;
-  for (const { key, dir, manifest } of discovered(opts).loaded) {
-    if (typeof isEnabled === 'function' && !isEnabled(key)) continue;
+  for (const { dir, manifest } of enabled) {
     const routeKeys = (manifest.contributes && manifest.contributes.routes) || [];
     for (const rk of routeKeys) {
       const factory = require(path.join(dir, 'routes', `${rk}.js`));

package/src/module-seams.js

@@ -75,10 +75,14 @@ function listPorts() {
 
 // BOOT-TIME (manifest-level) verification, distinct from resolve()'s RUNTIME
 // throw: given the ENABLED modules' manifests, confirm every consumed port is
-// provided by some enabled module, and no port has two providers. The loader
-// (BV1.R41) runs this before mounting so a required capability with no provider
-// is caught at boot with a clear message — not as a surprise throw the first time
-// the seam is used. Pure (no registry mutation), so it is safe to run anytime.
+// provided by some enabled module, and no port has two providers. The loader's
+// mountModuleRoutes (BV1.R41) runs this via verifyEnabledPorts before mounting any
+// module router, and THROWS on a non-ok result, so a required capability with no
+// provider is caught at boot with a clear message — not as a surprise throw the
+// first time the seam is used. This function itself only REPORTS: it is pure (no
+// registry mutation, no throw), so it is safe to run anytime, and the loader owns
+// the decision to refuse the boot. Wired + regression-pinned by task 1003820,
+// which found it defined, exported, tested, and called by nothing.
 // manifests: [{ key, provides: [...], consumes: [...] }] → { ok, errors: [...] }.
 function verifyPortsSatisfied(manifests = []) {
   const provided = new Map(); // port -> [providerKey,...]

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/module_loader.mjs

@@ -155,6 +155,71 @@ test('mountModuleRoutes: mounts an enabled module router, skips a disabled one',
   loader._reset();
 });
 
+// ---------------------------------------------------------------------------
+// task 1003820 — the mount hook must VERIFY the seam wiring before it mounts.
+//
+// verifyPortsSatisfied was defined, exported through the doorway, and unit-tested
+// in isolation, but no production code called it: a module consuming a port no
+// enabled module provided booted clean and threw later, on a request path, out of
+// resolve(). These pin the CALL, not the function — see also the spawn-boot half
+// in tests/platform_boot.mjs, which is what actually turns red if the call site is
+// deleted (learning 1000154).
+// ---------------------------------------------------------------------------
+
+test('task 1003820: mountModuleRoutes refuses an enabled module consuming an unprovided port', () => {
+  loader._reset();
+  const factory = "module.exports = () => function moduleRoute(req, res, next) { next(); };";
+  const root = fixtureRoot({
+    consumer: {
+      manifest: validManifest('consumer', { consumes: ['reward'], contributes: { routes: ['main'] } }),
+      files: { 'routes/main.js': factory },
+    },
+  });
+  const used = [];
+  const fakeRouter = { use: (fn) => used.push(fn) };
+  assert.throws(
+    () => loader.mountModuleRoutes(fakeRouter, { isEnabled: () => true }, { roots: [root], core: '1.0.0' }),
+    (e) => /unsatisfiable module wiring/.test(e.message)
+      && /"consumer" consumes port "reward"/.test(e.message),
+    'the refusal names the module and the port it cannot satisfy'
+  );
+  assert.equal(used.length, 0, 'it refuses BEFORE requiring any module route factory');
+  loader._reset();
+});
+
+test('task 1003820: a DISABLED module’s unsatisfied consumes is not a wiring error', () => {
+  loader._reset();
+  const factory = "module.exports = () => function moduleRoute(req, res, next) { next(); };";
+  const root = fixtureRoot({
+    consumer: { manifest: validManifest('consumer', { consumes: ['reward'] }) },
+    plain: {
+      manifest: validManifest('plain', { contributes: { routes: ['main'] } }),
+      files: { 'routes/main.js': factory },
+    },
+  });
+  const used = [];
+  const fakeRouter = { use: (fn) => used.push(fn) };
+  // Only the ENABLED set is verified: a module that is off is a module that is
+  // not there, so its consumes names nothing that has to be provided.
+  const mounted = loader.mountModuleRoutes(fakeRouter, { isEnabled: (k) => k === 'plain' }, { roots: [root], core: '1.0.0' });
+  assert.equal(mounted, 1);
+  loader._reset();
+});
+
+test('task 1003820: mountModuleRoutes refuses two enabled providers of one port', () => {
+  loader._reset();
+  const root = fixtureRoot({
+    a: { manifest: validManifest('a', { provides: ['reward'] }) },
+    b: { manifest: validManifest('b', { provides: ['reward'] }) },
+  });
+  assert.throws(
+    () => loader.mountModuleRoutes({ use: () => {} }, { isEnabled: () => true }, { roots: [root], core: '1.0.0' }),
+    (e) => /provided by more than one enabled module/.test(e.message),
+    'the single-provider invariant is enforced at boot, not at first resolve()'
+  );
+  loader._reset();
+});
+
 test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49/R72)', () => {
   // dev-box graduated first (modules/dev-box/, BV1.R43), art-pipeline next
   // (BV1.R48 / task 1417), discord next (BV1.R47 / task 1416), game next
@@ -352,6 +417,9 @@ test('the demo proof module mounts + serves through the loader (BV1.R52 / task 1
 
   const used = [];
   const fakeRouter = { use: (fn) => used.push(fn) };
+  // Since task 1003820 this also proves the SHIPPED enabled set is satisfiable:
+  // mountModuleRoutes verifies the seam wiring first and throws on a half-wired
+  // set, so a manifest change that strands a consumed port reds this test.
   const mounted = loader.mountModuleRoutes(fakeRouter, { isEnabled: isModuleEnabled });
   assert.ok(mounted >= 1, 'at least the demo router mounted');
 

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'",
 ];

package/tests/patch_value_summary_e2e.mjs

@@ -0,0 +1,142 @@
+// tests/patch_value_summary_e2e.mjs — PATCH /tasks/:id value_summary over real
+// HTTP (task 1003817).
+//
+// WHY A SECOND FILE. migration_allocation.mjs pins the two halves in isolation:
+// the route's schema/gate/write as SOURCE TEXT, and db.updateTaskValueSummary
+// driven against a stubbed pool so the real `SET value_summary =` SQL is proven.
+// Neither exercises the WIRING, and the wiring is where this class of change
+// fails — the whole defect being fixed is a value that reached three consumers
+// and never reached the row. Specifically, source text cannot see that the
+// route's STRICT validator (ADR 0118) actually admits the new field: before this
+// task, `value_summary` on this route was a hard 400 `unknown_field`, and a
+// schema entry that is subtly wrong (mis-typed, mis-named, declared on the
+// create schema instead) fails exactly the same way while every text assertion
+// still passes.
+//
+// So this drives the REAL router over a real socket with the db layer stubbed at
+// the module boundary, the way task_visual_route_gate.mjs and
+// goal_archive_route_e2e.mjs do — the router under test is the shipped one.
+//
+// THE CASES WORTH THE FILE: (2) proves acceptance 1 end to end — a corrected
+// summary reaches the write. (4) and (5) prove acceptance 2 from the other side:
+// an OMITTED field must not touch the row at all, and a whitespace-only one must
+// be refused rather than trimmed into a blank record. `value_summary` is the
+// public shipped-value sentence, so blanking it is the one failure mode that is
+// worse than the bug.
+//
+// Run:  node tests/patch_value_summary_e2e.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+process.env.NODE_ENV = 'test';
+
+const express = require('express');
+const api = require('../src/module-api.js');
+const db = require('../modules/lifecycle/db.js');
+
+api.requireBuilder = (req, _res, next) => { req.builder = { id: '3', rank: 'archon' }; next(); };
+api.requirePermission = () => (req, _res, next) => next();
+
+const TASK = { id: 5150, title: 'a task', status: 'completed', version_id: 'BONGOS-V2', value_summary: 'the FIRST ship sentence' };
+
+// Every write the handler can reach, recorded rather than performed — so a test
+// can assert not only what WAS written but that nothing else was.
+let writes = [];
+db.getTask = async () => ({ ...TASK });
+db.updateTaskValueSummary = async (id, v) => { writes.push({ fn: 'value_summary', id, v }); return { ...TASK, value_summary: v }; };
+db.updateTaskTitle = async (id, v) => { writes.push({ fn: 'title', id, v }); return { ...TASK, title: v }; };
+db.updateTaskKind = async (id, v) => { writes.push({ fn: 'kind', id, v }); return { ...TASK, kind: v }; };
+
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => {
+  res.fail = (code, statusOrOpts, details) => {
+    const o = typeof statusOrOpts === 'number' ? { status: statusOrOpts } : (statusOrOpts || {});
+    return res.status(o.status || 400).json({ error: code, message: o.message, details: o.details ?? details });
+  };
+  next();
+});
+app.use('/api/gds', require('../modules/lifecycle/routes/tasks.js')());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/gds`;
+
+const patch = async (body) => {
+  writes = [];
+  const r = await fetch(`${base}/tasks/${TASK.id}`, {
+    method: 'PATCH',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return { status: r.status, body: await r.json().catch(() => null), writes };
+};
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+console.log('PATCH /tasks/:id value_summary (task 1003817):');
+
+// 1. The regression guard: this is what the route used to do with the field.
+await t('the field is no longer rejected as an unknown field', async () => {
+  const r = await patch({ value_summary: 'anything' });
+  assert.notEqual(r.body && r.body.error, 'unknown_field',
+    'the strict validator must ADMIT value_summary — a missing schema entry looks exactly like the original bug');
+  assert.notEqual(r.body && r.body.error, 'no_supported_fields',
+    'and the supported-fields guard must count it, or a value_summary-only PATCH is refused');
+});
+
+// 2. ACCEPTANCE 1, end to end.
+await t('a corrected summary reaches the write, trimmed', async () => {
+  const r = await patch({ value_summary: '  the CORRECTED sentence  ' });
+  assert.equal(r.status, 200, `expected 200, got ${r.status} ${JSON.stringify(r.body)}`);
+  assert.deepEqual(r.writes, [{ fn: 'value_summary', id: TASK.id, v: 'the CORRECTED sentence' }]);
+});
+
+// 3. It composes with the other planning fields rather than replacing them.
+await t('it can travel with another field in one body', async () => {
+  const r = await patch({ value_summary: 'both', title: 'new title' });
+  assert.equal(r.status, 200);
+  const fns = r.writes.map((w) => w.fn).sort();
+  assert.deepEqual(fns, ['title', 'value_summary']);
+});
+
+// 4. ACCEPTANCE 2, from the route's side.
+await t('ACCEPTANCE 2: an omitted value_summary writes nothing at all', async () => {
+  const r = await patch({ title: 'only the title' });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.writes.filter((w) => w.fn === 'value_summary'), [],
+    'an omitted field must not reach the column — not even to write back what was there');
+});
+
+// 5. The failure mode worse than the bug.
+await t('a blank or whitespace-only summary is REFUSED, never written', async () => {
+  for (const bad of ['', '   ', '\t\n ']) {
+    const r = await patch({ value_summary: bad });
+    assert.equal(r.status, 400, `${JSON.stringify(bad)} must be refused, got ${r.status}`);
+    assert.deepEqual(r.writes, [], `${JSON.stringify(bad)} must not reach the column`);
+  }
+});
+
+// 6. And the refusal has to be diagnosable, since the caller is usually a script.
+await t('the refusal names the field and says omission is how you leave it alone', async () => {
+  const r = await patch({ value_summary: '   ' });
+  assert.equal(r.body.error, 'bad_value_summary');
+  assert.match(r.body.message, /never blanked/i);
+  assert.match(r.body.message, /omit/i);
+});
+
+// 7. The cap is the shared one, not a number re-typed on this route.
+await t('an over-long summary is refused by the shared LIMITS cap', async () => {
+  const r = await patch({ value_summary: 'x'.repeat(api.LIMITS.VALUE_SUMMARY + 1) });
+  assert.equal(r.status, 400);
+  assert.deepEqual(r.writes, []);
+});
+
+server.close();
+console.log(`\npatch_value_summary_e2e: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/platform_boot.mjs

@@ -284,3 +284,56 @@ test('task 1002419: a real `node src/platform-server.js` boot announces the reco
     child.kill('SIGKILL');
   }
 });
+
+// ---------------------------------------------------------------------------
+// task 1003820 — a half-wired module set must REFUSE the boot.
+//
+// The mutation-proof half of the wiring guard. tests/module_loader.mjs calls
+// mountModuleRoutes directly, so it stays green if the verifyEnabledPorts call
+// site is deleted; this spawns the real entrypoint the way docker-entrypoint.sh
+// does and asserts the process dies with the wiring error, so removing the call
+// turns it red (learning 1000154 — the same shape as task 1002419 above).
+//
+// The unsatisfiable set is built from REAL modules via a documented env knob, not
+// a fixture: economy provides the `reward` port and ideas consumes it, both
+// default:true, so turning economy off strands ideas. DB-free — the refusal
+// happens while the router is being built, long before anything opens a socket.
+// ---------------------------------------------------------------------------
+
+test('task 1003820: platform-server refuses to boot when an enabled module consumes an unprovided port', async () => {
+  const port = await freePort();
+  const child = spawn(process.execPath, [path.join(REPO_ROOT, 'src', 'platform-server.js')], {
+    cwd: REPO_ROOT,
+    env: {
+      ...process.env,
+      PORT: String(port),
+      HOST: '127.0.0.1',
+      // economy provides "reward"; ideas consumes it and stays on.
+      CLOUDBONGOS_MODULE_ECONOMY: '0',
+    },
+  });
+
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; });
+  child.stderr.on('data', (d) => { out += d; });
+
+  // SIGKILL in a finally: if the guard regresses, the child boots CLEANLY and never
+  // exits, so without this the suite would hang on a live server instead of failing.
+  try {
+    const code = await new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`platform-server stayed up; it must refuse a half-wired boot. Log:${out}`)),
+        20_000
+      );
+      child.on('error', (e) => { clearTimeout(timer); reject(e); });
+      child.on('exit', (c) => { clearTimeout(timer); resolve(c); });
+    });
+
+    assert.notEqual(code, 0, `the boot must FAIL, not come up half-wired (exit ${code}). Log:${out}`);
+    assert.match(out, /unsatisfiable module wiring/, 'the refusal says what is wrong');
+    assert.match(out, /"ideas" consumes port "reward"/, 'it names the module and the port');
+    assert.doesNotMatch(out, /listening/, 'it never reaches the listen announcement');
+  } finally {
+    child.kill('SIGKILL');
+  }
+});

package/tests/ship_cannot_lie.mjs

@@ -242,15 +242,16 @@ test('the refusal is wired into the regrade path, before any grade spend', () =>
     .replace(/\/\/[^\n]*/g, '')), 'usage does not offer --notes');
 });
 
-test('ACCEPTANCE 3: --summary reaches the GRADER on a re-grade but never the task row', () => {
+test('ACCEPTANCE 3: --summary reaches the grader AND the task row on a re-grade', () => {
   // Task 1003702's third acceptance asked whether --summary reaches the stored
-  // value_summary on a re-grade. It does NOT, and that is a separate defect
-  // filed as task 1003817 (it needs a server route change; this task's fix is
-  // CLI-only). Pinned here rather than left in prose for the reason this whole
-  // file exists: the panel reads the DIFF, so an answer that lives only in ship
-  // notes is an answer nobody can check — which is the very bug task 1003702 is.
+  // value_summary on a re-grade. It did NOT — a separate defect, filed and fixed
+  // as task 1003817, which added value_summary to the PATCH /tasks/:id schema and
+  // the persistRegradeSummary call below. This test used to pin the ABSENCE of a
+  // writer; it now pins its PRESENCE, for the reason this whole file exists: the
+  // panel reads the DIFF, so an answer that lives only in ship notes is an answer
+  // nobody can check — which is the very bug task 1003702 was.
   const src = readFileSync(new URL('../scripts/gds/ship-flow.js', import.meta.url), 'utf8');
-  const regrade = src.slice(src.indexOf('async function regradeMain'));
+  const regrade = src.slice(src.indexOf('async function persistRegradeSummary'));
   const code = regrade.replace(/\/\/[^\n]*/g, ''); // comments describe, they do not write
 
   // Half one — the threading is intact, so nothing regressed: --summary still
@@ -261,10 +262,38 @@ test('ACCEPTANCE 3: --summary reaches the GRADER on a re-grade but never the tas
     'the summary still reaches the grader prompt');
   assert.match(code, /valueSummary: summary/, 'and the completion card');
 
-  // Half two — and there is no writer. A `value_summary:` KEY would be a request
-  // payload; the legitimate read is `task.value_summary`, dot-access. If someone
-  // later adds the write (task 1003817), this assertion is what tells them to
-  // update the comment above `const summary` rather than leave it lying.
-  assert.ok(!/[^.]\bvalue_summary\s*:/.test(code),
-    'regradeMain writes value_summary nowhere — see task 1003817');
+  // Half two — and now there IS a writer, wired into the path (the (1) lesson:
+  // a helper nothing calls is not a fix).
+  assert.match(code, /patchTasksId\(\{[\s\S]{0,80}?body: \{ value_summary: next \}/,
+    'persistRegradeSummary PATCHes value_summary onto the task row');
+  assert.match(code, /await persistRegradeSummary\(\{ taskId, summaryArg, task \}\)/,
+    'and regradeMain actually calls it');
+});
+
+test('a re-grade that omits --summary leaves the stored value_summary alone', () => {
+  // ACCEPTANCE 2. The row must survive an omitted flag: `summary` falls back to
+  // task.value_summary, so writing that fallback back would be a no-op at best
+  // and, on any future refactor of the fallback, a way to overwrite the record
+  // with something derived. persistRegradeSummary keys on summaryArg — the RAW
+  // flag — not on the resolved `summary`, and returns before the PATCH when it
+  // is absent. Pinned as source structure because the alternative (a live
+  // re-grade) costs a 4-worker panel run.
+  const src = readFileSync(new URL('../scripts/gds/ship-flow.js', import.meta.url), 'utf8');
+  const start = src.indexOf('async function persistRegradeSummary');
+  const fn = src.slice(start, src.indexOf('async function regradeMain', start));
+  const code = fn.replace(/\/\/[^\n]*/g, '');
+
+  // It reads the raw flag, never the resolved fallback.
+  assert.match(code, /const next = \(summaryArg \|\| ''\)\.trim\(\)/,
+    'the guard keys on the raw --summary, not the stored-value fallback');
+
+  // Both early returns precede the only PATCH in the function.
+  const omitted = code.indexOf("reason: 'omitted'");
+  const unchanged = code.indexOf("reason: 'unchanged'");
+  const patch = code.indexOf('patchTasksId');
+  assert.ok(omitted !== -1 && omitted < patch, 'an omitted --summary returns before the write');
+  assert.ok(unchanged !== -1 && unchanged < patch, 'an unchanged --summary returns before the write too');
+
+  // And a failed write never aborts the re-grade — no process.exit, no throw.
+  assert.ok(!/process\.exit/.test(code), 'a summary that will not persist must not kill the re-grade');
 });