@bookedsolid/rea 0.40.0 → 0.42.0

package/dist/cli/doctor.js

@@ -1264,18 +1264,74 @@ function defaultPython3PyYamlReachable(baseDir) {
         return false;
     }
 }
+/**
+ * 0.42.0 codex round 5 P2 (2026-05-16) — execution probe for the
+ * python3 list-walker. Mirrors `defaultPython3PyYamlReachable` exactly
+ * but swaps the `import yaml` for `import json` (the actual stdlib
+ * module the shim's list-walker branch imports). Spawning the
+ * interpreter end-to-end catches the broken-symlink / unreachable-
+ * shim case that a bare PATH check misses.
+ */
+function defaultPython3ListWalkerReachable(baseDir) {
+    try {
+        const probeEnv = { ...process.env, PYTHONSAFEPATH: '1' };
+        delete probeEnv['PYTHONPATH'];
+        delete probeEnv['PYTHONHOME'];
+        delete probeEnv['PYTHONSTARTUP'];
+        // Same sys.path scrub as the production loader, applied before
+        // `import json`. `json` is stdlib so a malicious `./json.py`
+        // attack would matter the same way `./yaml.py` does.
+        const probeBody = [
+            'import sys',
+            'import os',
+            '_cwd = os.getcwd()',
+            '_cwd_real = os.path.realpath(_cwd)',
+            'sys.path[:] = [p for p in sys.path if p not in ("", ".", _cwd, _cwd_real)]',
+            'import json',
+            'sys.stdout.write("ok")',
+        ].join('\n');
+        const res = spawnSync('python3', ['-c', probeBody], {
+            cwd: baseDir,
+            env: probeEnv,
+            timeout: 5_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (res.status !== 0)
+            return false;
+        return (res.stdout?.toString().trim() ?? '') === 'ok';
+    }
+    catch {
+        return false;
+    }
+}
 const DEFAULT_PROBES = {
     cliDistExists: defaultCliDistExists,
     cliInvokable: defaultCliInvokable,
     python3OnPath: () => resolveBinaryOnPath('python3'),
     python3PyYamlReachable: defaultPython3PyYamlReachable,
+    python3ListWalkerReachable: defaultPython3ListWalkerReachable,
     awkOnPath: () => resolveBinaryOnPath('awk'),
     jqOnPath: () => resolveBinaryOnPath('jq'),
 };
 function resolveProbes(probes) {
     if (probes === undefined)
         return DEFAULT_PROBES;
-    return { ...DEFAULT_PROBES, ...probes };
+    // 0.42.0 codex round 5 P2 (2026-05-16): when a caller (typically
+    // a unit test) stubs `python3OnPath` but does NOT stub the new
+    // `python3ListWalkerReachable` execution probe, derive a faithful
+    // fallback from `python3OnPath` instead of falling through to the
+    // real `defaultPython3ListWalkerReachable` (which would spawn a
+    // python3 subprocess and break test determinism). The convention
+    // matches `python3PyYamlReachable` in the existing test suite:
+    // stubs that say "python3 is present" want both downstream probes
+    // to report reachable, and stubs that say "python3 is absent" want
+    // both downstream probes to report unreachable.
+    const overrides = { ...probes };
+    if (overrides.python3ListWalkerReachable === undefined && overrides.python3OnPath !== undefined) {
+        const stubbedPython3OnPath = overrides.python3OnPath;
+        overrides.python3ListWalkerReachable = () => stubbedPython3OnPath() !== null;
+    }
+    return { ...DEFAULT_PROBES, ...overrides };
 }
 /**
  * Tier 1 — `rea hook policy-get`. Reachable when the rea CLI is
@@ -1374,12 +1430,12 @@ export function checkPolicyReaderTier2(baseDir, probes) {
  * Practically always present (POSIX requirement).
  *
  * 0.40.0 charter item 2 — conditional verdict, refined by codex
- * round 1 P2:
+ * round 1 P2 (0.40.0) and round 2 P2 (0.42.0):
  *   - awk present                                            → `pass`
  *   - awk absent AND Tier 2 reachable                        → `warn`
  *     (Tier 2 implies python3, which is a list-walker)
  *   - awk absent AND Tier 1 reachable AND a list walker
- *     (jq OR python3) is on PATH                             → `warn`
+ *     (jq OR full Tier-2 reachable) is usable                → `warn`
  *   - awk absent AND Tier 1 reachable BUT no list walker     → `fail`
  *     (codex round 1 P2 — list-valued policy reads silently
  *     fail-closed even though scalar reads work, so the
@@ -1398,9 +1454,29 @@ export function checkPolicyReaderTier2(baseDir, probes) {
  * functional box that has python3 + jq + the rea CLI all wired but
  * happens to lack awk.
  *
+ * List-iteration semantic (clarifying note for codex round 2 P2,
+ * 2026-05-16): `policy_reader_get_list` in
+ * `hooks/_lib/policy-reader.sh` walks the cached subtree JSON via
+ * `jq` OR `python3` (stdlib-only — `json` module, no PyYAML import).
+ * PyYAML is only needed for Tier 2 itself (YAML PARSING into JSON),
+ * NOT for iterating the already-parsed JSON arrays at list-read time.
+ *
+ * Codex round 5 P2 (2026-05-16): the "list walker" predicate uses
+ * `python3ListWalkerReachable` — an EXECUTION probe that actually
+ * spawns `python3 -c "import json"` — instead of `python3OnPath`. A
+ * PATH-only check passes for broken pyenv/asdf shims, dangling
+ * symlinks, and sandboxed environments where the interpreter cannot
+ * start; in those cases the shim's list-walker branch would actually
+ * fail and `blocked_paths`/`protected_writes` enforcement would
+ * silently break while doctor reported `warn`. The execution probe
+ * mirrors `defaultPython3PyYamlReachable` exactly but swaps the
+ * `import yaml` for `import json` so it's not gated on PyYAML
+ * availability (which is irrelevant to list iteration).
+ *
  * Takes `baseDir` so it can evaluate Tier 1's two-stage check (dist
- * present + CLI invokable) and Tier 2's reachability. Probes are
- * threaded through identically.
+ * present + CLI invokable), Tier 2's reachability, and the
+ * list-walker execution probe. All probes are threaded through
+ * identically.
  */
 export function checkPolicyReaderTier3(baseDir, probes) {
     const label = 'policy-reader Tier 3 (awk)';
@@ -1420,22 +1496,25 @@ export function checkPolicyReaderTier3(baseDir, probes) {
     // ladder would actually do at runtime.
     const tier1 = p.cliDistExists(baseDir) && p.cliInvokable(baseDir);
     const tier2 = p.python3OnPath() !== null && p.python3PyYamlReachable(baseDir);
-    // Codex round 1 P2 (2026-05-16): the downgrade-to-warn branch needs
-    // a list walker too. `policy_reader_get_list` (the helper that reads
-    // list-valued keys like `blocked_paths`) iterates the parsed JSON
-    // array via jq OR python3, falling back to Tier 3 awk for inline
-    // arrays. With awk gone AND no jq AND no python3, list-valued
-    // policy reads silently fail-closed even when Tier 1 is reachable —
-    // `blocked-paths-bash-gate.sh` etc. would see an EMPTY blocked-paths
-    // set and stop enforcing entries the operator declared. Pre-fix
-    // this concrete shape (cliInvokable + no python3 + no jq + no awk)
-    // returned `warn` and the doctor exited 0 on a broken install.
-    // Post-fix the downgrade requires a list walker; otherwise we stay
-    // on `fail`. Tier 2 implies python3 on PATH (the interpreter that
-    // ran PyYAML), so Tier 2 always brings list-walker support — no
-    // additional check needed for the Tier-2 branch.
-    const py = p.python3OnPath();
-    const listWalker = p.jqOnPath() !== null || py !== null;
+    // Codex round 1 P2 (0.40.0) + round 2 P2 corrected (0.42.0,
+    // 2026-05-16) + round 5 P2 (0.42.0, 2026-05-16): the
+    // downgrade-to-warn branch needs a list walker too.
+    // `policy_reader_get_list` iterates the parsed JSON array via jq
+    // OR python3. The python3 branch uses `json` from stdlib only —
+    // PyYAML is NOT required (it's only needed for Tier 2's YAML
+    // parsing step, which has already run by the time list iteration
+    // executes).
+    //
+    // Round 5 P2 hardening: the python3 leg of this predicate uses an
+    // EXECUTION probe (`python3ListWalkerReachable`), not just a PATH
+    // check. A `python3` symlink can resolve on PATH while the
+    // interpreter itself fails to start (dangling pyenv/asdf shim,
+    // sandboxed runner without dynamic libs, permission denied on the
+    // resolved binary). PATH-only would let doctor declare `warn` on
+    // a box where the shim's list walker would actually fail —
+    // silently breaking `blocked_paths` / `protected_writes`
+    // enforcement while doctor exits 0.
+    const listWalker = p.jqOnPath() !== null || p.python3ListWalkerReachable(baseDir);
     if (tier2 || (tier1 && listWalker)) {
         const reachable = [];
         if (tier1)
@@ -1451,21 +1530,43 @@ export function checkPolicyReaderTier3(baseDir, probes) {
                 'to restore the last-resort fallback.',
         };
     }
-    // Codex round 1 P2: separate "no list walker" diagnosis from the
-    // catastrophic "no tier at all" case. Tier 1 reachable but no jq
-    // AND no python3 AND no awk means list-valued policy reads
-    // fail-closed silently — distinct from the truly-empty
-    // no-CLI-no-python-no-awk shape, and worth a precise remediation.
+    // Codex round 1 P2 (0.40.0) + round 2 P2 (0.42.0): separate "no list
+    // walker" diagnosis from the catastrophic "no tier at all" case.
+    // Tier 1 reachable but no jq AND no python3 AND no awk means
+    // list-valued policy reads fail-closed silently — distinct from the
+    // truly-empty no-CLI-no-python-no-awk shape, and worth a precise
+    // remediation. The python3-as-list-walker signal is plain
+    // `python3OnPath` (the `json` module is stdlib — PyYAML is NOT
+    // required for list iteration).
     if (tier1) {
+        // 0.42.0 codex round 6 P3 (2026-05-16): distinguish "python3 not
+        // on PATH" from "python3 on PATH but execution fails". Pre-fix
+        // this branch always reported "python3 is not on PATH" even when
+        // a python3 binary was resolvable but a broken pyenv/asdf shim
+        // or sandboxed interpreter failed the execution probe — that
+        // sent operators toward the wrong remediation. Round 5 added
+        // the execution probe specifically to surface this case; the
+        // diagnostic needs to follow.
+        const pythonOnPath = p.python3OnPath();
+        const pythonState = pythonOnPath === null
+            ? 'python3 is not on PATH'
+            : `python3 at ${pythonOnPath} cannot execute \`import json\` (broken pyenv/asdf shim, ` +
+                'sandboxed interpreter, or permission-denied binary — fix the interpreter or ' +
+                'remove the shim)';
+        const remediation = pythonOnPath === null
+            ? 'Install awk OR jq OR python3 to restore list-iteration.'
+            : `Install awk OR jq, or repair the python3 interpreter at ${pythonOnPath}, ` +
+                'to restore list-iteration.';
         return {
             label,
             status: 'fail',
-            detail: 'awk not on PATH AND neither jq nor python3 is on PATH — Tier 1 (rea CLI) parses ' +
-                'flow-form scalars, but `policy_reader_get_list` cannot iterate list-valued keys ' +
-                '(e.g. `blocked_paths: [.env, ...]`) without jq, python3, OR awk to walk the ' +
-                'resulting JSON arrays. Affected hooks (`blocked-paths-bash-gate.sh`, ' +
-                '`blocked-paths-enforcer.sh`, …) see an EMPTY list and silently stop enforcing. ' +
-                'Install awk OR jq OR python3 to restore list-iteration.',
+            detail: `awk not on PATH AND jq is not on PATH AND ${pythonState} — ` +
+                'Tier 1 (rea CLI) parses flow-form scalars, but `policy_reader_get_list` ' +
+                'cannot iterate list-valued keys (e.g. `blocked_paths: [.env, ...]`) ' +
+                'without jq OR python3 OR awk to walk the resulting JSON arrays. ' +
+                'Affected hooks (`blocked-paths-bash-gate.sh`, ' +
+                `\`blocked-paths-enforcer.sh\`, …) see an EMPTY list and silently stop ` +
+                `enforcing. ${remediation}`,
         };
     }
     return {
@@ -1542,11 +1643,14 @@ export function checkPolicyReaderTierSummary(baseDir, probes) {
     const tier2 = py !== null && p.python3PyYamlReachable(baseDir);
     const tier3 = p.awkOnPath() !== null;
     const jq = p.jqOnPath();
-    // List iteration after Tier 1/2 needs jq OR python3 to walk the
-    // JSON. Tier 2 implies python3 on PATH (the interpreter that ran
-    // the loader); so the only "lists broken" shape is Tier 1 reachable
-    // but neither jq nor python3 on PATH.
-    const listWalker = jq !== null || py !== null;
+    // 0.42.0 codex round 5 P2 (2026-05-16): list iteration after Tier
+    // 1/2 needs jq OR a python3 that can ACTUALLY execute (not just
+    // resolve on PATH). The execution probe catches the broken-shim
+    // case where `python3` resolves but the interpreter cannot start —
+    // PATH-only would falsely declare the list walker "usable" on a
+    // box where the shim's python3 branch will fall through to Tier 3
+    // and silently miss flow-form arrays.
+    const listWalker = jq !== null || p.python3ListWalkerReachable(baseDir);
     const reachable = [];
     if (tier1)
         reachable.push('Tier 1 (CLI)');

package/dist/cli/index.js

@@ -13,6 +13,8 @@ import { runServe } from './serve.js';
 import { runStatus } from './status.js';
 import { runTofuAccept, runTofuList } from './tofu.js';
 import { runUpgrade } from './upgrade.js';
+import { runUpgradeCheck } from './upgrade-check.js';
+import { registerAuditSummaryCommand } from './audit-summary.js';
 import { registerVerifyClaimCommand } from './verify-claim.js';
 import { err, getPkgVersion } from './utils.js';
 async function main() {
@@ -51,7 +53,34 @@ async function main() {
         .option('--dry-run', 'show what would change; write nothing')
         .option('-y, --yes', 'non-interactive — keep drifted files, skip removed-upstream')
         .option('--force', 'non-interactive — overwrite drift, delete removed-upstream')
+        // 0.41.0 — `--check` is a non-interactive, structured preview that
+        // emits unified diffs per modified file and exits 0 regardless of
+        // what would change. Distinct from `--dry-run`, which rehearses the
+        // FULL interactive flow with writes suppressed. Use `--check` in CI
+        // to surface the changes a `rea upgrade` PR would produce; use
+        // `--dry-run` locally to walk through the same prompts you'd see
+        // during a real upgrade.
+        .option('--check', '0.41.0 — preview-only mode: classify files, emit unified diffs, exit 0')
+        .option('--json', '(with --check) emit a single JSON document instead of the text summary')
+        .option('--no-diff', '(with --check) omit unified-diff bodies (counts + paths only)')
         .action(async (opts) => {
+        if (opts.check === true) {
+            await runUpgradeCheck({
+                json: opts.json === true,
+                noDiff: opts.diff === false,
+            });
+            return;
+        }
+        // Codex round-2 P1: `--json` / `--no-diff` are preview-only.
+        // Before this PR they were unknown flags and commander rejected
+        // them; now they exist on the command. Refuse them without
+        // `--check` rather than silently performing a real upgrade —
+        // a CI typo (`rea upgrade --json` without `--check`) must not
+        // rewrite `.claude/` / `.husky/` / managed fragments.
+        if (opts.json === true || opts.diff === false) {
+            err('`--json` / `--no-diff` are preview-only flags; pass `--check` to use them.');
+            process.exit(2);
+        }
         await runUpgrade({
             dryRun: opts.dryRun,
             yes: opts.yes,
@@ -111,6 +140,10 @@ async function main() {
     // records. Read-only; honors $CLAUDE_SESSION_ID for current-session
     // filtering. v1 omits --since / --session (deferred to 0.29.1).
     registerAuditSpecialistsSubcommand(audit);
+    // 0.41.0 — `rea audit summary [--since=DUR] [--json]` high-level
+    // overview reader. Counts events by tool_name, tier, session,
+    // status; samples chain integrity. Tier-Read; never mutates.
+    registerAuditSummaryCommand(audit);
     // Register `rea hook push-gate` — the stateless pre-push Codex gate
     // called by `.husky/pre-push` and `.git/hooks/pre-push`.
     registerHookCommand(program);

package/dist/cli/install/gitignore.d.ts

@@ -102,6 +102,28 @@ export interface EnsureGitignoreResult {
     addedEntries: string[];
     /** Non-fatal operator-facing messages (e.g. symlink refused, duplicate blocks). */
     warnings: string[];
+    /**
+     * 0.41.0 — when computed under `dryRun: true`, the full would-be
+     * on-disk content. Omitted in real-write mode (the file IS the
+     * authoritative copy). Callers like `rea upgrade --check` use this
+     * to render a unified diff against the current on-disk content.
+     */
+    previewContent?: string;
+    /**
+     * 0.41.0 — current on-disk content at planning time. `null` when
+     * the file does not exist. Omitted in real-write mode.
+     */
+    previousContent?: string | null;
+}
+export interface EnsureGitignoreOptions {
+    /**
+     * When `true`, compute the action + would-be content without
+     * writing. Returns `previewContent` and `previousContent`. Default
+     * `false` (write-on).
+     */
+    dryRun?: boolean;
+    /** Override the canonical entry list. Tests use this. */
+    entries?: readonly string[];
 }
 /**
  * Main entry point. Idempotent: calling twice in a row produces `unchanged`
@@ -111,4 +133,4 @@ export interface EnsureGitignoreResult {
  * init` and `rea upgrade` pass the default. Tests override to verify
  * reconciliation.
  */
-export declare function ensureReaGitignore(targetDir: string, entries?: readonly string[]): Promise<EnsureGitignoreResult>;
+export declare function ensureReaGitignore(targetDir: string, optionsOrEntries?: EnsureGitignoreOptions | readonly string[]): Promise<EnsureGitignoreResult>;

package/dist/cli/install/gitignore.js

@@ -271,7 +271,15 @@ async function writeAtomic(absPath, content) {
  * init` and `rea upgrade` pass the default. Tests override to verify
  * reconciliation.
  */
-export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTRIES) {
+export async function ensureReaGitignore(targetDir, optionsOrEntries = {}) {
+    // Back-compat: pre-0.41.0 callers passed `entries` as the second
+    // positional argument. Detect the legacy shape and forward to the
+    // options form so we don't break existing call sites.
+    const options = Array.isArray(optionsOrEntries)
+        ? { entries: optionsOrEntries }
+        : optionsOrEntries;
+    const entries = options.entries ?? REA_GITIGNORE_ENTRIES;
+    const dryRun = options.dryRun === true;
     const absPath = path.resolve(targetDir, GITIGNORE);
     const warnings = [];
     let existing;
@@ -280,18 +288,26 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
     }
     catch (err) {
         warnings.push(err.message);
-        return { path: absPath, action: 'unchanged', addedEntries: [], warnings };
+        return {
+            path: absPath,
+            action: 'unchanged',
+            addedEntries: [],
+            warnings,
+            ...(dryRun ? { previousContent: null, previewContent: '' } : {}),
+        };
     }
     // Detect EOL so a CRLF repo stays CRLF and doesn't get torn. Codex F3.
     const eol = existing !== null && existing.includes('\r\n') ? '\r\n' : '\n';
     if (existing === null) {
         const content = buildManagedBlock(entries, '\n') + '\n';
-        await writeAtomic(absPath, content);
+        if (!dryRun)
+            await writeAtomic(absPath, content);
         return {
             path: absPath,
             action: 'created',
             addedEntries: [...entries],
             warnings,
+            ...(dryRun ? { previousContent: null, previewContent: content } : {}),
         };
     }
     const lines = existing.split(/\r?\n/);
@@ -300,7 +316,13 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
     if (block === 'duplicate') {
         warnings.push(`${absPath} contains multiple '# === rea managed' blocks — refusing to modify. ` +
             `Consolidate the managed blocks manually and rerun.`);
-        return { path: absPath, action: 'unchanged', addedEntries: [], warnings };
+        return {
+            path: absPath,
+            action: 'unchanged',
+            addedEntries: [],
+            warnings,
+            ...(dryRun ? { previousContent: existing, previewContent: existing } : {}),
+        };
     }
     if (block === null) {
         // No managed block. Append one after a blank-line separator (unless the
@@ -315,12 +337,14 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
         const separator = bodyLines.length === 0 ? [] : [''];
         const newLines = [...bodyLines, ...separator, buildManagedBlock(entries, eol)];
         const content = newLines.join(eol) + eol;
-        await writeAtomic(absPath, content);
+        if (!dryRun)
+            await writeAtomic(absPath, content);
         return {
             path: absPath,
             action: 'updated',
             addedEntries: [...entries],
             warnings,
+            ...(dryRun ? { previousContent: existing, previewContent: content } : {}),
         };
     }
     // Managed block exists — reconcile body lines.
@@ -332,6 +356,7 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
             action: 'unchanged',
             addedEntries: [],
             warnings,
+            ...(dryRun ? { previousContent: existing, previewContent: existing } : {}),
         };
     }
     const newLines = [
@@ -342,11 +367,13 @@ export async function ensureReaGitignore(targetDir, entries = REA_GITIGNORE_ENTR
     let content = newLines.join(eol);
     if (hadTrailingNewline && !content.endsWith(eol))
         content += eol;
-    await writeAtomic(absPath, content);
+    if (!dryRun)
+        await writeAtomic(absPath, content);
     return {
         path: absPath,
         action: 'updated',
         addedEntries: added,
         warnings,
+        ...(dryRun ? { previousContent: existing, previewContent: content } : {}),
     };
 }

package/dist/cli/install/unified-diff.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Minimal LCS-based unified-diff renderer (0.41.0).
+ *
+ * Used by `rea upgrade --check` to emit a per-file preview of what the
+ * upgrade flow WOULD change. We deliberately ship our own implementation
+ * rather than pulling in the `diff` npm package — REA's dependency
+ * footprint is small and load-bearing, and the upgrade-check preview is
+ * the only consumer.
+ *
+ * Output shape mirrors `diff -u`:
+ *
+ *     --- a/path/to/file
+ *     +++ b/path/to/file
+ *     @@ -1,3 +1,4 @@
+ *      context line
+ *     -removed line
+ *     +added line
+ *      context line
+ *
+ * Hunks are constructed greedily — adjacent changed regions within
+ * `contextLines` of each other are merged into a single hunk so a
+ * reviewer reading the output doesn't have to mentally stitch tiny
+ * back-to-back hunks together.
+ *
+ * Performance: classic O(n*m) LCS with two parallel `Uint32Array`s for
+ * the DP table. Files in the upgrade-check path are bounded at
+ * `DIFF_SIZE_CAP_BYTES` (256 KiB) by callers, so even the worst-case
+ * shape (256 KiB of single-character lines) stays inside the addressable
+ * range of `Uint32Array` indices (~4 GiB worth of cells). The caller is
+ * responsible for refusing to diff files larger than the cap; this
+ * module trusts its inputs.
+ *
+ * Newline handling: we split on `\n` only. A file with `\r\n` line
+ * endings will surface as one big changed block if compared against a
+ * `\n`-ending canonical, which is the right behavior — line endings
+ * differing IS a real difference. We do not normalize.
+ */
+/**
+ * Hard cap on the DP-table cell count. The O(m*n) LCS table is the
+ * dominant memory cost; with a 4-byte `Uint32Array` cell, this works
+ * out to ~16 MiB of allocation at the cap. We deliberately key off
+ * cell COUNT, not file bytes — codex round-1 P1 flagged that the
+ * 256 KiB byte cap callers enforce can still produce pathological
+ * matrices when files are mostly single-character lines (200 KiB of
+ * one-char lines = 200K lines = 40 GiB of cells).
+ *
+ * Exported so callers can detect the "too large to diff" verdict
+ * structurally instead of grepping the returned string.
+ */
+export declare const MAX_LCS_CELLS = 4000000;
+/**
+ * Sentinel returned in place of a real diff when the line counts
+ * would blow past `MAX_LCS_CELLS`. Wrapped in a recognizable comment
+ * shape so consumers grepping the diff body see a clear notice.
+ */
+export declare const DIFF_TOO_LARGE_NOTICE = "# rea: diff suppressed \u2014 file pair too large for the LCS matrix budget\n";
+export interface UnifiedDiffOptions {
+    /** Defaults to `'file'`. Appears after `--- a/` in the header. */
+    oldPath?: string;
+    /** Defaults to `oldPath`. Appears after `+++ b/` in the header. */
+    newPath?: string;
+    /** Lines of context around each change. Default 3 — matches `diff -u`. */
+    contextLines?: number;
+}
+/**
+ * Compute a unified diff between two text blobs.
+ *
+ * Returns the empty string when the two inputs are byte-identical. The
+ * caller decides whether to wrap that in a "no changes" notice.
+ *
+ * Splits on `\n` and drops a single trailing `\n` if present so the
+ * final line is not phantom-blank. A file that genuinely ends without
+ * a newline will appear identical to one that ends with a single
+ * newline — REA's canonical files all end with `\n`, so this is fine
+ * for our use case. Callers that need strict-EOL fidelity should
+ * normalize upstream.
+ */
+export declare function diffUnified(oldText: string, newText: string, options?: UnifiedDiffOptions): string;