@astragenie/astramemory-local 0.7.2

package/dist/recall/pack.js

@@ -0,0 +1,90 @@
+/**
+ * Memory-pack selection (KF-B) — the "injection judgment" v1.
+ * Heuristic, no ML: score = typeWeight · recency · importance,
+ * take top-N under a token budget, render grouped Markdown.
+ * Recency half-life 30 days mirrors search freshness decay.
+ */
+export const DEFAULT_TYPE_WEIGHTS = {
+    decision: 1.0,
+    lesson: 0.9,
+    fact: 0.7,
+    command: 0.6,
+    note: 0.4,
+    todo: 0.4,
+    event: 0.4,
+};
+export const DEFAULT_BUDGET_TOKENS = 1500;
+const RECENCY_HALF_LIFE_DAYS = 30;
+const CANDIDATE_LIMIT = 500;
+/**
+ * Rough token estimate: ~4 chars per token. Real tokenizers vary ±20% —
+ * callers needing exact budgets should leave ~10% headroom. The default
+ * 1500-token budget is deliberately conservative for this reason.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export function selectPack(db, opts) {
+    const now = opts.now ?? Date.now();
+    const budget = opts.budgetTokens ?? DEFAULT_BUDGET_TOKENS;
+    const weights = opts.typeWeights ?? DEFAULT_TYPE_WEIGHTS;
+    // Atom v3 (ADR-001): invalidated memories (valid_to set) are excluded from
+    // the injected pack — a superseded/dead memory must not surface in recall.
+    const rows = db.prepare(`
+    SELECT id, type, text, importance, created_at
+    FROM memories
+    WHERE repo = ? AND valid_to IS NULL
+    ORDER BY created_at DESC
+    LIMIT ?
+  `).all(opts.repo, CANDIDATE_LIMIT);
+    const scored = rows.map(r => {
+        const ageDays = (now - r.created_at) / (24 * 60 * 60 * 1000);
+        const recency = Math.exp(-ageDays / RECENCY_HALF_LIFE_DAYS);
+        const typeWeight = weights[r.type] ?? 0.4;
+        return { id: r.id, type: r.type, text: r.text, score: typeWeight * recency * r.importance };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    const pack = [];
+    let spent = 0;
+    for (const m of scored) {
+        const cost = estimateTokens(m.text);
+        if (spent + cost > budget) {
+            // Guarantee at least the single best memory even under a tiny budget
+            if (pack.length === 0)
+                pack.push(m);
+            break;
+        }
+        pack.push(m);
+        spent += cost;
+    }
+    return pack;
+}
+const TYPE_HEADINGS = {
+    decision: 'Decisions',
+    lesson: 'Lessons',
+    fact: 'Facts',
+    command: 'Commands',
+    todo: 'Todos',
+    note: 'Notes',
+    event: 'Events',
+};
+/** Render the pack as compact Markdown grouped by type, memory ids inline. */
+export function renderPack(memories) {
+    if (memories.length === 0)
+        return '';
+    const byType = new Map();
+    for (const m of memories) {
+        const list = byType.get(m.type) ?? [];
+        list.push(m);
+        byType.set(m.type, list);
+    }
+    const sections = ['# Repo memory pack'];
+    for (const [type, list] of byType) {
+        sections.push(`\n## ${TYPE_HEADINGS[type] ?? type}`);
+        // Collapse internal newlines — a multi-line text would break the Markdown list item
+        for (const m of list)
+            sections.push(`- ${m.text.replace(/\s+/g, ' ')} \`(${m.id})\``);
+    }
+    return sections.join('\n');
+}
+//# sourceMappingURL=pack.js.map

package/dist/recall/pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.js","sourceRoot":"","sources":["../../src/recall/pack.ts"],"names":[],"mappings":"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"}

package/dist/recall/policy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Injection-policy v1 (Wave 4d, ADR-005/ADR-010) — the heuristic
+ * "when-to-recall" layer. This is deliberately a THIN layer above pack
+ * selection, not part of search: the store answers "what matches",
+ * the policy answers "should anything be injected at all, and how much".
+ *
+ * v1 heuristics (no ML — instrumented via usefulness events so it can
+ * become learned later):
+ *   1. Task-type gating — trivial/smalltalk or very short prompts get no
+ *      injection unless they explicitly reference memory ("remember",
+ *      "last time", "we decided", ...).
+ *   2. Confidence threshold — only memories whose selection score clears
+ *      `minScore` are injected; a pack of weak matches is worse than none.
+ *   3. Token-budget-aware top-k — the longer the prompt already is, the
+ *      smaller the injection budget ("long context kills retrieval").
+ *
+ * Every injected memory is recorded as a recall_served usefulness event
+ * (ADR-010) so served-but-never-used patterns can tune this layer.
+ */
+import type { DB } from '../storage/db.js';
+import type { Config } from '../config/config.js';
+import { type PackMemory } from './pack.js';
+export interface PolicyDecision {
+    inject: boolean;
+    /** Machine-readable reason — stable strings, used in tests + telemetry. */
+    reason: 'injected' | 'no-eligible-memories' | 'prompt-too-short' | 'smalltalk' | 'below-min-score' | 'policy-disabled';
+    memories: PackMemory[];
+    pack: string;
+    budget_tokens: number;
+}
+export interface PolicyInput {
+    repo: string;
+    prompt: string;
+    /** Requested budget; the policy may shrink it, never grow it. */
+    budgetTokens?: number;
+    now?: number;
+}
+export declare function shrinkBudgetForPrompt(baseBudget: number, promptChars: number): number;
+export declare function decideInjection(db: DB, config: Config, input: PolicyInput): PolicyDecision;

package/dist/recall/policy.js

@@ -0,0 +1,96 @@
+/**
+ * Injection-policy v1 (Wave 4d, ADR-005/ADR-010) — the heuristic
+ * "when-to-recall" layer. This is deliberately a THIN layer above pack
+ * selection, not part of search: the store answers "what matches",
+ * the policy answers "should anything be injected at all, and how much".
+ *
+ * v1 heuristics (no ML — instrumented via usefulness events so it can
+ * become learned later):
+ *   1. Task-type gating — trivial/smalltalk or very short prompts get no
+ *      injection unless they explicitly reference memory ("remember",
+ *      "last time", "we decided", ...).
+ *   2. Confidence threshold — only memories whose selection score clears
+ *      `minScore` are injected; a pack of weak matches is worse than none.
+ *   3. Token-budget-aware top-k — the longer the prompt already is, the
+ *      smaller the injection budget ("long context kills retrieval").
+ *
+ * Every injected memory is recorded as a recall_served usefulness event
+ * (ADR-010) so served-but-never-used patterns can tune this layer.
+ */
+import { selectPack, renderPack, DEFAULT_BUDGET_TOKENS } from './pack.js';
+import { recordRecallServed } from '../storage/usefulness.js';
+/** Prompts that explicitly ask for memory always get injection. */
+const MEMORY_REFERENCE_RE = /\b(remember|recall|last time|previously|we decided|as before|earlier session|what did (i|we))\b/i;
+/** Cheap smalltalk/greeting classifier — gate, don't inject. */
+const SMALLTALK_RE = /^\s*(hi|hey|hello|thanks?|thank you|ok(ay)?|yes|no|cool|nice|lol|good (morning|evening|night)|how are you)\s*[!.?]*\s*$/i;
+/** Prompt sizes at which the injection budget starts shrinking / bottoms out. */
+const PROMPT_SHRINK_START_CHARS = 4_000;
+const PROMPT_SHRINK_FLOOR_TOKENS = 300;
+export function shrinkBudgetForPrompt(baseBudget, promptChars) {
+    if (promptChars <= PROMPT_SHRINK_START_CHARS)
+        return baseBudget;
+    // Linear decay: every additional 4k chars halves the remaining headroom.
+    const over = promptChars - PROMPT_SHRINK_START_CHARS;
+    const factor = Math.max(0, 1 - over / 16_000);
+    return Math.max(PROMPT_SHRINK_FLOOR_TOKENS, Math.round(baseBudget * factor));
+}
+export function decideInjection(db, config, input) {
+    const policyCfg = config.recallPack.policy;
+    const baseBudget = input.budgetTokens ?? config.recallPack.budgetTokens ?? DEFAULT_BUDGET_TOKENS;
+    if (!policyCfg.enabled) {
+        // Policy off = legacy behavior: always inject whatever the pack selects.
+        const memories = selectPack(db, { repo: input.repo, budgetTokens: baseBudget, now: input.now });
+        record(db, input, memories);
+        return {
+            inject: memories.length > 0,
+            reason: memories.length > 0 ? 'injected' : 'no-eligible-memories',
+            memories,
+            pack: renderPack(memories),
+            budget_tokens: baseBudget,
+        };
+    }
+    const prompt = input.prompt ?? '';
+    const referencesMemory = MEMORY_REFERENCE_RE.test(prompt);
+    // 1. Task-type gating (memory references override every gate).
+    //    Smalltalk first — a greeting is smalltalk regardless of its length.
+    if (!referencesMemory) {
+        if (SMALLTALK_RE.test(prompt)) {
+            return skip('smalltalk', baseBudget);
+        }
+        if (prompt.trim().length < policyCfg.minPromptChars) {
+            return skip('prompt-too-short', baseBudget);
+        }
+    }
+    // 3. Token-budget-aware top-k.
+    const budget = shrinkBudgetForPrompt(baseBudget, prompt.length);
+    const candidates = selectPack(db, { repo: input.repo, budgetTokens: budget, now: input.now });
+    if (candidates.length === 0)
+        return skip('no-eligible-memories', budget);
+    // 2. Confidence threshold on the selection score.
+    const confident = candidates.filter(m => m.score >= policyCfg.minScore);
+    if (confident.length === 0)
+        return skip('below-min-score', budget);
+    record(db, input, confident);
+    return {
+        inject: true,
+        reason: 'injected',
+        memories: confident,
+        pack: renderPack(confident),
+        budget_tokens: budget,
+    };
+    function skip(reason, budgetTokens) {
+        return { inject: false, reason, memories: [], pack: '', budget_tokens: budgetTokens };
+    }
+}
+function record(db, input, memories) {
+    if (memories.length === 0)
+        return;
+    recordRecallServed(db, {
+        query: `pack:${input.repo}`,
+        atomIds: memories.map(m => m.id),
+        scores: memories.map(m => m.score),
+        surface: 'rest',
+        mode: 'pack-policy',
+    });
+}
+//# sourceMappingURL=policy.js.map

package/dist/recall/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/recall/policy.ts"],"names":[],"mappings":"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"}

package/dist/redact/detectors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pattern-based secret detectors (stage-0 redaction, SEC-3/5, spec §4.2).
+ *
+ * Each detector is a regex run with the `d` (hasIndices) flag so that, when
+ * `valueGroup` is set, we can redact JUST the captured secret value and keep
+ * the surrounding key name / scheme intact (e.g. `Password=` stays, only the
+ * value after it is replaced).
+ */
+export interface PatternDetector {
+    type: string;
+    /** Regex WITHOUT the 'g'/'d' flags — added automatically at match time. */
+    source: string;
+    flags: string;
+    /** Capture group index to redact instead of the whole match (1-based). */
+    valueGroup?: number;
+}
+export declare const PEM_DETECTOR: PatternDetector;
+export declare const PATTERN_DETECTORS: PatternDetector[];
+/** Build a `custom` detector from a user-supplied regex source string. */
+export declare function customDetector(source: string): PatternDetector;

package/dist/redact/detectors.js

@@ -0,0 +1,85 @@
+/**
+ * Pattern-based secret detectors (stage-0 redaction, SEC-3/5, spec §4.2).
+ *
+ * Each detector is a regex run with the `d` (hasIndices) flag so that, when
+ * `valueGroup` is set, we can redact JUST the captured secret value and keep
+ * the surrounding key name / scheme intact (e.g. `Password=` stays, only the
+ * value after it is replaced).
+ */
+// ---------------------------------------------------------------------------
+// PEM private-key blocks — run first, whole block redacted (spec §4.2).
+// ---------------------------------------------------------------------------
+export const PEM_DETECTOR = {
+    type: 'pem_private_key',
+    source: '-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----[\\s\\S]*?-----END (?:[A-Z0-9]+ )*PRIVATE KEY-----',
+    flags: 's',
+};
+// ---------------------------------------------------------------------------
+// Vendor-specific token/key patterns.
+// ---------------------------------------------------------------------------
+export const PATTERN_DETECTORS = [
+    {
+        type: 'aws_access_key',
+        source: '\\bAKIA[0-9A-Z]{16}\\b',
+        flags: '',
+    },
+    {
+        type: 'github_token',
+        source: '\\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,255}\\b|\\bgithub_pat_[A-Za-z0-9_]{20,255}\\b',
+        flags: '',
+    },
+    // Azure storage account key, labeled: `;AccountKey=<base64>`
+    {
+        type: 'azure_key',
+        source: '\\bAccountKey\\s*=\\s*(\\S+)',
+        flags: 'id',
+        valueGroup: 1,
+    },
+    // Azure SAS token query param: `...&sig=<urlencoded-base64>`
+    {
+        type: 'azure_key',
+        source: '[?&]sig=([A-Za-z0-9%+/=]{10,})',
+        flags: 'id',
+        valueGroup: 1,
+    },
+    // Bare Azure storage account key (88-char base64, no label).
+    {
+        type: 'azure_key',
+        source: '\\b[A-Za-z0-9+/]{86}==',
+        flags: '',
+    },
+    {
+        type: 'gcp_api_key',
+        source: '\\bAIza[0-9A-Za-z\\-_]{35}\\b',
+        flags: '',
+    },
+    {
+        type: 'slack_token',
+        source: '\\bxox[baprs]-[0-9A-Za-z-]{10,72}\\b',
+        flags: '',
+    },
+    // Generic `key = value` / `key: value` credential — redact value only.
+    {
+        type: 'generic_credential',
+        source: '\\b(?:api[_-]?key|secret|token|password|passwd|pwd)\\s*[:=]\\s*(\\S+)',
+        flags: 'id',
+        valueGroup: 1,
+    },
+    {
+        type: 'jwt',
+        source: '\\bey[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\.[A-Za-z0-9_-]{10,}\\b',
+        flags: '',
+    },
+    // Connection-string userinfo: scheme://user:pass@ — redact the "user:pass" span.
+    {
+        type: 'connection_string',
+        source: '\\b[a-zA-Z][a-zA-Z0-9+.-]*://([^/\\s:@]+:[^/\\s@]+)@',
+        flags: 'd',
+        valueGroup: 1,
+    },
+];
+/** Build a `custom` detector from a user-supplied regex source string. */
+export function customDetector(source) {
+    return { type: 'custom', source, flags: 'g' };
+}
+//# sourceMappingURL=detectors.js.map

package/dist/redact/detectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectors.js","sourceRoot":"","sources":["../../src/redact/detectors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,8EAA8E;AAC9E,wEAAwE;AACxE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAoB;IAC3C,IAAI,EAAE,iBAAiB;IACvB,MAAM,EAAE,8FAA8F;IACtG,KAAK,EAAE,GAAG;CACX,CAAC;AAEF,8EAA8E;AAC9E,sCAAsC;AACtC,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD;QACE,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,wBAAwB;QAChC,KAAK,EAAE,EAAE;KACV;IACD;QACE,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,yFAAyF;QACjG,KAAK,EAAE,EAAE;KACV;IACD,6DAA6D;IAC7D;QACE,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,8BAA8B;QACtC,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,CAAC;KACd;IACD,6DAA6D;IAC7D;QACE,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,gCAAgC;QACxC,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,CAAC;KACd;IACD,6DAA6D;IAC7D;QACE,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,wBAAwB;QAChC,KAAK,EAAE,EAAE;KACV;IACD;QACE,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,+BAA+B;QACvC,KAAK,EAAE,EAAE;KACV;IACD;QACE,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,sCAAsC;QAC9C,KAAK,EAAE,EAAE;KACV;IACD,uEAAuE;IACvE;QACE,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,uEAAuE;QAC/E,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,CAAC;KACd;IACD;QACE,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,sEAAsE;QAC9E,KAAK,EAAE,EAAE;KACV;IACD,iFAAiF;IACjF;QACE,IAAI,EAAE,mBAAmB;QACzB,MAAM,EAAE,sDAAsD;QAC9D,KAAK,EAAE,GAAG;QACV,UAAU,EAAE,CAAC;KACd;CACF,CAAC;AAEF,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAChD,CAAC"}

package/dist/redact/entropy.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shannon-entropy secret detector (stage-0 redaction, SEC-3/5).
+ *
+ * Runs LAST, over whatever text survives the pattern-detector pass — catches
+ * high-randomness tokens (raw keys, unlabeled secrets) that don't match a
+ * known vendor format. False-positive guards keep it from flagging git SHAs,
+ * UUIDs, and file paths (see redactText doc-comment for the full list).
+ */
+/** Shannon entropy in bits/char over the token's character distribution. */
+export declare function shannonEntropy(token: string): number;
+export interface EntropyToken {
+    value: string;
+    start: number;
+    end: number;
+}
+/** Split text into whitespace-delimited tokens with their [start,end) offsets. */
+export declare function tokenize(text: string): EntropyToken[];
+export interface EntropyMatch {
+    start: number;
+    end: number;
+    value: string;
+}
+/** Find entropy-based secret candidates in `text` above `threshold` bits/char. */
+export declare function findEntropySecrets(text: string, threshold: number): EntropyMatch[];

package/dist/redact/entropy.js

@@ -0,0 +1,77 @@
+/**
+ * Shannon-entropy secret detector (stage-0 redaction, SEC-3/5).
+ *
+ * Runs LAST, over whatever text survives the pattern-detector pass — catches
+ * high-randomness tokens (raw keys, unlabeled secrets) that don't match a
+ * known vendor format. False-positive guards keep it from flagging git SHAs,
+ * UUIDs, and file paths (see redactText doc-comment for the full list).
+ */
+const MIN_TOKEN_LENGTH = 20;
+const CONTEXT_WINDOW = 40;
+const HEX_DIGEST_CONTEXT_RE = /\b(commit|sha|hash|digest)\b/i;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PURE_HEX_RE = /^[0-9a-f]+$/i;
+const PLACEHOLDER_RE = /^\[REDACTED:[^\]]+\]$/;
+/** Shannon entropy in bits/char over the token's character distribution. */
+export function shannonEntropy(token) {
+    if (token.length === 0)
+        return 0;
+    const freq = new Map();
+    for (const ch of token) {
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    }
+    let entropy = 0;
+    for (const count of freq.values()) {
+        const p = count / token.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+/** Split text into whitespace-delimited tokens with their [start,end) offsets. */
+export function tokenize(text) {
+    const tokens = [];
+    const re = /\S+/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        tokens.push({ value: m[0], start: m.index, end: m.index + m[0].length });
+    }
+    return tokens;
+}
+/**
+ * True if `token` should be SKIPPED (i.e. is a known false-positive shape)
+ * rather than flagged as a high-entropy secret.
+ */
+function isGuarded(token, text, start, end) {
+    if (token.length < MIN_TOKEN_LENGTH)
+        return true;
+    if (PLACEHOLDER_RE.test(token))
+        return true;
+    if (UUID_RE.test(token))
+        return true;
+    if (token.includes('/') || token.includes('\\'))
+        return true;
+    // Pure-hex 40/64-char strings (git SHA-1 / SHA-256) adjacent to a
+    // commit/sha/hash/digest keyword within ~40 chars are assumed to be
+    // content hashes, not secrets.
+    if ((token.length === 40 || token.length === 64) && PURE_HEX_RE.test(token)) {
+        const windowStart = Math.max(0, start - CONTEXT_WINDOW);
+        const windowEnd = Math.min(text.length, end + CONTEXT_WINDOW);
+        if (HEX_DIGEST_CONTEXT_RE.test(text.slice(windowStart, windowEnd))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Find entropy-based secret candidates in `text` above `threshold` bits/char. */
+export function findEntropySecrets(text, threshold) {
+    const matches = [];
+    for (const tok of tokenize(text)) {
+        if (isGuarded(tok.value, text, tok.start, tok.end))
+            continue;
+        if (shannonEntropy(tok.value) >= threshold) {
+            matches.push({ start: tok.start, end: tok.end, value: tok.value });
+        }
+    }
+    return matches;
+}
+//# sourceMappingURL=entropy.js.map

package/dist/redact/entropy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entropy.js","sourceRoot":"","sources":["../../src/redact/entropy.ts"],"names":[],"mappings":"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"}

package/dist/redact/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Stage-0 secret redaction (spec docs/specs/2026-07-02-encryption-and-secret-redaction.md
+ * §4.2/§4.3, SEC-3..6/SEC-9).
+ *
+ * Single entry point: `redactText(input, opts)`. Invoked at the ingest choke
+ * point (POST /ingest/transcript, before the `transcripts` INSERT) and on the
+ * `/remember` manual-write path (spec OQ-2: yes). Downstream pipeline stages
+ * inherit already-redacted text — there is no second redaction pass.
+ *
+ * Placeholder format: `[REDACTED:<type>:<hash8>]` where hash8 = first 8 hex
+ * chars of SHA-256(secret value). Same secret -> same placeholder (dedup-safe
+ * across a transcript); the raw value is NEVER stored or logged (SEC-5).
+ *
+ * Detection order (never redact inside an already-inserted placeholder):
+ *   1. PEM private-key blocks (multiline, whole block)
+ *   2. Vendor/pattern detectors (AWS, GitHub, Azure, GCP, Slack, generic
+ *      key=value, JWT, connection-string userinfo) + config custom patterns
+ *   3. Shannon-entropy detector over whatever text remains
+ */
+import type { Config } from '../config/config.js';
+export interface RedactionEvent {
+    type: string;
+    hash8: string;
+    /** Offset of the redacted span within the text snapshot at detection time. */
+    offset: number;
+}
+export interface RedactOptions {
+    /** Shannon-entropy threshold in bits/char. Default 4.0. */
+    entropyThreshold?: number;
+    /** Additional regex sources (as strings) from config, type 'custom'. */
+    customPatterns?: string[];
+}
+export interface RedactResult {
+    text: string;
+    events: RedactionEvent[];
+}
+/**
+ * Redact secrets from `input`. Pure function — no I/O, no DB writes (callers
+ * aggregate `events` into `redaction_log` themselves).
+ */
+export declare function redactText(input: string, opts?: RedactOptions): RedactResult;
+/**
+ * Choke-point helper for route handlers: applies config (enabled flag,
+ * entropy threshold, custom patterns) and is a no-op passthrough when
+ * `security.redaction.enabled` is false (SEC-9).
+ */
+export declare function redactIfEnabled(input: string, config: Config): RedactResult;