@ijfw/memory-server 1.5.5 → 1.6.0

package/src/profile/serve.js

@@ -0,0 +1,345 @@
+/**
+ * profile/serve.js — Cross-system profile bus, PHASE P4 (P4.4 + P4.6 serving).
+ *
+ * The MCP-facing READ path for the user-global profile. Two operations, both
+ * ZERO-LLM by construction (the moat): this module imports ONLY store.js
+ * (read), render-brief.js (compose), egress.js (audit), sensitivity.js (gate) —
+ * none of which reach the LLM tier. The P4.5 import-graph guard proves it.
+ *
+ *   profileGet(opts)   — the structured, sensitivity-filtered listing of what
+ *                        the profile knows (style axes + expertise + the
+ *                        inferences cleared for the caller's sensitivity tier).
+ *                        Logs an egress entry (a `get` is an exfiltration).
+ *   profileBrief(opts) — the short descriptive brief for passive injection
+ *                        (renderBrief). Logs an egress entry for what left.
+ *
+ * COLD START — a missing/empty profile yields an empty result, NEVER an error
+ * (design-v2 §5 + the P4 spec): the absence of a profile must be a graceful
+ * "nothing yet", not a failure the host has to handle.
+ *
+ * The host + session identifiers (for the egress ledger) come from the caller's
+ * context so the audit trail can answer "which host saw what, when".
+ *
+ * Zero deps, Node built-ins only. NO LLM calls.
+ */
+
+import { readProfile } from './store.js';
+import { renderBrief, renderSnapshot, BRIEF_MIN_CONFIDENCE, BRIEF_MIN_EVIDENCE } from './render-brief.js';
+import { appendEgress, appendExemplarEgress } from './egress.js';
+// V3 voice few-shot seam. BOTH imports are zero-LLM by construction:
+// exemplar-retrieve ranks the user's OWN writing with pure BM25 + register/
+// recency (no LLM/network/embedder), and exemplar-capture's classifyRegister is
+// a pure string heuristic. Pulling them here keeps the P4.5 moat intact — the
+// serve read path still never reaches the LLM tier (the moat-guard import-graph
+// test re-proves this on every run).
+import { retrieveExemplars } from './exemplar-retrieve.js';
+import { classifyRegister } from './exemplar-capture.js';
+// S5 — serve.js is the ONLY profile read-path module that loads the approval
+// registry from disk; render-brief stays pure and is handed the registry. audit
+// imports only lock/store/egress/schema (zero-LLM), so the moat is unchanged.
+import { readApprovals } from './audit.js';
+import {
+  fieldSensitivity,
+  sensitivityAllowed,
+  loadRedaction,
+  killSwitchEngaged,
+  isRedacted,
+} from './sensitivity.js';
+import { styleAxisConfirmed, expertiseBand } from './derive-heuristic.js';
+import { STYLE_AXES } from './schema.js';
+
+/**
+ * isCloudHost(host) -> boolean. Conservative classifier for the exemplar-egress
+ * cloud flag (V4). A voice exemplar is the user's OWN raw writing, so when it is
+ * disclosed to a CLOUD host the egress record must say so distinctly. We default
+ * to FALSE (local) and flag TRUE only when the resolved host string clearly names
+ * a hosted/web surface. First-party LOCAL CLI hosts (claude-code, cursor,
+ * windsurf, codex, gemini-cli, …) are local => false. Unknown => false (we never
+ * over-claim cloud; the flag is an honesty marker, not a gate — the inject
+ * decision is the user's opt-in, made upstream).
+ */
+export function isCloudHost(host) {
+  const h = String(host || '').toLowerCase().trim();
+  if (!h) return false;
+  // Explicit cloud/web markers anywhere in the host string.
+  if (/(^|[^a-z])(cloud|web|hosted|saas|server|remote)([^a-z]|$)/.test(h)) return true;
+  // Known hosted assistant surfaces (web apps / hosted APIs), distinct from the
+  // local CLIs of the same vendors (claude-code, gemini-cli stay local).
+  const CLOUD_HOSTS = new Set([
+    'claude-web', 'claude.ai', 'chatgpt', 'openai', 'gemini-web', 'gemini.google.com',
+    'copilot-web', 'github-copilot-web', 'perplexity', 'poe',
+  ]);
+  if (CLOUD_HOSTS.has(h)) return true;
+  return false;
+}
+
+/** Pull host/session for the egress ledger from a caller context. */
+function egressMeta(opts = {}) {
+  const ctx = opts.context && typeof opts.context === 'object' ? opts.context : {};
+  return {
+    host: typeof ctx.host === 'string' ? ctx.host : (typeof opts.host === 'string' ? opts.host : null),
+    session: typeof ctx.session === 'string' ? ctx.session : (typeof opts.session === 'string' ? opts.session : null),
+  };
+}
+
+/**
+ * profileBrief(opts) -> { ok, brief, fields, egress }. Renders the descriptive
+ * brief and records exactly what left in the egress ledger. Cold start -> empty
+ * brief (ok:true). Never throws.
+ *
+ * @param {object} [opts] forwarded to renderBrief (tokenBudget, context,
+ *   shareSensitive, env, redactFile) plus context.host/context.session for the
+ *   egress ledger.
+ */
+export function profileBrief(opts = {}) {
+  let profile = null;
+  try {
+    const r = readProfile();
+    // A corrupt/symlinked profile is NOT a serve error — serve nothing rather
+    // than leak a half-read profile or throw at the host. Cold start semantics.
+    profile = r && r.ok ? r.profile : null;
+  } catch {
+    profile = null;
+  }
+
+  // Thread the RESOLVED host (from caller context) into renderBrief so the
+  // sensitivity gate can cross-check it against the share-hosts allowlist
+  // (audit MED-2). forceLowOnly (audit MED-3) is honored when the caller marks
+  // this a passive read (the MCP resource path sets it). Self-declared host in
+  // the field payload is NEVER used — only the resolved context host.
+  const meta = egressMeta(opts);
+  const briefOpts = {
+    ...opts,
+    host: meta.host,
+    forceLowOnly: opts.forceLowOnly === true,
+    enforceHostAllowlist: true, // MED-2: every serve-path read binds to the host allowlist.
+  };
+  const { text, fields } = renderBrief(profile, briefOpts);
+
+  // Record the egress ONLY when something actually left (empty brief => no
+  // exfiltration => no ledger noise).
+  let egress = null;
+  if (fields.length > 0) {
+    egress = appendEgress({ host: meta.host, session: meta.session, fields });
+  }
+
+  return { ok: true, brief: text, fields, egress };
+}
+
+/**
+ * profileSnapshot(opts) -> { ok, snapshot, fields, egress }. Renders the flat
+ * RULES-FILE snapshot (renderSnapshot) for cursor/windsurf/copilot-style standing
+ * context, and — when `includePreferences` is set — appends ONLY corroborated +
+ * approved + precision-eligible preference slugs (S5 gate). serve.js loads the S3
+ * approval registry from disk ONCE and threads it into the pure renderer; an
+ * absent/corrupt registry reads as "nothing approved" (fail-closed), so no
+ * un-cleared preference can leak. Records what left in the egress ledger. Cold
+ * start -> empty snapshot (ok:true). Never throws.
+ *
+ * @param {object} [opts] forwarded to renderSnapshot (tokenBudget, context,
+ *   shareSensitive, env, redactFile, includePreferences) plus context.host/
+ *   context.session for the egress ledger. `forceLowOnly` is honored for passive
+ *   reads; the host allowlist is enforced on every serve-path read (MED-2).
+ */
+export function profileSnapshot(opts = {}) {
+  let profile = null;
+  try {
+    const r = readProfile();
+    profile = r && r.ok ? r.profile : null;
+  } catch {
+    profile = null;
+  }
+
+  // Load the approval registry ONCE here (the pure renderer never touches disk).
+  // A symlinked/oversized/corrupt store degrades to an empty registry inside
+  // readApprovals (fail-closed = nothing approved), so a tampered approvals file
+  // can never GRANT injection — it can only withhold it.
+  let registry = null;
+  if (opts.includePreferences === true) {
+    try {
+      const ar = readApprovals();
+      registry = ar && ar.registry && typeof ar.registry === 'object' ? ar.registry : null;
+    } catch {
+      registry = null; // fail-closed
+    }
+  }
+
+  const meta = egressMeta(opts);
+
+  // --- V3 VOICE FEW-SHOT SEAM (sibling of the S5 includePreferences gate) -----
+  // Behind `opts.includeVoiceExemplars === true`, AND honoring the SAME kill-
+  // switch the preference path respects, AND requiring a non-empty `opts.taskText`,
+  // we retrieve the user's OWN writing samples (ZERO-LLM) and hand them to the
+  // PURE renderer to few-shot a "match their voice" block. FAIL-CLOSED on every
+  // axis: flag off, kill-switch engaged, empty taskText, retrieval throws, or no
+  // exemplars => no voice block, no exemplar-egress disclosure. The gate is the
+  // ONLY way `voiceExemplars` reaches renderSnapshot, so with the flag off the
+  // output is byte-identical to today's (regression-guarded by the unit test).
+  let voiceExemplars = null;
+  const wantVoice = opts.includeVoiceExemplars === true;
+  const taskText = typeof opts.taskText === 'string' ? opts.taskText.trim() : '';
+  if (wantVoice && taskText) {
+    // Kill-switch check, same source the preference/brief paths use. Engaged =>
+    // never retrieve, never inject, never disclose.
+    let killed = false;
+    try {
+      killed = killSwitchEngaged(loadRedaction({ env: opts.env || process.env, redactFile: opts.redactFile }));
+    } catch {
+      killed = false;
+    }
+    if (!killed) {
+      try {
+        const register = classifyRegister(taskText, 'prompt');
+        const k = Number.isFinite(opts.voiceK) && opts.voiceK > 0 ? Math.floor(opts.voiceK) : 3;
+        // DI: tests/callers may inject a candidate set; default loads via store.
+        const got = retrieveExemplars({
+          register,
+          taskText,
+          k,
+          exemplars: Array.isArray(opts.exemplars) ? opts.exemplars : null,
+          env: opts.env || process.env,
+        });
+        voiceExemplars = Array.isArray(got) && got.length > 0 ? got : null;
+      } catch {
+        voiceExemplars = null; // fail-closed: any retrieval failure => no voice.
+      }
+    }
+  }
+
+  const snapOpts = {
+    ...opts,
+    host: meta.host,
+    forceLowOnly: opts.forceLowOnly === true,
+    enforceHostAllowlist: true, // MED-2: every serve-path read binds to the host allowlist.
+    registry,
+    voiceExemplars, // null when the gate is off / fail-closed => renderer emits nothing.
+  };
+  const { text, fields, voice } = renderSnapshot(profile, snapOpts);
+
+  let egress = null;
+  if (fields.length > 0) {
+    egress = appendEgress({ host: meta.host, session: meta.session, fields });
+  }
+
+  // Voice disclosure (V4): record ONLY the exemplars that ACTUALLY landed in the
+  // block (renderSnapshot returns them in `voice` after its own budget cap), and
+  // ONLY through the dedicated exemplar-egress channel. Cloud-host flagged when
+  // the resolved host is a cloud surface. Empty `voice` => no disclosure line.
+  let voiceEgress = null;
+  const landed = Array.isArray(voice) ? voice : [];
+  if (landed.length > 0) {
+    voiceEgress = appendExemplarEgress({
+      ids: landed.map((e) => e && e.id).filter(Boolean),
+      host: meta.host,
+      session: meta.session,
+      cloudHost: isCloudHost(meta.host),
+    });
+  }
+
+  return { ok: true, snapshot: text, fields, egress, voice: landed, voiceEgress };
+}
+
+/**
+ * profileGet(opts) -> { ok, profile:{ style, expertise, inferences }, fields,
+ * egress }. The structured, sensitivity-filtered listing. Mirrors the brief's
+ * gates (sensitivity tier + redaction + kill-switch) so `get` can never leak
+ * more than `brief` would. Cold start -> empty listing (ok:true). Never throws.
+ */
+export function profileGet(opts = {}) {
+  const env = opts.env || process.env;
+  const redaction = loadRedaction({ env, redactFile: opts.redactFile });
+  // Resolve the host from caller context (NOT self-declared) for the MED-2
+  // share-hosts allowlist cross-check; honor forceLowOnly for passive reads.
+  const meta = egressMeta(opts);
+  const shareOpts = {
+    env,
+    shareSensitive: opts.shareSensitive,
+    host: meta.host,
+    forceLowOnly: opts.forceLowOnly === true,
+    enforceHostAllowlist: true, // MED-2: bind med/high to the share-hosts allowlist.
+    shareHostsFile: opts.shareHostsFile,
+  };
+
+  const empty = { ok: true, profile: { style: {}, expertise: {}, inferences: [] }, fields: [], egress: null };
+
+  // Kill-switch: hard stop, return nothing.
+  if (killSwitchEngaged(redaction)) return empty;
+
+  let profile = null;
+  try {
+    const r = readProfile();
+    profile = r && r.ok ? r.profile : null;
+  } catch {
+    profile = null;
+  }
+  if (!profile || typeof profile !== 'object' || !profile.global) return empty;
+
+  const context = opts.context && typeof opts.context === 'object' ? opts.context : {};
+  const overlayKey = typeof context.overlay === 'string' ? context.overlay : null;
+  const overlay = overlayKey && profile.overlays ? profile.overlays[overlayKey] : null;
+
+  const out = { style: {}, expertise: {}, inferences: [] };
+  const fields = [];
+
+  // Style — confirmed axes only, low-sensitivity, redaction-gated. Overlay
+  // overrides global per axis.
+  for (const axis of STYLE_AXES) {
+    const a = (overlay && overlay.style && overlay.style[axis])
+      || (profile.global.style && profile.global.style[axis]);
+    if (!a || !styleAxisConfirmed(a)) continue;
+    const fieldId = `style:${axis}`;
+    if (!sensitivityAllowed(fieldSensitivity({ kind: 'style' }), shareOpts)) continue;
+    if (isRedacted(fieldId, redaction)) continue;
+    out.style[axis] = { ema: a.ema, evidence_count: a.evidence_count };
+    fields.push(fieldId);
+  }
+
+  // Expertise — banded domains only, low-sensitivity, redaction-gated.
+  if (profile.expertise && typeof profile.expertise === 'object') {
+    for (const [domain, rec] of Object.entries(profile.expertise)) {
+      const band = expertiseBand(rec);
+      if (band === 'unknown') continue;
+      const fieldId = `expertise:${domain}`;
+      if (!sensitivityAllowed(fieldSensitivity({ kind: 'expertise' }), shareOpts)) continue;
+      if (isRedacted(fieldId, redaction)) continue;
+      out.expertise[domain] = { band, wilsonLB: rec.wilsonLB, n: rec.n };
+      fields.push(fieldId);
+    }
+  }
+
+  // Inferences — confidence/evidence floor + sensitivity tier + redaction.
+  const byId = new Map();
+  for (const inf of (Array.isArray(profile.global.dialectic) ? profile.global.dialectic : [])) {
+    if (inf && inf.id) byId.set(inf.id, inf);
+  }
+  if (overlay && Array.isArray(overlay.dialectic)) {
+    for (const inf of overlay.dialectic) if (inf && inf.id) byId.set(inf.id, inf);
+  }
+  for (const inf of byId.values()) {
+    // Inclusion floor shared with the brief (audit L2): confidence > 0.45 AND
+    // evidence_count >= 3 so a corroborated dialectic trait (conf 0.5) can
+    // surface while the evidence gate remains the real corroboration barrier.
+    if (!(Number(inf.confidence) > BRIEF_MIN_CONFIDENCE
+        && (Number(inf.evidence_count) || 0) >= BRIEF_MIN_EVIDENCE)) continue;
+    const sens = fieldSensitivity({ kind: 'inference', sensitivity: inf.sensitivity });
+    if (!sensitivityAllowed(sens, shareOpts)) continue;
+    if (isRedacted(inf.id, redaction)) continue;
+    out.inferences.push({
+      id: inf.id,
+      kind: inf.kind,
+      subject: inf.subject,
+      value: inf.value,
+      confidence: inf.confidence,
+      evidence_count: inf.evidence_count,
+      sensitivity: sens,
+    });
+    fields.push(inf.id);
+  }
+
+  let egress = null;
+  if (fields.length > 0) {
+    egress = appendEgress({ host: meta.host, session: meta.session, fields });
+  }
+
+  return { ok: true, profile: out, fields, egress };
+}

package/src/profile/store.js

@@ -0,0 +1,261 @@
+/**
+ * profile/store.js — Cross-system profile bus, P0.2 + P0.3.
+ *
+ * The user-global profile store: path resolution + atomic read/write with a
+ * `.bak` backup and a symlink guard.
+ *
+ * KEY INVARIANT (design-v2 §2, audit MED-Storage): this tier is **user-global,
+ * homedir-rooted, and EXEMPT from the per-project PROJECT_HASH namespacing**.
+ * Project memory is REPO_ROOT-scoped to prevent cross-project worming; the
+ * profile is the deliberate, documented exception (it's about the user, not the
+ * project). Therefore every path resolves from `os.homedir()` — NEVER from CWD
+ * or REPO_ROOT — so two host processes in two projects converge on ONE file.
+ *
+ * Layout-v2 note: a future rename moves `.ijfw/` → `ijfw/`. We key off homedir
+ * + a single base-dir constant so that rename is a one-line change here, not a
+ * literal sprinkled across the codebase.
+ *
+ * Atomic write: temp file in the SAME directory → fsync → rename. The target is
+ * opened with O_NOFOLLOW (via openSync flags) so a symlinked target is refused
+ * rather than followed (anti-symlink-swap). A `.bak` copy of the prior good
+ * content is kept; a corrupt/unparseable primary is recovered from `.bak`.
+ *
+ * Zero deps, Node built-ins only. NO LLM calls.
+ */
+
+import {
+  openSync,
+  writeFileSync,
+  fsyncSync,
+  closeSync,
+  renameSync,
+  unlinkSync,
+  readFileSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  lstatSync,
+  constants as fsConstants,
+} from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { makeProfile, serializeProfile, parseProfile } from './schema.js';
+import { resolveOverrideDir, homedirProfileDefault } from './path-policy.js';
+
+const PROFILE_FILE = 'user-profile.md';
+
+/**
+ * Max bytes we will read from an on-disk profile (audit LOW: read-size cap).
+ * The profile is bounded by P0.6 eviction/decay, so a file larger than this is
+ * a hand-edited or corrupt artifact; refusing to slurp it whole avoids an OOM
+ * on a pathological input. 4 MiB is ~orders of magnitude above any legitimate
+ * profile. A too-large primary falls through to .bak recovery (readProfile).
+ */
+const MAX_PROFILE_BYTES = 4 * 1024 * 1024;
+
+/**
+ * The user-global profile directory. Override via IJFW_PROFILE_DIR (tests +
+ * power users). Default: `~/.ijfw/profile`. Resolved from homedir, never CWD.
+ *
+ * SECURITY (audit HIGH-4): a verbatim env override is a relocation/identity-
+ * partition-defeat surface, so the override is validated by `resolveOverrideDir`
+ * — honored only under a test runner OR when it resolves under os.homedir() and
+ * is uid-owned. An unsafe override falls back to the default homedir path.
+ *
+ * TEST-ISOLATION: when there is no safe override, the default is resolved by
+ * `homedirProfileDefault`, which under a test context returns a process-unique
+ * `os.tmpdir()` scratch dir (never the real homedir) — so a test that forgot to
+ * set IJFW_PROFILE_DIR is auto-isolated and can never write into the user's real
+ * `~/.ijfw/profile`. Production behavior is unchanged (real homedir).
+ */
+export function profileDir() {
+  const safe = resolveOverrideDir(process.env.IJFW_PROFILE_DIR);
+  if (safe) return safe;
+  return homedirProfileDefault(['.ijfw', 'profile']);
+}
+
+export function profilePath() {
+  return join(profileDir(), PROFILE_FILE);
+}
+
+export function backupPath() {
+  return `${profilePath()}.bak`;
+}
+
+/** The user-global archive dir (P0.6 decay-to-archive lands files here). */
+export function archiveDir() {
+  return join(profileDir(), 'archive');
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * True iff `p` exists AND is a symlink. We refuse to read/write through a
+ * symlinked target — an attacker who can pre-create the profile path as a
+ * symlink could otherwise redirect our atomic rename / our read at an arbitrary
+ * file. lstat() (not stat()) so the link itself is inspected, not its target.
+ */
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false; // absent → not a symlink
+  }
+}
+
+/**
+ * writeProfile(profile) — atomic, backup-keeping, symlink-guarded write.
+ * Returns { ok:true } or { ok:false, code, message }. Never throws.
+ */
+export function writeProfile(profile) {
+  const target = profilePath();
+  // Symlink guard: refuse a symlinked target outright.
+  if (isSymlink(target)) {
+    return { ok: false, code: 'EPROFILE_SYMLINK', message: `refusing symlinked target: ${target}` };
+  }
+
+  let content;
+  try {
+    content = serializeProfile(profile);
+  } catch (err) {
+    return { ok: false, code: 'ESERIALIZE', message: err.message };
+  }
+
+  try {
+    ensureDir(profileDir());
+  } catch (err) {
+    return { ok: false, code: err.code || 'EMKDIR', message: err.message };
+  }
+
+  // Back up the prior good content (best-effort) BEFORE we overwrite, so a
+  // crash mid-rename leaves a recoverable .bak. Guard BOTH sides against a
+  // symlink swap: the source (`target`) so we don't read through a link, AND
+  // the destination (`backupPath()`) — a pre-planted `user-profile.md.bak`
+  // symlink would otherwise let copyFileSync follow it and overwrite an
+  // arbitrary file. If the .bak path is a symlink, drop it (unlink) and copy to
+  // a real file instead; never write through the link.
+  if (existsSync(target) && !isSymlink(target)) {
+    try {
+      const bak = backupPath();
+      if (isSymlink(bak)) {
+        try { unlinkSync(bak); } catch {}
+      }
+      copyFileSync(target, bak);
+    } catch {
+      // non-fatal — proceed; worst case is no fresh backup this round.
+    }
+  }
+
+  const tmp = `${target}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+  let fd;
+  try {
+    // O_NOFOLLOW on the tmp create is belt-and-suspenders; the tmp name is
+    // random so it cannot pre-exist as an attacker symlink, but we keep the
+    // flag for defense in depth. O_EXCL ensures we never open an existing file.
+    // NOTE: O_NOFOLLOW is a no-op on Windows (no symlink semantics there) — the
+    // real cross-platform guard is the isSymlink() (lstat) check above/below.
+    fd = openSync(
+      tmp,
+      fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
+      0o600,
+    );
+    writeFileSync(fd, content, 'utf8');
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+    // Re-check the target right before rename — TOCTOU narrowing.
+    if (isSymlink(target)) {
+      try { unlinkSync(tmp); } catch {}
+      return { ok: false, code: 'EPROFILE_SYMLINK', message: `target became a symlink: ${target}` };
+    }
+    renameSync(tmp, target);
+    // Durability: rename() is atomic, but on Linux ext4/XFS the parent
+    // directory entry is not guaranteed to survive a power-fail until the
+    // directory itself is fsynced — even though the file data was fsynced
+    // above. Best-effort fsync the parent dir to durably commit the new entry.
+    // Wrapped in try/catch: rename atomicity already holds, so a failed dir
+    // fsync degrades durability, not correctness, and must not fail the write.
+    try {
+      const dirFd = openSync(profileDir(), fsConstants.O_RDONLY);
+      try {
+        fsyncSync(dirFd);
+      } finally {
+        closeSync(dirFd);
+      }
+    } catch {
+      // best-effort — some platforms (e.g. Windows) cannot fsync a directory.
+    }
+    return { ok: true };
+  } catch (err) {
+    if (fd != null) { try { closeSync(fd); } catch {} }
+    try { unlinkSync(tmp); } catch {}
+    return { ok: false, code: err.code || 'EWRITE', message: err.message };
+  }
+}
+
+function tryParseFile(p) {
+  // Refuse symlinked source.
+  if (isSymlink(p)) return { ok: false, code: 'EPROFILE_SYMLINK' };
+  // Read-size cap (audit LOW): refuse to slurp a pathologically large profile
+  // into memory. The profile is bounded by P0.6, so an oversized file is a
+  // corrupt/hand-edited artifact — surface ETOOBIG so readProfile falls through
+  // to .bak recovery rather than OOMing on the read.
+  try {
+    const st = lstatSync(p);
+    if (st.isFile() && st.size > MAX_PROFILE_BYTES) {
+      return { ok: false, code: 'ETOOBIG', message: `profile exceeds ${MAX_PROFILE_BYTES} bytes` };
+    }
+  } catch {
+    // stat failure falls through to the read, which will surface its own error.
+  }
+  let raw;
+  try {
+    raw = readFileSync(p, 'utf8');
+  } catch (err) {
+    return { ok: false, code: err.code || 'EREAD', message: err.message };
+  }
+  try {
+    return { ok: true, profile: parseProfile(raw) };
+  } catch (err) {
+    return { ok: false, code: 'EPARSE', message: err.message };
+  }
+}
+
+/**
+ * readProfile() — read the user-global profile.
+ *  - missing file → fresh default profile, { ok:true, created:true }
+ *  - good file    → { ok:true, profile }
+ *  - corrupt file → recover from .bak → { ok:true, profile, recovered:true }
+ *  - symlinked    → { ok:false } (refused)
+ */
+export function readProfile() {
+  const target = profilePath();
+
+  if (isSymlink(target)) {
+    return { ok: false, code: 'EPROFILE_SYMLINK', message: `refusing symlinked target: ${target}` };
+  }
+
+  if (!existsSync(target)) {
+    return { ok: true, profile: makeProfile(), created: true };
+  }
+
+  const primary = tryParseFile(target);
+  if (primary.ok) return { ok: true, profile: primary.profile };
+
+  // Primary unparseable — attempt backup recovery.
+  const bak = backupPath();
+  if (existsSync(bak) && !isSymlink(bak)) {
+    const recovered = tryParseFile(bak);
+    if (recovered.ok) {
+      return { ok: true, profile: recovered.profile, recovered: true };
+    }
+  }
+
+  // Neither primary nor backup is usable. Surface the error rather than
+  // silently clobbering with a default (caller decides; merge layer will hold
+  // the lock and can choose to reinitialize).
+  return { ok: false, code: 'ECORRUPT', message: 'primary unparseable and no usable backup' };
+}