@bongos/core 1.17.0

package/modules/memory/memory.js

@@ -0,0 +1,572 @@
+// GDS builder-memory store — server-side helpers for a builder's Claude Code
+// per-session memory dir.
+//
+// Implements ADR 0024 (cloneable repo + local-first memory with server-canonical
+// sync) §1 (schema) and the helper-layer half of §4 (per-builder isolation).
+// Schema lives in migrations/054_builder_memory.sql.
+//
+// Scope of THIS module (task #273 / V3.R54): the storage layer only — the three
+// helpers below, plus quota enforcement and per-builder isolation. The HTTP
+// endpoints that call these (POST /memory/sync, GET /memory/since, GET
+// /memory/files, GET /memory/files/:path) land in #274/#276 (src/bongos/routes/
+// memory.js); the /builder-ship push wiring lands in #274; the pull-on-start
+// wiring lands in #275. Those tasks build ON these helpers.
+//
+// Isolation (ADR 0024 §4): EVERY helper here is scoped by builder_id — there is
+// no helper that reads or lists across builders. A caller physically cannot use
+// this module to read another builder's files, because builder_id is a required
+// argument on every function and is part of the table's PRIMARY KEY. The route
+// layer (#276) adds the matching req.builder.id === path_owner check and the
+// Archon-only audit-logged forensic read; this layer is the floor beneath it.
+// Same trust-boundary posture as ADR 0016: enforce server-side, trust nothing a
+// builder can edit locally.
+//
+// Like db.js, this module is pure SQL plumbing over the shared Pool — routing
+// and auth live elsewhere.
+
+const crypto = require('crypto');
+// Carved into modules/memory/ (BV1.R72 / ADR 0091 §2): reach the shared pool
+// through the published doorway — a module never requires a core internal.
+const { pool } = require('../../src/module-api');
+// ADR 0095 C4: <private>…</private>-fenced content is stripped at ingest so it
+// is never persisted to builder memory (nor, via the chunker, indexed). Pure +
+// intra-module require (the chunker is the module's hermetic text-transform).
+const { stripPrivate } = require('./search-chunker');
+
+// -------------------------------------------------------------------------
+// Quotas (ADR 0024 §1) — enforced HERE, not by DB constraints, so the API can
+// return a clean 413 with a prune hint rather than a constraint-violation 500.
+// The numbers are deliberate over-estimates (current observed memory dirs are
+// kilobytes / ~3 files); if real usage outgrows them we raise the cap or prune,
+// neither of which is load-bearing.
+// -------------------------------------------------------------------------
+const MAX_FILE_BYTES = 1 * 1024 * 1024;        // 1 MB per file
+const MAX_BUILDER_BYTES = 50 * 1024 * 1024;    // 50 MB total per builder
+const MAX_BUILDER_FILES = 2000;                // 2000 files per builder
+
+// Reject a path that tries to escape the builder's memory dir. The store keys
+// by (builder_id, relative-path) and never touches the local filesystem, so
+// path traversal can't read another builder's *rows* — but a '..' or absolute
+// path is still a malformed key we don't want to persist (it would make the
+// pull side write outside the memory dir on restore). Belt-and-braces with the
+// route layer's own validation.
+function assertValidPath(path) {
+  if (typeof path !== 'string' || path.length === 0) {
+    throw { code: 'BAD_PATH', message: 'path must be a non-empty string' };
+  }
+  if (path.startsWith('/') || path.includes('..') || path.includes('\0') || path.includes('\\')) {
+    throw { code: 'BAD_PATH', message: 'path must be a relative path inside the memory dir (no leading /, no "..", no backslash, no NUL)' };
+  }
+}
+
+function sha256Hex(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+// Normalize a client-supplied mtime into a valid Date or null. mtime is
+// advisory (the server clock is the conflict authority), so an unparseable
+// value must NOT throw — we store NULL and let the row's own updated_at be the
+// truth. Guards against `new Date('garbage')` producing an Invalid Date that pg
+// would choke on.
+function normalizeMtime(mtime) {
+  if (mtime == null) return null;
+  const d = mtime instanceof Date ? mtime : new Date(mtime);
+  if (isNaN(d.getTime())) return null;
+  return d;
+}
+
+// storeMemoryFile — upsert one file for one builder (ADR 0024 §1 + §3).
+//
+// Per-file quota is checked first (1 MB). Then the per-builder caps (50 MB
+// total, 2000 files) are checked transactionally against the builder's CURRENT
+// stored set, treating this write as a replace-or-add of `path` — so re-saving
+// an existing file never trips the count cap, and the byte cap is computed on
+// the post-write total (current total − old size of this path + new size).
+//
+// Conflict policy (§3) is last-write-wins, server clock. We do NOT compare
+// mtimes here and reject — the route layer decides whether an incoming push is
+// "newer" before calling this; this helper unconditionally writes what it's
+// given (an UPSERT). The stored `mtime` is the client's reported file mtime
+// (for the pull side's newer-than check); the server's own "when did this row
+// change" truth is updated_at (trigger-maintained).
+//
+// Returns the stored row's metadata (no content echo). Throws:
+//   { code:'BAD_PATH' }                          — malformed path
+//   { code:'FILE_TOO_LARGE', byteLen, max }      — single file over 1 MB
+//   { code:'MEMORY_QUOTA_EXCEEDED', kind, ... }  — would exceed 50 MB or 2000 files
+async function storeMemoryFile(builderId, path, content, opts = {}) {
+  assertValidPath(path);
+  // ADR 0095 C4: strip <private>-fenced content before it is sized/hashed/stored.
+  const body = stripPrivate(typeof content === 'string' ? content : String(content ?? ''));
+  const byteLen = Buffer.byteLength(body, 'utf8');
+
+  if (byteLen > MAX_FILE_BYTES) {
+    throw { code: 'FILE_TOO_LARGE', byteLen, max: MAX_FILE_BYTES, path };
+  }
+
+  const sha256 = sha256Hex(body);
+  // mtime: caller may pass the source file's mtime; default to server now().
+  // An unparseable mtime is normalized to NULL (advisory field — never throws).
+  const mtime = normalizeMtime(opts.mtime);
+
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    // Lock this builder's rows for the duration so the quota check and the
+    // upsert see a consistent snapshot (two concurrent pushes from the same
+    // builder can't both slip under the cap).
+    const { rows: existing } = await client.query(
+      `SELECT path, byte_len FROM builder_memory
+        WHERE builder_id = $1
+        FOR UPDATE`,
+      [builderId]
+    );
+
+    const currentTotalBytes = existing.reduce((sum, r) => sum + Number(r.byte_len), 0);
+    const oldRow = existing.find((r) => r.path === path);
+    const isReplace = oldRow !== undefined;
+    const oldBytes = isReplace ? Number(oldRow.byte_len) : 0;
+
+    // File-count cap only bites when ADDING a new path.
+    if (!isReplace && existing.length >= MAX_BUILDER_FILES) {
+      throw {
+        code: 'MEMORY_QUOTA_EXCEEDED',
+        kind: 'file_count',
+        current: existing.length,
+        max: MAX_BUILDER_FILES,
+      };
+    }
+
+    // Byte cap on the post-write total.
+    const projectedTotal = currentTotalBytes - oldBytes + byteLen;
+    if (projectedTotal > MAX_BUILDER_BYTES) {
+      throw {
+        code: 'MEMORY_QUOTA_EXCEEDED',
+        kind: 'total_bytes',
+        currentBytes: currentTotalBytes,
+        projectedBytes: projectedTotal,
+        max: MAX_BUILDER_BYTES,
+      };
+    }
+
+    const { rows } = await client.query(
+      `INSERT INTO builder_memory (builder_id, path, content, mtime, sha256, byte_len)
+       VALUES ($1, $2, $3, COALESCE($4, now()), $5, $6)
+       ON CONFLICT (builder_id, path) DO UPDATE
+         SET content  = EXCLUDED.content,
+             mtime    = EXCLUDED.mtime,
+             sha256   = EXCLUDED.sha256,
+             byte_len = EXCLUDED.byte_len
+       RETURNING builder_id, path, mtime, sha256, byte_len, created_at, updated_at`,
+      [builderId, path, body, mtime, sha256, byteLen]
+    );
+
+    await client.query('COMMIT');
+    return rows[0];
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// storeMemoryFilesBatch — upsert MANY files for one builder in ONE transaction.
+//
+// Same semantics as storeMemoryFile, but the whole batch shares a single
+// BEGIN/COMMIT (the route used to open one transaction PER file — N+1). The
+// per-builder quota (50 MB total, 2000 files) is computed ONCE against the
+// builder's currently-stored rows, then the batch's effect is folded in as we
+// walk it — so the cap accounts for the whole batch, not each file in
+// isolation. Conflict policy is unchanged (last-write-wins UPSERT).
+//
+// Failure model matches the single-file helper, but per-file: instead of
+// throwing on the first bad file (which would roll back the whole batch and
+// punish the good files), each file gets its own result entry. A file that
+// trips a per-file or per-builder limit is recorded with the SAME error shape
+// storeMemoryFile throws ({ code, ... }); the good files still commit. This
+// lets the route map errors exactly as it does for the single-file path.
+//
+// `files` is [ { path, content, mtime? }, ... ]. Returns a results array, one
+// entry per input file IN ORDER:
+//   { ok: true,  row }                 — stored (row is the upserted metadata)
+//   { ok: false, error: { code, ... } } — rejected (BAD_PATH / FILE_TOO_LARGE /
+//                                          MEMORY_QUOTA_EXCEEDED), same codes as
+//                                          storeMemoryFile.
+// Content that isn't a string is the route's concern (BAD_CONTENT) — it filters
+// those before calling, so here every entry is assumed to have string content.
+async function storeMemoryFilesBatch(builderId, files) {
+  const entries = Array.isArray(files) ? files : [];
+  const results = new Array(entries.length);
+
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    // Snapshot + lock this builder's rows once for the whole batch, so the
+    // quota check sees a consistent view and concurrent pushes can't both slip
+    // under the cap.
+    const { rows: existing } = await client.query(
+      `SELECT path, byte_len FROM builder_memory
+        WHERE builder_id = $1
+        FOR UPDATE`,
+      [builderId]
+    );
+
+    // Running totals start from what's already stored, then fold in each
+    // accepted file in this batch (a replace swaps old bytes for new and keeps
+    // the file count flat; a new path adds bytes and bumps the count).
+    let runningBytes = existing.reduce((sum, r) => sum + Number(r.byte_len), 0);
+    let runningFiles = existing.length;
+    // Track sizes of paths we've already touched IN THIS BATCH so a second
+    // write to the same path within one batch is treated as a replace, not an
+    // add (mirrors the single-file replace-or-add math).
+    const knownBytes = new Map();
+    for (const r of existing) knownBytes.set(r.path, Number(r.byte_len));
+
+    for (let i = 0; i < entries.length; i++) {
+      const f = entries[i];
+      const path = f && f.path;
+      const content = f && f.content;
+      try {
+        assertValidPath(path);
+        // ADR 0095 C4: strip <private>-fenced content per file before sizing/storing.
+        const body = stripPrivate(typeof content === 'string' ? content : String(content ?? ''));
+        const byteLen = Buffer.byteLength(body, 'utf8');
+
+        if (byteLen > MAX_FILE_BYTES) {
+          throw { code: 'FILE_TOO_LARGE', byteLen, max: MAX_FILE_BYTES, path };
+        }
+
+        const isReplace = knownBytes.has(path);
+        const oldBytes = isReplace ? knownBytes.get(path) : 0;
+
+        // File-count cap only bites when ADDING a new path.
+        if (!isReplace && runningFiles >= MAX_BUILDER_FILES) {
+          throw {
+            code: 'MEMORY_QUOTA_EXCEEDED',
+            kind: 'file_count',
+            current: runningFiles,
+            max: MAX_BUILDER_FILES,
+          };
+        }
+
+        // Byte cap on the post-write running total.
+        const projectedTotal = runningBytes - oldBytes + byteLen;
+        if (projectedTotal > MAX_BUILDER_BYTES) {
+          throw {
+            code: 'MEMORY_QUOTA_EXCEEDED',
+            kind: 'total_bytes',
+            currentBytes: runningBytes,
+            projectedBytes: projectedTotal,
+            max: MAX_BUILDER_BYTES,
+          };
+        }
+
+        const sha256 = sha256Hex(body);
+        const mtime = normalizeMtime(f && f.mtime);
+
+        const { rows } = await client.query(
+          `INSERT INTO builder_memory (builder_id, path, content, mtime, sha256, byte_len)
+           VALUES ($1, $2, $3, COALESCE($4, now()), $5, $6)
+           ON CONFLICT (builder_id, path) DO UPDATE
+             SET content  = EXCLUDED.content,
+                 mtime    = EXCLUDED.mtime,
+                 sha256   = EXCLUDED.sha256,
+                 byte_len = EXCLUDED.byte_len
+           RETURNING builder_id, path, mtime, sha256, byte_len, created_at, updated_at`,
+          [builderId, path, body, mtime, sha256, byteLen]
+        );
+
+        // Commit the accepted file's effect to the running totals.
+        runningBytes = projectedTotal;
+        if (!isReplace) runningFiles += 1;
+        knownBytes.set(path, byteLen);
+
+        results[i] = { ok: true, row: rows[0] };
+      } catch (err) {
+        // Per-file rejection: record it, leave the rest of the batch alone.
+        // The error object carries the same `code` storeMemoryFile throws.
+        results[i] = { ok: false, error: err };
+      }
+    }
+
+    await client.query('COMMIT');
+    return results;
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// fetchMemoryFile — read ONE file for ONE builder (ADR 0024 §4 isolation).
+//
+// Scoped by builder_id in the WHERE clause: there is no way to read another
+// builder's file through this helper. Returns the full row (content included)
+// or null if this builder has no file at that path. A path belonging to a
+// DIFFERENT builder returns null here too — it's simply not in this builder's
+// keyspace.
+async function fetchMemoryFile(builderId, path) {
+  assertValidPath(path);
+  const { rows } = await pool.query(
+    `SELECT builder_id, path, content, mtime, sha256, byte_len, created_at, updated_at
+       FROM builder_memory
+      WHERE builder_id = $1 AND path = $2`,
+    [builderId, path]
+  );
+  return rows[0] ?? null;
+}
+
+// listMemoryFiles — list a builder's files (metadata only, no content) so the
+// pull side (#275) can decide what to fetch without dragging every body over
+// the wire (ADR 0024 §2/§4). Scoped by builder_id — never lists across
+// builders. Newest-changed first (matches the (builder_id, updated_at DESC)
+// index). Returns [] for a builder with no stored memory.
+async function listMemoryFiles(builderId) {
+  // Defensive LIMIT: the per-builder file cap (MAX_BUILDER_FILES) is enforced on
+  // write, so a builder can never hold more than that many rows — but bounding
+  // the SELECT too means a single list query stays cheap even if the cap were
+  // ever bypassed (manual SQL insert, a future code path, etc.). Metadata-only,
+  // so the bound is essentially free.
+  const { rows } = await pool.query(
+    `SELECT builder_id, path, mtime, sha256, byte_len, created_at, updated_at
+       FROM builder_memory
+      WHERE builder_id = $1
+      ORDER BY updated_at DESC, path ASC
+      LIMIT $2`,
+    [builderId, MAX_BUILDER_FILES]
+  );
+  return rows;
+}
+
+// -------------------------------------------------------------------------
+// BFG cross-builder WRITE (ADR 0026 §6C / task #446) — the first cross-builder
+// memory write path. Everything here is reachable ONLY through the
+// principal-gated route (src/bongos/routes/memory.js, requireBfgPrincipal); the
+// helpers themselves enforce the namespace + attribution + audit invariants so
+// the guarantee can't be bypassed by a future careless caller.
+// -------------------------------------------------------------------------
+
+// Reserved namespace: every BFG-written file lives under this prefix, and the
+// SELF sync path (POST /memory/sync) REJECTS writes under it. That reservation
+// is what makes "the BFG never overwrites a builder's own file" airtight —
+// `bfg/` is exclusively the BFG's keyspace, so there is no collision to resolve.
+// A builder still READS and can DELETE files here (it's their own keyspace); the
+// frontmatter (author: BFG) self-announces who wrote them.
+const BFG_NAMESPACE_PREFIX = 'bfg/';
+const BFG_KINDS = new Set(['dream', 'correction']);
+
+// assertBfgPath — a BFG write target must be a valid relative path AND live
+// under the reserved bfg/ namespace. Layered on assertValidPath (no traversal).
+function assertBfgPath(path) {
+  assertValidPath(path);
+  if (!path.startsWith(BFG_NAMESPACE_PREFIX)) {
+    throw { code: 'NOT_BFG_NAMESPACE', message: `BFG writes must live under '${BFG_NAMESPACE_PREFIX}'` };
+  }
+}
+
+// isReservedNamespacePath — the SELF sync path calls this to refuse a builder
+// writing into the BFG's reserved namespace. Pure + exported for the route + tests.
+function isReservedNamespacePath(path) {
+  return typeof path === 'string' && path.startsWith(BFG_NAMESPACE_PREFIX);
+}
+
+// buildBfgMemoryFile — PURE constructor for a BFG-authored memory file. Returns
+// { path, content }. The attribution is structural, not optional: the caller
+// supplies semantic fields (kind/slug/title/body/rationale) and this function
+// emits the mandatory self-announcing frontmatter + banner, so a BFG write can
+// NEVER masquerade as the builder's own note (ADR 0026 §6C). Exported + unit-
+// tested. `now` is injectable for deterministic tests.
+function buildBfgMemoryFile({ kind, slug, title, body_md, rationale, sourceBuilder, targetBuilderId, now }) {
+  if (!BFG_KINDS.has(kind)) {
+    throw { code: 'BAD_BFG_KIND', message: `kind must be one of: ${[...BFG_KINDS].join(', ')}` };
+  }
+  if (typeof slug !== 'string' || !/^[a-z0-9][a-z0-9-]{0,80}$/.test(slug)) {
+    throw { code: 'BAD_BFG_SLUG', message: 'slug must be kebab-case ([a-z0-9-], starts alnum, <=81 chars)' };
+  }
+  if (typeof body_md !== 'string' || body_md.trim() === '') {
+    throw { code: 'BAD_BFG_BODY', message: 'body_md is required (non-empty string)' };
+  }
+  if (typeof rationale !== 'string' || rationale.trim() === '') {
+    throw { code: 'BAD_BFG_RATIONALE', message: 'rationale is required (non-empty string)' };
+  }
+  const safeTitle = typeof title === 'string' && title.trim() ? title.trim() : `BFG ${kind}: ${slug}`;
+  const date = (now instanceof Date ? now : new Date(now || Date.now())).toISOString();
+  const path = `${BFG_NAMESPACE_PREFIX}${kind}-${slug}.md`;
+  // JSON.stringify yields a safely double-quoted scalar (YAML accepts JSON
+  // string syntax), collapsing newlines so a multi-line rationale can't break
+  // the frontmatter block.
+  const yamlStr = (s) => JSON.stringify(String(s).replace(/\s+/g, ' ').trim());
+  const banner =
+    kind === 'correction'
+      ? '> **This is a BFG correction note — written by the BFG (system), not by you.** It names an observed behavior, the rule it touched, and the expected change. It is transparent and attributed by design (ADR 0026 §6C); a karma adjustment accompanies it. You may delete this file.'
+      : '> **This is a BFG dream — written by the BFG (system), not by you.** It is a practice the BFG planted because it looked like an obvious improvement worth adopting. It is clearly marked and yours to keep or delete (ADR 0026 §6C).';
+  const content = `---
+name: bfg-${kind}-${slug}
+author: BFG
+type: bfg-${kind}
+source_builder: ${yamlStr(sourceBuilder || 'bfg-system')}
+target_builder: ${targetBuilderId}
+date: ${date}
+rationale: ${yamlStr(rationale)}
+---
+
+${banner}
+
+## ${safeTitle}
+
+${body_md.trim()}
+`;
+  return { path, content };
+}
+
+// bfgWriteMemoryFile — upsert a BFG-authored file into ANOTHER builder's memory
+// AND write its audit_log row in ONE transaction. This atomicity is the
+// fail-closed guarantee ADR 0026 §6C requires: there is no cross-builder write
+// without a durable audit row, and no audit row that claims a write which rolled
+// back. Same quota math as storeMemoryFile (the write counts against the TARGET
+// builder's quota). The path MUST be in the bfg/ namespace (assertBfgPath).
+//
+// `audit` carries the principal + semantics: { principalId, route, action,
+// kind, rationale, responseStatus, ip, userAgent }. The audit row is attributed
+// to the PRINCIPAL (builder_id = principalId), method 'POST' (the audit_log
+// CHECK forbids 'GET'-style verbs), with the true semantics in the redacted body.
+async function bfgWriteMemoryFile({ targetBuilderId, path, content, audit, karma }) {
+  assertBfgPath(path);
+  // ADR 0095 C4: strip <private>-fenced content even on the BFG cross-builder
+  // write — a planted dream/correction must not smuggle fenced content past the
+  // marker into another builder's keyspace.
+  const body = stripPrivate(typeof content === 'string' ? content : String(content ?? ''));
+  const byteLen = Buffer.byteLength(body, 'utf8');
+  if (byteLen > MAX_FILE_BYTES) {
+    throw { code: 'FILE_TOO_LARGE', byteLen, max: MAX_FILE_BYTES, path };
+  }
+  const sha256 = sha256Hex(body);
+  const a = audit || {};
+
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    // Lock the TARGET builder's rows so the quota check + upsert see a consistent
+    // snapshot (mirrors storeMemoryFile).
+    const { rows: existing } = await client.query(
+      `SELECT path, byte_len FROM builder_memory WHERE builder_id = $1 FOR UPDATE`,
+      [targetBuilderId]
+    );
+    const currentTotalBytes = existing.reduce((sum, r) => sum + Number(r.byte_len), 0);
+    const oldRow = existing.find((r) => r.path === path);
+    const isReplace = oldRow !== undefined;
+    if (!isReplace && existing.length >= MAX_BUILDER_FILES) {
+      throw { code: 'MEMORY_QUOTA_EXCEEDED', kind: 'file_count', current: existing.length, max: MAX_BUILDER_FILES };
+    }
+    const projectedTotal = currentTotalBytes - (isReplace ? Number(oldRow.byte_len) : 0) + byteLen;
+    if (projectedTotal > MAX_BUILDER_BYTES) {
+      throw { code: 'MEMORY_QUOTA_EXCEEDED', kind: 'total_bytes', currentBytes: currentTotalBytes, projectedBytes: projectedTotal, max: MAX_BUILDER_BYTES };
+    }
+
+    const { rows } = await client.query(
+      `INSERT INTO builder_memory (builder_id, path, content, mtime, sha256, byte_len)
+       VALUES ($1, $2, $3, now(), $4, $5)
+       ON CONFLICT (builder_id, path) DO UPDATE
+         SET content  = EXCLUDED.content,
+             mtime    = EXCLUDED.mtime,
+             sha256   = EXCLUDED.sha256,
+             byte_len = EXCLUDED.byte_len
+       RETURNING builder_id, path, mtime, sha256, byte_len, created_at, updated_at`,
+      [targetBuilderId, path, body, sha256, byteLen]
+    );
+
+    // Fail-closed audit, same transaction. Shape mirrors db.insertAuditLog so the
+    // row is indistinguishable from a middleware-written one to the audit reader;
+    // the true semantics (action, target, path, rationale) live in the redacted
+    // body — auditors query by `action`, not `method`.
+    // NOTE: the global audit middleware ALSO logs this POST (a second, generic
+    // row with method=POST and no `action`). That's harmless redundancy — THIS
+    // in-transaction row is the authoritative one and the only one guaranteed to
+    // exist iff the write committed. Auditors filter on action='bfg_*_write'.
+    const { rows: auditRows } = await client.query(
+      `INSERT INTO audit_log (builder_id, route, method, request_body_redacted, response_status, ip, user_agent)
+       VALUES ($1, $2, 'POST', $3, $4, $5, $6)
+       RETURNING id, recorded_at`,
+      [
+        a.principalId ?? null,
+        a.route ?? '/api/gds/memory/builders/:builderId/bfg-write',
+        {
+          action: a.action || 'bfg_dream_write',
+          http_method: 'POST',
+          target_builder_id: targetBuilderId,
+          path,
+          kind: a.kind ?? null,
+          rationale: a.rationale ?? null,
+        },
+        a.responseStatus ?? 201,
+        a.ip ?? null,
+        a.userAgent ?? null,
+      ]
+    );
+
+    // 6C.2 — a CORRECTION carries a negative karma delta in the SAME transaction
+    // as its visible note + audit row (ADR 0026 §6C: "a visible BFG-authored
+    // corrective note PLUS a negative karma_log delta"). The gds_apply_karma
+    // trigger updates builders.karma on this insert; bundling it here means the
+    // note, the karma dock, and the audit either all land or all roll back —
+    // there is never a dock without its explanatory note, or vice-versa.
+    let karmaRow = null;
+    if (karma && Number.isFinite(Number(karma.delta)) && Math.trunc(Number(karma.delta)) !== 0) {
+      const { rows: kr } = await client.query(
+        `INSERT INTO karma_log (builder_id, delta, reason, granted_by)
+         VALUES ($1, $2, $3, $4) RETURNING id`,
+        [targetBuilderId, Math.trunc(Number(karma.delta)), karma.reason || 'bfg_correction', karma.grantedBy ?? null]
+      );
+      karmaRow = kr[0];
+    }
+
+    await client.query('COMMIT');
+    return { row: rows[0], audit_id: auditRows[0].id, audit_recorded_at: auditRows[0].recorded_at, karma_id: karmaRow ? karmaRow.id : null };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// deleteMemoryFile — remove ONE file from ONE builder's memory (ADR 0026 §6C
+// delete affordance). Scoped by builder_id, so the self DELETE route can only
+// ever remove the AUTHENTICATED builder's own file — including a BFG-written
+// dream/correction, which lives in the target builder's keyspace. Returns the
+// number of rows deleted (0 if there was nothing at that path).
+async function deleteMemoryFile(builderId, path) {
+  assertValidPath(path);
+  const { rowCount } = await pool.query(
+    `DELETE FROM builder_memory WHERE builder_id = $1 AND path = $2`,
+    [builderId, path]
+  );
+  return rowCount;
+}
+
+module.exports = {
+  storeMemoryFile,
+  storeMemoryFilesBatch,
+  fetchMemoryFile,
+  listMemoryFiles,
+  deleteMemoryFile,
+  // exported for the route layer (#274/#276) + tests so the quota numbers and
+  // path validation live in exactly one place.
+  assertValidPath,
+  sha256Hex,
+  MAX_FILE_BYTES,
+  MAX_BUILDER_BYTES,
+  MAX_BUILDER_FILES,
+  // BFG cross-builder write (6C.1, ADR 0026 §6C)
+  bfgWriteMemoryFile,
+  buildBfgMemoryFile,
+  assertBfgPath,
+  isReservedNamespacePath,
+  BFG_NAMESPACE_PREFIX,
+  BFG_KINDS,
+};

package/modules/memory/module.json

@@ -0,0 +1,12 @@
+{
+  "key": "memory",
+  "title": "Memory & recall",
+  "description": "Per-builder session memory, the lexical recall/search retrieval layer (ADR 0060), and durable learnings. A core-domain module carved out of the GDS core in BV1.R72 (ADR 0091); default-on because every instance needs the build system's memory.",
+  "coreVersion": "^1.5.0",
+  "default": true,
+  "contributes": {
+    "routes": ["memory", "search", "learnings"]
+  },
+  "provides": [],
+  "consumes": []
+}

package/modules/memory/routes/learnings.js

@@ -0,0 +1,90 @@
+const express = require('express');
+// Carved into modules/memory/ (BV1.R72 / ADR 0091 §2): auth + the shared request
+// validators (validateOrRespond/LIMITS) via the doorway; the learnings lib is an
+// intra-module require.
+const api = require('../../../src/module-api');
+const auth = api;
+const learnings = require('../learnings');
+const { validateOrRespond, LIMITS } = api;
+
+module.exports = function buildLearningsRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — read learnings (own + others').
+  router.get('/learnings', auth.requireBuilder, async (req, res) => {
+    const tagsRaw = req.query.tags;
+    const touchesRaw = req.query.touches;
+    // touches[] cleanup [3/8] (task 878): the preferred claim-time lookup keys
+    // off the task's discipline + title (always present) rather than its
+    // predicted touches[]. ?touches= is kept for back-compat.
+    const disciplineRaw = req.query.discipline;
+    const titleRaw = req.query.title;
+    try {
+      let rows;
+      if (tagsRaw) {
+        const tags = String(tagsRaw)
+          .split(',')
+          .map((s) => s.trim().toLowerCase())
+          .filter(Boolean);
+        rows = await learnings.findLearningsByTags(tags);
+      } else if (disciplineRaw || titleRaw) {
+        rows = await learnings.findLearningsForTask({
+          discipline: disciplineRaw ? String(disciplineRaw) : null,
+          title: titleRaw ? String(titleRaw) : null,
+        });
+      } else if (touchesRaw) {
+        const touches = String(touchesRaw).split(',').map((s) => s.trim()).filter(Boolean);
+        rows = await learnings.findLearningsForTouches(touches);
+      } else {
+        rows = await learnings.listAllLearnings();
+      }
+      res.json({ learnings: rows });
+    } catch (err) {
+      console.error('[gds] GET /learnings', err);
+      res.fail('list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — capture a learning (own contribution).
+  router.post('/learnings', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      title: { required: true, type: 'string', maxLength: LIMITS.TITLE, minLength: 1 },
+      body_md: { required: true, type: 'string', maxLength: LIMITS.DESCRIPTION, minLength: 1 },
+      tags: { type: 'array', maxItems: 64, itemsType: 'string' },
+      related_files: { type: 'array', maxItems: 256, itemsType: 'string' },
+      source: { type: 'string', maxLength: LIMITS.SOURCE },
+      source_ref: { type: 'string', maxLength: LIMITS.SOURCE_REF },
+      task_id: { type: 'integer', min: 1 },
+    })) return;
+    const body = req.body || {};
+    if (!body.title || !body.body_md) {
+      return res.fail('title_and_body_md_required', 400);
+    }
+    try {
+      const tags = Array.isArray(body.tags)
+        ? body.tags.map((t) => String(t).toLowerCase())
+        : [];
+      const relatedFiles = Array.isArray(body.related_files) ? body.related_files : [];
+      const out = await learnings.createLearning({
+        title: body.title,
+        bodyMd: body.body_md,
+        tags,
+        relatedFiles,
+        capturedBy: req.builder.id,
+        source: body.source ?? null,
+        sourceRef: body.source_ref ?? null,
+        taskId: body.task_id ?? null,
+      });
+      if (!out) {
+        // ON CONFLICT skipped: same (source, source_ref) already captured.
+        return res.status(200).json({ skipped: true, reason: 'duplicate_source_ref' });
+      }
+      res.status(201).json({ learning: out });
+    } catch (err) {
+      console.error('[gds] POST /learnings', err);
+      res.fail('create_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};