@bongos/core 1.17.0

package/tests/main_audit.mjs

@@ -0,0 +1,137 @@
+// tests/main_audit.mjs
+//
+// Unit smoke for scripts/gds/main-audit.js — the post-push main audit
+// (SEC #863, layer 3). Pure analyzer: feed synthetic commits + a rank map.
+//
+// Run:  node tests/main_audit.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { analyzeCommits } = require('../scripts/gds/main-audit.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const RANKS = {
+  iammasterqua: 'thetes',     // Builder 25 (incident author — not the Archon)
+  somearchon: 'archon',
+  somemetic: 'metic',
+  somexenos: 'xenos',
+};
+
+// The exact incident: a Thetes non-merge commit editing src/bongos/db.js.
+t('reconstructs #863: thetes commit touching db.js → BLOCKER', () => {
+  const commits = [{
+    sha: 'b5de8affbf6f5fedc6c0921cfb35c8cbf85f7def',
+    subject: 'fix(gds): add thetes to rank-tier CASE in listClaimableTasks',
+    authorName: 'IAMMASTERQUA',
+    authorEmail: 'lars@hermeslines.com',
+    isMerge: false,
+    files: ['src/bongos/db.js', 'tests/rank_gate.mjs'],
+  }];
+  const r = analyzeCommits(commits, RANKS);
+  assert.equal(r.hardFail, true);
+  assert.equal(r.findings.length, 1);
+  assert.equal(r.findings[0].severity, 'blocker');
+  assert.equal(r.findings[0].rank, 'thetes');
+});
+
+t('Metic editing a protected path → no finding', () => {
+  const r = analyzeCommits([{
+    sha: 'aaa', subject: 'x', authorName: 'SomeMetic', authorEmail: 'm@x',
+    isMerge: false, files: ['src/bongos/db.js'],
+  }], RANKS);
+  assert.equal(r.hardFail, false);
+  assert.equal(r.findings.length, 0);
+});
+
+t('Archon editing a protected path → no finding', () => {
+  const r = analyzeCommits([{
+    sha: 'bbb', subject: 'x', authorName: 'somearchon', authorEmail: 'l@x',
+    isMerge: false, files: ['scripts/gds/ship.js', 'CLAUDE.md'],
+  }], RANKS);
+  assert.equal(r.hardFail, false);
+});
+
+t('sub-Metic editing only innocent files → no finding', () => {
+  const r = analyzeCommits([{
+    sha: 'ccc', subject: 'art', authorName: 'somexenos', authorEmail: 'x@x',
+    isMerge: false, files: ['public/game/main.js', 'art/x.md'],
+  }], RANKS);
+  assert.equal(r.hardFail, false);
+});
+
+t('clean MERGE (empty --cc surface) → no finding (no double-count)', () => {
+  // A normal pipeline merge has an empty evil-merge (--cc) set; parseCommits
+  // leaves files=[] so the feature changes are attributed to the feature
+  // commits, not re-counted on the merge.
+  const r = analyzeCommits([{
+    sha: 'ddd', subject: 'Merge claude/x', authorName: 'IAMMASTERQUA', authorEmail: 'i@x',
+    isMerge: true, files: [],
+  }], RANKS);
+  assert.equal(r.findings.length, 0, 'clean merges must not flag');
+});
+
+t('#863-followup: EVIL MERGE smuggling a protected change is caught (attributed to merge author)', () => {
+  // parseCommits backfills a merge's files with the --cc surface (changes in
+  // neither parent). A sub-Metic merge author smuggling a protected edit → blocker.
+  const r = analyzeCommits([{
+    sha: 'eee', subject: 'Merge claude/x', authorName: 'IAMMASTERQUA', authorEmail: 'i@x',
+    isMerge: true, files: ['src/bongos/db.js'],
+  }], RANKS);
+  assert.equal(r.hardFail, true, 'evil merge by a sub-Metic author must be a blocker');
+  assert.equal(r.findings[0].severity, 'blocker');
+});
+
+t('unresolved author on protected path → review (not a block) by default', () => {
+  // The trusted operator/deployer commits under a git author NAME that is not a
+  // GDS login, so unresolved must NOT auto-block (would brick every deploy).
+  const r = analyzeCommits([{
+    sha: 'eee', subject: 'x', authorName: 'ghost-contributor', authorEmail: 'g@x',
+    isMerge: false, files: ['src/bongos/auth.js'],
+  }], RANKS);
+  assert.equal(r.hardFail, false);
+  assert.equal(r.findings.length, 1);
+  assert.equal(r.findings[0].severity, 'review');
+  assert.equal(r.findings[0].rank, null);
+});
+
+t('unresolved author escalates to BLOCKER under --strict', () => {
+  const r = analyzeCommits([{
+    sha: 'fff', subject: 'x', authorName: 'ghost', authorEmail: 'g@x',
+    isMerge: false, files: ['src/bongos/auth.js'],
+  }], RANKS, { strict: true });
+  assert.equal(r.hardFail, true);
+  assert.equal(r.findings[0].severity, 'blocker');
+});
+
+t('#863-followup (finding #6): resolution is by github_login ONLY — email no longer resolves', () => {
+  // Everyone shares one commit email, so email keying was non-distinguishing
+  // (and poisonable). An author whose NAME is not a known login is unresolved,
+  // regardless of email → 'review' by default (not silently passed as Metic).
+  const r = analyzeCommits([{
+    sha: 'ggg', subject: 'x', authorName: 'Display Name Mismatch', authorEmail: 'somemetic',
+    isMerge: false, files: ['src/bongos/db.js'],
+  }], RANKS);
+  assert.equal(r.findings.length, 1);
+  assert.equal(r.findings[0].rank, null, 'email must not resolve a rank');
+  assert.equal(r.findings[0].severity, 'review');
+});
+
+t('#863-followup (finding #6): a sub-Metic author NAME still resolves and BLOCKS (the incident)', () => {
+  // The honest/lazy case — niels committed as his real login "IAMMASTERQUA".
+  const r = analyzeCommits([{
+    sha: 'hhh', subject: 'x', authorName: 'IAMMASTERQUA', authorEmail: 'shared@x',
+    isMerge: false, files: ['src/bongos/db.js'],
+  }], RANKS);
+  assert.equal(r.hardFail, true);
+  assert.equal(r.findings[0].rank, 'thetes');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/memory_isolation.mjs

@@ -0,0 +1,431 @@
+// tests/memory_isolation.mjs
+//
+// Unit + HTTP smoke for per-builder memory isolation (V3.R57 / #276 — the read
+// side + isolation hardening of the ADR 0024 cloneable-memory chain).
+//
+// The invariant under test (ADR 0024 §4, same posture as ADR 0016): a builder
+// can only read/write THEIR OWN memory. The owner is ALWAYS req.builder.id,
+// NEVER from input — except the two Archon-only forensic reads, which take a
+// target id from the path, are rank-gated, and audit-log every call.
+//
+// Two layers of test:
+//   1. Pure-helper + source-structure checks (no Express, no DB):
+//        - assertSelf() — the explicit isolation invariant for self endpoints.
+//        - recordForensicRead() — the Archon audit shape + accurate status.
+//        - a source-level structural check that the self endpoints derive their
+//          owner from req.builder.id ONLY, and that the ONLY input-owner
+//          endpoints are the rank-gated, audited Archon forensic reads.
+//   2. REAL in-process HTTP checks through the actual router (no DB): we mount
+//      buildMemoryRouter() on a throwaway express app, inject fake auth by
+//      stubbing auth.requireBuilder / auth.requireRank, stub the memory store
+//      helpers to record the builderId they were called with, stub the audit
+//      insert to record/await/throw, then fire real requests via node:http +
+//      global fetch and assert status + isolation behavior end-to-end. This is
+//      the authenticated "builder A reading builder B → 403" smoke the done-when
+//      requires, plus the fail-closed-audit proof.
+//
+// Run:  node tests/memory_isolation.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+// Grab the real module objects so we can monkeypatch their exported functions
+// BEFORE building the router (requireBuilder / requireRank are captured at
+// build time; memory.* and db.insertAuditLog are called by property at request
+// time). This is the same "stub the dependency module" pattern the project uses
+// elsewhere — no DI framework, just Node's module cache.
+const auth = require('../src/module-api'); // doorway: memory-module routes capture api.requireBuilder, so the stub must patch the doorway (BV1.R72 / ADR 0091)
+const memory = require('../modules/memory/memory.js');
+const db = require('../src/bongos/db.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then(() => { passed++; console.log(`  PASS  ${name}`); })
+    .catch((e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); });
+}
+
+// ===========================================================================
+// Layer 1 — pure helpers + source structure
+// ===========================================================================
+
+const buildMemoryRouter = require('../modules/memory/routes/memory.js');
+const { assertSelf, recordForensicRead } = buildMemoryRouter._internals;
+
+console.log('assertSelf (isolation invariant for the self endpoints):');
+
+await t('returns the session builder id when no owner is claimed', () => {
+  const id = assertSelf({ builder: { id: 42 } });
+  assert.equal(id, 42);
+});
+
+await t('returns the session id when a matching owner is claimed', () => {
+  const id = assertSelf({ builder: { id: 42 } }, 42);
+  assert.equal(id, 42);
+});
+
+await t('THROWS CROSS_BUILDER_FORBIDDEN when a DIFFERENT owner is claimed', () => {
+  assert.throws(
+    () => assertSelf({ builder: { id: 42 } }, 99),
+    (e) => e && e.code === 'CROSS_BUILDER_FORBIDDEN' && String(e.self) === '42' && String(e.claimed) === '99'
+  );
+});
+
+await t('THROWS CROSS_BUILDER_FORBIDDEN even when ids differ only by string/number type', () => {
+  assert.throws(() => assertSelf({ builder: { id: 42 } }, '99'), (e) => e.code === 'CROSS_BUILDER_FORBIDDEN');
+  assert.equal(assertSelf({ builder: { id: 42 } }, '42'), 42);
+});
+
+await t('fails closed (NOT_AUTHENTICATED) when there is no builder on the request', () => {
+  assert.throws(() => assertSelf({}), (e) => e && e.code === 'NOT_AUTHENTICATED');
+  assert.throws(() => assertSelf({ builder: {} }), (e) => e && e.code === 'NOT_AUTHENTICATED');
+});
+
+console.log('\nrecordForensicRead (Archon cross-builder reads are audit-logged):');
+
+await t('writes an audit row with the archon id, target id, path, and forensic action', async () => {
+  let captured = null;
+  const req = {
+    builder: { id: 7, rank: 'archon' },
+    ip: '203.0.113.9',
+    headers: { 'user-agent': 'gds-cli/1.0' },
+  };
+  await recordForensicRead(
+    req,
+    { route: '/api/gds/memory/builders/:builderId/file', targetBuilderId: 99, target: 'MEMORY.md' },
+    (row) => { captured = row; }
+  );
+  assert.ok(captured, 'an audit row should have been built');
+  assert.equal(captured.builderId, 7, 'audit row attributes the read to the ARCHON');
+  assert.ok(['POST', 'PATCH', 'PUT', 'DELETE'].includes(captured.method), 'method must satisfy the CHECK constraint');
+  assert.equal(captured.route, '/api/gds/memory/builders/:builderId/file');
+  assert.equal(captured.requestBodyRedacted.action, 'archon_forensic_memory_read');
+  assert.equal(captured.requestBodyRedacted.http_method, 'GET');
+  assert.equal(captured.requestBodyRedacted.target_builder_id, 99);
+  assert.equal(captured.requestBodyRedacted.target, 'MEMORY.md');
+  assert.equal(captured.ip, '203.0.113.9');
+  assert.equal(captured.userAgent, 'gds-cli/1.0');
+});
+
+await t('records the ACTUAL outcome status (404 when the target file was absent)', async () => {
+  // Fix #4: the audit row must carry the real outcome, not a hardcoded 200.
+  let captured = null;
+  await recordForensicRead(
+    { builder: { id: 7 }, headers: {} },
+    { route: '/api/gds/memory/builders/:builderId/file', targetBuilderId: 99, target: 'gone.md', responseStatus: 404 },
+    (row) => { captured = row; }
+  );
+  assert.equal(captured.responseStatus, 404, 'a 404 look must be audited as 404');
+});
+
+await t('defaults responseStatus to 200 when not specified', async () => {
+  let captured = null;
+  await recordForensicRead(
+    { builder: { id: 7 }, headers: {} },
+    { route: '/api/gds/memory/builders/:builderId/files', targetBuilderId: 99, target: 'list' },
+    (row) => { captured = row; }
+  );
+  assert.equal(captured.responseStatus, 200);
+});
+
+await t('uses target="list" for the directory-listing forensic read', async () => {
+  let captured = null;
+  await recordForensicRead(
+    { builder: { id: 7 }, headers: {} },
+    { route: '/api/gds/memory/builders/:builderId/files', targetBuilderId: 99, target: 'list' },
+    (row) => { captured = row; }
+  );
+  assert.equal(captured.requestBodyRedacted.target, 'list');
+});
+
+await t('PROPAGATES an audit insert failure (fail-closed: caller must see it)', async () => {
+  // Fix #1: recordForensicRead no longer swallows. The route catches the
+  // rejection and fails the read closed (500) — proven end-to-end below — but
+  // at the helper level the contract is now "reject, do not swallow".
+  let threw = false;
+  try {
+    await recordForensicRead(
+      { builder: { id: 7 }, headers: {} },
+      { route: '/api/gds/memory/builders/:builderId/files', targetBuilderId: 99, target: 'list' },
+      () => { throw new Error('db down'); }
+    );
+  } catch (_e) {
+    threw = true;
+  }
+  assert.equal(threw, true, 'recordForensicRead MUST reject on insert failure so the route can fail closed');
+});
+
+console.log('\nroute source structural checks (the trust boundary is airtight):');
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const rawSrc = fs.readFileSync(path.join(here, '..', 'modules', 'memory', 'routes', 'memory.js'), 'utf8');
+const src = rawSrc; // route/rank-gate checks run against the full source
+const codeOnly = rawSrc
+  .split('\n')
+  .map((line) => {
+    const idx = line.indexOf('//');
+    return idx >= 0 ? line.slice(0, idx) : line;
+  })
+  .join('\n');
+
+await t('the two Archon forensic endpoints are both rank-gated to archon', () => {
+  const forensicRoutes = [
+    "'/memory/builders/:builderId/files'",
+    "'/memory/builders/:builderId/file'",
+  ];
+  for (const route of forensicRoutes) {
+    const idx = src.indexOf(route);
+    assert.ok(idx >= 0, `route ${route} should be declared`);
+    const window = src.slice(idx, idx + 200);
+    assert.ok(
+      /requireRank\('archon'\)/.test(window),
+      `route ${route} must be gated by requireRank('archon')`
+    );
+  }
+});
+
+await t('every forensic endpoint calls recordForensicRead (audited)', () => {
+  const callSites = (src.match(/recordForensicRead\(req,/g) || []).length;
+  assert.ok(callSites >= 2, `expected >=2 recordForensicRead call sites, found ${callSites}`);
+});
+
+await t('production code contains no grader-system references', () => {
+  // Fix #3: shipped code must not name the grader or its workers.
+  assert.ok(!/grader/i.test(rawSrc), 'memory.js route source must not mention the grader');
+  assert.ok(!/hacker worker/i.test(rawSrc), 'memory.js route source must not mention grader workers');
+});
+
+await t('the SELF read endpoints never derive the owner from request input', () => {
+  assert.ok(!/req\.query\.builder/i.test(codeOnly), 'no owner should come from req.query.builder*');
+  assert.ok(!/req\.body\.builder/i.test(codeOnly), 'no owner should come from req.body.builder*');
+  assert.ok(!/req\.body\.owner/i.test(codeOnly), 'no owner should come from req.body.owner');
+  // An input-supplied owner (req.params.builderId) may ONLY appear inside a
+  // PRIVILEGED cross-builder endpoint: either the Archon-rank-gated forensic
+  // READS (requireRank('archon')) or the BFG-principal-gated WRITE
+  // (requireBfgPrincipal — an identity gate stricter than any rank; 6C.1 /
+  // ADR 0026 §6C). Both are audited. No SELF endpoint reads it.
+  const paramUses = [...codeOnly.matchAll(/req\.params\.builderId/g)].map((m) => m.index);
+  for (const i of paramUses) {
+    const window = codeOnly.slice(Math.max(0, i - 700), i);
+    assert.ok(
+      /requireRank\('archon'\)/.test(window) || /requireBfgPrincipal/.test(window),
+      'req.params.builderId may only be read inside an archon-gated forensic read OR the BFG-principal-gated write'
+    );
+  }
+});
+
+await t('listMemoryFiles / fetchMemoryFile are called with a self-scoped or audited id only', () => {
+  assert.ok(/assertSelf\(req\)/.test(src), 'self endpoints must call assertSelf(req)');
+  assert.ok(/Number\(req\.params\.builderId\)/.test(src), 'forensic endpoints must coerce + validate the target id');
+});
+
+// ===========================================================================
+// Layer 2 — REAL in-process HTTP through the actual router (no DB)
+//
+// We monkeypatch the dependency modules, build the REAL router, mount it on a
+// throwaway express app, listen on an ephemeral port, and fire real requests.
+// This proves the done-when "builder A reading builder B → 403" against the
+// actual middleware stack, plus the fail-closed-audit fix end-to-end.
+// ===========================================================================
+
+console.log('\nHTTP-level isolation (real router, fake auth, stubbed store/audit):');
+
+// --- save originals so we can restore after the HTTP suite ---
+const orig = {
+  requireBuilder: auth.requireBuilder,
+  requireRank: auth.requireRank,
+  listMemoryFiles: memory.listMemoryFiles,
+  fetchMemoryFile: memory.fetchMemoryFile,
+  insertAuditLog: db.insertAuditLog,
+  assertValidPath: memory.assertValidPath,
+};
+
+// --- mutable test fixtures the stubs read/write ---
+const fixture = {
+  // the authenticated session injected by the fake requireBuilder
+  session: { id: 1, rank: 'xenos' },
+  // record every (fn, builderId) the store helpers were called with
+  storeCalls: [],
+  // record every audit row the insert stub was handed; toggle to make it throw
+  auditCalls: [],
+  auditShouldThrow: false,
+};
+
+// Fake auth: requireBuilder injects whatever fixture.session currently is.
+auth.requireBuilder = function fakeRequireBuilder(req, _res, next) {
+  req.builder = { ...fixture.session };
+  next();
+};
+// Real-shaped requireRank: 403 if the injected session's rank isn't allowed —
+// this is the exact gate behavior, so the 403 we assert is the real rank gate.
+auth.requireRank = function fakeRequireRank(...allowed) {
+  const allowedSet = new Set(allowed);
+  return function rankGate(req, res, next) {
+    const actual = req.builder && req.builder.rank;
+    if (!actual || !allowedSet.has(actual)) {
+      res.status(403).json({ error: 'rank_forbidden', required: [...allowedSet], actual: actual ?? null });
+      return;
+    }
+    next();
+  };
+};
+
+// Stub the store helpers to RECORD the builderId they were called with (the
+// isolation assertion) and return canned rows — no DB.
+memory.listMemoryFiles = async function stubList(builderId) {
+  fixture.storeCalls.push({ fn: 'listMemoryFiles', builderId });
+  return [
+    { path: 'MEMORY.md', sha256: 'abc', byte_len: 10, mtime: null, updated_at: '2026-05-30T00:00:00Z', created_at: '2026-05-30T00:00:00Z' },
+  ];
+};
+memory.fetchMemoryFile = async function stubFetch(builderId, p) {
+  fixture.storeCalls.push({ fn: 'fetchMemoryFile', builderId, path: p });
+  if (p === 'missing.md') return null;
+  return { path: p, content: 'hello', sha256: 'abc', byte_len: 5, mtime: null, updated_at: '2026-05-30T00:00:00Z', created_at: '2026-05-30T00:00:00Z' };
+};
+// Keep path validation real (it's a pure function) — just pass through.
+memory.assertValidPath = orig.assertValidPath;
+
+// Stub the audit insert: async, records the row, optionally throws. Making it
+// async + asserting the response waited for it proves the route AWAITS it.
+db.insertAuditLog = async function stubAudit(row) {
+  // yield a turn so a non-awaited caller would race ahead of us
+  await new Promise((r) => setImmediate(r));
+  if (fixture.auditShouldThrow) throw new Error('audit db down');
+  fixture.auditCalls.push(row);
+  return { id: fixture.auditCalls.length, recorded_at: new Date().toISOString() };
+};
+
+// Build the REAL router AFTER the auth stubs are in place (middleware captured
+// at build time). express is a CJS dep already in the tree.
+const express = require('express');
+const app = express();
+app.use(express.json());
+app.use('/api/gds', buildMemoryRouter());
+
+const server = http.createServer(app);
+await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+const base = `http://127.0.0.1:${server.address().port}/api/gds`;
+
+function reset() {
+  fixture.storeCalls = [];
+  fixture.auditCalls = [];
+  fixture.auditShouldThrow = false;
+}
+
+try {
+  await t('(a) NON-Archon authenticated builder hitting the forensic route → 403 (rank gate)', async () => {
+    reset();
+    fixture.session = { id: 1, rank: 'xenos' };
+    const res = await fetch(`${base}/memory/builders/99/files`);
+    assert.equal(res.status, 403, 'a non-archon must be refused by the rank gate');
+    const body = await res.json();
+    assert.equal(body.error, 'rank_forbidden');
+    // The store must NEVER have been touched for builder 99.
+    assert.equal(fixture.storeCalls.length, 0, 'no store call may happen when the rank gate refuses');
+  });
+
+  await t('(a2) a metic is ALSO refused the forensic route (archon-only)', async () => {
+    reset();
+    fixture.session = { id: 5, rank: 'metic' };
+    const res = await fetch(`${base}/memory/builders/99/file?path=MEMORY.md`);
+    assert.equal(res.status, 403);
+    assert.equal(fixture.storeCalls.length, 0);
+  });
+
+  await t('(b) GET /memory/files only ever lists the AUTHENTICATED builder', async () => {
+    reset();
+    fixture.session = { id: 42, rank: 'xenos' };
+    const res = await fetch(`${base}/memory/files`);
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.builder_id, 42);
+    // The store was asked for builder 42 — the session id — and nothing else.
+    assert.equal(fixture.storeCalls.length, 1);
+    assert.equal(fixture.storeCalls[0].fn, 'listMemoryFiles');
+    assert.equal(fixture.storeCalls[0].builderId, 42, 'self endpoint must pass the SESSION id to the store');
+  });
+
+  await t('(b2) GET /memory/file only ever fetches the AUTHENTICATED builder (no owner param to even request another)', async () => {
+    reset();
+    fixture.session = { id: 42, rank: 'xenos' };
+    const res = await fetch(`${base}/memory/file?path=MEMORY.md`);
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.builder_id, 42);
+    assert.equal(fixture.storeCalls.length, 1);
+    assert.equal(fixture.storeCalls[0].fn, 'fetchMemoryFile');
+    assert.equal(fixture.storeCalls[0].builderId, 42, 'self endpoint must pass the SESSION id, never a path-supplied owner');
+  });
+
+  await t('(c) an Archon hitting the forensic route → 200 AND an audit row was written (and awaited)', async () => {
+    reset();
+    fixture.session = { id: 7, rank: 'archon' };
+    const res = await fetch(`${base}/memory/builders/99/files`);
+    assert.equal(res.status, 200, 'archon is allowed through the rank gate');
+    const body = await res.json();
+    assert.equal(body.builder_id, 99);
+    assert.equal(body.forensic, true);
+    // The store was queried for the TARGET (99), the audit attributes it to the ARCHON (7).
+    assert.equal(fixture.storeCalls[0].builderId, 99, 'forensic read targets the path-supplied id');
+    assert.equal(fixture.auditCalls.length, 1, 'exactly one audit row must have been written');
+    assert.equal(fixture.auditCalls[0].builderId, 7, 'audit attributes the read to the archon');
+    assert.equal(fixture.auditCalls[0].responseStatus, 200, 'a successful list is audited as 200');
+    // If the route had NOT awaited the (async) audit insert, the 200 response
+    // would have raced ahead and auditCalls would be empty when we read it.
+    // It is populated → the route awaited it.
+  });
+
+  await t('(c2) forensic file read of a MISSING file → 404 AND audited as 404 (accurate status)', async () => {
+    reset();
+    fixture.session = { id: 7, rank: 'archon' };
+    const res = await fetch(`${base}/memory/builders/99/file?path=missing.md`);
+    assert.equal(res.status, 404);
+    assert.equal(fixture.auditCalls.length, 1, 'a 404 look is still audited (the Archon TRIED to read it)');
+    assert.equal(fixture.auditCalls[0].responseStatus, 404, 'the absent-file look must be audited as 404, not 200');
+  });
+
+  await t('(d) FAIL CLOSED: if the audit insert throws, the forensic read → 500 and does NOT leak the target data', async () => {
+    reset();
+    fixture.session = { id: 7, rank: 'archon' };
+    fixture.auditShouldThrow = true;
+    const res = await fetch(`${base}/memory/builders/99/file?path=MEMORY.md`);
+    assert.equal(res.status, 500, 'a failed audit must fail the read closed');
+    const body = await res.json();
+    assert.equal(body.error, 'audit_failed');
+    // Critically: the target's file content must NOT be in the response.
+    assert.ok(!('content' in body), 'the target builder content must NOT leak when the audit failed');
+    assert.equal(body.content, undefined);
+  });
+
+  await t('(d2) FAIL CLOSED also applies to the forensic LIST endpoint', async () => {
+    reset();
+    fixture.session = { id: 7, rank: 'archon' };
+    fixture.auditShouldThrow = true;
+    const res = await fetch(`${base}/memory/builders/99/files`);
+    assert.equal(res.status, 500);
+    const body = await res.json();
+    assert.equal(body.error, 'audit_failed');
+    assert.ok(!('files' in body), 'the target builder file list must NOT leak when the audit failed');
+  });
+} finally {
+  await new Promise((resolve) => server.close(resolve));
+  // restore originals so we don't poison any later test in the same process
+  auth.requireBuilder = orig.requireBuilder;
+  auth.requireRank = orig.requireRank;
+  memory.listMemoryFiles = orig.listMemoryFiles;
+  memory.fetchMemoryFile = orig.fetchMemoryFile;
+  db.insertAuditLog = orig.insertAuditLog;
+  memory.assertValidPath = orig.assertValidPath;
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/memory_map.mjs

@@ -0,0 +1,107 @@
+// Tests for scripts/gds/memory-map.js — the memory-map guard + auto-tidy (task 1362).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const mm = require(path.join(ROOT, 'scripts/gds/memory-map.js'));
+
+// Build a synthetic MEMORY.md: `rules` feedback_* entries + `projects` project-NNN
+// entries, each hook `hookLen` chars. mtime is injected by index so project-001 is
+// oldest and project-<projects> is newest.
+function mkMap({ rules = 3, projects = 45, hookLen = 400 } = {}) {
+  const lines = [];
+  for (let i = 1; i <= rules; i++) lines.push(`- [rule ${i}](feedback_rule_${i}.md) — ${'x'.repeat(hookLen)}`);
+  for (let i = 1; i <= projects; i++) {
+    const n = String(i).padStart(3, '0');
+    lines.push(`- [proj ${n}](project-${n}.md) — ${'x'.repeat(hookLen)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+// Deterministic metadata: feedback_* → rule; project-NNN → project, mtime = NNN.
+const metaOf = (file) => /^feedback_/.test(file)
+  ? { type: 'feedback', mtime: 0 }
+  : { type: 'project', mtime: Number((file.match(/(\d+)/) || [0, 0])[1]) };
+
+test('measure flags over-budget sizes, counts entries, and catches over-long lines', () => {
+  const small = '- [a](a.md) — short\n';
+  assert.equal(mm.measure(small).overWarn, false);
+  assert.equal(mm.measure(small).count, 1);
+
+  const big = mkMap({ rules: 3, projects: 45, hookLen: 400 }); // ~21KB
+  const m = mm.measure(big);
+  assert.equal(m.overWarn, true);
+  assert.equal(m.overTidy, true, 'a ~21KB map must be over the tidy threshold');
+  assert.equal(m.count, 48);
+
+  const longLine = `- [x](x.md) — ${'y'.repeat(mm.MAX_LINE_CHARS + 10)}\n`;
+  assert.equal(mm.measure(longLine).longLines.length, 1, 'a >MAX_LINE_CHARS entry is flagged');
+});
+
+test('auto-tidy keeps every rule + the newest non-rule entries, demotes the oldest', () => {
+  const text = mkMap({ rules: 3, projects: 45, hookLen: 400 });
+  const plan = mm.planCompaction(text, { metaOf, keepNewest: 25, targetBytes: mm.TARGET_BYTES });
+
+  assert.equal(plan.willChange, true, 'an over-target map must compact');
+  // No standing rule is ever demoted.
+  assert.ok(!plan.demote.some((d) => /^feedback_/.test(d.file)), 'rules must never be demoted');
+  assert.ok(plan.newText.includes('feedback_rule_1.md'), 'rule lines stay in the map');
+  // Oldest project demoted; newest kept.
+  assert.ok(plan.demote.some((d) => d.file === 'project-001.md'), 'the oldest non-rule entry is demoted');
+  assert.ok(!plan.demote.some((d) => d.file === 'project-045.md'), 'the newest non-rule entry is kept');
+  assert.ok(!plan.newText.includes('project-001.md'), 'a demoted entry leaves the map');
+  // Result is back under target.
+  assert.ok(mm.measure(plan.newText).bytes <= mm.TARGET_BYTES, 'compaction lands under target');
+  assert.equal(mm.measure(plan.newText).overTidy, false);
+});
+
+test('rules are never demoted even when the map is all rules and over target', () => {
+  const allRules = mkMap({ rules: 60, projects: 0, hookLen: 400 }); // big, but every entry is a rule
+  assert.equal(mm.measure(allRules).overTidy, true);
+  const plan = mm.planCompaction(allRules, { metaOf, keepNewest: 25, targetBytes: mm.TARGET_BYTES });
+  assert.equal(plan.demote.length, 0, 'a map of only standing rules demotes nothing');
+  assert.equal(plan.willChange, false);
+});
+
+test('a pinned entry stays on the home screen even when it is the oldest', () => {
+  const text = mkMap({ rules: 0, projects: 45, hookLen: 400 });
+  // pin the OLDEST project (project-001) — it would otherwise be demoted first.
+  const metaPinned = (file) => file === 'project-001.md'
+    ? { type: 'project', mtime: 1, pin: true }
+    : metaOf(file);
+  const plan = mm.planCompaction(text, { metaOf: metaPinned, keepNewest: 25, targetBytes: mm.TARGET_BYTES });
+  assert.ok(plan.willChange, 'an over-target map still compacts');
+  assert.ok(!plan.demote.some((d) => d.file === 'project-001.md'), 'a pinned entry is never demoted');
+  assert.ok(plan.newText.includes('project-001.md'), 'the pinned entry stays in the map');
+});
+
+test('demotion only removes lines — it never returns or touches a topic file', () => {
+  // planCompaction is pure on (text, meta); it produces newText, never filesystem ops.
+  const text = mkMap({ rules: 2, projects: 40, hookLen: 400 });
+  const plan = mm.planCompaction(text, { metaOf, keepNewest: 10, targetBytes: mm.TARGET_BYTES });
+  // every demoted file is simply absent from newText; nothing claims to delete it.
+  for (const d of plan.demote) assert.ok(!plan.newText.includes(`(${d.file})`), `${d.file} line removed`);
+  // kept + demoted accounts for all non-rule entries (none silently lost).
+  const keptEntries = mm.entries(plan.newText).length;
+  assert.equal(keptEntries + plan.demote.length, mm.entries(text).length, 'no entry vanishes unaccounted-for');
+});
+
+test('applyCompaction is parallel-safe: it skips the write if the file changed since read', () => {
+  const expected = '- [a](a.md) — one\n';
+  const next = '- [a](a.md) — two\n';
+  let written = null;
+  const deps = { readFile: () => expected, writeFile: (_p, c) => { written = c; } };
+  assert.deepEqual(mm.applyCompaction('/x/MEMORY.md', expected, next, deps), { written: true });
+  assert.equal(written, next);
+
+  // Now a concurrent session changed the file out from under us → do NOT clobber.
+  written = null;
+  const deps2 = { readFile: () => 'something a parallel session wrote\n', writeFile: (_p, c) => { written = c; } };
+  const r = mm.applyCompaction('/x/MEMORY.md', expected, next, deps2);
+  assert.equal(r.written, false);
+  assert.equal(r.reason, 'changed-since-read');
+  assert.equal(written, null, 'must not write when the file changed since read');
+});