@bongos/core 1.19.286 → 1.19.287

package/src/bongos/route-rank-check.js

@@ -363,6 +363,10 @@ const MODULE_EXPECTED_RANKS = {
     // out of asking/accepting, and any gate removal.
     'GET /goals/inbox': 'any-builder',
     'PATCH /goals/:id/visibility': 'any-builder',
+    // task 1003102: a goal's own authority (owner|manager|Archon, in-handler
+    // authorizeGoalManagement) corrects its own title/description — same shape
+    // and same gate as the visibility route above.
+    'PATCH /goals/:id': 'any-builder',
     'POST /goals/:id/requests': 'any-builder',
     'POST /goals/:id/requests/:reqId/respond': 'any-builder',
     'POST /goals/:id/invitations': 'any-builder',
@@ -381,6 +385,9 @@ const MODULE_EXPECTED_RANKS = {
     // planning/building version, so the in-handler wall is load-bearing — and an
     // unauthorized caller is masked as bad_goal_id. Unsatisfy stays Archon.
     'POST /versions/:id/done-when': 'metic+archon',
+    // task 1003102: correcting a criterion's words is the SAME authority as
+    // authoring them, so this is pinned to the create gate, not to satisfy.
+    'PATCH /done-when/:criterionId': 'metic+archon',
     // ...and its inverse stays ARCHON. Un-flipping a CONFIRMED criterion rewrites
     // shipped scope-truth; ADR 0154's whole safety argument is that the backward
     // ratchet did not move with the create. Previously unpinned — pinned here so a
@@ -402,6 +409,10 @@ const MODULE_EXPECTED_RANKS = {
   // criterion). Metic+ may file the proposal; ADR 0157 also lets Metic ratify it
   // (`idea.ratify` archon→metic) — the rank that triages ideas now also ratifies them.
   ideas: {
+    // task 1003102: an idea's AUTHOR may correct their own text, so this is
+    // requireBuilder + an in-handler author|triage gate. Deliberately a separate
+    // route from the triage-gated PATCH /inbox/:id, which keeps its own rank.
+    'PATCH /inbox/:id/body': 'any-builder',
     'POST /inbox/:id/ratify': 'perm:idea.ratify',
   },
   // Cross-builder memory READS — the counterpart to the BFG cross-builder WRITE the

package/src/module-api.js

@@ -999,8 +999,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.284 with no explicit bump. run 32531963073. (task 1002620)
 //   1.19.286 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.285 with no explicit bump. run 32533647172. (task 1002620)
+//   1.19.287 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.286 with no explicit bump. run 32539649191. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.286'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.287'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/prose_edits.mjs

@@ -0,0 +1,339 @@
+// tests/prose_edits.mjs — durable prose is CORRECTABLE (task 1003102 / idea 1000740).
+//
+// A goal's title/description, an idea's body and a criterion's text were all
+// write-once: created, then reachable only by prod SQL. The incident that forced
+// it — a shell-quoting error stripped backtick-wrapped literals out of three
+// criteria on goal 1000073 AT CREATION TIME, leaving text that was wrong with no
+// API path to fix it.
+//
+// What these pin, in order of how badly getting them wrong would hurt:
+//
+//  1. THE SATISFIED-CRITERION REFUSAL. This task's own item 5 asked for a
+//     decision and it is a real one: a satisfied criterion is a claim somebody
+//     VERIFIED, so re-wording it re-points that verification at text nobody
+//     checked. Refused by name, with the two-step unsatisfy→edit→re-satisfy
+//     escape so the undo is recorded rather than implicit.
+//  2. ABSENT FIELDS ARE NOT BLANKED. A title-only PATCH must not wipe a
+//     description — and a goal description is where a whole planning spec can
+//     live (goal 1000062 carries a decision record in its description).
+//  3. THE AUDIT DELTA. The global write-audit middleware records only the
+//     REQUEST body (the NEW text), so without an explicit from/to the trail says
+//     a field changed and never what it replaced.
+//  4. THE ROUTE-RANK SHAPE. The idea-author path is a NEW route rather than a
+//     new field on the triage-gated PATCH /inbox/:id, precisely so nothing
+//     already pinned gets widened to reach one field.
+//
+// Run:  node tests/prose_edits.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const goalEdits = require('../modules/lifecycle/goal-edits.js');
+const { checkRouteRanks, MODULE_EXPECTED_RANKS, pinMismatch } = require('../src/bongos/route-rank-check.js');
+const { test, summary } = makeRunner();
+
+// ---- 1. the decision: a satisfied criterion's text is frozen ---------------
+
+await test('DECISION: a satisfied criterion refuses the edit, and names the recorded way round it', () => {
+  const r = goalEdits.criterionProseRefusal({ id: 5, satisfied: true, criterion_md: 'x' });
+  assert.equal(r.code, 'criterion_satisfied');
+  assert.equal(r.status, 409);
+  assert.match(r.message, /verified/i, 'says WHY, not just no');
+  assert.match(r.message, /unsatisfy/i, 'and names the escape hatch');
+});
+
+await test('DECISION: an UNSATISFIED criterion is editable — nobody has certified it', () => {
+  assert.equal(goalEdits.criterionProseRefusal({ id: 5, satisfied: false, criterion_md: 'x' }), null);
+});
+
+await test('a missing criterion is a 404, distinct from the 409 freeze', () => {
+  assert.equal(goalEdits.criterionProseRefusal(null).status, 404);
+  assert.equal(goalEdits.criterionProseRefusal(undefined).code, 'criterion_not_found');
+});
+
+// ---- 2. absent fields are left alone --------------------------------------
+
+function fakePool(...results) {
+  const calls = [];
+  return { calls, async query(sql, params) { calls.push({ sql, params }); return results[calls.length - 1] || { rows: [] }; } };
+}
+const GOAL = { id: 7, title: 'Old title', description: 'A whole spec lives here.' };
+
+await test('THE HAZARD: a title-only PATCH preserves the description verbatim', async () => {
+  const pool = fakePool({ rows: [GOAL] }, { rows: [{ ...GOAL, title: 'New title' }] });
+  const out = await goalEdits.updateGoalProse({ goalId: 7, patch: { title: 'New title' } }, { pool });
+  // the UPDATE must carry the ORIGINAL description, not null/undefined
+  assert.equal(pool.calls[1].params[2], 'A whole spec lives here.', 'description must be carried through untouched');
+  assert.deepEqual(out.deltas.map((d) => d.field), ['title'], 'and only the title reports a delta');
+});
+
+await test('a description-only PATCH preserves the title', async () => {
+  const pool = fakePool({ rows: [GOAL] }, { rows: [GOAL] });
+  await goalEdits.updateGoalProse({ goalId: 7, patch: { description: 'new' } }, { pool });
+  assert.equal(pool.calls[1].params[1], 'Old title');
+});
+
+await test('an explicitly EMPTY description is honoured (clearing is not the same as omitting)', async () => {
+  const pool = fakePool({ rows: [GOAL] }, { rows: [GOAL] });
+  await goalEdits.updateGoalProse({ goalId: 7, patch: { description: '' } }, { pool });
+  assert.equal(pool.calls[1].params[2], '', 'an explicit empty string means clear it');
+});
+
+await test('a no-change PATCH writes nothing and says so', async () => {
+  const pool = fakePool({ rows: [GOAL] });
+  const out = await goalEdits.updateGoalProse({ goalId: 7, patch: { title: GOAL.title } }, { pool });
+  assert.equal(pool.calls.length, 1, 'no UPDATE issued');
+  assert.equal(out.unchanged, true);
+  assert.deepEqual(out.deltas, []);
+});
+
+await test('a missing goal returns null rather than inventing a row', async () => {
+  assert.equal(await goalEdits.updateGoalProse({ goalId: 9, patch: { title: 'x' } }, { pool: fakePool({ rows: [] }) }), null);
+});
+
+// ---- 3. the audit delta ---------------------------------------------------
+
+await test('AUDIT: a delta names the field and both sides, with real lengths', () => {
+  const d = goalEdits.proseDelta('description', 'before text', 'after text');
+  assert.equal(d.field, 'description');
+  assert.equal(d.from, 'before text');
+  assert.equal(d.to, 'after text');
+  assert.equal(d.from_len, 11);
+  assert.equal(d.to_len, 10);
+});
+
+await test('AUDIT: an unchanged value yields NO delta (a no-op PATCH is not an edit)', () => {
+  assert.equal(goalEdits.proseDelta('title', 'same', 'same'), null);
+});
+
+await test('AUDIT: long prose is CLIPPED — the audit line is not a revision store', () => {
+  const d = goalEdits.proseDelta('description', 'x'.repeat(500), 'y'.repeat(500));
+  assert.ok(d.from.length <= goalEdits.AUDIT_EXCERPT, `from clipped (${d.from.length})`);
+  assert.ok(d.to.length <= goalEdits.AUDIT_EXCERPT);
+  assert.match(d.from, /…$/, 'and says it was clipped');
+  assert.equal(d.from_len, 500, 'while still reporting the TRUE length');
+});
+
+await test('AUDIT: newlines are flattened so one edit is one log line', () => {
+  const d = goalEdits.proseDelta('description', 'a\nb\n\nc', 'z');
+  assert.equal(d.from, 'a b c');
+});
+
+await test('AUDIT: logProseEdit emits one line per changed field, and nothing on a no-op', () => {
+  const lines = [];
+  goalEdits.logProseEdit('goal', 7, 42, [goalEdits.proseDelta('title', 'a', 'b')], (m) => lines.push(m));
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /goal 7 title edited by builder 42/);
+  goalEdits.logProseEdit('goal', 7, 42, [], (m) => lines.push(m));
+  goalEdits.logProseEdit('goal', 7, 42, null, (m) => lines.push(m));
+  assert.equal(lines.length, 1, 'no deltas => no noise');
+});
+
+// ---- 4. the route-rank shape ----------------------------------------------
+
+await test('ROUTE SHAPE: all three new routes exist and classify to their pins', () => {
+  const res = checkRouteRanks();
+  const byKey = new Map();
+  for (const r of res.routes) if (!byKey.has(r.key)) byKey.set(r.key, r);
+  const expect = [
+    ['PATCH /goals/:id', MODULE_EXPECTED_RANKS.lifecycle, 'any-builder'],
+    ['PATCH /done-when/:criterionId', MODULE_EXPECTED_RANKS.lifecycle, 'metic+archon'],
+    ['PATCH /inbox/:id/body', MODULE_EXPECTED_RANKS.ideas, 'any-builder'],
+  ];
+  for (const [key, pins, want] of expect) {
+    const row = byKey.get(key);
+    assert.ok(row, `${key} must exist in the live route set`);
+    assert.equal(pins[key], want, `${key} must be pinned ${want}`);
+    assert.equal(pinMismatch(pins[key], row), null, `${key} classification must match its pin`);
+  }
+});
+
+await test('ROUTE SHAPE: the triage-gated PATCH /inbox/:id was NOT widened to reach body_md', () => {
+  // The whole reason the author path is its own route. If someone later drops
+  // this route's permission gate to add body_md, this fails.
+  const res = checkRouteRanks();
+  const row = res.routes.find((r) => r.key === 'PATCH /inbox/:id');
+  assert.ok(row, 'the triage route still exists');
+  assert.equal(row.rank, 'metic+archon', 'PATCH /inbox/:id must keep its triage-level gate');
+  const src = readFileSync(new URL('../modules/ideas/routes/inbox.js', import.meta.url), 'utf8');
+  const start = src.indexOf("router.patch('/inbox/:id',");
+  const body = src.slice(start, src.indexOf('router.', start + 20));
+  // Assert on the VALIDATION SCHEMA, not on any mention of the string: that route
+  // already discusses body_md in a comment (about it not being parseable as a
+  // criterion spec), so a bare /body_md/ match would fail on prose forever.
+  const schema = body.slice(body.indexOf('validateOrRespond'), body.indexOf('})) return;'));
+  assert.ok(!/body_md/.test(schema), 'body_md must NOT be an accepted FIELD on the triage route');
+});
+
+await test('ROUTE SHAPE: the author gate is fail-closed and uses the array form of rankMeetsThreshold', () => {
+  const api = require('../src/module-api');
+  // The array form is the correct one — a bare string throws inside reduce, which
+  // is exactly the bug a silent fallback would have hidden.
+  assert.equal(api.rankMeetsThreshold('xenos', ['metic', 'archon']), false);
+  assert.equal(api.rankMeetsThreshold('thetes', ['metic', 'archon']), false);
+  assert.equal(api.rankMeetsThreshold('metic', ['metic', 'archon']), true);
+  assert.equal(api.rankMeetsThreshold(null, ['metic', 'archon']), false, 'unknown rank fails closed');
+  const src = readFileSync(new URL('../modules/ideas/routes/inbox.js', import.meta.url), 'utf8');
+  assert.match(src, /rankMeetsThreshold\(req\.builder\.rank, \['metic', 'archon'\]\)/, 'array form, not a bare string');
+  assert.match(src, /captured_by != null/, 'and the author check treats a NULL author as not-you');
+});
+
+await test('ROUTE SHAPE: the goal + visibility handlers share ONE authority gate', () => {
+  // Both were moved into goal-edits.js precisely because they are the same kind
+  // of operation behind the same gate; this pins that they still are.
+  const src = readFileSync(new URL('../modules/lifecycle/goal-edits.js', import.meta.url), 'utf8');
+  assert.equal((src.match(/authorizeGoalManagement\(/g) || []).length, 2, 'prose + visibility, both gated');
+  assert.equal(typeof goalEdits.goalProseHandler, 'function');
+  assert.equal(typeof goalEdits.goalVisibilityHandler, 'function');
+  const routes = readFileSync(new URL('../modules/lifecycle/routes/goals.js', import.meta.url), 'utf8');
+  assert.match(routes, /router\.patch\('\/goals\/:id',/, 'the REGISTRATION stays in the route file so route-rank-check sees it');
+  assert.match(routes, /router\.patch\('\/goals\/:id\/visibility',/);
+});
+
+// ---- 5. THE HANDLERS ARE ACTUALLY INVOKED ---------------------------------
+// The gap that let a blocker through on the first cut of this task: the handler
+// body, once extracted into goal-edits.js, still called `proseEdits.updateGoalProse`
+// — a name that exists only in the ROUTE file — so PATCH /goals/:id threw a
+// ReferenceError and 500'd on every call. Every test passed, because they
+// exercised the helpers and the route CLASSIFICATION and never the handler.
+// So: invoke it. A factory-built handler with fakes is cheap to drive.
+
+function fakeReqRes({ body = {}, params = {}, builder = { id: 42, rank: 'archon' } } = {}) {
+  const res = {
+    code: null, payload: null, statusCode: 200,
+    json(p) { this.payload = p; return this; },
+    status(c) { this.statusCode = c; return this; },
+    fail(code, statusOrOpts, extra) { this.code = code; this.statusCode = typeof statusOrOpts === 'number' ? statusOrOpts : (statusOrOpts && statusOrOpts.status) || 500; this.payload = extra || statusOrOpts; return this; },
+  };
+  return { req: { body, params, builder, ip: '127.0.0.1', get: () => 'test' }, res };
+}
+const deps = {
+  db: {
+    getGoal: async () => ({ id: 7, status: 'open', created_by: 42, version_id: 'V1' }),
+    getGoalMember: async () => ({ membership_kind: 'lead' }),
+  },
+  authorizeGoalManagement: () => ({ ok: true }),
+  validateOrRespond: () => false,
+  parseId: () => 7,
+  LIMITS: { TITLE: 200, DESCRIPTION: 50000 },
+};
+
+await test('INVOKED: goalProseHandler runs end-to-end and returns the updated goal', async () => {
+  const recorded = [];
+  const handler = goalEdits.goalProseHandler({
+    ...deps,
+    update: async ({ goalId, patch }) => ({ goal: { id: goalId, ...patch }, deltas: [goalEdits.proseDelta('title', 'Old', patch.title)] }),
+    record: async (...a) => { recorded.push(a); },
+  });
+  const { req, res } = fakeReqRes({ body: { title: 'Corrected title' } });
+  await handler(req, res);
+  // THE REGRESSION: the extracted handler called `proseEdits.updateGoalProse`, a
+  // name that exists only in the route file, so this threw ReferenceError and the
+  // catch turned it into a 500 on every legitimate call.
+  assert.equal(res.code, null, `must not fail — got ${res.code}`);
+  assert.equal(res.payload.ok, true);
+  assert.equal(res.payload.goal.title, 'Corrected title');
+  assert.deepEqual(res.payload.deltas.map((d) => d.field), ['title']);
+  assert.equal(recorded.length, 1, 'and the edit is recorded (audit row + log)');
+});
+
+await test('INVOKED: a PATCH with no editable field is refused before any write', async () => {
+  const handler = goalEdits.goalProseHandler(deps);
+  const { req, res } = fakeReqRes({ body: { unrelated: 'x' } });
+  await handler(req, res);
+  assert.equal(res.code, 'nothing_to_update');
+  assert.equal(res.statusCode, 400);
+});
+
+await test('INVOKED: an unauthorized actor is refused and NOTHING is written', async () => {
+  let wrote = false;
+  const handler = goalEdits.goalProseHandler({
+    ...deps,
+    authorizeGoalManagement: () => ({ ok: false, status: 403, body: { error: 'not_owner_or_manager' } }),
+    db: { ...deps.db, getGoal: async () => { return { id: 7, status: 'open' }; } },
+  });
+  const { req, res } = fakeReqRes({ body: { title: 'sneaky' } });
+  await handler(req, res);
+  assert.equal(res.statusCode, 403);
+  assert.equal(res.payload.error, 'not_owner_or_manager');
+  assert.equal(wrote, false);
+});
+
+await test('the file no longer references a name that does not exist in it', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/goal-edits.js', import.meta.url), 'utf8');
+  assert.ok(!/proseEdits\./.test(src), 'the extracted handler must call its LOCAL helpers');
+});
+
+// ---- 6. the audit row is PERSISTED, not just logged ------------------------
+
+await test('AUDIT ROW: a prose edit writes a queryable audit_log row carrying the delta', async () => {
+  const rows = [];
+  const logs = [];
+  const { req } = fakeReqRes();
+  await goalEdits.recordProseEdit('goal', 7, req, [goalEdits.proseDelta('title', 'a', 'b')], {
+    insertAuditLog: async (row) => { rows.push(row); },
+    log: (m) => logs.push(m),
+  });
+  assert.equal(rows.length, 1, 'the delta must reach audit_log, not only stdout');
+  assert.equal(rows[0].route, 'goal:7:prose-edit');
+  assert.equal(rows[0].method, 'PATCH');
+  assert.match(rows[0].requestBodyRedacted, /"from":"a"/);
+  assert.match(rows[0].requestBodyRedacted, /"to":"b"/);
+  assert.equal(rows[0].builderId, 42);
+  assert.equal(logs.length, 1, 'and it still logs');
+});
+
+await test('AUDIT ROW: a no-op edit writes no row, and an audit failure never throws', async () => {
+  const rows = [];
+  const { req } = fakeReqRes();
+  await goalEdits.recordProseEdit('goal', 7, req, [], { insertAuditLog: async (r) => rows.push(r), log: () => {} });
+  assert.equal(rows.length, 0, 'nothing changed => no audit row');
+  const logs = [];
+  await goalEdits.recordProseEdit('goal', 7, req, [goalEdits.proseDelta('title', 'a', 'b')], {
+    insertAuditLog: async () => { throw new Error('db down'); }, log: (m) => logs.push(m),
+  });
+  assert.match(logs.join('\n'), /AUDIT GAP/, 'a failed audit write is loud, not swallowed');
+});
+
+// ---- 7. the criterion PATCH enforces the OWNERSHIP half, not just the rank --
+
+await test('OWNERSHIP: the criterion PATCH runs authorizeCriterionCreate, like its CREATE sibling', () => {
+  // The second blocker on the first cut: the route claimed "gated like criterion
+  // CREATION" while reusing only the rank-floor half, letting any Metic rewrite
+  // criteria on a goal they had nothing to do with.
+  const src = readFileSync(new URL('../modules/lifecycle/routes/done-when.js', import.meta.url), 'utf8');
+  const start = src.indexOf("router.patch('/done-when/:criterionId'");
+  assert.ok(start > 0, 'the route exists');
+  const body = src.slice(start, src.indexOf('router.', start + 30));
+  assert.match(body, /authorizeCriterionCreate\(/, 'the per-goal ownership wall must run here too');
+  assert.match(body, /getGoalMember\(/, 'membership is resolved for the non-Archon case');
+  assert.match(body, /requirePermission\('criterion\.create'\)/, 'and the rank floor still applies');
+  // ordering: authority before the satisfied-freeze, so an outsider learns nothing about state
+  assert.ok(body.indexOf('authorizeCriterionCreate(') < body.indexOf('criterionProseRefusal('),
+    'authority is decided BEFORE any state-based refusal');
+});
+
+await test('AUDIT ROW: ALL THREE prose surfaces persist a row, not just log (item 4 says all three)', () => {
+  // The gap the grader caught on re-grade: goals + criteria went through
+  // recordProseEdit (which writes audit_log) while the ideas route only called
+  // api.logger. A log line is not an audit row — not queryable, and it rotates.
+  // Asserted per-surface so a future surface cannot quietly ship log-only.
+  const goalEditsSrc = readFileSync(new URL('../modules/lifecycle/goal-edits.js', import.meta.url), 'utf8');
+  assert.match(goalEditsSrc, /insertAuditLog/, 'goal + criterion path persists via recordProseEdit');
+
+  const doneWhenSrc = readFileSync(new URL('../modules/lifecycle/routes/done-when.js', import.meta.url), 'utf8');
+  assert.match(doneWhenSrc, /recordProseEdit\('criterion'/, 'the criterion route uses the persisting helper');
+
+  const ideasSrc = readFileSync(new URL('../modules/ideas/routes/inbox.js', import.meta.url), 'utf8');
+  const bodyRoute = ideasSrc.slice(ideasSrc.indexOf("router.patch('/inbox/:id/body'"));
+  const upTo = bodyRoute.slice(0, bodyRoute.indexOf('router.') > 0 ? bodyRoute.indexOf('router.', 30) : bodyRoute.length);
+  assert.match(upTo, /api\.insertAuditLog\(/, 'the ideas route must PERSIST its delta, not only log it');
+  assert.match(upTo, /route: `idea:\$\{id\}:prose-edit`/, 'and use the same route shape as the other two');
+  assert.match(upTo, /AUDIT GAP/, 'with a loud failure rather than a swallowed one');
+});
+
+summary();