@bongos/core 1.19.673 → 1.19.675

package/tests/criterion_goal_attach.mjs

@@ -0,0 +1,347 @@
+// tests/criterion_goal_attach.mjs
+//
+// Route-level proof that an EXISTING criterion can join a goal, leave one, and
+// that BOTH ends of the move are walled (task 1003509 — walk finding W5).
+//
+// WHY THE ROUTE AND NOT THE PREDICATE. tests/criterion_authoring_gate.mjs already
+// pins authorizeCriterionCreate as a pure decision. The defect this file exists to
+// catch is one layer up and invisible there: a move is a criterion write on the
+// DESTINATION goal as much as on the source, so gating only the goal it leaves
+// would let a goal's own owner push their criterion into a goal they hold no
+// authority over. That failure passes every pure-gate test — the gate is correct,
+// it is simply not asked twice. This route's own history records the same shape
+// once already ("the comment said it, the code did half of it", task 1003102).
+//
+// So this runs the REAL Express router with the data layer and the auth gate
+// stubbed at the module boundary — the tests/task_visual_route_gate.mjs pattern.
+// No DB, no network, no session.
+//
+// Run:  node tests/criterion_goal_attach.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const express = require('express');
+const api = require('../src/module-api.js');
+
+// The REAL updateCriterionGoal SQL runs here, against a recording pool. That
+// matters: db-tasks.js destructures `pool` off the doorway at REQUIRE time and
+// takes no deps seam (its siblings createCriterion/updateTaskGoal take none
+// either, and growing one just for a test would make this function the odd one
+// out), so the pool has to be replaced BEFORE the first require below. Stubbing
+// db.updateCriterionGoal instead would leave its SQL with no coverage at all —
+// a mutation that made the UPDATE write nothing stayed green until this landed.
+const sqlLog = [];
+Object.defineProperty(api, 'pool', {
+  configurable: true,
+  value: {
+    query: async (sql, params) => {
+      sqlLog.push({ sql, params });
+      if (/UPDATE done_when_criteria/.test(sql)) {
+        const [goalId, id] = params;
+        criterion = { ...criterion, id: Number(id), goal_id: goalId };
+        return { rows: [{ ...criterion }] };
+      }
+      throw new Error(`unexpected SQL reached the pool: ${sql}`);
+    },
+  },
+});
+
+const db = require('../modules/lifecycle/db.js');
+const doneWhen = require('../modules/lifecycle/done-when.js');
+const goalEdits = require('../modules/lifecycle/goal-edits.js');
+
+// ---- the world the route sees ---------------------------------------------
+const V1 = 'INST-V1';
+const V2 = 'INST-V2';
+const ARCHON = { id: 900, rank: 'archon' };
+const METIC = { id: 700, rank: 'metic' };
+
+let actor = METIC;
+let criterion = null;
+const goals = new Map();
+let calls = {};
+let completable = new Set();
+
+function resetWorld() {
+  actor = METIC;
+  completable = new Set([3]);
+  sqlLog.length = 0;
+  calls = { achieve: [], auditMove: [], prose: [] };
+  // Derived from the SQL the real updateCriterionGoal actually sent, as
+  // [criterionId, goalId] — so "nothing was written" means no UPDATE reached the
+  // pool, not merely that a stub went uncalled.
+  Object.defineProperty(calls, 'updateGoal', {
+    get: () => sqlLog
+      .filter((q) => /UPDATE done_when_criteria/.test(q.sql))
+      .map((q) => [Number(q.params[1]), q.params[0]]),
+  });
+  // The shape a wizard-born instance actually starts with: seeded under V1 by
+  // provision-repo.js, belonging to no goal because none existed at standup.
+  criterion = { id: 55, version_id: V1, criterion_id: 'first-goal', criterion_md: 'ship something', goal_id: null, satisfied: false, sort_order: 10 };
+  goals.clear();
+  //                        id           version    status   created_by (owner)
+  goals.set(3, { id: 3, version_id: V1, status: 'open', created_by: METIC.id });
+  goals.set(4, { id: 4, version_id: V1, status: 'open', created_by: 999 });   // someone else's
+  goals.set(9, { id: 9, version_id: V2, status: 'open', created_by: METIC.id }); // another version
+}
+
+// ---- stubs at the module boundary -----------------------------------------
+api.requireBuilder = (req, _res, next) => { req.builder = actor; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+
+doneWhen.getCriterion = async (id) => (criterion && criterion.id === Number(id) ? { ...criterion } : null);
+db.getVersion = async (id) => ({ id, status: 'building' });
+db.getGoal = async (id) => (goals.has(Number(id)) ? { ...goals.get(Number(id)) } : null);
+db.getGoalMember = async () => null;  // membership is never the path under test; ownership is
+// NOT stubbed — db.updateCriterionGoal is the real one, running its real SQL
+// against the pool above. `calls.updateGoal` is derived from what that SQL sent.
+db.achieveGoalIfComplete = async ({ goalId }) => {
+  calls.achieve.push(goalId);
+  // Which goals a re-derive would actually complete is per-test — BOTH ends of a
+  // move can be completed by it, and which one matters is the point.
+  return { achieved: completable.has(Number(goalId)), goal: goals.get(Number(goalId)) ?? null };
+};
+goalEdits.recordCriterionGoalMove = async (move) => { calls.auditMove.push(move); };
+goalEdits.updateCriterionProse = async ({ criterionId, criterionMd }) => {
+  calls.prose.push([criterionId, criterionMd]);
+  criterion = { ...criterion, criterion_md: criterionMd };
+  return { criterion: { ...criterion }, deltas: [{ field: 'criterion_md' }], unchanged: false };
+};
+goalEdits.recordProseEdit = async () => {};
+
+const buildRouter = require('../modules/lifecycle/routes/done-when.js');
+
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => {
+  res.fail = (code, status, extra) => {
+    const s = typeof status === 'number' ? status : (status && status.status) || 500;
+    return res.status(s).json({ error: code, ...(extra && typeof extra === 'object' ? extra : {}) });
+  };
+  next();
+});
+app.use(buildRouter());
+
+const server = http.createServer(app);
+await new Promise((r) => server.listen(0, '127.0.0.1', r));
+const base = `http://127.0.0.1:${server.address().port}`;
+
+async function patch(body) {
+  const res = await fetch(`${base}/done-when/55`, {
+    method: 'PATCH',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+}
+
+let passed = 0, failed = 0;
+async function test(name, fn) {
+  resetWorld();
+  try { await fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}\n     ${err.message}`); failed++; }
+}
+
+// ---------------------------------------------------------------------------
+
+await test('the ungrouped V1 criterion joins a goal — the W5 fix', async () => {
+  // The founder of a wizard-born instance IS its Archon, which is what makes the
+  // W5 case reachable: a goal-LESS criterion is version-level, and ADR 0154 keeps
+  // version-level criteria Archon-only. That predates this task — the same gate
+  // already refused a non-Archon PROSE edit on an ungrouped criterion.
+  actor = ARCHON;
+  const r = await patch({ goal_id: 3 });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  assert.equal(r.body.criterion.goal_id, 3);
+  assert.deepEqual(calls.updateGoal, [[55, 3]]);
+});
+
+await test('BOTH ends are gated: owning the source does not license the destination', async () => {
+  // The criterion already sits in goal 3, which METIC owns. Goal 4 is someone
+  // else's. Gating only the source would let this through — that is the defect.
+  criterion.goal_id = 3;
+  const r = await patch({ goal_id: 4 });
+  assert.equal(r.status, 403, `expected the destination wall, got ${r.status} ${JSON.stringify(r.body)}`);
+  assert.equal(r.body.error, 'goal_not_yours');
+  assert.deepEqual(calls.updateGoal, [], 'nothing was written');
+});
+
+await test('a METIC moves a criterion between two goals they own — no Archon needed', async () => {
+  // The other half of the W5 fix: regrouping WITHIN a workspace someone already
+  // holds needs no escalation. Goal 7 is a second goal owned by the same Metic.
+  goals.set(7, { id: 7, version_id: V1, status: 'open', created_by: METIC.id });
+  criterion.goal_id = 3;
+  const r = await patch({ goal_id: 7 });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  assert.equal(r.body.criterion.goal_id, 7);
+  assert.deepEqual(calls.auditMove, [{ criterionId: 55, fromGoalId: 3, toGoalId: 7 }]);
+});
+
+await test('a criterion may never cross versions', async () => {
+  actor = ARCHON;
+  const r = await patch({ goal_id: 9 });   // goal 9 lives on V2, the criterion on V1
+  assert.equal(r.status, 400);
+  assert.equal(r.body.error, 'bad_goal_id');
+  assert.deepEqual(calls.updateGoal, []);
+});
+
+await test('an absent goal is the same refusal as a foreign-version one', async () => {
+  actor = ARCHON;
+  const r = await patch({ goal_id: 4242 });
+  assert.equal(r.status, 400);
+  assert.equal(r.body.error, 'bad_goal_id');
+});
+
+await test('DETACH is Archon-only — it lands on the gate\'s goal-less branch (ADR 0154)', async () => {
+  criterion.goal_id = 3;
+  const denied = await patch({ goal_id: null });
+  assert.equal(denied.status, 403);
+  assert.equal(denied.body.error, 'goal_id_required');
+  assert.deepEqual(calls.updateGoal, []);
+
+  actor = ARCHON;
+  const allowed = await patch({ goal_id: null });
+  assert.equal(allowed.status, 200, JSON.stringify(allowed.body));
+  assert.equal(allowed.body.criterion.goal_id, null);
+  assert.deepEqual(calls.updateGoal, [[55, null]]);
+});
+
+await test('a SATISFIED criterion still moves — only its text is frozen', async () => {
+  actor = ARCHON;
+  criterion.satisfied = true;
+  const moved = await patch({ goal_id: 3 });
+  assert.equal(moved.status, 200, JSON.stringify(moved.body));
+  assert.equal(moved.body.criterion.goal_id, 3);
+
+  const reworded = await patch({ criterion_md: 'something else' });
+  assert.equal(reworded.status, 409);
+  assert.equal(reworded.body.error, 'criterion_satisfied');
+  assert.deepEqual(calls.prose, [], 'the frozen text was never written');
+});
+
+await test('adopting a criterion that completes the goal reports the achievement', async () => {
+  actor = ARCHON;
+  const r = await patch({ goal_id: 3 });
+  assert.equal(r.status, 200);
+  assert.deepEqual(calls.achieve, [3], 'the destination is re-derived, not assumed');
+  assert.equal(r.body.achieved_goals.includes(3), true);
+});
+
+await test('leaving a goal can COMPLETE it — the source is re-derived too', async () => {
+  // The half that is easy to miss: pulling an UNSATISFIED criterion out of goal 3
+  // can leave everything still in goal 3 satisfied. Nothing else would ever close
+  // it — no later ship re-checks that goal, because no task under it changed.
+  actor = ARCHON;
+  criterion.goal_id = 3;
+  completable = new Set([3]);          // the goal it LEAVES is the one that completes
+  const r = await patch({ goal_id: 4 });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  assert.deepEqual(calls.achieve, [3, 4], 'both ends re-derived, source first');
+  assert.deepEqual(r.body.achieved_goals, [3]);
+});
+
+await test('a DETACH still re-derives the goal it left', async () => {
+  actor = ARCHON;
+  criterion.goal_id = 3;
+  completable = new Set([3]);
+  const r = await patch({ goal_id: null });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  assert.deepEqual(calls.achieve, [3], 'no destination, but the source still counts');
+  assert.deepEqual(r.body.achieved_goals, [3]);
+});
+
+await test('a move that completes BOTH ends reports both', async () => {
+  actor = ARCHON;
+  criterion.goal_id = 3;
+  completable = new Set([3, 4]);
+  const r = await patch({ goal_id: 4 });
+  assert.deepEqual(r.body.achieved_goals, [3, 4]);
+});
+
+await test('a no-op move writes nothing at all', async () => {
+  actor = ARCHON;
+  criterion.goal_id = 3;
+  const r = await patch({ goal_id: 3 });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  assert.deepEqual(calls.updateGoal, [], 'no UPDATE reached the pool');
+  assert.deepEqual(calls.auditMove, [], 'nothing to audit');
+  assert.deepEqual(calls.achieve, [], 'nothing changed, so nothing to re-derive');
+});
+
+await test('a DETACH from a goal-less criterion is also a no-op', async () => {
+  actor = ARCHON;
+  const r = await patch({ goal_id: null });
+  assert.equal(r.status, 200);
+  assert.deepEqual(calls.updateGoal, []);
+});
+
+await test('a DETACH re-derives no DESTINATION — there is none to complete', async () => {
+  actor = ARCHON;
+  criterion.goal_id = 3;
+  completable = new Set();             // nothing completes; only the CALL shape is under test
+  const r = await patch({ goal_id: null });
+  assert.equal(r.status, 200);
+  assert.deepEqual(calls.achieve, [3], 'the source, and only the source');
+  assert.equal(r.body.achieved_goals.length, 0);
+});
+
+await test('the move is audited with the goal it LEFT, which the request body cannot show', async () => {
+  criterion.goal_id = 3;
+  actor = ARCHON;
+  await patch({ goal_id: 4 });
+  assert.deepEqual(calls.auditMove, [{ criterionId: 55, fromGoalId: 3, toGoalId: 4 }]);
+});
+
+await test('prose and goal move in one call: both land, and the response carries both', async () => {
+  actor = ARCHON;
+  const r = await patch({ criterion_md: 'reworded', goal_id: 3 });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  assert.deepEqual(calls.prose, [[55, 'reworded']]);
+  assert.deepEqual(calls.updateGoal, [[55, 3]]);
+  // The goal move happens last, so the returned row must carry BOTH changes —
+  // returning the prose result here would report goal_id as it was before.
+  assert.equal(r.body.criterion.goal_id, 3);
+  assert.equal(r.body.criterion.criterion_md, 'reworded');
+});
+
+await test('an empty patch is refused rather than silently doing nothing', async () => {
+  const r = await patch({});
+  assert.equal(r.status, 400);
+  assert.equal(r.body.error, 'nothing_to_update');
+});
+
+await test('prose-only editing is unchanged (the pre-existing contract)', async () => {
+  actor = ARCHON;
+  const r = await patch({ criterion_md: 'clearer wording' });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  assert.deepEqual(calls.prose, [[55, 'clearer wording']]);
+  assert.deepEqual(calls.updateGoal, [], 'an absent goal_id never touches the linkage');
+  assert.ok(Array.isArray(r.body.deltas) && r.body.deltas.length === 1);
+});
+
+await test('the UPDATE sets goal_id from the parameter, keyed by criterion id', async () => {
+  // What a recording pool CAN prove is the statement, not its execution — there is
+  // no Postgres in this lane. So pin the shape: a SET that writes the bound
+  // parameter (not the column back onto itself), keyed by id, RETURNING the row
+  // the route hands back. Without this, `SET goal_id = goal_id` is a silent no-op
+  // that every behavioural test above still passes, because they read the row this
+  // fake returns rather than one a database wrote.
+  actor = ARCHON;
+  await patch({ goal_id: 3 });
+  const update = sqlLog.find((q) => /UPDATE done_when_criteria/.test(q.sql));
+  assert.ok(update, 'the move reached the pool at all');
+  const sql = update.sql.replace(/\s+/g, ' ').trim();
+  assert.match(sql, /SET goal_id = \$1\b/, 'writes the bound parameter, not the column onto itself');
+  assert.match(sql, /WHERE id = \$2\b/, 'keyed by the criterion id');
+  assert.match(sql, /RETURNING\b[^;]*\bgoal_id\b/, 'returns the moved row, so the response cannot go stale');
+  assert.deepEqual(update.params, [3, 55]);
+});
+
+await new Promise((r) => server.close(r));
+console.log(`\ncriterion_goal_attach: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/discord_channels_snapshot.mjs

@@ -0,0 +1,198 @@
+// tests/discord_channels_snapshot.mjs
+//
+// Seeding docs/discord/channels.json from the LIVE guild (task 1003510).
+//
+// WHY THIS EXISTS. ADR 0037 §1 calls channels.json "the single source of truth"
+// and rests its security argument on it — changing channels means editing a repo
+// file and merging it, and merging is rank-gated, so the layout is Archon-gated
+// by construction. That property only holds for channels the file actually
+// describes. It described one (board-room, task 1003033); the rest of the guild
+// was configured somewhere untracked. Reconstructing them by hand from the ADR's
+// access table was rejected on purpose: the table lists `view` but no names and
+// no topics, so guessing would make the bot EDIT live channels to match an
+// invention. `configFromSnapshot` reads the real values instead.
+//
+// THE PROPERTY THAT MAKES IT TRUSTWORTHY — and the whole point of this file:
+//
+//     planChannelReconcile(snapshot, configFromSnapshot(snapshot).config) === no ops
+//
+// Feeding the derived config straight back at the guild it came from must ask for
+// NOTHING. Any field inverted wrongly — a view, a name, a topic, a parent — makes
+// the planner emit an op, so this one assertion tests the whole function instead
+// of restating it field by field. A config that round-trips is one an operator can
+// commit without the next reconcile rewriting the guild.
+//
+// Pure: no Discord, no network, no DB.
+//
+// Run:  node tests/discord_channels_snapshot.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ch = require('../modules/discord/discord-channels.js');
+const { configFromSnapshot, viewFromOverwrites, planChannelReconcile, mergeViewOverwrites, resolveViewRoles } = ch;
+
+const EVERYONE = '100';
+const ROLES = { xenos: '201', thetes: '202', metic: '203', archon: '204' };
+const BOT = '999';
+const ctx = { everyoneId: EVERYONE, roleMap: ROLES, botId: BOT };
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (e) { console.error(`  FAIL ${name}\n     ${e.message}`); failed++; }
+}
+
+// Build the overwrites a REAL reconciled channel carries for a given view, using
+// the production forward path — so the fixtures are what the bot actually writes,
+// not a hand-rolled guess at it.
+const owFor = (view) => mergeViewOverwrites([], resolveViewRoles(view, ROLES), ctx);
+
+// ---- the inverse, on its own ----------------------------------------------
+
+test('everyone-visible reads back as "everyone"', () => {
+  assert.equal(viewFromOverwrites(owFor('everyone'), ctx), 'everyone');
+});
+
+test('each rank round-trips through the overwrites the bot writes', () => {
+  for (const rank of ['xenos', 'thetes', 'metic', 'archon']) {
+    assert.equal(viewFromOverwrites(owFor(rank), ctx), rank, `view=${rank}`);
+  }
+});
+
+test('the LOWEST allowed rank wins — view grants that rank and every rank above', () => {
+  // thetes' overwrites allow thetes+metic+archon. The answer must be the floor,
+  // not whichever happens to be first in the array.
+  const ow = owFor('thetes');
+  assert.ok(ow.some((o) => o.id === ROLES.archon), 'fixture really does allow archon too');
+  assert.equal(viewFromOverwrites(ow, ctx), 'thetes');
+});
+
+test('no managed overwrite at all reads back as null, never "everyone"', () => {
+  // A channel the bot has never touched. Claiming "everyone" here would write a
+  // claim the guild never made, and the next reconcile would act on it.
+  assert.equal(viewFromOverwrites([], ctx), null);
+  assert.equal(viewFromOverwrites([{ id: '777', type: 0, allow: '0', deny: '0' }], ctx), null);
+});
+
+test('@everyone denied with no rank allowed fails safe to archon', () => {
+  const ow = [{ id: EVERYONE, type: 0, allow: '0', deny: '1024' }];
+  assert.equal(viewFromOverwrites(ow, ctx), 'archon', 'mirrors resolveViewRoles fail-safe');
+});
+
+// ---- the round trip --------------------------------------------------------
+
+// A guild shaped like the real one: a public category, a restricted one, emoji in
+// the names, and a channel whose view is TIGHTER than its category's.
+function guild() {
+  return {
+    categories: [
+      { id: '1', name: 'COMMONS', overwrites: owFor('everyone') },
+      { id: '2', name: 'BUILDERS', overwrites: owFor('xenos') },
+    ],
+    channels: [
+      { id: '10', name: '👋-welcome', type: 0, parentId: '1', topic: 'Start here.', overwrites: owFor('everyone') },
+      { id: '11', name: '📯-ship-news', type: 0, parentId: '1', topic: 'What shipped.', overwrites: owFor('everyone') },
+      { id: '12', name: '🏛️-board-room', type: 0, parentId: '2', topic: 'Ratification votes.', overwrites: owFor('xenos') },
+      { id: '13', name: '🔒-archon-only', type: 0, parentId: '2', topic: 'Archon business.', overwrites: owFor('archon') },
+    ],
+  };
+}
+
+test('ROUND TRIP: the derived config asks the planner for nothing', () => {
+  const snapshot = guild();
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  assert.deepEqual(warnings, [], 'a fully-reconciled guild produces no warnings');
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.deepEqual(ops, [], `expected zero ops, got: ${JSON.stringify(ops.map((o) => [o.op, o.name]))}`);
+});
+
+test('the real names survive, emoji and all — they are what slug matching needs', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const names = config.categories.flatMap((c) => c.channels.map((x) => x.name));
+  assert.deepEqual(names, ['👋-welcome', '📯-ship-news', '🏛️-board-room', '🔒-archon-only']);
+  const keys = config.categories.flatMap((c) => c.channels.map((x) => x.key));
+  assert.deepEqual(keys, ['welcome', 'ship-news', 'board-room', 'archon-only'], 'key is the slug');
+});
+
+test('topics are carried verbatim — the ADR table has none, which is why guessing was refused', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const commons = config.categories.find((c) => c.name === 'COMMONS');
+  assert.equal(commons.channels.find((c) => c.key === 'ship-news').topic, 'What shipped.');
+});
+
+test('a channel view EQUAL to its category is omitted; a tighter one is stated', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const builders = config.categories.find((c) => c.name === 'BUILDERS');
+  assert.equal(builders.view, 'xenos');
+  // board-room matches its category → inherits, so no `view` key to drift later.
+  assert.equal('view' in builders.channels.find((c) => c.key === 'board-room'), false);
+  // archon-only is tighter → must be stated or the config would widen it.
+  assert.equal(builders.channels.find((c) => c.key === 'archon-only').view, 'archon');
+});
+
+test('a tighter channel view is not merely recorded — it survives the round trip', () => {
+  // Guard against "stated but wrong": drop the view and the planner must object.
+  const snapshot = guild();
+  const { config } = configFromSnapshot(snapshot, ctx);
+  const builders = config.categories.find((c) => c.name === 'BUILDERS');
+  delete builders.channels.find((c) => c.key === 'archon-only').view;
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.ok(ops.length > 0, 'removing the tighter view must make the planner want to widen it');
+});
+
+// ---- the honest edges ------------------------------------------------------
+
+test('an uncategorised channel is REPORTED and omitted, never invented into a category', () => {
+  const snapshot = guild();
+  snapshot.channels.push({ id: '14', name: 'stray', type: 0, parentId: null, topic: '', overwrites: owFor('everyone') });
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  const all = config.categories.flatMap((c) => c.channels.map((x) => x.key));
+  assert.ok(!all.includes('stray'), 'omitted — channels.json cannot express it');
+  assert.ok(warnings.some((w) => /stray/.test(w) && /no category/.test(w)), 'and said so');
+  // Omitted means UNTOUCHED, which is the file header's own rule.
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.deepEqual(ops, [], 'an omitted channel still produces no op');
+});
+
+test('a never-reconciled channel warns instead of silently claiming a view', () => {
+  const snapshot = guild();
+  snapshot.channels.push({ id: '15', name: 'untouched', type: 0, parentId: '1', topic: '', overwrites: [] });
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  const entry = config.categories.find((c) => c.name === 'COMMONS').channels.find((c) => c.key === 'untouched');
+  assert.equal('view' in entry, false, 'inherits the category, as it does in the guild');
+  assert.ok(warnings.some((w) => /untouched/.test(w)), 'the operator is told before they apply');
+});
+
+test('a CATEGORY with no managed overwrite is recorded as everyone, and warns', () => {
+  // The category-side twin of the channel null path above. A guild can carry a
+  // category the bot has never restricted; channels.json has no way to say
+  // "inherits" for a category (it is the top of the tree), so 'everyone' is the
+  // only expressible answer — and it is a WIDER claim than the guild made, which
+  // is exactly why it has to warn rather than pass silently.
+  const snapshot = {
+    categories: [{ id: '1', name: 'UNMANAGED', overwrites: [] }],
+    channels: [{ id: '10', name: 'chat', type: 0, parentId: '1', topic: '', overwrites: owFor('everyone') }],
+  };
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  assert.equal(config.categories[0].view, 'everyone');
+  assert.ok(
+    warnings.some((w) => /UNMANAGED/.test(w) && /confirm/i.test(w)),
+    'the operator is told the category view was assumed, not read'
+  );
+});
+
+test('the output is the shape channels.json actually declares', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  assert.deepEqual(Object.keys(config), ['categories']);
+  for (const c of config.categories) {
+    assert.deepEqual(Object.keys(c).sort(), ['channels', 'name', 'view']);
+    for (const x of c.channels) {
+      for (const k of Object.keys(x)) assert.ok(['key', 'name', 'topic', 'view'].includes(k), `unexpected key ${k}`);
+    }
+  }
+});
+
+console.log(`\ndiscord_channels_snapshot: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);