heyspex 0.1.0 → 0.2.1

package/spexharness/src/profile/vault-inclusion.mjs

@@ -0,0 +1,386 @@
+// spexharness/src/profile/vault-inclusion.mjs
+//
+// P7 (epic [[HS-HEBV-8CMW-EPIC-spexcode-profile-v0-learn-the-developer]], task
+// [[HS-TYX1-8CMW-TASK-p7-vault-inclusion-by-reference-and]]) — two things bolted onto
+// P1's profile file without touching learn.mjs itself:
+//
+//   1. Vault inclusion (scope item 1): every launch, every vault `memory-decision` and
+//      `memory-lesson` (plus `memory-ui-pattern` when the caller says this is console UI
+//      work) is merged into the profile BY REFERENCE — id plus one line, never the
+//      memory's body. Same recall path the harness already uses for prompt-submit vault
+//      grounding: `scripts/claude-hooks/_vault-retrieval.mjs`'s `loadVaultIndex(repoRoot)`,
+//      which reads the machine-local `.heyspex/vault-index.json` — this module never
+//      re-implements that read or re-parses a vault markdown file itself. Because the
+//      references are recomputed live from the index on every call, a memory removed from
+//      the vault (and so absent from a rebuilt index) simply stops appearing — no explicit
+//      "delete" path is needed.
+//
+//   2. Supersession (scope items 2-3): a new candidate observation that CONTRADICTS an
+//      already-accepted profile entry (same subject, opposite stance — including an
+//      explicit "I changed my mind about X") never retires anything silently. It is routed
+//      through P6's own proposal queue (`./proposals.mjs`'s `queueProposal`/`accept`) as an
+//      accept/approve ask, carrying a `supersedes` pointer at the matched entry. Only once
+//      that proposal is APPROVED does the old entry move under a `## retired` heading (with
+//      the date) and the new entry's line gain a `supersedes: <retired id>` reference. The
+//      contradiction alone changes nothing.
+//
+// Reuse, never duplicate: section state and rendering are P1's (`learn.mjs`'s
+// `loadProfileState`/`saveProfileState`/`classifySection`/`renderProfileMarkdown`); the
+// accept/decline ledger is P6's (`./proposals.mjs`). This module owns only: reading the
+// vault index for memory references, detecting a same-subject/opposite-stance contradiction,
+// the retired-entries store, and composing the final profile markdown (learned sections +
+// vault references + retired) from all three.
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { loadProfileState, renderProfileMarkdown, saveProfileState } from './learn.mjs';
+import { accept, listPending, normalizeFingerprint, queueProposal } from './proposals.mjs';
+import { loadVaultIndex } from '../../../scripts/claude-hooks/_vault-retrieval.mjs';
+
+export { loadVaultIndex };
+
+// ── paths ─────────────────────────────────────────────────────────────────────────
+
+/** The retired-entries store's canonical, machine-local location. */
+export function defaultRetiredStorePath(repoRoot) {
+  return join(repoRoot, '.heyspex', 'profile-retired.json');
+}
+
+// ── vault inclusion (scope item 1) ──────────────────────────────────────────────────
+
+/** The vault memory `type`s this module ever includes by reference — `memory-ui-pattern`
+ *  only when the caller opts in (`includeUiPatterns`), since it is only relevant to
+ *  console UI work, not every session. */
+export const VAULT_MEMORY_TYPES = Object.freeze(['memory-decision', 'memory-lesson']);
+export const VAULT_UI_PATTERN_TYPE = 'memory-ui-pattern';
+
+/**
+ * Every vault memory (decision/lesson, plus ui-pattern when opted in) currently in the
+ * index — id, type, title, summary only, sorted by id for a deterministic render. Reads
+ * the index fresh every call: a memory removed from the vault since the index was last
+ * built is simply absent on the next call, no stale reference carried forward.
+ *
+ * @param {{ repoRoot: string, includeUiPatterns?: boolean, loadIndex?: typeof loadVaultIndex }} opts
+ * @returns {Array<{ id: string, type: string, title: string, summary: string|null }>}
+ */
+export function collectVaultReferences({ repoRoot, includeUiPatterns = false, loadIndex = loadVaultIndex } = {}) {
+  if (!repoRoot) throw new Error('collectVaultReferences: repoRoot is required');
+  const wantedTypes = new Set(VAULT_MEMORY_TYPES);
+  if (includeUiPatterns) wantedTypes.add(VAULT_UI_PATTERN_TYPE);
+
+  const specs = loadIndex(repoRoot) ?? [];
+  const refs = [];
+  for (const spec of specs) {
+    if (!spec || !wantedTypes.has(spec.type)) continue;
+    refs.push({
+      id: spec.id,
+      type: spec.type,
+      title: spec.title ?? spec.id,
+      summary: spec.summary ?? spec.meta_description ?? null,
+    });
+  }
+  refs.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+  return refs;
+}
+
+/** One reference line — id plus one line, never the memory's body. */
+export function vaultReferenceLine(ref) {
+  const type = ref.type ? String(ref.type).toUpperCase() : 'MEMORY';
+  const title = String(ref.title ?? ref.id);
+  const line = `- ${ref.id} (${type}) ${title}`;
+  if (!ref.summary) return line;
+  return `${line} — ${String(ref.summary).replace(/\s+/g, ' ').trim()}`;
+}
+
+/** The "## Vault references" block, or `''` when there is nothing to include (the whole
+ *  heading is omitted, same "empty section omitted" rule `renderProfileMarkdown` follows). */
+export function renderVaultReferencesSection(refs) {
+  if (!refs || refs.length === 0) return '';
+  const lines = ['## Vault references', ''];
+  for (const ref of refs) lines.push(vaultReferenceLine(ref));
+  return lines.join('\n');
+}
+
+// ── retired store + rendering (scope item 3) ────────────────────────────────────────
+
+/** Read the retired-entries store; missing/corrupt -> []. */
+export function loadRetiredStore(path) {
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Persist the retired-entries store. */
+export function saveRetiredStore(path, entries) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(entries, null, 2)}\n`);
+}
+
+/** One retired line — the old entry's text, its retirement date, and what superseded it. */
+export function retiredLine(entry) {
+  return `- ${entry.text} _(retired: ${entry.retiredAt}, superseded by: ${entry.supersededBy})_`;
+}
+
+/** The "## retired" block, or `''` when nothing has ever been retired. */
+export function renderRetiredSection(entries) {
+  if (!entries || entries.length === 0) return '';
+  const lines = ['## retired', ''];
+  for (const entry of entries) lines.push(retiredLine(entry));
+  return lines.join('\n');
+}
+
+/** A short, stable id for a retired entry, derived from its own fingerprint — used as the
+ *  `supersedes` pointer a newly accepted entry's line cites. */
+export function retiredIdForFingerprint(fingerprint) {
+  return `RETIRED-${createHash('sha1').update(String(fingerprint ?? '')).digest('hex').slice(0, 10)}`;
+}
+
+// ── compose (pure — learned sections + vault references + retired) ─────────────────
+
+/**
+ * Assemble the full profile markdown from all three stores. Pure, no I/O — the same
+ * "always rebuild the whole document fresh from persisted state" discipline
+ * `renderProfileMarkdown` itself follows, just composed with two more sections.
+ *
+ * @param {{ sections: object, vaultReferences?: Array, retiredEntries?: Array }} opts
+ * @returns {string}
+ */
+export function composeProfileMarkdown({ sections, vaultReferences = [], retiredEntries = [] }) {
+  const base = renderProfileMarkdown(sections).replace(/\n+$/, '');
+  const blocks = [base, renderVaultReferencesSection(vaultReferences), renderRetiredSection(retiredEntries)].filter(
+    (b) => b.length > 0,
+  );
+  return `${blocks.join('\n\n')}\n`;
+}
+
+/**
+ * The "at every launch" entrypoint for scope item 1: recompute vault references live,
+ * recompose the full profile (learned sections + vault refs + whatever is already
+ * retired), and write it. Never touches the proposal ledger — vault inclusion is
+ * automatic, with no proposal step.
+ *
+ * @param {{ repoRoot: string, profilePath: string, profileStatePath: string,
+ *   retiredStorePath?: string|null, includeUiPatterns?: boolean,
+ *   loadIndex?: typeof loadVaultIndex }} opts
+ * @returns {{ profilePath: string, markdown: string, vaultReferences: Array }}
+ */
+export function writeProfile({
+  repoRoot,
+  profilePath,
+  profileStatePath,
+  retiredStorePath = null,
+  includeUiPatterns = false,
+  loadIndex = loadVaultIndex,
+} = {}) {
+  if (!repoRoot) throw new Error('writeProfile: repoRoot is required');
+  if (!profilePath) throw new Error('writeProfile: profilePath is required');
+  if (!profileStatePath) throw new Error('writeProfile: profileStatePath is required');
+
+  const state = loadProfileState(profileStatePath);
+  const vaultReferences = collectVaultReferences({ repoRoot, includeUiPatterns, loadIndex });
+  const retiredEntries = retiredStorePath ? loadRetiredStore(retiredStorePath) : [];
+  const markdown = composeProfileMarkdown({ sections: state.sections, vaultReferences, retiredEntries });
+
+  mkdirSync(dirname(profilePath), { recursive: true });
+  writeFileSync(profilePath, markdown);
+  return { profilePath, markdown, vaultReferences };
+}
+
+// ── contradiction detection (scope item 2) ──────────────────────────────────────────
+
+const NEGATIVE_STANCE_MARKERS = [
+  /\bnever\b/i,
+  /\bdon'?t\b/i,
+  /\bdo not\b/i,
+  /\bstop\b/i,
+  /\bavoid\b/i,
+  /\bno longer\b/i,
+  /\bnot anymore\b/i,
+  /\bchanged (my|your|their) mind\b/i,
+];
+
+const POSITIVE_STANCE_MARKERS = [/\balways\b/i, /\bprefer(s|red)?\b/i, /\bfrom now on\b/i];
+
+/** Words a stance marker itself introduces — dropped from the "subject" comparison so
+ *  "always use tabs" and "never use tabs" compare on {use, tabs}, not on the polarity word. */
+const POLARITY_WORDS = new Set([
+  'never', 'always', 'dont', 'do', 'not', 'stop', 'avoid', 'longer', 'anymore', 'changed', 'mind', 'now',
+]);
+
+const MIN_SUBJECT_WORD_LENGTH = 4;
+
+function stanceOf(text) {
+  const t = String(text ?? '');
+  if (NEGATIVE_STANCE_MARKERS.some((re) => re.test(t))) return 'negative';
+  if (POSITIVE_STANCE_MARKERS.some((re) => re.test(t))) return 'positive';
+  return 'neutral';
+}
+
+function subjectWords(text) {
+  const words = normalizeFingerprint(text)
+    .split(' ')
+    .filter((w) => w.length >= MIN_SUBJECT_WORD_LENGTH && !POLARITY_WORDS.has(w));
+  return new Set(words);
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const w of a) if (b.has(w)) intersection += 1;
+  return intersection / (a.size + b.size - intersection);
+}
+
+/**
+ * Does `observation` contradict an already-accepted profile entry — the same subject,
+ * opposite stance (an explicit "I changed my mind about X" counts as a negative-stance
+ * marker too)? Returns the first match found (accepted entries are checked in section
+ * order, then array order), or `null`.
+ *
+ * @param {{ text: string }} observation
+ * @param {object} sections - the same shape `learn.mjs`'s profile-state `sections` carries.
+ * @param {{ minOverlap?: number }} [opts]
+ * @returns {{ sectionKey: string, entry: object, overlap: number }|null}
+ */
+export function detectContradiction(observation, sections, { minOverlap = 0.34 } = {}) {
+  const text = observation?.text;
+  const newStance = stanceOf(text);
+  if (newStance === 'neutral') return null;
+  const newSubject = subjectWords(text);
+  if (newSubject.size === 0) return null;
+
+  for (const sectionKey of Object.keys(sections ?? {})) {
+    for (const entry of sections[sectionKey] ?? []) {
+      const entryStance = stanceOf(entry.text);
+      if (entryStance === 'neutral' || entryStance === newStance) continue;
+      const overlap = jaccard(newSubject, subjectWords(entry.text));
+      if (overlap >= minOverlap) return { sectionKey, entry, overlap };
+    }
+  }
+  return null;
+}
+
+/**
+ * Run `detectContradiction` against the CURRENT accepted profile state and, on a match,
+ * queue an accept/approve proposal through P6's own queue (never retires anything itself —
+ * that only happens on `approveSupersession`). No match -> `{ contradiction: false }`, and
+ * the observation is left for the caller's normal (non-supersession) proposal path.
+ *
+ * @param {object} observation
+ * @param {{ profileStatePath: string, ledgerPath: string, now?: () => string }} opts
+ * @returns {{ contradiction: boolean, queued?: boolean, id?: string, matched?: object }}
+ */
+export function checkForContradictionAndPropose(observation, { profileStatePath, ledgerPath, now } = {}) {
+  if (!profileStatePath) throw new Error('checkForContradictionAndPropose: profileStatePath is required');
+  if (!ledgerPath) throw new Error('checkForContradictionAndPropose: ledgerPath is required');
+
+  const state = loadProfileState(profileStatePath);
+  const match = detectContradiction(observation, state.sections);
+  if (!match) return { contradiction: false };
+
+  const supersedes = {
+    sectionKey: match.sectionKey,
+    fingerprint: normalizeFingerprint(match.entry.text),
+  };
+  const result = queueProposal({ ...observation, supersedes }, { ledgerPath, now });
+  return { contradiction: true, queued: result.queued, id: result.id, matched: match.entry };
+}
+
+// ── approval: the ONLY path that ever retires an entry ──────────────────────────────
+
+/**
+ * Approve a pending supersession proposal (queued by `checkForContradictionAndPropose`).
+ * Accepts it through P6's own `accept()` (writing the new entry with its usual
+ * provenance), then — and ONLY on this explicit approval — moves the matched old entry
+ * under `## retired` with the date, and appends a `supersedes: <retired id>` reference to
+ * the new entry's line. A plain accept (no `supersedes` on the queued observation) behaves
+ * exactly like P6's own `accept()` — no retirement, nothing extra.
+ *
+ * @param {string} id
+ * @param {{ ledgerPath: string, profilePath: string, profileStatePath: string,
+ *   retiredStorePath: string, repoRoot: string, includeUiPatterns?: boolean,
+ *   loadIndex?: typeof loadVaultIndex, now?: () => string }} opts
+ * @returns {{ ok: boolean, id: string, reason?: string, retired?: object|null, retiredAt?: string|null }}
+ */
+export function approveSupersession(id, {
+  ledgerPath,
+  profilePath,
+  profileStatePath,
+  retiredStorePath,
+  repoRoot,
+  includeUiPatterns = false,
+  loadIndex = loadVaultIndex,
+  now = () => new Date().toISOString(),
+} = {}) {
+  if (!retiredStorePath) throw new Error('approveSupersession: retiredStorePath is required');
+  if (!repoRoot) throw new Error('approveSupersession: repoRoot is required');
+
+  const pending = listPending({ ledgerPath }).find((p) => p.id === id);
+  const supersedes = pending?.observation?.supersedes ?? null;
+
+  const acceptResult = accept(id, { ledgerPath, profilePath, profileStatePath, now });
+  if (!acceptResult.ok) return acceptResult;
+
+  if (!supersedes) {
+    return { ok: true, id, retired: null, retiredAt: null };
+  }
+
+  const state = loadProfileState(profileStatePath);
+  const entries = state.sections[supersedes.sectionKey] ?? [];
+  const idx = entries.findIndex((e) => normalizeFingerprint(e.text) === supersedes.fingerprint);
+  let retiredEntry = null;
+  if (idx !== -1) {
+    [retiredEntry] = entries.splice(idx, 1);
+  }
+
+  const retiredAt = now();
+  const retiredStore = loadRetiredStore(retiredStorePath);
+  let retiredRecord = null;
+  if (retiredEntry) {
+    const retiredId = retiredIdForFingerprint(supersedes.fingerprint);
+    retiredRecord = { id: retiredId, ...retiredEntry, retiredAt, supersededBy: id };
+    retiredStore.push(retiredRecord);
+
+    // Tag the newly accepted entry's own line with the supersedes pointer — it is always
+    // the LAST entry in its own section (accept() only ever pushes), unaffected by the
+    // splice above even when both entries happen to share a section.
+    const newSectionEntries = state.sections[acceptResult.section] ?? [];
+    const newest = newSectionEntries[newSectionEntries.length - 1];
+    if (newest) newest.text = `${newest.text} _(supersedes: ${retiredId})_`;
+  }
+
+  saveProfileState(profileStatePath, state);
+  saveRetiredStore(retiredStorePath, retiredStore);
+
+  const vaultReferences = collectVaultReferences({ repoRoot, includeUiPatterns, loadIndex });
+  const markdown = composeProfileMarkdown({ sections: state.sections, vaultReferences, retiredEntries: retiredStore });
+  mkdirSync(dirname(profilePath), { recursive: true });
+  writeFileSync(profilePath, markdown);
+
+  return { ok: true, id, retired: retiredRecord, retiredAt, markdown };
+}
+
+export default {
+  defaultRetiredStorePath,
+  VAULT_MEMORY_TYPES,
+  VAULT_UI_PATTERN_TYPE,
+  collectVaultReferences,
+  vaultReferenceLine,
+  renderVaultReferencesSection,
+  loadRetiredStore,
+  saveRetiredStore,
+  retiredLine,
+  renderRetiredSection,
+  retiredIdForFingerprint,
+  composeProfileMarkdown,
+  writeProfile,
+  detectContradiction,
+  checkForContradictionAndPropose,
+  approveSupersession,
+  loadVaultIndex,
+};

package/spexharness/src/redact.mjs

@@ -0,0 +1,151 @@
+// spexharness/src/redact.mjs
+//
+// The ONE redaction module every log sink calls before a byte reaches disk
+// ([[HS-Y424-NYPR-TASK-add-one-redaction-module-that-strips]] of
+// [[HS-KRK5-NYPR-EPIC-harness-security-customer-hooks]]).
+//
+// Two call sites today (the epic's own listed sinks — "session record, run
+// records" — both live in spexharness):
+//   - ../session-record.mjs's `appendSessionRecord` — the session record
+//     (ask, tool-call inputs/outputs, event decisions).
+//   - ./adapters/audit.mjs's `recordGuardrailAudit` — the guardrail-history
+//     row, whose `matchContext` field is literally a snippet of whatever text
+//     tripped a rule (naughty-list-gate) — the single field most likely to
+//     carry ingested prose verbatim.
+//
+// WHAT GETS STRIPPED (a closed, named set — never a generic high-entropy
+// heuristic, which would false-positive on git SHAs and other ordinary hex
+// content a record legitimately carries):
+//   - fixture/provider KEY SHAPES — the same closed vocabulary
+//     scripts/scan-key-custody.mjs scans FOR (OpenAI/DeepSeek `sk-`,
+//     Anthropic `sk-ant-`, AWS `AKIA…`, GitHub `ghp_…`/`github_pat_…`,
+//     Google `AIza…`, Slack `xox…`, a JWT). That scan proves a key never
+//     LANDS in a committed/generated file; THIS module is the reason it
+//     doesn't even reach the byte stream those files are made of.
+//   - BEARER TOKENS — `Authorization: Bearer <token>` (and a bare
+//     `Bearer <token>` fragment) wherever it appears in a string field.
+//   - INGESTED PROSE — a caller marks a block of untrusted/ingested content
+//     (a fetched document, a scraped page — [[uc-ingest-anywhere]]'s
+//     preview/confirm boundary) by wrapping it with
+//     {@link wrapIngestedProse} before it ever reaches a record; this module
+//     recognizes that marker pair and strips the ENTIRE marked block,
+//     regardless of what it contains.
+//
+// Pure: no I/O. `redactRecord`/`redactDeep` never mutate their input — every
+// sink gets a redacted COPY to serialize, so the in-memory record a caller
+// keeps using (or hands to another consumer) is never silently rewritten out
+// from under it.
+
+/** Sentinel pair a caller wraps a block of untrusted/ingested prose in, so this module can find and strip the WHOLE block regardless of content. */
+export const INGESTED_PROSE_MARKERS = Object.freeze({
+  start: '☃HEYSPEX-INGESTED-PROSE-START☃',
+  end: '☃HEYSPEX-INGESTED-PROSE-END☃',
+});
+
+/** Wrap `text` as an ingested-prose block — the marker pair {@link redactText} strips wholesale. */
+export function wrapIngestedProse(text) {
+  return `${INGESTED_PROSE_MARKERS.start}${text}${INGESTED_PROSE_MARKERS.end}`;
+}
+
+function escapeRegExp(literal) {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const INGESTED_PROSE_RE = new RegExp(
+  `${escapeRegExp(INGESTED_PROSE_MARKERS.start)}[\\s\\S]*?${escapeRegExp(INGESTED_PROSE_MARKERS.end)}`,
+  'g',
+);
+
+/**
+ * Closed vocabulary of key-shaped patterns — kept in sync by hand with
+ * scripts/scan-key-custody.mjs's own table (same shapes, different job: that
+ * script SCANS for a leak that already happened; this module PREVENTS one
+ * from reaching disk in the first place).
+ * @type {ReadonlyArray<{ id: string, re: RegExp }>}
+ */
+export const KEY_SHAPE_PATTERNS = Object.freeze([
+  { id: 'openai-or-deepseek-secret-key', re: /\bsk-[A-Za-z0-9]{20,}\b/g },
+  { id: 'anthropic-secret-key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+  { id: 'aws-access-key-id', re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { id: 'github-token', re: /\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/g },
+  { id: 'github-fine-grained-pat', re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g },
+  { id: 'google-api-key', re: /\bAIza[0-9A-Za-z\-_]{35,}\b/g },
+  { id: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { id: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
+]);
+
+/** `Authorization: Bearer <token>` or a bare `Bearer <token>` fragment. */
+const BEARER_TOKEN_RE = /\bBearer\s+[A-Za-z0-9\-._~+/]{8,}=*/g;
+
+/**
+ * Redact one string: ingested-prose blocks first (a whole-block replace, so
+ * a key shape ALSO inside a marked block is subsumed by the block redaction
+ * rather than double-processed), then every named key shape, then bearer
+ * tokens. Non-string input is returned unchanged (callers use
+ * {@link redactDeep} for a whole object/array).
+ *
+ * @param {unknown} input
+ * @returns {unknown}
+ */
+export function redactText(input) {
+  if (typeof input !== 'string' || input.length === 0) return input;
+  let out = input.replace(INGESTED_PROSE_RE, '[REDACTED:ingested-prose]');
+  for (const { id, re } of KEY_SHAPE_PATTERNS) {
+    out = out.replace(re, `[REDACTED:${id}]`);
+  }
+  out = out.replace(BEARER_TOKEN_RE, '[REDACTED:bearer-token]');
+  return out;
+}
+
+/**
+ * Recursively redact every string leaf of `value` — plain objects, arrays,
+ * Maps, and Sets included (a session record's `toolCalls[].output` or a
+ * gate's `metadata` can nest arbitrarily). Never mutates `value`; returns a
+ * new structure. Numbers/booleans/null/undefined pass through unchanged.
+ * Circular references are left as-is on a second visit rather than
+ * infinite-looping (defensive — a real circular record would already fail
+ * `JSON.stringify` before reaching this module).
+ *
+ * @param {unknown} value
+ * @param {WeakSet<object>} [seen]
+ * @returns {unknown}
+ */
+export function redactDeep(value, seen = new WeakSet()) {
+  if (typeof value === 'string') return redactText(value);
+  if (value === null || typeof value !== 'object') return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.map((item) => redactDeep(item, seen));
+  }
+  if (value instanceof Map) {
+    const out = new Map();
+    for (const [k, v] of value.entries()) out.set(k, redactDeep(v, seen));
+    return out;
+  }
+  if (value instanceof Set) {
+    const out = new Set();
+    for (const item of value.values()) out.add(redactDeep(item, seen));
+    return out;
+  }
+
+  const out = {};
+  for (const [key, v] of Object.entries(value)) {
+    out[key] = redactDeep(v, seen);
+  }
+  return out;
+}
+
+/**
+ * Redact a whole record (a session record, a guardrail-audit row, a WIP
+ * hand-off block, a cost-ledger row) before it is serialized to any sink.
+ * Alias of {@link redactDeep} at the top level — named separately so a call
+ * site reads as "redact this whole record" rather than "redact this value".
+ *
+ * @param {object} record
+ * @returns {object}
+ */
+export function redactRecord(record) {
+  return redactDeep(record);
+}