@bongos/core 1.17.0

package/modules/memory/routes/memory.js

@@ -0,0 +1,916 @@
+// GDS builder-memory sync — HTTP surface over the #273/R54 storage helpers.
+//
+// Implements the push half of ADR 0024 (cloneable repo + local-first memory
+// with server-canonical sync): /builder-ship enumerates the builder's local
+// Claude Code memory dir and POSTs each file here; this route stores them via
+// src/bongos/memory.js (storeMemoryFile), last-write-wins.
+//
+// Scope of THIS task (#274 / V3.R55): the POST /memory/sync endpoint + the
+// ship.js wiring (in scripts/gds/ship.js). The READ side (GET /memory/files,
+// GET /memory/file) + the isolation-hardening + Archon forensic read land in
+// #276 (this task); the pull-on-start wiring lands in #275. Those build ON
+// this.
+//
+// ISOLATION (ADR 0024 §4, same posture as ADR 0016) — the trust boundary of
+// this entire module:
+//   * Every SELF endpoint (the common path: POST /memory/sync, GET
+//     /memory/files, GET /memory/file) takes its owner ALWAYS from
+//     req.builder.id — the authenticated session — NEVER from req.body,
+//     req.query, or req.params. There is deliberately no `builder_id` /
+//     `owner` input field on any self endpoint. A builder physically cannot
+//     read OR write another builder's keyspace through these routes: there is
+//     no parameter to even name another builder.
+//   * The ONLY endpoints that accept an owner id from input are the two
+//     Archon-only forensic reads (GET /memory/builders/:builderId/files and
+//     .../file). They are READ-ONLY, gated by requireRank('archon'), and EVERY
+//     call writes an audit_log row recording {archon id, target builder id,
+//     path|'list', action}. No write path ever accepts a cross-builder owner.
+// This mirrors ADR 0016: enforce server-side, trust nothing a builder can edit
+// locally. The grep-test for a reviewer is simple — search this file for
+// `req.body`, `req.query.builder`, `req.params.builderId`; the only owner
+// derived from input lives under the audited Archon path.
+//
+// RENDER / STORED-XSS (#575, audit 2026-06-19) — memory content is stored RAW
+// and is NEVER emitted as HTML. Every endpoint here returns it as JSON
+// (res.json — content as a string field), and the only consumers are the CLI /
+// dev-box memory sync (it writes the strings to the local filesystem) and the
+// Archon-only forensic reads (also JSON). An audit of every web surface
+// (modules/hall-ui/public/, modules/status-ui/public/) found NO code path that interpolates
+// memory content into the DOM: there is no markdown→HTML renderer in the client
+// at all, and the one place that does render externally-authored markdown — the
+// Archon "Watch" security-doc reader (modules/hall-ui/public/watch.js) — escapes via
+// OTB.escapeHtml + a <pre>. So the stored-XSS vector that the threat model lists
+// for "memory content" (docs/security/threat-model.md §5 external input) is NOT
+// realized today; this is the "record why low-priority" outcome of #575.
+// FORWARD RULE (load-bearing): if a memory-viewer UI is ever added to the hall,
+// it MUST escape the content at the render boundary (OTB.escapeHtml, like
+// watch.js) — memory is builder-controlled free text, never trusted markup.
+//
+// Body limit: the global GDS json parser is capped at 64 KB (routes.js), but a
+// single memory file may be up to 1 MB (memory.js MAX_FILE_BYTES) and a sync
+// batches several files. So this router mounts its OWN express.json with a
+// larger limit, scoped to the /memory/sync path only — it does not relax the
+// 64 KB cap that every other GDS write still runs under. The read endpoints
+// take no body and rely on the global parser.
+
+const express = require('express');
+// Carved into modules/memory/ (BV1.R72 / ADR 0091 §2): reach core ONLY through
+// the published doorway. Auth gates + the kernel db helpers this route uses
+// (getBuilderById, insertAuditLog) come off `api`; the memory lib is an
+// intra-module require.
+const api = require('../../../src/module-api');
+const auth = api;
+const memory = require('../memory');
+const db = api;
+
+// Per-builder rate limit for POST /memory/sync, layered ON TOP of the global
+// per-IP / per-session limiter (middleware/rate-limit.js, applied to every
+// write). This endpoint is special: a single request can carry up to 50 MB
+// across 2000 files, so even one request/minute is a lot of work — the global
+// 30-writes/min cap is the wrong shape here. We add a tighter sliding-window
+// cap keyed on the AUTHENTICATED builder id (never on input), reusing the same
+// in-memory sliding-window technique as the global limiter rather than
+// inventing a new system. A sync runs once per /builder-ship, so a few per
+// minute is generous headroom; the cap exists to stop a runaway loop from
+// hammering large bodies.
+const SYNC_RATE_WINDOW_MS = 60 * 1000;
+const SYNC_RATE_LIMIT = 6; // syncs per builder per minute
+const syncBuckets = new Map(); // builderId -> timestamp[]
+
+const syncSweepTimer = setInterval(() => {
+  const cutoff = Date.now() - SYNC_RATE_WINDOW_MS;
+  for (const [k, arr] of syncBuckets) {
+    while (arr.length && arr[0] < cutoff) arr.shift();
+    if (arr.length === 0) syncBuckets.delete(k);
+  }
+}, 5 * 60 * 1000);
+if (typeof syncSweepTimer.unref === 'function') syncSweepTimer.unref();
+
+// Express middleware: enforce the per-builder sync cap. Runs AFTER
+// auth.requireBuilder so req.builder.id is populated.
+function syncRateLimit(req, res, next) {
+  const now = Date.now();
+  const key = String(req.builder.id);
+  let bucket = syncBuckets.get(key);
+  if (!bucket) { bucket = []; syncBuckets.set(key, bucket); }
+  const cutoff = now - SYNC_RATE_WINDOW_MS;
+  while (bucket.length && bucket[0] < cutoff) bucket.shift();
+  if (bucket.length >= SYNC_RATE_LIMIT) {
+    const retryAfter = Math.max(1, Math.ceil((bucket[0] + SYNC_RATE_WINDOW_MS - now) / 1000));
+    res.set('Retry-After', String(retryAfter));
+    res.set('X-RateLimit-Scope', 'per-builder-memory-sync');
+    res.set('X-RateLimit-Limit', String(SYNC_RATE_LIMIT));
+    res.set('X-RateLimit-Window-Seconds', String(SYNC_RATE_WINDOW_MS / 1000));
+    return res.fail('rate_limited', 429, { scope: 'per-builder-memory-sync', retry_after_seconds: retryAfter });
+  }
+  bucket.push(now);
+  return next();
+}
+
+// Per-builder rate limit for the READ endpoints (GET /memory/files,
+// GET /memory/file, and the two Archon forensic reads). The global
+// rate-limit middleware (middleware/rate-limit.js) only caps WRITE methods —
+// GET requests bypass it entirely — so without this a pull loop (or a forensic
+// sweep) could hammer reads uncapped. Reads are cheaper than a sync, so the cap
+// is more generous, but it still exists: keyed on the AUTHENTICATED builder id
+// (never on input), same sliding-window technique as the sync limiter and the
+// global limiter. We reuse one bucket map for every read on this router.
+const READ_RATE_WINDOW_MS = 60 * 1000;
+const READ_RATE_LIMIT = 120; // memory reads per builder per minute
+const readBuckets = new Map(); // builderId -> timestamp[]
+
+const readSweepTimer = setInterval(() => {
+  const cutoff = Date.now() - READ_RATE_WINDOW_MS;
+  for (const [k, arr] of readBuckets) {
+    while (arr.length && arr[0] < cutoff) arr.shift();
+    if (arr.length === 0) readBuckets.delete(k);
+  }
+}, 5 * 60 * 1000);
+if (typeof readSweepTimer.unref === 'function') readSweepTimer.unref();
+
+// Express middleware: enforce the per-builder read cap. Runs AFTER
+// auth.requireBuilder so req.builder.id is populated. Keyed on the
+// authenticated id only — never on any path/query input.
+function readRateLimit(req, res, next) {
+  const now = Date.now();
+  const key = String(req.builder.id);
+  let bucket = readBuckets.get(key);
+  if (!bucket) { bucket = []; readBuckets.set(key, bucket); }
+  const cutoff = now - READ_RATE_WINDOW_MS;
+  while (bucket.length && bucket[0] < cutoff) bucket.shift();
+  if (bucket.length >= READ_RATE_LIMIT) {
+    const retryAfter = Math.max(1, Math.ceil((bucket[0] + READ_RATE_WINDOW_MS - now) / 1000));
+    res.set('Retry-After', String(retryAfter));
+    res.set('X-RateLimit-Scope', 'per-builder-memory-read');
+    res.set('X-RateLimit-Limit', String(READ_RATE_LIMIT));
+    res.set('X-RateLimit-Window-Seconds', String(READ_RATE_WINDOW_MS / 1000));
+    return res.fail('rate_limited', 429, { scope: 'per-builder-memory-read', retry_after_seconds: retryAfter });
+  }
+  bucket.push(now);
+  return next();
+}
+
+// assertSelf — the explicit, testable statement of the isolation invariant for
+// the SELF endpoints. It returns the ONLY id a self endpoint may ever use as
+// the memory owner: req.builder.id (the authenticated session). It throws if a
+// caller-supplied owner is present and DOESN'T match the session — defense in
+// depth, since the self endpoints never read such a field in the first place,
+// but it makes the invariant impossible to violate by a later careless edit
+// (e.g. someone wiring a caller-supplied owner-id query param into a handler).
+// The invariant: a self endpoint's owner is ALWAYS the authenticated session
+// (req.builder.id). The ONLY owner-from-input path in this module is the Archon
+// forensic route, which is rank-gated and audited. Reading these helpers and
+// their call sites establishes that a self endpoint cannot return another
+// builder's data, full stop.
+function assertSelf(req, claimedOwnerId) {
+  const selfId = req.builder && req.builder.id;
+  if (selfId === undefined || selfId === null) {
+    // Should be unreachable behind requireBuilder, but fail closed.
+    throw { code: 'NOT_AUTHENTICATED' };
+  }
+  if (
+    claimedOwnerId !== undefined &&
+    claimedOwnerId !== null &&
+    String(claimedOwnerId) !== String(selfId)
+  ) {
+    throw { code: 'CROSS_BUILDER_FORBIDDEN', self: selfId, claimed: claimedOwnerId };
+  }
+  return selfId;
+}
+
+// recordForensicRead — write an audit_log row for an Archon's cross-builder
+// memory read. The global audit middleware only instruments mutating methods
+// (POST/PATCH/PUT/DELETE), and these are GETs, so it does NOT fire for them —
+// we record explicitly here so every forensic look is logged (the done-when
+// requirement). The audit_log.method column is CHECK-constrained to a write
+// verb, so we record the action as 'POST' (it IS a logged, privileged action)
+// and carry the true semantics in route + the redacted body.
+//
+// FAIL-CLOSED (V3.R57): unlike the global audit middleware (which
+// fires after the response and may swallow), this MUST be awaited BEFORE the
+// Archon is shown any of the target builder's data, and a failed insert MUST
+// surface to the caller as a rejected promise. The invariant is that no
+// forensic cross-builder read is ever served without a durable audit row — so
+// the caller awaits this, and on rejection returns 500 and withholds the data.
+// We do NOT catch/swallow here: the catch belongs to the route, which turns a
+// rejection into a 500 (and logs it) rather than leaking the target's content.
+//
+// `responseStatus` is the ACTUAL outcome of the look (200 when a file/list was
+// returned, 404 when the target file was absent) so the forensic trail is
+// accurate rather than always claiming 200.
+function recordForensicRead(req, { route, targetBuilderId, target, responseStatus = 200, action = 'archon_forensic_memory_read' }, insertFn) {
+  const insert = typeof insertFn === 'function' ? insertFn : db.insertAuditLog;
+  // Return the insert promise directly (awaited by the caller). Any rejection
+  // propagates — the route's try/catch fails the read closed.
+  return Promise.resolve(
+    insert({
+      builderId: req.builder.id,
+      route,
+      method: 'POST', // CHECK constraint forbids 'GET'; semantics live in the body
+      requestBodyRedacted: {
+        // 'archon_forensic_memory_read' (Archon rank-gated) or 'bfg_memory_read'
+        // (BFG-principal-gated, 6B.1) — auditors query by this action.
+        action,
+        http_method: 'GET',
+        target_builder_id: targetBuilderId,
+        target, // a path string, or 'list'
+      },
+      responseStatus,
+      ip: req.ip || (req.socket && req.socket.remoteAddress) || null,
+      userAgent: (req.headers && req.headers['user-agent']) || null,
+    })
+  );
+}
+
+// Generous batch cap: MAX_BUILDER_BYTES (50 MB) + framing headroom. A push
+// that would exceed the per-builder quota is still rejected per-file with a
+// clean 413 below; this limit only stops a pathological request body from
+// being buffered into memory. Files-per-request is capped separately.
+const SYNC_BODY_LIMIT = '64mb';
+const MAX_FILES_PER_SYNC = memory.MAX_BUILDER_FILES; // 2000 — same as the per-builder file cap
+
+// Kill-switch (ADR 0026 §6C): the cross-builder WRITE path is DISABLED unless
+// BFG_WRITE_ENABLED === 'true' in the environment. Fail-safe default — this is a
+// deliberate, bounded puncture of the trust boundary (ADR 0016), so the capability
+// stays OFF until an operator turns it on (set in the droplet EnvironmentFile,
+// then restart). Unsetting it + restart instantly closes the path again. Checked
+// per-request so the running process reflects the env at request time. Pure +
+// exported so tests can drive it via process.env without standing up the server.
+function bfgWriteEnabled() {
+  return process.env.BFG_WRITE_ENABLED === 'true';
+}
+
+module.exports = function buildMemoryRouter() {
+  const router = express.Router();
+
+  // Larger body parser, scoped to this path only. Mounted before the handler
+  // so the route sees the parsed array. routes.js explicitly SKIPS the global
+  // 64 KB parser for the /memory/sync path (its mounter checks req.path and
+  // calls next() without parsing), so this router's own express.json is the
+  // ONLY body parser that runs here — making SYNC_BODY_LIMIT the effective cap.
+  const syncJson = express.json({ limit: SYNC_BODY_LIMIT });
+
+  // POST /memory/sync — push a builder's local memory files to the server.
+  //
+  // Auth: any authenticated builder (requireBuilder). A builder can only ever
+  // write their OWN memory — the owner is req.builder.id, never from input.
+  //
+  // Request body (two accepted shapes):
+  //   { files: [ { path, content, mtime? }, ... ] }   (preferred)
+  //   [ { path, content, mtime? }, ... ]               (bare array, also ok)
+  // where:
+  //   path    — string, relative path under the memory dir (e.g. 'MEMORY.md').
+  //             Validated by storeMemoryFile (no leading '/', no '..', no NUL).
+  //   content — string, the file body (UTF-8).
+  //   mtime   — optional ISO-8601 string or epoch ms; the source file's mtime.
+  //             Stored for the pull side's newer-than check. Server clock is the
+  //             conflict authority (last-write-wins), so this is advisory.
+  //
+  // Response 200 (always 200 when the request itself was well-formed; per-file
+  // outcomes are in the body so one bad file doesn't sink the batch):
+  //   {
+  //     stored:  <count of files upserted>,
+  //     skipped: <count of files skipped — e.g. non-string content>,
+  //     errors:  [ { path, code, message, hint? }, ... ],
+  //     results: [ { path, stored: true, sha256, byte_len, updated_at } | { path, error: {...} } ]
+  //   }
+  // A quota/oversize failure on a file is reported in errors[] with code
+  // FILE_TOO_LARGE / MEMORY_QUOTA_EXCEEDED and an HTTP 413 IF ANY file tripped a
+  // quota (so the client knows to prune), otherwise HTTP 200. Malformed paths
+  // (BAD_PATH) are per-file errors and do NOT force a non-200 — they're a client
+  // bug, not a quota signal.
+  router.post('/memory/sync', auth.requireBuilder, syncRateLimit, syncJson, async (req, res) => {
+    const builderId = req.builder.id;
+
+    // strict:false — /memory/sync accepts a bare ARRAY or { files: [...] } (dual
+    // shape), and the block below does the authoritative shape/size validation;
+    // this declares `files` for the spec + type-checks the object form only.
+    if (api.validateOrRespond(req, res, { files: { type: 'array' } }, { strict: false })) return;
+
+    // Normalize the two accepted body shapes into an array of file entries.
+    const body = req.body;
+    let files;
+    if (Array.isArray(body)) {
+      files = body;
+    } else if (body && Array.isArray(body.files)) {
+      files = body.files;
+    } else {
+      return res.fail('bad_request', { status: 400, message: 'body must be an array of {path, content, mtime?} or { files: [...] }' });
+    }
+
+    if (files.length > MAX_FILES_PER_SYNC) {
+      return res.fail('too_many_files', { status: 413, message: `at most ${MAX_FILES_PER_SYNC} files per sync`, details: { count: files.length, max: MAX_FILES_PER_SYNC } });
+    }
+
+    const results = [];
+    const errors = [];
+    let stored = 0;
+    let skipped = 0;
+    let quotaTripped = false;
+
+    // First pass: filter out the files that fail input-shape validation
+    // (BAD_PATH / BAD_CONTENT) — those are the caller's bug and never reach the
+    // DB. The rest go to the batch helper, which does all upserts + the
+    // per-builder quota check inside ONE transaction (was N transactions —
+    // one per file — before this fix).
+    const toStore = [];          // { path, content, mtime } entries for the batch
+    const placeholder = [];      // results[] slots to fill from the batch, in order
+    for (const f of files) {
+      const path = f && typeof f.path === 'string' ? f.path : null;
+      if (!path) {
+        skipped += 1;
+        const err = { path: path ?? '<missing>', code: 'BAD_PATH', message: 'path must be a non-empty string' };
+        errors.push(err);
+        results.push({ path: err.path, error: { code: err.code, message: 'internal error' } });
+        continue;
+      }
+      if (typeof f.content !== 'string') {
+        skipped += 1;
+        const err = { path, code: 'BAD_CONTENT', message: 'content must be a string' };
+        errors.push(err);
+        results.push({ path, error: { code: err.code, message: 'internal error' } });
+        continue;
+      }
+      // Reserved-namespace guard (ADR 0026 §6C): a builder cannot SYNC into the
+      // BFG's keyspace. `bfg/` is exclusively BFG-written, so the BFG never
+      // collides with — nor overwrites — a builder's own file. The builder can
+      // still READ and DELETE files under bfg/ (their own keyspace); they just
+      // can't create/overwrite them via sync.
+      if (memory.isReservedNamespacePath(path)) {
+        skipped += 1;
+        const err = { path, code: 'RESERVED_NAMESPACE', message: `'${memory.BFG_NAMESPACE_PREFIX}' is reserved for BFG-authored notes and cannot be synced into` };
+        errors.push(err);
+        results.push({ path, error: { code: err.code, message: 'internal error' } });
+        continue;
+      }
+      // Reserve this file's slot in results[] now so order is preserved.
+      const slot = results.length;
+      results.push(null);
+      placeholder.push(slot);
+      toStore.push({ path, content: f.content, mtime: f.mtime ?? null });
+    }
+
+    // Single transaction for every well-formed file (N+1 fix).
+    let batch = [];
+    try {
+      batch = await memory.storeMemoryFilesBatch(builderId, toStore);
+    } catch (e) {
+      // A throw here means the transaction itself failed (BEGIN/COMMIT/connect),
+      // not a per-file rejection — those come back inside the results array.
+      console.error('[gds] POST /memory/sync batch transaction error', { builderId, err: e });
+      return res.fail('store_failed', { status: 500, message: 'memory sync failed; nothing was stored' });
+    }
+
+    // Fold the batch's per-file outcomes back into the response, preserving the
+    // exact shape (and the exact error mapping) the old per-file loop produced.
+    for (let i = 0; i < batch.length; i++) {
+      const slot = placeholder[i];
+      const r = batch[i];
+      const path = toStore[i].path;
+      if (r && r.ok) {
+        const row = r.row;
+        stored += 1;
+        results[slot] = {
+          path: row.path,
+          stored: true,
+          sha256: row.sha256,
+          byte_len: Number(row.byte_len),
+          updated_at: row.updated_at,
+        };
+        continue;
+      }
+      // Per-file rejection — same code/hint mapping as before.
+      const e = r && r.error ? r.error : null;
+      const code = e && e.code ? e.code : 'STORE_FAILED';
+      let message = (e && e.message) || 'store failed';
+      let hint;
+      if (code === 'FILE_TOO_LARGE') {
+        quotaTripped = true;
+        message = `file exceeds the ${memory.MAX_FILE_BYTES}-byte per-file limit`;
+        hint = 'Prune or split this file before syncing; the server stores files individually.';
+      } else if (code === 'MEMORY_QUOTA_EXCEEDED') {
+        quotaTripped = true;
+        message =
+          e.kind === 'file_count'
+            ? `would exceed the ${memory.MAX_BUILDER_FILES}-file per-builder limit`
+            : `would exceed the ${memory.MAX_BUILDER_BYTES}-byte per-builder limit`;
+        hint = 'Prune old memory files (the limit is per-builder, summed across all files).';
+      } else if (code !== 'BAD_PATH' && code !== 'STORE_FAILED') {
+        // Unknown helper error code — log for forensics, still report per-file.
+        console.error('[gds] POST /memory/sync store error', { builderId, path, code, err: e });
+      } else if (code === 'STORE_FAILED') {
+        console.error('[gds] POST /memory/sync unexpected error', { builderId, path, err: e });
+      }
+      const err = { path, code, message, ...(hint ? { hint } : {}) };
+      errors.push(err);
+      results[slot] = { path, error: { code, message, ...(hint ? { hint } : {}) } };
+    }
+
+    const payload = { stored, skipped, errors, results };
+    // 413 only when a quota/size limit was actually hit, so the client knows to
+    // prune. Malformed-path / bad-content errors stay on a 200 — the batch was
+    // accepted, those individual files are just the caller's bug.
+    res.status(quotaTripped ? 413 : 200).json(payload);
+  });
+
+  // -----------------------------------------------------------------------
+  // READ side (#276 / V3.R57) — strictly self-scoped. The pull side (#275)
+  // and a builder inspecting their own memory call these. The owner is ALWAYS
+  // req.builder.id; there is no parameter to name another builder, so these
+  // are inherently isolated — assertSelf() states that invariant explicitly.
+  // -----------------------------------------------------------------------
+
+  // GET /memory/files — list the AUTHENTICATED builder's memory files
+  // (metadata only, no content). Single query (listMemoryFiles is one SELECT —
+  // no N+1). Returns newest-changed first.
+  //
+  // Auth: any authenticated builder (requireBuilder). Self-scoped: owner is
+  // req.builder.id. NO owner param is accepted.
+  //
+  // Response 200:
+  //   { builder_id, count, files: [ { path, sha256, byte_len, mtime, updated_at, created_at }, ... ] }
+  router.get('/memory/files', auth.requireBuilder, readRateLimit, async (req, res) => {
+    let builderId;
+    try {
+      builderId = assertSelf(req); // owner is the session, never input
+    } catch (_e) {
+      return res.fail('unauthenticated', 401);
+    }
+    try {
+      const rows = await memory.listMemoryFiles(builderId);
+      res.set('Cache-Control', 'no-store');
+      return res.json({
+        builder_id: builderId,
+        count: rows.length,
+        files: rows.map((r) => ({
+          path: r.path,
+          sha256: r.sha256,
+          byte_len: Number(r.byte_len),
+          mtime: r.mtime,
+          updated_at: r.updated_at,
+          created_at: r.created_at,
+        })),
+      });
+    } catch (err) {
+      console.error('[gds] GET /memory/files', { builderId, err });
+      return res.fail('list_failed', { status: 500, message: 'could not list memory files' });
+    }
+  });
+
+  // GET /memory/file?path=... — fetch ONE of the AUTHENTICATED builder's files
+  // (content included). Single query (fetchMemoryFile is one SELECT). 404 if
+  // this builder has no file at that path. We use a ?path= query rather than a
+  // path-segment param because the stored keys are relative paths that may
+  // contain '/' (e.g. 'sub/dir/notes.md'); a single :path segment can't carry a
+  // slash, and a wildcard segment re-opens the traversal surface that
+  // assertValidPath exists to close. The query value is validated by
+  // assertValidPath (no leading '/', no '..', no NUL, no backslash) before it
+  // ever reaches the store.
+  //
+  // Auth: any authenticated builder. Self-scoped: owner is req.builder.id.
+  //
+  // Response 200:
+  //   { builder_id, path, content, sha256, byte_len, mtime, updated_at, created_at }
+  router.get('/memory/file', auth.requireBuilder, readRateLimit, async (req, res) => {
+    let builderId;
+    try {
+      builderId = assertSelf(req);
+    } catch (_e) {
+      return res.fail('unauthenticated', 401);
+    }
+    const path = typeof req.query.path === 'string' ? req.query.path : null;
+    if (path === null) {
+      return res.fail('bad_request', { status: 400, message: 'path query param is required', details: { code: 'BAD_PATH' } });
+    }
+    try {
+      memory.assertValidPath(path); // reuse the one canonical validator
+    } catch (e) {
+      return res.fail('bad_path', { status: 400, message: 'internal error' ? e.message : 'invalid path', details: { code: 'BAD_PATH' } });
+    }
+    try {
+      const row = await memory.fetchMemoryFile(builderId, path);
+      if (!row) {
+        return res.fail('not_found', 404, { path });
+      }
+      res.set('Cache-Control', 'no-store');
+      return res.json({
+        builder_id: builderId,
+        path: row.path,
+        content: row.content,
+        sha256: row.sha256,
+        byte_len: Number(row.byte_len),
+        mtime: row.mtime,
+        updated_at: row.updated_at,
+        created_at: row.created_at,
+      });
+    } catch (err) {
+      console.error('[gds] GET /memory/file', { builderId, path, err });
+      return res.fail('fetch_failed', { status: 500, message: 'could not fetch memory file' });
+    }
+  });
+
+  // DELETE /memory/file?path=... — the SELF delete affordance (ADR 0026 §6C).
+  // A builder removes ONE of their OWN files — INCLUDING a BFG-written
+  // dream/correction, which lives in this builder's keyspace. Owner is ALWAYS
+  // req.builder.id (assertSelf); there is no parameter to delete another
+  // builder's file, so this can't be a cross-builder delete. This is what makes
+  // a BFG write reversible by its recipient (the load-bearing consent property).
+  // Single-line opener so the route-rank auditor classifies it ('any-builder').
+  router.delete('/memory/file', auth.requireBuilder, readRateLimit, async (req, res) => {
+    // Query-param validation (R11/#1998): type-check `path`. strict:false tolerates
+    // incidental query params rather than reject; the handler enforces path
+    // presence/shape (bad_request/bad_path) below.
+    if (api.validateOrRespond(req, res, {}, { query: { path: { type: 'string' } }, strict: false })) return;
+    let builderId;
+    try { builderId = assertSelf(req); } catch (_e) { return res.fail('unauthenticated', 401); }
+    const path = typeof req.query.path === 'string' ? req.query.path : null;
+    if (path === null) {
+      return res.fail('bad_request', { status: 400, message: 'path query param is required', details: { code: 'BAD_PATH' } });
+    }
+    try {
+      memory.assertValidPath(path);
+    } catch (e) {
+      return res.fail('bad_path', { status: 400, message: 'internal error' ? e.message : 'invalid path', details: { code: 'BAD_PATH' } });
+    }
+    try {
+      const n = await memory.deleteMemoryFile(builderId, path);
+      if (n === 0) return res.fail('not_found', 404, { path });
+      return res.json({ deleted: true, builder_id: builderId, path });
+    } catch (err) {
+      console.error('[gds] DELETE /memory/file', { builderId, path, err });
+      return res.fail('delete_failed', { status: 500, message: 'could not delete memory file' });
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // ARCHON FORENSIC OVERRIDE (#276 / V3.R57) — the ONLY endpoints in this
+  // module that take an owner id from input. READ-ONLY, requireRank('archon'),
+  // and EVERY call is audit-logged (recordForensicRead) because the global
+  // audit middleware doesn't instrument GETs. This is the documented exception
+  // to the isolation invariant: an Archon can read another builder's memory for
+  // forensics, but the read leaves an immutable trail.
+  // -----------------------------------------------------------------------
+
+  // GET /memory/builders/:builderId/files — Archon lists ANOTHER builder's
+  // memory file metadata. Audit-logged.
+  router.get(
+    '/memory/builders/:builderId/files',
+    auth.requireBuilder,
+    auth.requireRank('archon'),
+    readRateLimit,
+    async (req, res) => {
+      const targetId = Number(req.params.builderId);
+      if (!Number.isInteger(targetId) || targetId <= 0) {
+        return res.fail('bad_builder_id', 400);
+      }
+      const route = '/api/bongos/memory/builders/:builderId/files';
+      let rows;
+      try {
+        rows = await memory.listMemoryFiles(targetId);
+      } catch (err) {
+        console.error('[gds] GET /memory/builders/:builderId/files', { targetId, err });
+        return res.fail('list_failed', { status: 500, message: 'could not list memory files' });
+      }
+      // FAIL CLOSED: the audit row must land durably BEFORE we return any of the
+      // target builder's data. A list always "succeeds" (empty list is a valid
+      // result), so the audited responseStatus is 200. If the audit insert
+      // throws, withhold the data and return 500 — no forensic read is ever
+      // served without a durable audit row.
+      try {
+        await recordForensicRead(req, { route, targetBuilderId: targetId, target: 'list', responseStatus: 200 });
+      } catch (auditErr) {
+        console.error('[gds] forensic-read audit insert failed (read withheld)', {
+          route, targetId, err: auditErr && auditErr.message ? auditErr.message : String(auditErr),
+        });
+        return res.fail('audit_failed', { status: 500, message: 'forensic read not served: audit could not be recorded' });
+      }
+      res.set('Cache-Control', 'no-store');
+      return res.json({
+        builder_id: targetId,
+        forensic: true,
+        count: rows.length,
+        files: rows.map((r) => ({
+          path: r.path,
+          sha256: r.sha256,
+          byte_len: Number(r.byte_len),
+          mtime: r.mtime,
+          updated_at: r.updated_at,
+          created_at: r.created_at,
+        })),
+      });
+    }
+  );
+
+  // GET /memory/builders/:builderId/file?path=... — Archon reads ONE of
+  // ANOTHER builder's files (content included). Audit-logged. 404 if the
+  // target has no file at that path.
+  router.get(
+    '/memory/builders/:builderId/file',
+    auth.requireBuilder,
+    auth.requireRank('archon'),
+    readRateLimit,
+    async (req, res) => {
+      const targetId = Number(req.params.builderId);
+      if (!Number.isInteger(targetId) || targetId <= 0) {
+        return res.fail('bad_builder_id', 400);
+      }
+      const path = typeof req.query.path === 'string' ? req.query.path : null;
+      if (path === null) {
+        return res.fail('bad_request', { status: 400, message: 'path query param is required', details: { code: 'BAD_PATH' } });
+      }
+      try {
+        memory.assertValidPath(path);
+      } catch (e) {
+        return res.fail('bad_path', { status: 400, message: 'internal error' ? e.message : 'invalid path', details: { code: 'BAD_PATH' } });
+      }
+      const route = '/api/bongos/memory/builders/:builderId/file';
+      let row;
+      try {
+        row = await memory.fetchMemoryFile(targetId, path);
+      } catch (err) {
+        console.error('[gds] GET /memory/builders/:builderId/file', { targetId, path, err });
+        return res.fail('fetch_failed', { status: 500, message: 'could not fetch memory file' });
+      }
+      // FAIL CLOSED: audit the look — logged even if the path is a 404, because
+      // "the Archon TRIED to read X" is the forensic fact we want — and the row
+      // must land durably BEFORE we return data. responseStatus reflects the
+      // ACTUAL outcome (200 if the file existed, 404 if absent), not a hardcoded
+      // 200. If the audit insert throws, withhold data and return 500.
+      const outcomeStatus = row ? 200 : 404;
+      try {
+        await recordForensicRead(req, { route, targetBuilderId: targetId, target: path, responseStatus: outcomeStatus });
+      } catch (auditErr) {
+        console.error('[gds] forensic-read audit insert failed (read withheld)', {
+          route, targetId, path, err: auditErr && auditErr.message ? auditErr.message : String(auditErr),
+        });
+        return res.fail('audit_failed', { status: 500, message: 'forensic read not served: audit could not be recorded' });
+      }
+      if (!row) {
+        return res.fail('not_found', 404, { builder_id: targetId, path });
+      }
+      res.set('Cache-Control', 'no-store');
+      return res.json({
+        builder_id: targetId,
+        forensic: true,
+        path: row.path,
+        content: row.content,
+        sha256: row.sha256,
+        byte_len: Number(row.byte_len),
+        mtime: row.mtime,
+        updated_at: row.updated_at,
+        created_at: row.created_at,
+      });
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // BFG CROSS-BUILDER READ (#444 / ADR 0026 §6B) — the "read the room"
+  // substrate. Reachable ONLY by the BFG service principal (requireBfgPrincipal,
+  // an IDENTITY gate — NOT Archon rank), same audited fail-closed posture as the
+  // Archon forensic reads above but with a distinct audit action
+  // ('bfg_memory_read'). Lets the BFG read any builder's memory to SCORE
+  // interaction quality and (in 6B.2) extract transferable practice. Openers are
+  // single-line so the route-rank auditor detects + classifies them.
+  // -----------------------------------------------------------------------
+
+  router.get('/memory/bfg/builders/:builderId/files',
+    auth.requireBuilder,
+    auth.requireBfgPrincipal,
+    readRateLimit,
+    async (req, res) => {
+      const targetId = Number(req.params.builderId);
+      if (!Number.isInteger(targetId) || targetId <= 0) {
+        return res.fail('bad_builder_id', 400);
+      }
+      const route = '/api/bongos/memory/bfg/builders/:builderId/files';
+      let rows;
+      try {
+        rows = await memory.listMemoryFiles(targetId);
+      } catch (err) {
+        console.error('[gds] GET /memory/bfg/builders/:builderId/files', { targetId, err });
+        return res.fail('list_failed', { status: 500, message: 'could not list memory files' });
+      }
+      // FAIL CLOSED: the audit row must land before any of the target's data is
+      // served (same invariant as the Archon forensic read).
+      try {
+        await recordForensicRead(req, { route, targetBuilderId: targetId, target: 'list', responseStatus: 200, action: 'bfg_memory_read' });
+      } catch (auditErr) {
+        console.error('[gds] bfg-read audit insert failed (read withheld)', { route, targetId, err: auditErr && auditErr.message ? auditErr.message : String(auditErr) });
+        return res.fail('audit_failed', { status: 500, message: 'read not served: audit could not be recorded' });
+      }
+      res.set('Cache-Control', 'no-store');
+      return res.json({
+        builder_id: targetId,
+        bfg_read: true,
+        count: rows.length,
+        files: rows.map((r) => ({ path: r.path, sha256: r.sha256, byte_len: Number(r.byte_len), mtime: r.mtime, updated_at: r.updated_at, created_at: r.created_at })),
+      });
+    }
+  );
+
+  router.get('/memory/bfg/builders/:builderId/file',
+    auth.requireBuilder,
+    auth.requireBfgPrincipal,
+    readRateLimit,
+    async (req, res) => {
+      const targetId = Number(req.params.builderId);
+      if (!Number.isInteger(targetId) || targetId <= 0) {
+        return res.fail('bad_builder_id', 400);
+      }
+      const path = typeof req.query.path === 'string' ? req.query.path : null;
+      if (path === null) {
+        return res.fail('bad_request', { status: 400, message: 'path query param is required', details: { code: 'BAD_PATH' } });
+      }
+      try {
+        memory.assertValidPath(path);
+      } catch (e) {
+        return res.fail('bad_path', { status: 400, message: 'internal error' ? e.message : 'invalid path', details: { code: 'BAD_PATH' } });
+      }
+      const route = '/api/bongos/memory/bfg/builders/:builderId/file';
+      let row;
+      try {
+        row = await memory.fetchMemoryFile(targetId, path);
+      } catch (err) {
+        console.error('[gds] GET /memory/bfg/builders/:builderId/file', { targetId, path, err });
+        return res.fail('fetch_failed', { status: 500, message: 'could not fetch memory file' });
+      }
+      const outcomeStatus = row ? 200 : 404;
+      try {
+        await recordForensicRead(req, { route, targetBuilderId: targetId, target: path, responseStatus: outcomeStatus, action: 'bfg_memory_read' });
+      } catch (auditErr) {
+        console.error('[gds] bfg-read audit insert failed (read withheld)', { route, targetId, path, err: auditErr && auditErr.message ? auditErr.message : String(auditErr) });
+        return res.fail('audit_failed', { status: 500, message: 'read not served: audit could not be recorded' });
+      }
+      if (!row) return res.fail('not_found', 404, { builder_id: targetId, path });
+      res.set('Cache-Control', 'no-store');
+      return res.json({
+        builder_id: targetId,
+        bfg_read: true,
+        path: row.path,
+        content: row.content,
+        sha256: row.sha256,
+        byte_len: Number(row.byte_len),
+        mtime: row.mtime,
+        updated_at: row.updated_at,
+        created_at: row.created_at,
+      });
+    }
+  );
+
+  // -----------------------------------------------------------------------
+  // BFG CROSS-BUILDER WRITE (#446 / ADR 0026 §6C) — the FIRST cross-builder
+  // memory write path, the deliberate bounded exception to ADR 0016. Reachable
+  // ONLY by the BFG service principal (requireBfgPrincipal — an IDENTITY gate on
+  // system_role='bfg', NOT a rank gate, so an Archon/stolen token is rejected),
+  // ONLY when the kill-switch BFG_WRITE_ENABLED is on, and EVERY write lands a
+  // fail-closed audit row in the SAME transaction as the write (memory.bfgWrite-
+  // MemoryFile). Writes are namespaced (bfg/<kind>-<slug>.md) + self-announcing
+  // (frontmatter author: BFG) so a BFG note can never masquerade as the
+  // builder's own. The builder can always see and delete it.
+  //
+  // Rate limiting: this is a small write (one file), so the GLOBAL per-session/
+  // per-IP write limiter (middleware/rate-limit.js, applied to every GDS write)
+  // already throttles a runaway loop. Unlike /memory/sync — which carries up to
+  // 50 MB and needed a tighter dedicated cap — this endpoint doesn't warrant its
+  // own limiter, especially as it's principal-only + kill-switched.
+  //
+  // POST /memory/builders/:builderId/bfg-write
+  //   body: { kind: 'dream'|'correction', slug, title?, body_md, rationale }
+  //   201 → { ok, builder_id, path, kind, author:'BFG', audit_id, sha256, byte_len, updated_at }
+  // Declaration opener kept on ONE line (route path beside router.post) so the
+  // deterministic route-rank auditor (src/bongos/route-rank-check.js) detects +
+  // classifies it; it reads requireBuilder in the chain below → 'any-builder',
+  // and requireBfgPrincipal narrows that to the principal alone.
+  router.post('/memory/builders/:builderId/bfg-write',
+    auth.requireBuilder,
+    auth.requireBfgPrincipal,
+    async (req, res) => {
+      // Kill-switch first: a disabled write path must answer the same to the
+      // principal as to anyone else — the capability simply isn't on.
+      if (!bfgWriteEnabled()) {
+        return res.fail('bfg_write_disabled', { status: 503, message: 'the BFG cross-builder write path is disabled (BFG_WRITE_ENABLED is not set)' });
+      }
+      const targetId = Number(req.params.builderId);
+      if (!Number.isInteger(targetId) || targetId <= 0) {
+        return res.fail('bad_builder_id', 400);
+      }
+      if (String(targetId) === String(req.builder.id)) {
+        return res.fail('bfg_cannot_write_self', 400);
+      }
+
+      if (api.validateOrRespond(req, res, {
+        kind: { type: 'string' },
+        slug: { type: 'string' },
+        title: { type: 'string' },
+        body_md: { type: 'string' },
+        rationale: { type: 'string' },
+        karma_delta: {},  // non-positive integer or null; validated below (correction-only)
+      })) return;
+      const { kind, slug, title, body_md, rationale } = req.body || {};
+
+      // Construct the attributed file (pure) — throws BAD_BFG_* on bad input, so
+      // the mandatory frontmatter can never be omitted.
+      let file;
+      try {
+        file = memory.buildBfgMemoryFile({
+          kind,
+          slug,
+          title,
+          body_md,
+          rationale,
+          sourceBuilder: req.builder.github_login,
+          targetBuilderId: targetId,
+        });
+      } catch (e) {
+        return res.fail('bad_bfg_input', { status: 400, message: 'internal error', details: { code: e && e.code } });
+      }
+
+      // Target must be a real, non-system builder.
+      let target;
+      try {
+        target = await db.getBuilderById(targetId);
+      } catch (err) {
+        console.error('[gds] bfg-write target lookup', { targetId, err });
+        return res.fail('lookup_failed', 500);
+      }
+      if (!target) return res.fail('target_not_found', 404);
+      if (target.system_role) return res.fail('target_is_system_principal', 400);
+
+      // 6C.2 — a CORRECTION may carry a negative karma delta alongside its note
+      // (ADR 0026 §6C). It is only valid on a correction, and MUST be
+      // non-positive: the BFG corrects by docking, never by rewarding (a reward
+      // is a different, non-BFG mechanism). A dream never carries karma.
+      let karma = null;
+      if (req.body.karma_delta != null) {
+        if (kind !== 'correction') {
+          return res.fail('karma_delta_not_allowed', { status: 400, message: 'karma_delta is only valid for kind=correction' });
+        }
+        const kd = Number(req.body.karma_delta);
+        if (!Number.isInteger(kd) || kd > 0) {
+          return res.fail('bad_karma_delta', { status: 400, message: 'karma_delta must be a non-positive integer (corrections dock, never reward)' });
+        }
+        if (kd !== 0) karma = { delta: kd, reason: 'bfg_correction', grantedBy: req.builder.id };
+      }
+
+      const action = kind === 'correction' ? 'bfg_correction_write' : 'bfg_dream_write';
+      try {
+        const result = await memory.bfgWriteMemoryFile({
+          targetBuilderId: targetId,
+          path: file.path,
+          content: file.content,
+          audit: {
+            principalId: req.builder.id,
+            route: '/api/bongos/memory/builders/:builderId/bfg-write',
+            action,
+            kind,
+            rationale: String(rationale).slice(0, 500),
+            responseStatus: 201,
+            ip: req.ip || (req.socket && req.socket.remoteAddress) || null,
+            userAgent: (req.headers && req.headers['user-agent']) || null,
+          },
+          karma,
+        });
+        return res.status(201).json({
+          ok: true,
+          builder_id: targetId,
+          path: result.row.path,
+          kind,
+          author: 'BFG',
+          audit_id: result.audit_id,
+          karma_id: result.karma_id ?? null,
+          sha256: result.row.sha256,
+          byte_len: Number(result.row.byte_len),
+          updated_at: result.row.updated_at,
+        });
+      } catch (e) {
+        const code = e && e.code;
+        if (code === 'FILE_TOO_LARGE' || code === 'MEMORY_QUOTA_EXCEEDED') {
+          return res.fail('quota_exceeded', 413, { code });
+        }
+        if (code === 'NOT_BFG_NAMESPACE') {
+          // Unreachable via THIS route (buildBfgMemoryFile always yields a bfg/
+          // path), but bfgWriteMemoryFile is exported — this keeps the helper's
+          // own assertBfgPath guard mapped to a clean 400 for any direct caller.
+          return res.fail('bad_path', 400, { code });
+        }
+        console.error('[gds] POST /memory/builders/:builderId/bfg-write', e);
+        return res.fail('bfg_write_failed', 500);
+      }
+    }
+  );
+
+  return router;
+};
+
+// Exposed for the test suite — pure helpers + the middleware factories, no
+// router state. Tests exercise the isolation invariant (assertSelf) and the
+// forensic audit shape directly, without standing up Express or a DB.
+module.exports._internals = {
+  assertSelf,
+  recordForensicRead,
+  readRateLimit,
+  syncRateLimit,
+  READ_RATE_LIMIT,
+  SYNC_RATE_LIMIT,
+  bfgWriteEnabled,
+};