@bookedsolid/rea 0.1.0 → 0.2.0

package/dist/gateway/observability/codex-probe.js

@@ -0,0 +1,234 @@
+/**
+ * Codex availability probe (G11.3).
+ *
+ * Passive, periodic reachability check for the Codex CLI, used by `rea serve`
+ * at startup and by `rea doctor` to surface a one-line status about whether
+ * Codex is actually usable right now. This is INTENTIONALLY separate from
+ * the reviewer-selection path in `src/gateway/reviewers/select.ts`:
+ *
+ *   - The selector decides which reviewer to run for a specific push (it
+ *     respects `REA_REVIEWER`, registry pin, policy, etc.).
+ *   - The probe just reports "is the Codex CLI responding at all?" as a
+ *     observability signal — never gates a review.
+ *
+ * Startup must NEVER fail-closed on a probe failure. Codex going away is a
+ * degraded state, not a fatal one; the push gate has its own audited escape
+ * hatch (`REA_SKIP_CODEX_REVIEW`, G11.1).
+ *
+ * ## Probe shape
+ *
+ *   1. `codex --version`  — must exit 0 within {@link VERSION_TIMEOUT_MS}.
+ *      Success → `cli_installed: true` and `version` populated from stdout.
+ *   2. Catalog check     — see the `tryCatalogProbe` comment below. We try
+ *      a best-effort authenticated subcommand with a short timeout. If the
+ *      subcommand is unrecognized by this Codex build, we degrade to "assume
+ *      authenticated iff cli_installed is true" rather than flagging a false
+ *      negative.
+ *
+ * `cli_responsive` is the AND of both. Consumers should treat
+ * `cli_responsive: false` as "Codex may be unavailable — plan accordingly",
+ * not as authoritative proof that a specific review will fail.
+ *
+ * ## Concurrency
+ *
+ * `probe()` is safe to call concurrently. We serialize via a module-local
+ * promise; callers queue up behind the in-flight probe instead of kicking off
+ * duplicate exec calls. `start()` / `stop()` manage a single `setInterval`
+ * with `.unref()` so the probe never pins the event loop.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** Upper bound on `codex --version`. A hung CLI must not stall the gateway. */
+const VERSION_TIMEOUT_MS_DEFAULT = 2_000;
+/** Upper bound on the catalog probe. Longer because it may hit the network. */
+const CATALOG_TIMEOUT_MS_DEFAULT = 5_000;
+/** Default polling cadence — 10 minutes. Codex state rarely flaps faster. */
+const DEFAULT_INTERVAL_MS = 10 * 60 * 1_000;
+const defaultExec = (file, args, options) => execFileAsync(file, [...args], options);
+/** Initial sentinel state — cli considered unresponsive until first probe. */
+function unknownState() {
+    return {
+        cli_installed: false,
+        cli_authenticated: false,
+        cli_responsive: false,
+        last_probe_at: new Date(0).toISOString(),
+    };
+}
+/**
+ * Shallow equality check across the probe-state shape. We fire listeners
+ * only on actual transitions — callers don't want a timer tick to re-log
+ * identical state every 10 minutes.
+ */
+function statesEqual(a, b) {
+    return (a.cli_installed === b.cli_installed &&
+        a.cli_authenticated === b.cli_authenticated &&
+        a.cli_responsive === b.cli_responsive &&
+        a.last_error === b.last_error &&
+        a.version === b.version);
+}
+export class CodexProbe {
+    exec;
+    versionTimeoutMs;
+    catalogTimeoutMs;
+    state = unknownState();
+    inFlight;
+    timer;
+    listeners = new Set();
+    constructor(opts = {}) {
+        this.exec = opts.execFileFn ?? defaultExec;
+        this.versionTimeoutMs = opts.timeoutInstallMs ?? VERSION_TIMEOUT_MS_DEFAULT;
+        this.catalogTimeoutMs = opts.timeoutCatalogMs ?? CATALOG_TIMEOUT_MS_DEFAULT;
+    }
+    /**
+     * Execute a single probe. Safe to call concurrently — overlapping callers
+     * await the single in-flight attempt. Never throws.
+     */
+    probe() {
+        if (this.inFlight !== undefined)
+            return this.inFlight;
+        const attempt = this.runProbe().finally(() => {
+            this.inFlight = undefined;
+        });
+        this.inFlight = attempt;
+        return attempt;
+    }
+    /** Start periodic polling. Immediate probe, then every `intervalMs`. */
+    start(intervalMs = DEFAULT_INTERVAL_MS) {
+        if (this.timer !== undefined)
+            return;
+        // Fire-and-forget the initial probe; callers can await `probe()`
+        // separately if they need the result right now.
+        void this.probe();
+        this.timer = setInterval(() => void this.probe(), intervalMs);
+        // `unref` so the poller doesn't keep the Node event loop alive when the
+        // rest of the process is idle/exiting.
+        this.timer.unref?.();
+    }
+    /** Stop periodic polling. Safe to call even if never started. */
+    stop() {
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /** Snapshot of the most recent probe state. Never throws. */
+    getState() {
+        return { ...this.state };
+    }
+    /**
+     * Subscribe to state transitions. Returns an unsubscribe function. The
+     * listener fires only when any observable field changes, not on every
+     * tick.
+     */
+    onStateChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Core probe logic. Private — use `probe()`. */
+    async runProbe() {
+        const next = {
+            cli_installed: false,
+            cli_authenticated: false,
+            cli_responsive: false,
+            last_probe_at: new Date().toISOString(),
+        };
+        // 1. `codex --version` — cheap reachability signal.
+        try {
+            const { stdout } = await this.exec('codex', ['--version'], {
+                timeout: this.versionTimeoutMs,
+            });
+            next.cli_installed = true;
+            const parsed = stdout.trim();
+            if (parsed.length > 0)
+                next.version = parsed;
+        }
+        catch (err) {
+            next.last_error = formatExecError(err, 'codex --version');
+            this.commit(next);
+            return this.getState();
+        }
+        // 2. Catalog probe — best-effort authenticated check.
+        //
+        // `codex catalog --json` is the aspirational subcommand. If this Codex
+        // build doesn't recognize it, we refuse to fail the probe solely on
+        // that basis — the risk of a false "unauthenticated" flag driving users
+        // to re-login for no reason is higher than the benefit of a rigorous
+        // catalog check today. When the subcommand truly errors (not
+        // "unrecognized"), we surface the error verbatim.
+        const catalogResult = await this.tryCatalogProbe();
+        if (catalogResult.ok) {
+            next.cli_authenticated = true;
+        }
+        else if (catalogResult.skipped) {
+            // Degraded path: CLI installed, catalog subcommand unrecognized → we
+            // assume auth-healthy iff version probe succeeded AND nothing else
+            // has written `last_error`. Documented assumption in module header.
+            next.cli_authenticated = next.last_error === undefined;
+        }
+        else {
+            next.last_error = catalogResult.error;
+        }
+        next.cli_responsive = next.cli_installed && next.cli_authenticated;
+        this.commit(next);
+        return this.getState();
+    }
+    /**
+     * Try `codex catalog --json`. Returns:
+     *   - `{ ok: true }` on exit 0.
+     *   - `{ ok: false, skipped: true }` when the subcommand is unrecognized
+     *     (best-effort detection on stderr).
+     *   - `{ ok: false, skipped: false, error }` on any other failure.
+     */
+    async tryCatalogProbe() {
+        try {
+            await this.exec('codex', ['catalog', '--json'], {
+                timeout: this.catalogTimeoutMs,
+            });
+            return { ok: true };
+        }
+        catch (err) {
+            const message = formatExecError(err, 'codex catalog --json');
+            // A subcommand that isn't baked into this Codex build typically prints
+            // something like "unknown command" or "unrecognized" and exits non-
+            // zero. Treat those as degraded-skip rather than a hard failure.
+            if (/unknown command|unrecognized|usage:|invalid subcommand/i.test(message)) {
+                return { ok: false, skipped: true };
+            }
+            return { ok: false, skipped: false, error: message };
+        }
+    }
+    /** Persist `next` and fire listeners if anything observable changed. */
+    commit(next) {
+        const changed = !statesEqual(this.state, next);
+        this.state = next;
+        if (!changed)
+            return;
+        // Snapshot listeners in case a handler mutates the set.
+        for (const listener of [...this.listeners]) {
+            try {
+                listener({ ...next });
+            }
+            catch {
+                // Listener errors must not break the probe.
+            }
+        }
+    }
+}
+/** Format a child_process error into a single human-readable line. */
+function formatExecError(err, context) {
+    if (err instanceof Error) {
+        const maybeCode = err.code;
+        const maybeSignal = err.signal;
+        // execFile surfaces SIGTERM when `timeout` fires.
+        if (maybeSignal === 'SIGTERM' || /ETIMEDOUT|ESRCH/.test(String(maybeCode))) {
+            return `${context}: timeout`;
+        }
+        if (maybeCode === 'ENOENT')
+            return `${context}: not installed (ENOENT)`;
+        return `${context}: ${err.message}`;
+    }
+    return `${context}: ${String(err)}`;
+}

package/dist/gateway/observability/codex-telemetry.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Codex reviewer telemetry (G11.5).
+ *
+ * Append-only observational metrics for adversarial-review invocations. Each
+ * record captures the invocation type, estimated token counts, duration,
+ * exit code, and whether the downstream reviewer appears to have been
+ * rate-limited (detected from stderr).
+ *
+ * ## Non-goals
+ *
+ * - This is NOT the audit log. The audit log (`.rea/audit.jsonl`) is a
+ *   hash-chained record of every middleware invocation and is authoritative
+ *   for compliance. Telemetry is free-form, per-reviewer-call numbers for
+ *   operators to watch spend and rate-limit pressure.
+ * - No input/output payloads are stored. We estimate token counts from
+ *   character counts on the fly; the raw strings are discarded after the
+ *   record is constructed. This is non-negotiable — the brief explicitly
+ *   prohibits storing the diff or the reviewer output. Any future extension
+ *   that seems to need the text should reach for the audit log or a
+ *   dedicated, policy-gated payload store instead.
+ *
+ * ## Write discipline
+ *
+ * - File: `<reaDir>/.rea/metrics.jsonl`. Created with the parent dir if
+ *   absent. One JSON object per line, newline-terminated, fsync'd after
+ *   each append.
+ * - Fail-soft: write errors log a single stderr warning but never throw.
+ *   Telemetry must never interfere with the reviewed operation.
+ *
+ * ## Read discipline
+ *
+ * - `summarizeTelemetry` streams the file, bucketed by local-tz day, and
+ *   returns a fixed-shape summary. Missing file → all-zero summary.
+ *
+ * ## Token estimation
+ *
+ * - `chars / 4` — a well-known rule of thumb. Close enough for spend
+ *   forecasting; not suitable for billing reconciliation. If a future
+ *   caller needs precise counts, plug in a tokenizer per reviewer and keep
+ *   the estimation as a fallback.
+ */
+/**
+ * Stable identifiers for the contexts in which a reviewer runs. Keep this
+ * closed — downstream dashboards will key on these strings.
+ */
+export type TelemetryInvocationType = 'review' | 'adversarial-review' | 'rescue';
+/** One row in `metrics.jsonl`. */
+export interface TelemetryRecord {
+    timestamp: string;
+    invocation_type: TelemetryInvocationType;
+    estimated_input_tokens: number;
+    estimated_output_tokens: number;
+    duration_ms: number;
+    exit_code: number;
+    rate_limited: boolean;
+}
+/**
+ * Call site input. `input_text` / `output_text` are used ONLY for token
+ * estimation and are NOT persisted. See the file header.
+ */
+export interface RecordTelemetryInput {
+    invocation_type: TelemetryInvocationType;
+    input_text: string;
+    output_text: string;
+    duration_ms: number;
+    exit_code: number;
+    stderr?: string;
+}
+/** Shape returned by {@link summarizeTelemetry}. */
+export interface TelemetrySummary {
+    /** Number of days the summary covers. */
+    window_days: number;
+    /** Count per day, most-recent first. Always length === window_days. */
+    invocations_per_day: number[];
+    /** Sum of input + output estimates across the window. */
+    total_estimated_tokens: number;
+    /** How many records in the window flagged `rate_limited: true`. */
+    rate_limited_count: number;
+    /** Arithmetic mean of duration_ms across all records in the window. */
+    avg_latency_ms: number;
+}
+/** Canonical location for the metrics file under `baseDir`. */
+export declare function metricsFilePath(baseDir: string): string;
+/**
+ * Append a single telemetry row. Always fail-soft — the caller must be
+ * able to treat this as a best-effort observation and continue.
+ */
+export declare function recordTelemetry(baseDir: string, input: RecordTelemetryInput): Promise<void>;
+/**
+ * Build the fixed-shape summary. When `metrics.jsonl` is missing the result
+ * is all-zero — callers should NEVER see an exception for "no data yet".
+ */
+export declare function summarizeTelemetry(baseDir: string, windowDays?: number): Promise<TelemetrySummary>;

package/dist/gateway/observability/codex-telemetry.js

@@ -0,0 +1,221 @@
+/**
+ * Codex reviewer telemetry (G11.5).
+ *
+ * Append-only observational metrics for adversarial-review invocations. Each
+ * record captures the invocation type, estimated token counts, duration,
+ * exit code, and whether the downstream reviewer appears to have been
+ * rate-limited (detected from stderr).
+ *
+ * ## Non-goals
+ *
+ * - This is NOT the audit log. The audit log (`.rea/audit.jsonl`) is a
+ *   hash-chained record of every middleware invocation and is authoritative
+ *   for compliance. Telemetry is free-form, per-reviewer-call numbers for
+ *   operators to watch spend and rate-limit pressure.
+ * - No input/output payloads are stored. We estimate token counts from
+ *   character counts on the fly; the raw strings are discarded after the
+ *   record is constructed. This is non-negotiable — the brief explicitly
+ *   prohibits storing the diff or the reviewer output. Any future extension
+ *   that seems to need the text should reach for the audit log or a
+ *   dedicated, policy-gated payload store instead.
+ *
+ * ## Write discipline
+ *
+ * - File: `<reaDir>/.rea/metrics.jsonl`. Created with the parent dir if
+ *   absent. One JSON object per line, newline-terminated, fsync'd after
+ *   each append.
+ * - Fail-soft: write errors log a single stderr warning but never throw.
+ *   Telemetry must never interfere with the reviewed operation.
+ *
+ * ## Read discipline
+ *
+ * - `summarizeTelemetry` streams the file, bucketed by local-tz day, and
+ *   returns a fixed-shape summary. Missing file → all-zero summary.
+ *
+ * ## Token estimation
+ *
+ * - `chars / 4` — a well-known rule of thumb. Close enough for spend
+ *   forecasting; not suitable for billing reconciliation. If a future
+ *   caller needs precise counts, plug in a tokenizer per reviewer and keep
+ *   the estimation as a fallback.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const REA_DIR = '.rea';
+const METRICS_FILE = 'metrics.jsonl';
+/** Shared denominator for the chars/tokens heuristic. */
+const CHARS_PER_TOKEN = 4;
+/**
+ * Regex for rate-limit markers. Matches the common phrasings we've seen
+ * across Codex, OpenAI API, and Anthropic API error tails. Case-insensitive
+ * so "Rate Limit" and "429" both match.
+ *
+ * Keep this permissive — a false positive is cheap (we flag an invocation
+ * as throttled that wasn't), a false negative silently under-reports the
+ * problem the operator is trying to measure.
+ */
+const RATE_LIMIT_REGEX = /rate[- ]limit|\b429\b|usage limit|exceeded quota/i;
+/**
+ * Token count estimate. Floors to zero for empty strings so downstream
+ * math doesn't have to guard.
+ */
+function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/** Detect whether the reviewer's stderr looks rate-limited. */
+function detectRateLimited(stderr) {
+    if (stderr === undefined || stderr.length === 0)
+        return false;
+    return RATE_LIMIT_REGEX.test(stderr);
+}
+/** Canonical location for the metrics file under `baseDir`. */
+export function metricsFilePath(baseDir) {
+    return path.join(baseDir, REA_DIR, METRICS_FILE);
+}
+/**
+ * Append a single telemetry row. Always fail-soft — the caller must be
+ * able to treat this as a best-effort observation and continue.
+ */
+export async function recordTelemetry(baseDir, input) {
+    const record = {
+        timestamp: new Date().toISOString(),
+        invocation_type: input.invocation_type,
+        estimated_input_tokens: estimateTokens(input.input_text),
+        estimated_output_tokens: estimateTokens(input.output_text),
+        duration_ms: Math.max(0, input.duration_ms | 0),
+        exit_code: input.exit_code | 0,
+        rate_limited: detectRateLimited(input.stderr),
+    };
+    const filePath = metricsFilePath(baseDir);
+    const dir = path.dirname(filePath);
+    const line = JSON.stringify(record) + '\n';
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.appendFile(filePath, line);
+        // Best-effort fsync; failure is non-fatal.
+        let fh;
+        try {
+            fh = await fs.open(filePath, 'r');
+            await fh.sync();
+        }
+        catch {
+            /* ignored */
+        }
+        finally {
+            if (fh)
+                await fh.close();
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // One line, to stderr, never throw. Consumers tailing logs will see it.
+        console.warn(`[rea] WARN: codex telemetry write failed: ${message}`);
+    }
+}
+/** Group records by local-tz YYYY-MM-DD. */
+function dayKey(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return 'invalid';
+    // Local-tz date — operators want "today" to mean their local today.
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+/** Local-tz day key for a JS Date. */
+function dayKeyForDate(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+/**
+ * Load all records from `metrics.jsonl`. Returns `[]` when the file is
+ * missing; skips (not throws) individual unparseable lines so a single
+ * corrupt row doesn't hide the rest of the window.
+ */
+async function readRecords(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.timestamp === 'string' &&
+                typeof parsed.duration_ms === 'number' &&
+                typeof parsed.exit_code === 'number' &&
+                typeof parsed.rate_limited === 'boolean') {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // Malformed line — skip. A future integrity check can flag this.
+        }
+    }
+    return out;
+}
+/**
+ * Build the fixed-shape summary. When `metrics.jsonl` is missing the result
+ * is all-zero — callers should NEVER see an exception for "no data yet".
+ */
+export async function summarizeTelemetry(baseDir, windowDays = 7) {
+    const days = Math.max(1, windowDays | 0);
+    const filePath = metricsFilePath(baseDir);
+    let records;
+    try {
+        records = await readRecords(filePath);
+    }
+    catch {
+        // Read error (permissions, etc.) — treat as empty. Telemetry must never
+        // break a consumer that just wants to see "is this up?".
+        records = [];
+    }
+    // Build day buckets most-recent-first.
+    const now = new Date();
+    const bucketKeys = [];
+    for (let i = 0; i < days; i += 1) {
+        const d = new Date(now.getTime());
+        d.setDate(d.getDate() - i);
+        bucketKeys.push(dayKeyForDate(d));
+    }
+    const countsByKey = new Map();
+    for (const k of bucketKeys)
+        countsByKey.set(k, 0);
+    let totalTokens = 0;
+    let rateLimitedCount = 0;
+    let durationSum = 0;
+    let inWindow = 0;
+    for (const r of records) {
+        const key = dayKey(r.timestamp);
+        if (!countsByKey.has(key))
+            continue; // outside window
+        countsByKey.set(key, (countsByKey.get(key) ?? 0) + 1);
+        totalTokens +=
+            (r.estimated_input_tokens ?? 0) + (r.estimated_output_tokens ?? 0);
+        if (r.rate_limited)
+            rateLimitedCount += 1;
+        durationSum += r.duration_ms ?? 0;
+        inWindow += 1;
+    }
+    const invocations_per_day = bucketKeys.map((k) => countsByKey.get(k) ?? 0);
+    const avg_latency_ms = inWindow === 0 ? 0 : durationSum / inWindow;
+    return {
+        window_days: days,
+        invocations_per_day,
+        total_estimated_tokens: totalTokens,
+        rate_limited_count: rateLimitedCount,
+        avg_latency_ms,
+    };
+}

package/dist/gateway/redact-safe/match-timeout.d.ts

@@ -0,0 +1,83 @@
+/**
+ * G3 — ReDoS safety wrapper.
+ *
+ * Every regex that the middleware chain runs on untrusted MCP payloads must be
+ * bounded. This module provides a `SafeRegex` wrapper that enforces a per-call
+ * timeout by executing the match inside a worker thread, then `Promise.race`-ing
+ * against a `setTimeout`. On timeout the worker is terminated, the caller is told
+ * the operation timed out, and an optional callback fires so the audit layer can
+ * record the event.
+ *
+ * Implementation decision — Option A (worker thread per exec):
+ *   - No native dependency (compare: `re2` would add a native build step and a
+ *     second regex dialect to keep consistent with JS defaults).
+ *   - Timeout is authoritative: terminating the worker is a hard kill, unlike
+ *     interpreter-level heuristics.
+ *   - Overhead is ~1ms per call. That is acceptable for gateway payloads; if it
+ *     ever becomes measurable we can pool workers in a later release without
+ *     changing the public `SafeRegex` surface.
+ *   - Rejected Option B (re2): native dep + a different regex dialect than the
+ *     rest of the codebase assumes. Rejected Option C (length cap only): caps
+ *     bound worst-case cost but don't eliminate catastrophic backtracking.
+ *
+ * SECURITY: The `onTimeout` callback is invoked with the pattern and input. The
+ * callback contract (enforced by callers, not here) is that the input is used
+ * only for size accounting — the middleware must NEVER log the input text, only
+ * its byte length and pattern id. See `redact.ts` / `injection.ts` for the
+ * audit-event shape.
+ */
+export interface MatchTimeoutOptions {
+    /** Per-call timeout budget in milliseconds. Default 100ms. */
+    timeoutMs?: number;
+    /**
+     * Invoked exactly once when a match exceeds the timeout. Callers record an
+     * audit event here. The input text MUST NOT be logged — only size.
+     */
+    onTimeout?: (pattern: RegExp, input: string) => void;
+}
+export interface SafeRegexTestResult {
+    matched: boolean;
+    timedOut: boolean;
+}
+export interface SafeRegexReplaceResult {
+    output: string;
+    timedOut: boolean;
+}
+export interface SafeRegexMatchAllResult {
+    matches: string[];
+    timedOut: boolean;
+}
+export interface SafeRegex {
+    readonly pattern: RegExp;
+    /**
+     * Test whether the pattern matches `input`. On timeout returns
+     * `{ matched: false, timedOut: true }` and invokes `onTimeout`.
+     */
+    test(input: string): SafeRegexTestResult;
+    /**
+     * Replace pattern matches in `input` with `replacer`. On timeout returns
+     * `{ output: input, timedOut: true }` (unchanged input) and invokes
+     * `onTimeout`. The input is NEVER passed through unredacted when a timeout
+     * fires at a higher layer — the middleware substitutes a sentinel. See
+     * `redact.ts` for the sentinel contract.
+     */
+    replace(input: string, replacer: string): SafeRegexReplaceResult;
+    /**
+     * Return all full-string matches of the pattern in `input`. The pattern is
+     * compiled inside the worker with the global flag forced on so matchAll is
+     * meaningful regardless of how the original pattern was specified. On
+     * timeout returns `{ matches: [], timedOut: true }` and invokes `onTimeout`.
+     */
+    matchAll(input: string): SafeRegexMatchAllResult;
+}
+/**
+ * Wrap a RegExp in a timeout-enforced `SafeRegex`. Compilation happens both in
+ * the parent (to catch syntax errors early) and inside the worker (so a
+ * catastrophic compile or match spends only worker CPU).
+ *
+ * SECURITY: callers should pass regexes that have ALSO been cleared by
+ * `safe-regex` at load time — the timeout is a defense-in-depth backstop, not
+ * a replacement for static analysis. See `scripts/lint-safe-regex.mjs` and the
+ * load-time check in `src/policy/loader.ts`.
+ */
+export declare function wrapRegex(pattern: RegExp, opts?: MatchTimeoutOptions): SafeRegex;