@bongos/core 1.19.813 → 1.19.815

package/tests/abandon_route.mjs

@@ -0,0 +1,276 @@
+// tests/abandon_route.mjs
+//
+// Regression guard for task 1002443 / ADR 0297 — the COMPOSITION layer of
+// POST /tasks/:id/abandon (modules/lifecycle/routes/abandon-handler.js).
+//
+// WHY THIS FILE EXISTS. The route's authority is assembled from three pieces that
+// each have their own tests and none of which cover the seams between them:
+//   • abandon-authz.js  — the pure decision      (tests/abandon_creator_authz.mjs)
+//   • abandonTask       — the transaction seam   (tests/abandon_task.mjs)
+//   • this handler      — resolve, compose, map  (nothing, until now)
+// A mistake in the wiring — admitting when the government port is absent, mapping
+// a refusal to the wrong status, naming the wrong atom in a denial, passing the
+// wrong flags into the decision — would have passed both of the others. That gap
+// was the grade finding on the first ship of this task; this closes it.
+//
+// No Express, no DB, no live port: the handler takes its collaborators as `deps`,
+// so fakes are enough.
+//
+// Run:  node --test tests/abandon_route.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { makeAbandonHandler } = require('../modules/lifecycle/routes/abandon-handler.js');
+
+const { test, summary } = makeRunner();
+
+const ME = 7;
+const ANY_KEY = 'task.abandon';
+const OWN_KEY = 'task.abandon.own';
+
+// A res that records instead of writing. `fail` mirrors the real envelope's two
+// call shapes: fail(code, status) and fail(code, { status, message, details }).
+function fakeRes() {
+  const rec = { json: null, fail: null };
+  return {
+    rec,
+    json(body) { rec.json = body; return this; },
+    fail(code, second, third) {
+      const opts = (second && typeof second === 'object') ? second : { status: second };
+      rec.fail = { code, status: opts.status, message: opts.message, details: opts.details ?? third };
+      return this;
+    },
+  };
+}
+
+// A government port with only what the handler actually consults.
+function fakeGovernance({ holds = [], crossOwner = [ANY_KEY], resolveThrows = false, omit = [] } = {}) {
+  const port = {
+    resolveBuilderPermissions: async () => {
+      if (resolveThrows) throw new Error('DB blip');
+      return [...holds];
+    },
+    sameOwner: (a, b) => a != null && b != null && String(a) === String(b),
+    crossOwnerKeysFor: () => [...crossOwner],
+    permissionFloor: (k) => (k === ANY_KEY ? 'metic' : k === OWN_KEY ? 'xenos' : null),
+  };
+  for (const k of omit) delete port[k];
+  return port;
+}
+
+function harness({ governance = fakeGovernance(), abandon, taskId = 42, body = {} } = {}) {
+  const calls = { abandon: null, logged: [] };
+  const deps = {
+    db: {
+      abandonTask: async (args) => {
+        calls.abandon = args;
+        if (typeof abandon === 'function') return abandon(args);
+        return { taskId: args.taskId, taskTitle: 'fixture', taskStatus: 'abandoned', previousStatus: 'ready', alreadyAbandoned: false };
+      },
+    },
+    seams: { resolveOptional: (name) => (name === 'government' ? governance : null) },
+    log: { error: (...a) => calls.logged.push(a) },
+    validateOrRespond: () => false,                    // body is valid
+    parseId: () => taskId,                             // id parses
+  };
+  const req = { builder: { id: ME }, body, params: { id: String(taskId) } };
+  const res = fakeRes();
+  return { handler: makeAbandonHandler(deps), req, res, calls };
+}
+
+// ── the port is the wall, and its absence denies ──────────────────────────────
+await test('a MISSING government port denies fail-closed, and never reaches the db', async () => {
+  // Admitting here would make disabling a module a privilege escalation — the
+  // inversion ADR 0016 exists to prevent.
+  const { handler, req, res, calls } = harness({ governance: null });
+  await handler(req, res);
+  assert.equal(res.rec.fail.status, 403);
+  assert.equal(res.rec.fail.code, 'permission_forbidden');
+  assert.equal(res.rec.fail.details.held, null, 'held is null when authority could not be ESTABLISHED');
+  assert.equal(calls.abandon, null, 'no transaction may be opened');
+});
+
+await test('a MALFORMED port (missing a function the decision needs) also denies', async () => {
+  for (const missing of ['resolveBuilderPermissions', 'sameOwner']) {
+    const { handler, req, res, calls } = harness({ governance: fakeGovernance({ holds: [ANY_KEY], omit: [missing] }) });
+    await handler(req, res);
+    assert.equal(res.rec.fail.status, 403, `a port without ${missing} must deny`);
+    assert.equal(calls.abandon, null);
+  }
+});
+
+await test('a THROWING resolver denies rather than surfacing as a 500', async () => {
+  const { handler, req, res, calls } = harness({ governance: fakeGovernance({ resolveThrows: true }) });
+  await handler(req, res);
+  assert.equal(res.rec.fail.status, 403);
+  assert.equal(res.rec.fail.details.held, null);
+  assert.equal(calls.abandon, null);
+  assert.equal(calls.logged.length, 1, 'and it is logged — a DB blip should be visible');
+});
+
+// ── the denial names the right atoms ──────────────────────────────────────────
+await test('holding neither atom is a 403 naming BOTH ways in, with their floors', async () => {
+  const { handler, req, res, calls } = harness({ governance: fakeGovernance({ holds: [] }) });
+  await handler(req, res);
+  assert.equal(res.rec.fail.status, 403);
+  assert.deepEqual(res.rec.fail.details.required, [ANY_KEY, OWN_KEY],
+    'a denial listing only the metic key would send a creator after the wrong permission');
+  assert.deepEqual(res.rec.fail.details.floors, { [ANY_KEY]: 'metic', [OWN_KEY]: 'xenos' });
+  assert.deepEqual(res.rec.fail.details.held, []);
+  assert.equal(calls.abandon, null, 'the cheap pre-check must not open a transaction');
+});
+
+await test('floors come from the PORT, so a moved floor cannot leave a lie in the denial', async () => {
+  const gov = fakeGovernance({ holds: [] });
+  gov.permissionFloor = (k) => (k === ANY_KEY ? 'archon' : null);
+  const { handler, req, res } = harness({ governance: gov });
+  await handler(req, res);
+  assert.deepEqual(res.rec.fail.details.floors, { [ANY_KEY]: 'archon' },
+    'the floor is read at deny time, never hardcoded');
+});
+
+await test('a port that cannot answer floors still denies, without inventing one', async () => {
+  const { handler, req, res } = harness({ governance: fakeGovernance({ holds: [], omit: ['permissionFloor'] }) });
+  await handler(req, res);
+  assert.equal(res.rec.fail.status, 403);
+  assert.deepEqual(res.rec.fail.details.floors, {});
+});
+
+// ── the escalation path is read from the catalog ──────────────────────────────
+await test('the cross-owner key is DERIVED from the catalog, not hardcoded', async () => {
+  // If the declared counterpart ever changes, the route must follow it rather than
+  // keep admitting on a stale pairing.
+  const { handler, req, res, calls } = harness({
+    governance: fakeGovernance({ holds: ['task.manage.any'], crossOwner: ['task.manage.any'] }),
+  });
+  await handler(req, res);
+  assert.equal(res.rec.fail, null, 'the declared counterpart must admit');
+  assert.equal(res.rec.json.ok, true);
+  assert.equal(calls.abandon.authorize({ createdBy: 999, status: 'completed' }).ok, true,
+    'and it must compose as the CROSS-OWNER branch, unbounded by the creator window');
+});
+
+await test('holding the OLD atom does not admit once the catalog has moved on', async () => {
+  const { handler, req, res, calls } = harness({
+    governance: fakeGovernance({ holds: [ANY_KEY], crossOwner: ['task.manage.any'] }),
+  });
+  await handler(req, res);
+  assert.equal(res.rec.fail.status, 403, 'a catalog that moved on must not leave this gate wide');
+  assert.equal(calls.abandon, null);
+});
+
+await test('a port that cannot name the escalation falls back to the known atom, never to open', async () => {
+  const { handler, req, res } = harness({
+    governance: fakeGovernance({ holds: [ANY_KEY], omit: ['crossOwnerKeysFor'] }),
+  });
+  await handler(req, res);
+  assert.equal(res.rec.fail, null, 'the fallback keeps the metic path working');
+  assert.equal(res.rec.json.ok, true);
+});
+
+// ── composition: what the decision is actually handed ─────────────────────────
+await test('the own-scoped holder reaches the row question, composed correctly', async () => {
+  const { handler, req, res, calls } = harness({ governance: fakeGovernance({ holds: [OWN_KEY] }) });
+  await handler(req, res);
+  assert.ok(calls.abandon, 'an own-holder must be let as far as the transaction');
+  const verdict = calls.abandon.authorize;
+  assert.equal(verdict({ createdBy: ME, status: 'ready' }).ok, true, 'their own ready task admits');
+  assert.equal(verdict({ createdBy: 999, status: 'ready' }).ok, false, 'someone else\'s does not');
+  assert.equal(verdict({ createdBy: ME, status: 'completed' }).ok, false, 'and not past the grader');
+});
+
+await test('the callback is handed the CALLER as the owner to compare against', async () => {
+  // A wiring slip here (comparing against the task id, or a constant) would make
+  // every creator either always or never the owner.
+  let sawArgs = null;
+  const gov = fakeGovernance({ holds: [OWN_KEY] });
+  gov.sameOwner = (a, b) => { sawArgs = [a, b]; return true; };
+  const { handler, req, res, calls } = harness({ governance: gov });
+  await handler(req, res);
+  calls.abandon.authorize({ createdBy: 'abc', status: 'ready' });
+  assert.deepEqual(sawArgs, ['abc', ME], 'the row owner and the requesting builder, in that order');
+});
+
+await test('the reason is passed through and clamped to 2000 characters', async () => {
+  const { handler, req, res, calls } = harness({
+    governance: fakeGovernance({ holds: [ANY_KEY] }),
+    body: { reason: 'x'.repeat(2500) },
+  });
+  await handler(req, res);
+  assert.equal(calls.abandon.reason.length, 2000);
+});
+
+// ── refusal mapping ──────────────────────────────────────────────────────────
+await test('ABANDON_FORBIDDEN from the locked row maps to 403, carrying its reason', async () => {
+  const { handler, req, res } = harness({
+    governance: fakeGovernance({ holds: [OWN_KEY] }),
+    abandon: async () => { throw Object.assign(new Error('not yours'), { code: 'ABANDON_FORBIDDEN', reason: 'not_task_creator' }); },
+  });
+  await handler(req, res);
+  assert.equal(res.rec.fail.status, 403);
+  assert.equal(res.rec.fail.message, 'not yours', 'the row-scoped message reaches the caller');
+  assert.equal(res.rec.fail.details.reason, 'not_task_creator');
+  assert.deepEqual(res.rec.fail.details.held, [OWN_KEY], 'and it reports what they DO hold');
+});
+
+await test('the three lifecycle guards keep their own status codes', async () => {
+  const cases = [
+    ['TASK_NOT_FOUND', 404, 'task_not_found'],
+    ['CANNOT_ABANDON_SHIPPED', 409, 'cannot_abandon_shipped'],
+    ['TASK_HAS_ACTIVE_CLAIM', 409, 'task_has_active_claim'],
+  ];
+  for (const [code, status, envelope] of cases) {
+    const { handler, req, res } = harness({
+      governance: fakeGovernance({ holds: [ANY_KEY] }),
+      abandon: async () => { throw Object.assign(new Error(code), { code }); },
+    });
+    await handler(req, res);
+    assert.equal(res.rec.fail.status, status, `${code} must stay a ${status}`);
+    assert.equal(res.rec.fail.code, envelope);
+  }
+});
+
+await test('an unexpected error is a 500 and is logged, never a silent 403', async () => {
+  const { handler, req, res, calls } = harness({
+    governance: fakeGovernance({ holds: [ANY_KEY] }),
+    abandon: async () => { throw new Error('something else entirely'); },
+  });
+  await handler(req, res);
+  assert.equal(res.rec.fail.status, 500);
+  assert.equal(res.rec.fail.code, 'abandon_failed');
+  assert.equal(calls.logged.length, 1);
+});
+
+// ── the happy path ───────────────────────────────────────────────────────────
+await test('a successful retire answers ok with the db result spread in', async () => {
+  const { handler, req, res } = harness({ governance: fakeGovernance({ holds: [ANY_KEY] }) });
+  await handler(req, res);
+  assert.equal(res.rec.fail, null);
+  assert.equal(res.rec.json.ok, true);
+  assert.equal(res.rec.json.taskStatus, 'abandoned');
+  assert.equal(res.rec.json.previousStatus, 'ready');
+});
+
+await test('an invalid body or id short-circuits before any authority work', async () => {
+  for (const stop of ['body', 'id']) {
+    const calls = { abandon: null, resolved: 0 };
+    const gov = fakeGovernance({ holds: [ANY_KEY] });
+    const realResolve = gov.resolveBuilderPermissions;
+    gov.resolveBuilderPermissions = async (...a) => { calls.resolved++; return realResolve(...a); };
+    const handler = makeAbandonHandler({
+      db: { abandonTask: async () => { calls.abandon = true; } },
+      seams: { resolveOptional: () => gov },
+      log: { error: () => {} },
+      validateOrRespond: () => stop === 'body',
+      parseId: () => (stop === 'id' ? null : 42),
+    });
+    await handler({ builder: { id: ME }, body: {}, params: {} }, fakeRes());
+    assert.equal(calls.abandon, null, `a bad ${stop} must not reach the db`);
+    assert.equal(calls.resolved, 0, `a bad ${stop} must not even resolve permissions`);
+  }
+});
+
+summary();

package/tests/abandon_task.mjs

@@ -40,10 +40,17 @@ const { test, summary } = makeRunner();
 //   status         → the row's current status
 //   hasActiveClaim → the claims lookup returns an unreleased claim
 //   updatedStatus  → what the UPDATE ... RETURNING reports (restore returns 'backlog')
-function fakePool({ status = 'ready', notFound = false, hasActiveClaim = false, updatedStatus = 'abandoned' }) {
+// createdBy (task 1002443) rides the locked SELECT so the ownership predicate and
+// the UPDATE read the same row version; null is the honest default (every task
+// filed before core_227, and every system vector, has no creator).
+function fakePool({ status = 'ready', notFound = false, hasActiveClaim = false, updatedStatus = 'abandoned', createdBy = null }) {
   return makeSqlAwareClient((s, params) => {
-      if (/^SELECT id, title, status FROM tasks WHERE id = \$1 FOR UPDATE/.test(s)) {
-        return { rows: notFound ? [] : [{ id: params[0], title: 'fixture task', status }] };
+      // Both locked SELECTs, and the optional group is load-bearing: abandonTask
+      // reads created_by (task 1002443) and restoreTask does not, so a regex
+      // pinned to either one alone silently returns no row for the other — which
+      // surfaces as TASK_NOT_FOUND and looks like a code bug, not a fake bug.
+      if (/^SELECT id, title, status(, created_by)? FROM tasks WHERE id = \$1 FOR UPDATE/.test(s)) {
+        return { rows: notFound ? [] : [{ id: params[0], title: 'fixture task', status, created_by: createdBy }] };
       }
       if (/SELECT id FROM claims WHERE task_id = \$1 AND released_at IS NULL/.test(s)) {
         return { rows: hasActiveClaim ? [{ id: 999 }] : [] };
@@ -207,5 +214,140 @@ await test('restore: never consults claims (an abandoned task has none by constr
   assert.equal(all(pool._client.queries, /SELECT id FROM claims/).length, 0);
 });
 
+// =========================================================================
+// task 1002443 / ADR 0297 — the `authorize` seam: the row-scoped veto that lets a
+// task's CREATOR retire their own work without holding the metic-floor
+// task.abandon. The DECISION itself is pinned branch-by-branch in
+// tests/abandon_creator_authz.mjs; what is pinned HERE is the seam's mechanics —
+// what it is handed, when it runs, and that every unhappy path denies.
+
+await test('authorize is handed the LOCKED row: created_by and status', async () => {
+  // The whole point of doing this inside the transaction. If the callback were fed
+  // anything other than the row abandonTask just locked FOR UPDATE, the ownership
+  // check would be reading a different version than the UPDATE writes — the TOCTOU
+  // window this seam exists to close.
+  const pool = fakePool({ status: 'ready', createdBy: 7 });
+  let seen = null;
+  await abandonTask({
+    taskId: TASK,
+    reason: 'mine to retire',
+    authorize: (row) => { seen = row; return { ok: true }; },
+  }, { pool });
+  assert.equal(seen.createdBy, 7, 'created_by must reach the predicate');
+  assert.equal(seen.status, 'ready', 'and so must the row status');
+  assert.equal(seen.taskId, TASK);
+  assert.ok(find(pool._client.queries, /^UPDATE tasks/), 'an admit still performs the write');
+  assert.ok(find(pool._client.queries, /^COMMIT/));
+});
+
+await test('a refusing authorize throws ABANDON_FORBIDDEN, rolls back, writes nothing', async () => {
+  const pool = fakePool({ status: 'ready', createdBy: 8 });
+  await assert.rejects(
+    () => abandonTask({
+      taskId: TASK,
+      authorize: () => ({ ok: false, reason: 'not_task_creator', message: 'not yours' }),
+    }, { pool }),
+    (err) => err.code === 'ABANDON_FORBIDDEN' && err.reason === 'not_task_creator',
+  );
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0, 'a refusal must never write');
+  assert.ok(find(pool._client.queries, /^ROLLBACK/), 'must ROLLBACK');
+});
+
+await test('authorize runs BEFORE the already-abandoned idempotent return', async () => {
+  // Ordering, and it is a disclosure rule rather than a cosmetic one: if the
+  // idempotent branch came first, a builder with no authority over this row could
+  // probe it and read `alreadyAbandoned: true` back as a 200. An unauthorized retry
+  // is a refusal, not a no-op.
+  const pool = fakePool({ status: 'abandoned', createdBy: 8 });
+  await assert.rejects(
+    () => abandonTask({ taskId: TASK, authorize: () => ({ ok: false, reason: 'not_task_creator' }) }, { pool }),
+    (err) => err.code === 'ABANDON_FORBIDDEN',
+  );
+  assert.ok(!find(pool._client.queries, /^COMMIT/), 'must not COMMIT the idempotent no-op to an unauthorized caller');
+  assert.ok(find(pool._client.queries, /^ROLLBACK/));
+});
+
+await test('authorize also precedes the shipped and active-claim guards', async () => {
+  // Same reason: the 409s are informative, so an unauthorized caller must not be
+  // able to distinguish them. A refusal outranks every status branch below it.
+  for (const setup of [{ status: 'shipped' }, { status: 'ready', hasActiveClaim: true }]) {
+    const pool = fakePool({ ...setup, createdBy: 8 });
+    await assert.rejects(
+      () => abandonTask({ taskId: TASK, authorize: () => ({ ok: false }) }, { pool }),
+      (err) => err.code === 'ABANDON_FORBIDDEN',
+      `an unauthorized caller must get ABANDON_FORBIDDEN, not the ${setup.status} guard`,
+    );
+  }
+});
+
+await test('an authorized creator is STILL stopped by the existing guards', async () => {
+  // The widening adds an authority; it removes no guard. A creator who genuinely
+  // owns the row still cannot retire shipped history, nor a task someone is
+  // actively holding.
+  const shipped = fakePool({ status: 'shipped', createdBy: 7 });
+  await assert.rejects(
+    () => abandonTask({ taskId: TASK, authorize: () => ({ ok: true }) }, { pool: shipped }),
+    (err) => err.code === 'CANNOT_ABANDON_SHIPPED',
+  );
+  const claimed = fakePool({ status: 'ready', createdBy: 7, hasActiveClaim: true });
+  await assert.rejects(
+    () => abandonTask({ taskId: TASK, authorize: () => ({ ok: true }) }, { pool: claimed }),
+    (err) => err.code === 'TASK_HAS_ACTIVE_CLAIM',
+  );
+  assert.equal(all(claimed._client.queries, /^UPDATE tasks/).length, 0);
+});
+
+await test('the seam is FAIL-CLOSED: anything but an explicit { ok: true } denies', async () => {
+  for (const verdict of [undefined, null, false, {}, { ok: 'yes' }, { ok: 1 }, 'ok', { okay: true }]) {
+    const pool = fakePool({ status: 'ready', createdBy: 7 });
+    await assert.rejects(
+      () => abandonTask({ taskId: TASK, authorize: () => verdict }, { pool }),
+      (err) => err.code === 'ABANDON_FORBIDDEN',
+      `${JSON.stringify(verdict)} must not be read as an admit`,
+    );
+    assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+  }
+});
+
+await test('a THROWING authorize denies rather than escaping as a 500', async () => {
+  const pool = fakePool({ status: 'ready', createdBy: 7 });
+  await assert.rejects(
+    () => abandonTask({ taskId: TASK, authorize: () => { throw new Error('resolver blew up'); } }, { pool }),
+    (err) => err.code === 'ABANDON_FORBIDDEN' && err.reason === 'authorize_threw',
+  );
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+  assert.ok(find(pool._client.queries, /^ROLLBACK/));
+});
+
+await test('authorize never runs for a task that does not exist', async () => {
+  const pool = fakePool({ notFound: true });
+  let called = false;
+  await assert.rejects(
+    () => abandonTask({ taskId: 424242, authorize: () => { called = true; return { ok: true }; } }, { pool }),
+    (err) => err.code === 'TASK_NOT_FOUND',
+  );
+  assert.equal(called, false, 'there is no row to be the owner of');
+});
+
+await test('OMITTING authorize preserves the pre-1002443 behaviour exactly', async () => {
+  // Every caller whose route already gated the transition (and the merge path,
+  // which mirrors this function) must be untouched by the new parameter.
+  const pool = fakePool({ status: 'ready', createdBy: 8 });
+  const out = await abandonTask({ taskId: TASK, reason: 'no authorize supplied' }, { pool });
+  assert.equal(out.taskStatus, 'abandoned');
+  assert.equal(out.previousStatus, 'ready');
+  assert.ok(find(pool._client.queries, /^UPDATE tasks/));
+  assert.ok(find(pool._client.queries, /^COMMIT/));
+});
+
+await test('a non-function authorize is ignored, not treated as a refusal', async () => {
+  // `authorize: null` is the documented "no row-scoped veto" default; only a real
+  // function is consulted. This pins that a caller passing null does not
+  // accidentally brick the gated path it already guards in middleware.
+  const pool = fakePool({ status: 'ready', createdBy: 8 });
+  const out = await abandonTask({ taskId: TASK, authorize: null }, { pool });
+  assert.equal(out.taskStatus, 'abandoned');
+});
+
 // -------------------------------------------------------------------------
 summary();

package/tests/agents_validate.mjs

@@ -11,6 +11,9 @@
 //
 // Run:  node tests/agents_validate.mjs
 
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
@@ -73,9 +76,37 @@ await test('a failed validation returns NO value — nothing downstream can inse
 
 // --- THE EVENT CATALOG — the fail-closed rule -------------------------------
 
-await test('EVENT_CATALOG is exactly the v1 wired set, and is frozen', () => {
-  assert.deepEqual(EVENT_CATALOG, ['task.shipped']);
+await test('EVENT_CATALOG is frozen, and every entry is REALLY dispatched', () => {
   assert.equal(Object.isFrozen(EVENT_CATALOG), true, 'a caller must not be able to widen the catalog at runtime');
+  assert.ok(EVENT_CATALOG.includes('task.shipped'), 'the original wired event stays wired');
+
+  // The catalog's own comment is the rule: widening it "must land together with
+  // something that actually dispatches the new event". Pinned as that rule rather
+  // than as a frozen list, because a list cannot tell a legitimate widening from
+  // one that ships an entry nothing emits — and the second produces an agent that
+  // looks armed and never fires, which is the failure the catalog exists to stop.
+  const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const files = [];
+  const walk = (dir) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (e.name !== 'node_modules') walk(full); continue; }
+      if (e.name.endsWith('.js')) files.push(full);
+    }
+  };
+  for (const d of ['src', 'modules']) walk(path.join(ROOT, d));
+  const tree = files.map((f) => fs.readFileSync(f, 'utf8')).join('\n');
+
+  for (const event of EVENT_CATALOG) {
+    // Any quote style, emit or emitAsync. A plain substring scan rather than a
+    // built regex: the thing being asserted is "somebody emits this string".
+    const dispatched = ['emit(', 'emitAsync('].some((call) =>
+      [String.fromCharCode(39), '"', String.fromCharCode(96)].some((q) => tree.includes(call + q + event + q)));
+    assert.ok(dispatched,
+      `"${event}" is in the catalog but nothing in src/ or modules/ emits it — an agent armed on it would never fire`);
+  }
 });
 
 await test('an UNWIRED event name is REFUSED, never silently accepted', () => {

package/tests/discord_channels.mjs

@@ -24,6 +24,9 @@
 // Run:  node tests/discord_channels.mjs
 
 import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const ch = require('../modules/discord/discord-channels.js');
@@ -365,5 +368,168 @@ await t('the real config plans cleanly against an empty guild and never deletes'
   assert.ok(!ops.some((o) => String(o.op).startsWith('delete')), 'reconcile must never delete');
 });
 
+// ---- seeding channels.json from a live guild (task 1003841) ----------------
+//
+// WHY THESE EXIST. Seeding hangs on one subtle rule, and I read it wrong the
+// first time: an omitted `view` has TWO possible causes that look identical in
+// the config, and only one of them is a problem.
+//
+//   • the channel's view EQUALS its category's  -> omitted, NO warning  (fine)
+//   • the channel has no managed VIEW overwrite -> omitted, WITH a warning
+//
+// configFromSnapshot emits `view` only when it differs from the parent, because
+// the planner reads `ch.view || cat.view` and repeating the value is noise that
+// drifts later. So "the field is missing" is NOT evidence that a channel is
+// unmanaged — the WARNING is. These pin that distinction, because acting on the
+// wrong one means writing view values into the file that the module deliberately
+// omits, which is a diff against the guild rather than a record of it.
+
+const V_ALLOW = String(ch.VIEW_CHANNEL);
+const allowEveryone = [{ id: EVERYONE, type: 0, allow: V_ALLOW, deny: '0' }];
+const publicCat = (catOverwrites, chOverwrites) => ({
+  categories: [{ id: 'CAT_PUB', name: 'PUBLIC', overwrites: catOverwrites }],
+  channels: [{ id: 'CH_NEWS', type: 0, name: '📯-ship-news', parentId: 'CAT_PUB', topic: 'Ships land here.', overwrites: chOverwrites }],
+});
+
+await t('an omitted view means INHERITS when the channel matches its category — and warns nothing (task 1003841)', () => {
+  const { config, warnings } = ch.configFromSnapshot(publicCat(allowEveryone, allowEveryone), CTX);
+  const news = config.categories[0].channels[0];
+  assert.equal(news.view, undefined, 'a view identical to the category is deliberately omitted');
+  assert.deepEqual(warnings, [], 'and nothing is wrong, so nothing is warned about');
+});
+
+await t('an omitted view means UNMANAGED when the channel has no overwrite — and that WARNS (task 1003841)', () => {
+  // The distinguishing signal. Same missing field, different meaning.
+  const { config, warnings } = ch.configFromSnapshot(publicCat(allowEveryone, []), CTX);
+  assert.equal(config.categories[0].channels[0].view, undefined, 'also omitted — the config alone cannot tell them apart');
+  assert.equal(warnings.length, 1, 'but the warning does');
+  assert.match(warnings[0], /no VIEW overwrite/);
+});
+
+await t('the seeded file round-trips to ZERO ops for every channel that exists (task 1003841)', () => {
+  // The done-when, demonstrated rather than argued. Feeding the snapshot-derived
+  // config back against the same guild must plan to nothing — that is the whole
+  // correctness property of configFromSnapshot, and it is what makes committing
+  // the snapshot safe: applying it cannot edit a live channel.
+  const guild = publicCat(allowEveryone, allowEveryone);
+  const { config } = ch.configFromSnapshot(guild, CTX);
+  assert.deepEqual(ch.planChannelReconcile(guild, config, CTX).ops, [], 'a faithful snapshot is a no-op plan');
+});
+
+await t('writing view:everyone where the snapshot omitted it would ADD an op — which is why it is not written (task 1003841)', () => {
+  // The mistake this file avoids. Spelling out a value identical to the category
+  // is harmless to READ, but it is not what the module emits, and on a channel
+  // that genuinely lacks an overwrite it turns a record into an edit of the live
+  // guild. Pinned so nobody "tidies" the omitted fields back in.
+  const guild = publicCat(allowEveryone, []);
+  const spelled = {
+    categories: [{
+      name: 'PUBLIC', view: 'everyone',
+      channels: [{ key: 'ship-news', name: '📯-ship-news', view: 'everyone', topic: 'Ships land here.' }],
+    }],
+  };
+  const { ops } = ch.planChannelReconcile(guild, spelled, CTX);
+  assert.ok(ops.some((o) => o.op === 'edit-channel'), 'it edits the live channel');
+});
+
+await t('the committed file is the guild, plus board-room (task 1003841)', () => {
+  const cfg = ch.loadConfig();
+  const keys = cfg.categories.flatMap((c) => c.channels.map((x) => x.key));
+  assert.ok(keys.length >= 15, `expected the seeded guild, got ${keys.length} channels`);
+  assert.ok(keys.includes('board-room'), 'board-room stays declared — the bot never deletes');
+  for (const cat of cfg.categories) {
+    assert.ok(cat.view, `category ${cat.name} needs a view`);
+    for (const c of cat.channels) assert.ok(c.key && c.name, 'every channel carries its key and real name');
+  }
+  // The four PUBLIC channels inherit deliberately; asserting they have no view
+  // is what stops a later edit from spelling them out and creating a diff.
+  const pub = cfg.categories.find((c) => c.name === 'PUBLIC');
+  assert.equal(pub.view, 'everyone');
+  for (const c of pub.channels) assert.equal(c.view, undefined, `${c.key} must inherit, not repeat, its category view`);
+});
+
+// ---- the config path on a DEPLOYED instance (task 1003973) ---------------
+//
+// channels.json describes ONE guild, so it is instance identity and is NOT
+// published in the neutral core (ADR 0062 §7). The module used to resolve it
+// against its OWN directory, which on a deployed instance is
+// node_modules/@bongos/core/modules/discord/ — the file is not there, readFileSync
+// threw ENOENT, computePlan() threw, and the route returned a bare 500 that was
+// indistinguishable from a bot outage. These pin both halves of the fix.
+
+await t('resolveConfigPath prefers the INSTANCE root over the core package', () => {
+  // Point the instance root somewhere that is NOT the core checkout and give it
+  // its own channels.json. If resolution still lands on the core copy, a deployed
+  // instance would read cloudbongos.com's channel names — the thing ADR 0062 §7
+  // forbids — so this must fail loudly rather than pass because the two roots
+  // happen to coincide in a single checkout.
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-inst-1003973-'));
+  const own = path.join(root, 'docs', 'discord', 'channels.json');
+  fs.mkdirSync(path.dirname(own), { recursive: true });
+  fs.writeFileSync(own, JSON.stringify({ categories: [{ name: 'X', channels: [] }] }));
+  const prev = process.env.BONGOS_INSTANCE_ROOT;
+  process.env.BONGOS_INSTANCE_ROOT = root;
+  try {
+    assert.equal(ch.resolveConfigPath(), own,
+      'a deployed instance must read its OWN docs/discord/channels.json, not the core package copy');
+    assert.notEqual(ch.resolveConfigPath(), ch.CORE_CONFIG_PATH);
+    assert.deepEqual(ch.loadConfig().categories.map((c) => c.name), ['X'],
+      'loadConfig must follow the same resolution, not a stale module-scope constant');
+  } finally {
+    if (prev === undefined) delete process.env.BONGOS_INSTANCE_ROOT;
+    else process.env.BONGOS_INSTANCE_ROOT = prev;
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  // and with no pointer set, a single checkout still resolves to the repo file
+  assert.ok(fs.existsSync(ch.resolveConfigPath()), 'the single-checkout path must still resolve');
+});
+
+await t('loadConfig on a missing file throws a TAGGED error naming the path', () => {
+  const missing = path.join(os.tmpdir(), 'bongos-no-such-channels-1003973.json');
+  assert.throws(() => ch.loadConfig(missing), (err) => {
+    assert.equal(err.code, 'CONFIG_NOT_FOUND', 'ENOENT must be tagged, not left as a raw fs error');
+    assert.equal(err.configPath, missing);
+    assert.ok(err.message.includes(missing), 'the message must name the path the operator should fix');
+    return true;
+  });
+});
+
+await t('computePlan with no config returns {ok:false, no_config} instead of throwing', () => {
+  const missing = path.join(os.tmpdir(), 'bongos-no-such-channels-1003973.json');
+  const deps = {
+    getGuild: () => ({ id: '1', channels: { cache: new Map() } }),
+    loadConfig: () => ch.loadConfig(missing),
+    loadRoleMap: () => ({}),
+  };
+  const r = ch.computePlan(deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'no_config', 'a missing layout file must be its own reason, never a thrown 500');
+  assert.equal(r.configPath, missing, 'the caller needs the path to report it');
+  assert.deepEqual(r.ops, []);
+});
+
+await t('reconcileChannels with no config returns {ok:false, no_config} and writes nothing', async () => {
+  const missing = path.join(os.tmpdir(), 'bongos-no-such-channels-1003973.json');
+  const deps = {
+    getGuild: () => ({ id: '1', channels: { cache: new Map() } }),
+    loadBotToken: () => 'tok',
+    loadConfig: () => ch.loadConfig(missing),
+    loadRoleMap: () => ({}),
+  };
+  const r = await ch.reconcileChannels(deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'no_config');
+  assert.equal(r.applied, 0);
+});
+
+await t('a non-ENOENT read failure still propagates — only ENOENT is tagged', () => {
+  // A directory reads as EISDIR: a genuine internal error must NOT be laundered
+  // into the friendly 'put the file here' path.
+  assert.throws(() => ch.loadConfig(os.tmpdir()), (err) => {
+    assert.notEqual(err.code, 'CONFIG_NOT_FOUND');
+    return true;
+  });
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);