@bongos/core 1.19.909 → 1.19.911

package/tests/api_alias_caller_ratchet.mjs

@@ -0,0 +1,130 @@
+// tests/api_alias_caller_ratchet.mjs — the lowercase `/api/gds` CALLER ratchet
+// (task 1004064, from idea 1001030). Mirrors tests/fitness_gds_ratchet.mjs, its
+// case-sensitive sibling.
+//
+// WHAT THIS FILE IS DEFENDING AGAINST. The brief names the trap exactly: "this is a static scan;
+// it breaks by finding nothing, and a green run looks identical to a working one." Every case
+// below is written so that a scanner which enumerates nothing, excludes everything, or counts
+// nothing FAILS here rather than passing quietly. The aggregation cases inject their own file
+// list and reader, so the real exclusion + counting path runs without writing into the repo —
+// the unit lane runs test files in parallel, and a test that edited a tracked file would break
+// whichever suite happened to be scanning the tree at that moment.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const scan = require(path.join(ROOT, 'scripts', 'gds', 'api-alias-caller-scan.js'));
+
+// A reader over an in-memory tree — no repo writes.
+const fake = (tree) => ({ files: Object.keys(tree), readFile: (rel) => tree[rel] });
+
+test('the counter COUNTS — a file that should count, does (the trap case)', () => {
+  const r = scan.scanAliasCallers(fake({
+    'src/bongos/routes/thing.js': "await fetch(`${base}/api/gds/tasks/${id}`);\n",
+  }));
+  assert.equal(r.total, 1, 'a plain in-repo caller must be counted');
+  assert.deepEqual(Object.keys(r.byFile), ['src/bongos/routes/thing.js']);
+  assert.equal(r.scanned, 1, 'and the file must actually have been scanned');
+});
+
+test('a collapsed enumeration is visible as scanned=0, not as a flattering total of 0', () => {
+  const empty = scan.scanAliasCallers(fake({}));
+  assert.equal(empty.total, 0);
+  assert.equal(empty.scanned, 0, 'scanned is what distinguishes "nothing to find" from "nothing looked at"');
+
+  const allExcluded = scan.scanAliasCallers(fake({
+    'tests/x.mjs': '/api/gds\n',
+    'docs/x.md': '/api/gds\n',
+  }));
+  assert.equal(allExcluded.total, 0);
+  assert.equal(allExcluded.scanned, 0, 'an every-path-excluded run is also scanned=0 — the same signal');
+});
+
+test('the REAL scan enumerates the repo and lands on the committed baseline', () => {
+  const r = scan.scanAliasCallers();
+  assert.ok(r.scanned > 500, `the real tree must enumerate substantially (got ${r.scanned})`);
+  const baselines = JSON.parse(readFileSync(path.join(ROOT, 'config', 'fitness-baselines.json'), 'utf8'));
+  const floor = baselines.metrics.legacy_api_gds_callers;
+  assert.equal(typeof floor, 'number', 'the metric must have a baseline, or the ratchet only warns');
+  assert.ok(r.total <= floor, `caller count ${r.total} is ABOVE baseline ${floor} — a new /api/gds caller entered the tree`);
+});
+
+test('the exclusions are real and each one is reachable', () => {
+  // Rule numbers refer to the header of api-alias-caller-scan.js.
+  for (const p of [
+    'src/bongos/api-prefix.js',            // 1 the alias contract
+    'src/bongos/routes/auth.js',           // 2 the pinned OAuth callbacks
+    'modules/provisioning/provisioning.js',
+    'src/bongos/uptime-poller.js',         // 3 the live proof
+    'scripts/gds/smoke-gds.js',
+    'scripts/gds/gds-literal-scan.js',     // 4 the rename guardrails
+    'scripts/gds/fitness-ratchets.js',
+    'scripts/gds/api-alias-caller-scan.js',
+    'tests/api_alias_exceptions.mjs',      // 5 tests
+    'modules/dev-box/app/test/thing.mjs',
+    'docs/architecture.md',                // 6 docs
+    'migrations/033_audit_log.sql',        // 7 migrations
+    'scripts/hall-preview/fixtures/tasks.json', // 9 captured fixtures
+    'node_modules/pkg/index.js',           // vendored
+  ]) {
+    assert.equal(scan.isExcludedPath(p), true, `${p} must be excluded`);
+  }
+  // …and the exclusion is not a blanket that swallows the tree.
+  for (const p of [
+    'src/bongos/serve-internal.js',
+    'modules/lifecycle/abandon-leftovers.js',
+    'clients/bongos-client/index.mjs', // a .mjs that is NOT a test — a blanket \.mjs$ would blind the ratchet
+    'bin/bongos.js',
+    'CLAUDE.md',
+  ]) {
+    assert.equal(scan.isExcludedPath(p), false, `${p} must NOT be excluded`);
+  }
+});
+
+test('a line ABOUT the alias is not a caller of it — and the rule is not so loose it excuses everything', () => {
+  // Excluded: names the canonical prefix too, or says what it is.
+  assert.equal(scan.isCountedLine('mount /api/bongos and /api/gds'), false);
+  assert.equal(scan.isCountedLine('// /api/gds is a permanent alias'), false);
+  assert.equal(scan.isCountedLine('// the legacy /api/gds mount'), false);
+  assert.equal(scan.isCountedLine('// /api/gds stays FOREVER'), false);
+  // Counted: a bare caller, with none of those tells.
+  assert.equal(scan.isCountedLine('const r = await fetch(`${base}/api/gds/me`);'), true);
+  assert.equal(scan.isCountedLine('  node scripts/gds/api.js GET /api/gds/tasks/1'), true);
+  // And a line with no alias at all is never counted, whatever else it says.
+  assert.equal(scan.isCountedLine('fetch(`${base}/api/bongos/me`)'), false);
+  assert.equal(scan.isCountedLine('a line about a legacy alias, forever'), false);
+});
+
+test('occurrences are counted, not lines — moving ONE of two callers on a line lowers the number', () => {
+  assert.equal(scan.countInText('f("/api/gds/a"); f("/api/gds/b");\n'), 2);
+  assert.equal(scan.countInText('f("/api/bongos/a"); f("/api/gds/b");\n'), 0, 'the canonical name on the line is the alias-commentary rule, by design');
+  assert.equal(scan.countInText('nothing here\n'), 0);
+});
+
+test('the ratchet is WIRED — computeMetrics reports the metric and compareToBaselines fails a rise', () => {
+  const ratchets = require(path.join(ROOT, 'scripts', 'gds', 'fitness-ratchets.js'));
+  const baselines = JSON.parse(readFileSync(path.join(ROOT, 'config', 'fitness-baselines.json'), 'utf8')).metrics;
+
+  // A rise is a violation…
+  const worse = ratchets.compareToBaselines(
+    { legacy_api_gds_callers: baselines.legacy_api_gds_callers + 1 },
+    baselines,
+  );
+  assert.equal(worse.violations.length, 1, 'one more caller must RED the build');
+  assert.match(worse.violations[0], /legacy_api_gds_callers regressed/);
+  assert.match(worse.violations[0], /api-alias-caller-scan/, 'the hint must name the tool that lists the offenders');
+
+  // …a fall is a ratchet-down warning, not a failure.
+  const better = ratchets.compareToBaselines(
+    { legacy_api_gds_callers: baselines.legacy_api_gds_callers - 1 },
+    baselines,
+  );
+  assert.equal(better.violations.length, 0);
+  assert.equal(better.warnings.length, 1);
+  assert.match(better.warnings[0], /ratchet-down available/);
+});

package/tests/file_map.mjs

@@ -93,6 +93,65 @@ test('generation is deterministic + idempotent (a second run is a no-op)', () =>
   assert.match(r2.stdout, /already current/);
 });
 
+// ── module coverage (task 1004066) ────────────────────────────────────────────
+// The check is a set comparison over a directory listing, and a set comparison breaks by
+// comparing two empty sets and passing. Every case below is written so that a matcher which
+// vouches for everything, or a scan which enumerates nothing, FAILS here.
+
+test('every dir under modules/ is documented in file-map.md — and the set being compared is not empty', () => {
+  const cov = gen.moduleCoverage();
+  assert.ok(cov.onDisk.length > 0, 'modules/ enumerated to nothing — the coverage check would be vacuous');
+  assert.deepEqual(cov.defects, [], `module-coverage scan defects: ${cov.defects.join('; ')}`);
+  assert.deepEqual(cov.undocumented, [], `modules with no file-map entry: ${cov.undocumented.join(', ')}`);
+});
+
+test('--check FAILS (exit 2) on a module with no file-map entry — the trap case', () => {
+  const probe = path.join(ROOT, 'modules', '__filemap_probe__');
+  try {
+    mkdirSync(probe, { recursive: true });
+    writeFileSync(path.join(probe, 'module.json'), '{"key":"__filemap_probe__"}\n');
+    const cov = gen.moduleCoverage();
+    assert.ok(cov.onDisk.includes('__filemap_probe__'), 'the probe module must be enumerated');
+    assert.deepEqual(cov.undocumented, ['__filemap_probe__'], 'an undocumented module must be the ONLY finding');
+    const r = run(['--check']);
+    assert.equal(r.code, 2, 'an undocumented module must fail the gate');
+    assert.match(r.stderr, /modules with NO docs\/file-map\.md entry/);
+    assert.match(r.stderr, /__filemap_probe__/);
+  } finally {
+    rmSync(probe, { recursive: true, force: true });
+  }
+  // Asserted on the module finding rather than the exit code: --check reports every problem class
+  // at once, and a checkout carrying unrelated local noise (materialised module skills with no
+  // note) would otherwise make this read as "the probe is still there".
+  const after = run(['--check']);
+  assert.equal(gen.moduleCoverage().undocumented.length, 0, 'coverage is clean once the probe module is removed');
+  assert.doesNotMatch(after.stderr || '', /modules with NO docs\/file-map\.md entry/);
+});
+
+test('the matcher discriminates: a real module passes, an absent one does not, and a prefix cannot vouch', () => {
+  const md = readFileSync(path.join(ROOT, 'docs', 'file-map.md'), 'utf8');
+  const block = gen.modulesBlock(md);
+  assert.ok(block.length > 0, 'the modules/ tree block must be findable — an empty block would make entries unreadable');
+  assert.ok(gen.isModuleDocumented(md, block, 'government'), 'a documented module reads as documented');
+  assert.equal(gen.isModuleDocumented(md, block, '__no_such_module__'), false, 'an absent module must NOT read as documented');
+  // A bare substring test would let `modules/agents-extra` vouch for `agents`.
+  assert.equal(
+    gen.isModuleDocumented('see modules/agents-extra/thing.js', '', 'agents'),
+    false,
+    'a longer path sharing the prefix must not count as an entry',
+  );
+  // A skill dir listed in the same `├── name/` shape elsewhere in the map must not vouch either:
+  // the entry search is scoped to the modules/ block.
+  assert.equal(gen.modulesBlock('├── .claude/skills/\n├── recall/  ← a skill\n'), '', 'no modules/ block → no block to read entries from');
+});
+
+test('module coverage reports a SCAN DEFECT rather than passing when the map cannot be read', () => {
+  const cov = gen.moduleCoverage('');
+  assert.ok(cov.onDisk.length > 0);
+  assert.equal(cov.defects.length, 1, 'an unreadable map is a defect, not a pass');
+  assert.match(cov.defects[0], /cannot run/);
+});
+
 test('every note maps to a real skill/routine (sidecar has no dangling keys)', () => {
   const notes = JSON.parse(readFileSync(path.join(ROOT, 'docs', 'file-map.notes.json'), 'utf8'));
   for (const section of gen.SECTIONS) {

package/tests/idea_landing_preview.mjs

@@ -0,0 +1,337 @@
+// tests/idea_landing_preview.mjs
+//
+// task 1004083 (BV2.R02, goal 1000095) — GRAVITY: the landing verdict read
+// before the write. This drives the REAL `previewLanding` over a fake pool and a
+// fake lifecycle port, so `decideLanding`, `authorizeRoutedLanding` and every
+// branch inside the preview actually run.
+//
+// WHY THIS FILE EXISTS, stated plainly because it was a grader finding: the
+// first cut of this task tested only the hall composer, against a mock of
+// `postInboxPreviewLanding`. That proves the LINE renders what the server says
+// and proves nothing at all about what the server says — the verdict every one
+// of those cases asserted on was written by the test itself. The two halves need
+// two harnesses, and this is the server one.
+//
+// DB-FREE, the tests/capture_goal_routing.mjs way: the collaborators the preview
+// reaches through (`pool`, the `lifecycle` port, `moduleScopeMap`) are all
+// injectable or patchable, and none of them is the thing under test — the matrix
+// is, and the matrix is pure.
+//
+// THE PROPERTY THAT MATTERS MOST IS THE NEGATIVE ONE: previewing must never
+// WRITE. A preview runs on every keystroke of a debounced composer, and the
+// homeless path in the real capture resolves through `ensureMaintenanceGoal`,
+// which is find-or-CREATE. The last case in this file fails if the preview ever
+// reaches for it.
+//
+// Run:  node tests/idea_landing_preview.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { test, summary } = makeRunner();
+
+process.env.NODE_ENV = 'test';
+
+const api = require('../src/module-api');
+const { previewLanding, OUTCOMES } = require('../modules/ideas/landing-preview');
+
+// The goal row the preview reads, in the shape its SELECT returns. Defaults are
+// the happy one: a real, open goal on a building version, unprotected scope.
+function goalRow(over = {}) {
+  return {
+    id: '77', title: 'Idea routing', status: 'open',
+    version_id: 'BV2', scope_modules: ['ideas'], version_status: 'building',
+    ...over,
+  };
+}
+
+// A pool that answers one query and COUNTS them, so a case can assert that a
+// branch never reached the database at all.
+function fakePool(rows = []) {
+  const calls = [];
+  return { calls, query: async (sql, params) => { calls.push({ sql, params }); return { rows }; } };
+}
+
+// Patch the two singletons the preview reaches through the doorway, and restore
+// afterwards so cases cannot leak into each other.
+// `version` defaults to a real building version, because "there IS one" is the
+// ordinary world and a case that means the opposite must say so. The first cut
+// of this helper defaulted the lifecycle port to NULL, which made two cases pass
+// for the wrong reason — including the one whose whole subject is the missing
+// version, so it asserted the right answer via the wrong cause.
+async function withApi({ version = 'BV2', protectedScope = false } = {}, fn) {
+  const realResolve = api.resolveOptional;
+  const realMap = Object.getOwnPropertyDescriptor(api, 'moduleScopeMap');
+  const reached = { ensureMaintenanceGoal: 0, currentBuildingVersionId: 0 };
+  const lifecycle = { currentBuildingVersionId: async () => { reached.currentBuildingVersionId++; return version; } };
+  api.resolveOptional = (name) => (name === 'lifecycle' ? lifecycle : realResolve(name));
+  Object.defineProperty(api, 'moduleScopeMap', {
+    configurable: true,
+    value: { scopeIncludesProtected: () => protectedScope },
+  });
+  try { return await fn(reached); } finally {
+    api.resolveOptional = realResolve;
+    if (realMap) Object.defineProperty(api, 'moduleScopeMap', realMap);
+  }
+}
+
+// A lifecycle port that records which methods were touched. `ensureMaintenanceGoal`
+// THROWS rather than answering: the preview must never call it, and a method that
+// quietly succeeds would let that regression pass as a green test.
+function fakeLifecycle(versionId, reached) {
+  return {
+    currentBuildingVersionId: async () => { reached.currentBuildingVersionId++; return versionId; },
+    ensureMaintenanceGoal: async () => {
+      reached.ensureMaintenanceGoal++;
+      throw new Error('previewLanding must never create a goal');
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the two lies the composer's picker tells — the reason this task exists
+// ---------------------------------------------------------------------------
+
+await test('a homeless BUG routes, and the preview names whose maintenance goal catches it', async () => {
+  await withApi({}, async (reached) => {
+    const v = await previewLanding(
+      { goalId: null, kind: 'bug', grade: null, filerRank: 'archon', vector: 'api' },
+      { pool: fakePool() }
+    );
+    assert.equal(v.outcome, OUTCOMES.ROUTED_HOME, 'the picker says "homeless"; ADR 0262 says otherwise');
+    assert.equal(v.status, 'ready', 'a trusted filer\'s bug is claimable at once');
+    assert.equal(v.version_id, 'BV2');
+    assert.equal(v.goal, null, 'the goal row does not exist yet, so it is not named');
+  });
+});
+
+await test('the same bug from an UNTRUSTED filer still lands, but at backlog', async () => {
+  await withApi({}, async () => {
+    const v = await previewLanding(
+      { goalId: null, kind: 'bug', filerRank: 'thetes', vector: 'api' },
+      { pool: fakePool() }
+    );
+    assert.equal(v.outcome, OUTCOMES.ROUTED_HOME);
+    assert.equal(v.status, 'backlog', 'the rank split is the matrix\'s, not re-derived here');
+  });
+});
+
+await test('a homeless NON-bug floats — the homeless door is bug-only', async () => {
+  await withApi({}, async () => {
+    const v = await previewLanding({ goalId: null, kind: 'feature', filerRank: 'archon', vector: 'api' }, { pool: fakePool() });
+    assert.equal(v.outcome, OUTCOMES.FLOATS);
+    assert.equal(v.reason, 'no_goal');
+  });
+});
+
+await test('a homeless bug from an UNRECOGNISED vector floats — the allowlist holds', async () => {
+  await withApi({}, async () => {
+    const v = await previewLanding({ goalId: null, kind: 'bug', filerRank: 'archon', vector: 'discord-ideas' }, { pool: fakePool() });
+    assert.equal(v.outcome, OUTCOMES.FLOATS, '#ideas files with hints only (ADR 0234)');
+  });
+});
+
+await test('a NAMED goal on a judgment kind floats, and the goal is not claimed to catch it', async () => {
+  await withApi({}, async () => {
+    const v = await previewLanding(
+      { goalId: 77, kind: 'decision', filerRank: 'archon', vector: 'api' },
+      { pool: fakePool([goalRow()]) }
+    );
+    assert.equal(v.outcome, OUTCOMES.FLOATS);
+    assert.equal(v.reason, 'judgment_kind', 'the second lie the picker tells');
+    assert.equal(v.goal, null);
+  });
+});
+
+await test('a Full Idea never routes, however confidently a goal is picked', async () => {
+  await withApi({}, async () => {
+    const v = await previewLanding(
+      { goalId: 77, kind: 'feature', grade: 'full', filerRank: 'archon', vector: 'api' },
+      { pool: fakePool([goalRow()]) }
+    );
+    assert.equal(v.outcome, OUTCOMES.FLOATS);
+    assert.equal(v.reason, 'full_idea_never_routes');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// a named goal: the happy paths and the wall
+// ---------------------------------------------------------------------------
+
+await test('a named goal is named back, with the status the matrix chose', async () => {
+  await withApi({}, async () => {
+    const pool = fakePool([goalRow()]);
+    const v = await previewLanding({ goalId: 77, kind: 'bug', filerRank: 'archon', vector: 'api' }, { pool });
+    assert.equal(v.outcome, OUTCOMES.ROUTED);
+    assert.equal(v.status, 'ready');
+    assert.deepEqual(v.goal, { id: '77', title: 'Idea routing' });
+    assert.equal(pool.calls.length, 1, 'one read, and it is a SELECT');
+    assert.match(pool.calls[0].sql, /^\s*SELECT/i);
+  });
+});
+
+await test('a non-bug with a home soft-lands at backlog', async () => {
+  await withApi({}, async () => {
+    const v = await previewLanding({ goalId: 77, kind: 'refactor', filerRank: 'archon', vector: 'api' }, { pool: fakePool([goalRow()]) });
+    assert.equal(v.outcome, OUTCOMES.ROUTED);
+    assert.equal(v.status, 'backlog');
+  });
+});
+
+await test('PROTECTED scope + a sub-Metic filer is refused, in words, before the filing is spent', async () => {
+  await withApi({ protectedScope: true }, async () => {
+    const v = await previewLanding({ goalId: 77, kind: 'bug', filerRank: 'thetes', vector: 'api' }, { pool: fakePool([goalRow()]) });
+    assert.equal(v.outcome, OUTCOMES.REFUSED);
+    assert.equal(v.refusal.code, 'protected_scope');
+    assert.match(v.refusal.reason, /protected territory/);
+  });
+});
+
+await test('PROTECTED scope + a Metic+ filer is NOT refused — the two are layers, not alternatives', async () => {
+  await withApi({ protectedScope: true }, async () => {
+    const v = await previewLanding({ goalId: 77, kind: 'bug', filerRank: 'archon', vector: 'api' }, { pool: fakePool([goalRow()]) });
+    assert.equal(v.outcome, OUTCOMES.ROUTED);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// the degraded states — silence, never a guess
+// ---------------------------------------------------------------------------
+
+for (const [label, row] of [
+  ['a goal that is gone', undefined],
+  ['a goal that is archived', goalRow({ status: 'archived' })],
+  ['a goal on a version that is not building', goalRow({ version_status: 'shipped' })],
+]) {
+  await test(`${label} states NOTHING rather than guessing a sentence`, async () => {
+    await withApi({}, async () => {
+      const v = await previewLanding({ goalId: 77, kind: 'bug', filerRank: 'archon', vector: 'api' }, { pool: fakePool(row ? [row] : []) });
+      assert.equal(v.outcome, null, 'the real capture will name the refusal; the preview does not invent one');
+    });
+  });
+}
+
+await test('no building version means no promise — the homeless path says nothing', async () => {
+  await withApi({ version: null }, async (reached) => {
+    const v = await previewLanding({ goalId: null, kind: 'bug', filerRank: 'archon', vector: 'api' }, { pool: fakePool() });
+    assert.equal(v.outcome, null, 'the real capture fails closed here (NO_BUILDING_VERSION)');
+    assert.equal(reached.currentBuildingVersionId, 1, 'and it got there by asking, not by the port being absent');
+  });
+});
+
+await test('a pool that throws degrades to silence — a composer must never red on a keystroke', async () => {
+  await withApi({}, async () => {
+    const angry = { query: async () => { throw new Error('connection reset'); } };
+    const v = await previewLanding({ goalId: 77, kind: 'bug', filerRank: 'archon', vector: 'api' }, { pool: angry });
+    assert.equal(v.outcome, null);
+    assert.equal(v.refusal, null);
+  });
+});
+
+await test('a null input does not throw — the destructuring-defaults trap decideLanding records', async () => {
+  await withApi({}, async () => {
+    const v = await previewLanding(null, { pool: fakePool() });
+    assert.equal(v.outcome, OUTCOMES.FLOATS, 'nothing named, so nothing catches it');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// THE NEGATIVE PROPERTY — the one that makes this safe to run per keystroke
+// ---------------------------------------------------------------------------
+
+await test('previewing a homeless bug NEVER creates the maintenance goal', async () => {
+  const reached = { ensureMaintenanceGoal: 0, currentBuildingVersionId: 0 };
+  const realResolve = api.resolveOptional;
+  api.resolveOptional = (n) => (n === 'lifecycle' ? fakeLifecycle('BV2', reached) : realResolve(n));
+  try {
+    const v = await previewLanding({ goalId: null, kind: 'bug', filerRank: 'archon', vector: 'api' }, { pool: fakePool() });
+    assert.equal(v.outcome, OUTCOMES.ROUTED_HOME, 'it still answers');
+    assert.equal(reached.currentBuildingVersionId, 1, 'by READING the version');
+    assert.equal(reached.ensureMaintenanceGoal, 0,
+      'ensureMaintenanceGoal is find-or-CREATE; a preview that called it would mint a goal per keystroke');
+  } finally { api.resolveOptional = realResolve; }
+});
+
+await test('no branch writes — every pool call in this file was a SELECT', async () => {
+  await withApi({}, async () => {
+    const pool = fakePool([goalRow()]);
+    for (const kind of ['bug', 'feature', 'decision', 'criterion-proposal', 'refactor']) {
+      await previewLanding({ goalId: 77, kind, filerRank: 'archon', vector: 'api' }, { pool });
+    }
+    assert.ok(pool.calls.length > 0, 'the goal read did happen');
+    for (const c of pool.calls) {
+      assert.match(c.sql, /^\s*SELECT/i, `a preview issued a non-SELECT: ${c.sql.slice(0, 40)}`);
+      assert.doesNotMatch(c.sql, /FOR SHARE|FOR UPDATE/i, 'a preview holds no lock — it races nothing');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// THE ROUTE — asserted in SOURCE, the tests/filing_abuse_matrix.mjs idiom
+//
+// Those properties are guarantees about the CALL SITE, not about a return value:
+// "the rank is the authenticated one" cannot be observed from the outside,
+// because a route that read it from the body would answer identically to one
+// that did not — for a caller who sent the true rank. So they are asserted where
+// they live, exactly as F3 and F18 of the filing abuse matrix already do for
+// POST /inbox. This file is the ideas module's second reader of that source.
+// ---------------------------------------------------------------------------
+
+const routeSrc = readFileSync(new URL('../modules/ideas/routes/inbox.js', import.meta.url), 'utf8');
+const previewBlock = routeSrc.slice(routeSrc.indexOf("router.post('/inbox/preview-landing'"));
+
+await test('[route] the preview exists, is builder-gated, and declares its validator', () => {
+  assert.ok(previewBlock.length > 0, 'POST /inbox/preview-landing is declared');
+  assert.match(previewBlock.slice(0, 400), /api\.requireBuilder/, 'no anonymous caller');
+  assert.match(previewBlock.slice(0, 900), /validateOrRespond\(req, res, \{/, 'the input SHAPE is validated');
+});
+
+await test('[route] rank and vector come from AUTH and a literal — never from the body', () => {
+  const head = previewBlock.slice(0, 1600);
+  assert.match(head, /filerRank:\s*req\.builder\?\.rank/,
+    'a filer must not be able to preview a landing their rank does not grant');
+  assert.match(head, /vector:\s*'api'/, 'the vector is the door, hardcoded');
+  assert.ok(!/filerRank:\s*body\.|vector:\s*body\.|vector:\s*req\.body/.test(head),
+    'neither may be read from the request body');
+});
+
+await test('[route] the verdict is passed through, not re-shaped into a second vocabulary', () => {
+  assert.match(previewBlock.slice(0, 1600), /const verdict = await previewLanding\(/);
+  assert.match(previewBlock.slice(0, 1600), /res\.json\(verdict\)/,
+    'a route that rebuilt the object by hand would be a second place the shape can drift');
+});
+
+await test('[route] it is declared BEFORE the :id routes that would otherwise shadow it', () => {
+  // The file header calls this ordering load-bearing. A literal path declared
+  // after `/inbox/:id` binds `:id = 'preview-landing'`, parseId 400s, and the
+  // whole feature disappears with no error naming it.
+  const mine = routeSrc.indexOf("'/inbox/preview-landing'");
+  const byId = routeSrc.indexOf("'/inbox/:id(\\\\d+)'");
+  assert.ok(mine > 0, 'the route is there');
+  assert.ok(byId === -1 || mine < byId, 'and it is declared above the id-bearing routes');
+});
+
+await test('[route] the preview is not wired into the CAPTURE path — it is a read beside it', () => {
+  // The whole claim of "no new routing" is that the matrix has ONE caller that
+  // can write. previewLanding must never appear inside POST /inbox.
+  const capture = routeSrc.slice(routeSrc.indexOf("router.post('/inbox',"), routeSrc.indexOf("router.get('/inbox',"));
+  assert.ok(!/previewLanding/.test(capture), 'the capture does not consult the preview');
+});
+
+// Probes run, and these are the MEASURED counts:
+//   make the homeless branch call ensureMaintenanceGoal   -> 4 red (incl. the negative property)
+//   let authorizeRoutedLanding's refusal fall through     -> 1 red (protected-scope)
+//   drop the grade check from decideLanding's early exit  -> 1 red (full-idea)
+//   fabricate the goal instead of reading it              -> 1 red (goal-is-gone)
+//
+// Writing this file is what found two defects the composer suite could not:
+// `previewLanding(null)` THREW (a default in a parameter list fires on undefined
+// and not on null — the trap routing.js's own comment records, reproduced one
+// file away from it), and this harness's first `withApi` defaulted the lifecycle
+// port to null, which made two cases pass for the wrong reason — including the
+// one whose entire subject is the missing version.
+
+summary('idea_landing_preview');