@dsh-cc/context-crusher 0.7.1 → 0.8.0-rc.1

package/lib/receipt.js

@@ -0,0 +1,73 @@
+/**
+ * Receipt schema and canonical renderer for the evidence-preserving reducer.
+ * @module @dsh-cc/context-crusher/receipt
+ */
+import z from '@deepseek-ai/schemastery';
+/** schemastery has no `.optional()` method — union with `undefined` instead. */
+const opt = (t) => z.union([t, z.const(undefined)]);
+/** schemastery schema for the receipt shape (types only; see parseReceipt for key-set checks). */
+export const ReceiptSchema = z.object({
+    v: z.const(1),
+    cmd: z.string(),
+    exit: z.object({ ok: z.boolean(), code: opt(z.number().step(1)) }),
+    failures: z.array(z.object({ name: z.string(), evidence: z.string() })),
+    key_output: z.array(z.string()).max(8),
+    counts: opt(z.object({ pass: z.number(), fail: z.number(), skip: z.number() })),
+});
+/** Exact allowed key sets per object level (unknown keys are rejected, not stripped). */
+const ROOT_KEYS = ['v', 'cmd', 'exit', 'failures', 'key_output'];
+const ROOT_OPTIONAL_KEYS = ['counts'];
+const EXIT_KEYS = ['ok'];
+const EXIT_OPTIONAL_KEYS = ['code'];
+const FAILURE_KEYS = ['name', 'evidence'];
+const COUNTS_KEYS = ['pass', 'fail', 'skip'];
+/** Every present key must be in `allowed ∪ optional`; absent optional keys are fine. */
+function exactKeys(obj, allowed, optional = []) {
+    return Object.keys(obj).every((k) => allowed.includes(k) || optional.includes(k));
+}
+/**
+ * Parse and validate a raw receipt. Returns the receipt, or `null` when any
+ * check fails: schema types, the 8-entry `key_output` cap, or the explicit
+ * exact-key-set check at every object level (schemastery `z.object` keeps
+ * unknown keys rather than stripping them, so rejection is explicit here).
+ */
+export function parseReceipt(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (!exactKeys(r, ROOT_KEYS, ROOT_OPTIONAL_KEYS))
+        return null;
+    try {
+        ReceiptSchema(r);
+    }
+    catch {
+        return null;
+    }
+    const receipt = r;
+    if (!exactKeys(receipt.exit, EXIT_KEYS, EXIT_OPTIONAL_KEYS))
+        return null;
+    for (const f of receipt.failures) {
+        if (!exactKeys(f, FAILURE_KEYS))
+            return null;
+    }
+    if (receipt.counts !== undefined && !exactKeys(receipt.counts, COUNTS_KEYS))
+        return null;
+    return receipt;
+}
+/**
+ * Canonical few-line rendering (plan §3.5): deterministic, receipt body only.
+ * The caller appends the pinned `buildMarker(...)` line — never included here.
+ */
+export function renderReceipt(r) {
+    const lines = [`cmd: ${r.cmd}`];
+    const code = r.exit.code === undefined ? '' : ` code ${r.exit.code}`;
+    lines.push(`exit: ${r.exit.ok ? 'ok' : 'failed'}${code}`);
+    for (const f of r.failures)
+        lines.push(`FAIL ${f.name}: ${f.evidence}`);
+    for (const q of r.key_output)
+        lines.push(`key: ${q}`);
+    if (r.counts)
+        lines.push(`counts: pass=${r.counts.pass} fail=${r.counts.fail} skip=${r.counts.skip}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=receipt.js.map

package/lib/receipt.js.map

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

package/lib/reducer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Evidence-preserving reducer (plan §3.1-§3.3, §3.7): the escalation stage
+ * between the deterministic route and the passthrough decision. One cheap-lane
+ * side query extracts a receipt from the (possibly truncated) tool output
+ * view; a deterministic verifier (verifier.ts) gates the replacement; ANY
+ * failure — eligibility, lane provenance, timeout, malformed JSON, failed
+ * verification — returns `undefined` so the caller passes the ORIGINAL bytes
+ * through untouched (never the deterministic route's sub-threshold candidate).
+ *
+ * Fail-soft is the hard invariant: this stage never throws (the caller's
+ * waterfall try/catch is the backstop, and the stage also guards internally).
+ *
+ * @module @dsh-cc/context-crusher/reducer
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolExecution } from '@dsh-cc/tools';
+import type { CrusherMode, LedgerRow, ResolvedConfig } from './types.ts';
+/** Tools whose invocation command line is reducer-eligible (§3.2). */
+export declare const REDUCER_COMMAND_TOOLS: readonly string[];
+/** Executed command line of a tool invocation, when it is a string (§3.2). */
+export declare function invocationCommand(exec: ToolExecution): string | undefined;
+/** §3.2 eligibility: command surface, configured patterns, flag. */
+export declare function isReducerEligible(cfg: ResolvedConfig, exec: ToolExecution): boolean;
+/**
+ * Head/tail truncation for oversized sources (§3.3): the view budget is the
+ * `reducerMaxInputTokens` cap, split ~20% head / ~80% tail of lines (build
+ * and test failures concentrate at the tail).
+ */
+export declare function truncateView(text: string, maxTokens: number, estimate: (text: string) => number): string;
+export interface ReducerStageDeps {
+    ctx: Context;
+    cfg: ResolvedConfig;
+    exec: ToolExecution;
+    originalText: string;
+    tokensBefore: number;
+    isError: boolean;
+    estimate: (text: string) => number;
+    projectKey: string | undefined;
+    mode: CrusherMode;
+    /** Store write for the full original text (only called in `on` mode). */
+    put: (projectKey: string, text: string) => Promise<string>;
+    ledgerRow: (row: Omit<LedgerRow, 'ts' | 'sessionId' | 'tool'>) => Promise<void>;
+}
+/**
+ * Run one reducer attempt. Returns the replacement text
+ * (`renderReceipt` + the verbatim pinned `buildMarker` line as the LAST
+ * line), or `undefined` = passthrough the original bytes. Every rejection is
+ * ledgered `applied:false` with a reason (§3.4, §3.7); the deterministic
+ * route's sub-threshold candidate is never mixed in.
+ */
+export declare function reduceToolOutput(deps: ReducerStageDeps): Promise<string | undefined>;
+//# sourceMappingURL=reducer.d.ts.map

package/lib/reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducer.d.ts","sourceRoot":"","sources":["../src/reducer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAMlD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAExE,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAa,CAAA;AAoBhE,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAIzE;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAMnF;AAED;;;;GAIG;AAGH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CASxG;AAYD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,OAAO,CAAA;IACZ,GAAG,EAAE,cAAc,CAAA;IACnB,IAAI,EAAE,aAAa,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,IAAI,EAAE,WAAW,CAAA;IACjB,yEAAyE;IACzE,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1D,SAAS,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,WAAW,GAAG,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAChF;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAsH1F"}

package/lib/reducer.js

@@ -0,0 +1,202 @@
+/**
+ * Evidence-preserving reducer (plan §3.1-§3.3, §3.7): the escalation stage
+ * between the deterministic route and the passthrough decision. One cheap-lane
+ * side query extracts a receipt from the (possibly truncated) tool output
+ * view; a deterministic verifier (verifier.ts) gates the replacement; ANY
+ * failure — eligibility, lane provenance, timeout, malformed JSON, failed
+ * verification — returns `undefined` so the caller passes the ORIGINAL bytes
+ * through untouched (never the deterministic route's sub-threshold candidate).
+ *
+ * Fail-soft is the hard invariant: this stage never throws (the caller's
+ * waterfall try/catch is the backstop, and the stage also guards internally).
+ *
+ * @module @dsh-cc/context-crusher/reducer
+ */
+import { resolveAlias } from '@dsh-cc/model-aliases';
+import { runSideQuery } from '@dsh-cc/side-query';
+import { buildMarker } from "./marker.js";
+import { parseReceipt, renderReceipt } from "./receipt.js";
+import { verifyReceipt } from "./verifier.js";
+/** Tools whose invocation command line is reducer-eligible (§3.2). */
+export const REDUCER_COMMAND_TOOLS = ['bash'];
+/**
+ * System prompt for the extraction side query (§3.3, §3.7): pure extraction,
+ * no inference, no advice, strict JSON only. The prompt NEVER embeds the
+ * user's task or conversation history — only the single tool output view.
+ */
+const REDUCER_SYSTEM = [
+    'You extract evidence from tool output. Pure extraction only: never infer,',
+    'never diagnose, never advise. Every "evidence" and "key_output" string MUST',
+    'be copied verbatim from the tool output (no paraphrase, no trimming).',
+    'Output ONLY strict JSON — no prose, no code fences — matching exactly:',
+    '{"v":1,"cmd":"first line of the invocation","exit":{"ok":boolean,',
+    '"code":number only when the output states an exit code},"failures":',
+    '[{"name":"test/file identifier","evidence":"exact quote from the output"}],',
+    '"key_output":["exact quote", up to 8 entries],"counts":',
+    '{"pass":number,"fail":number,"skip":number} only when the counts are stated}.',
+    '"failures" is empty on success; omit "counts" when unknowable.',
+].join('\n');
+/** Executed command line of a tool invocation, when it is a string (§3.2). */
+export function invocationCommand(exec) {
+    const args = exec.arguments;
+    const command = args === null || typeof args !== 'object' ? undefined : args.command;
+    return typeof command === 'string' && command.length > 0 ? command : undefined;
+}
+/** §3.2 eligibility: command surface, configured patterns, flag. */
+export function isReducerEligible(cfg, exec) {
+    if (!cfg.reducerEnabled)
+        return false;
+    if (!REDUCER_COMMAND_TOOLS.includes(exec.name))
+        return false;
+    const command = invocationCommand(exec);
+    if (command === undefined)
+        return false;
+    return cfg.reducerCommands.some((pattern) => pattern.test(command));
+}
+/**
+ * Head/tail truncation for oversized sources (§3.3): the view budget is the
+ * `reducerMaxInputTokens` cap, split ~20% head / ~80% tail of lines (build
+ * and test failures concentrate at the tail).
+ */
+// ponytail: per-line token cost is a linear average, not per-line estimates;
+// if real logs skew the split, switch to incremental estimation.
+export function truncateView(text, maxTokens, estimate) {
+    if (estimate(text) <= maxTokens)
+        return text;
+    const lines = text.split('\n');
+    if (lines.length < 2)
+        return text;
+    const tokensPerLine = Math.max(estimate(text) / lines.length, 0.01);
+    const headCount = Math.max(1, Math.floor((0.2 * maxTokens) / tokensPerLine));
+    const tailCount = Math.max(1, Math.floor((0.8 * maxTokens) / tokensPerLine));
+    if (headCount + tailCount >= lines.length)
+        return text;
+    return [...lines.slice(0, headCount), ...lines.slice(lines.length - tailCount)].join('\n');
+}
+/** Side-query failure reason → ledger reason (§3.7 fail-mode: passthrough). */
+function laneReason(reason) {
+    switch (reason) {
+        case 'unrouted': return 'lane-missing';
+        case 'timeout': return 'lane-timeout';
+        case 'empty': return 'malformed';
+        case 'error': return 'lane-error';
+    }
+}
+/**
+ * Run one reducer attempt. Returns the replacement text
+ * (`renderReceipt` + the verbatim pinned `buildMarker` line as the LAST
+ * line), or `undefined` = passthrough the original bytes. Every rejection is
+ * ledgered `applied:false` with a reason (§3.4, §3.7); the deterministic
+ * route's sub-threshold candidate is never mixed in.
+ */
+export async function reduceToolOutput(deps) {
+    try {
+        if (!isReducerEligible(deps.cfg, deps.exec))
+            return undefined;
+        const { originalText, tokensBefore } = deps;
+        const ledger = async (applied, tokensAfter, reason, hash, charsAfter) => {
+            await deps.ledgerRow({
+                kind: 'receipt',
+                charsBefore: originalText.length,
+                charsAfter: charsAfter ?? receiptBodyRef.length,
+                tokensBefore,
+                tokensAfter,
+                applied,
+                ...(reason === undefined ? {} : { reason }),
+                ...(hash === undefined ? {} : { hash }),
+            });
+        };
+        // The extraction view: the full text under the input cap, else head/tail.
+        // Verifier quotes are checked against this SAME view (§3.3).
+        const view = truncateView(originalText, deps.cfg.reducerMaxInputTokens, deps.estimate);
+        let receiptBodyRef = '';
+        // Lane provenance pre-check: resolve the reducer alias ourselves so the
+        // string-form (model-only) alias hole — `toOneShotRoute` fills the
+        // provider from the parent request — never bills the parent route (§3.3).
+        const agent = deps.exec.agent;
+        if (agent === undefined) {
+            await ledger(false, 0, 'lane-missing');
+            return undefined;
+        }
+        const route = resolveAlias(deps.ctx, deps.cfg.reducerAlias);
+        if (route === undefined) {
+            // Unconfigured alias: the side query would return 'unrouted' anyway;
+            // decline here so no model call is attempted at all (§4 test b).
+            await ledger(false, 0, 'lane-missing');
+            return undefined;
+        }
+        if (route.provider === undefined || route.provider.length === 0) {
+            await ledger(false, 0, 'lane-inherited');
+            return undefined;
+        }
+        const side = await runSideQuery(deps.ctx, {
+            agent,
+            alias: deps.cfg.reducerAlias,
+            onUnrouted: 'skip', // mandatory: an unrouted alias never bills the parent route
+            rejectToolCalls: true, // llm.stream-class: no tools, no seeds (§3.7)
+            system: REDUCER_SYSTEM,
+            prompt: [
+                'Reduce the following tool output into the receipt JSON described in the system prompt.',
+                'The output is the complete and only source; quote from it verbatim.',
+                '--- tool output start ---',
+                view,
+                '--- tool output end ---',
+            ].join('\n'),
+            maxTokens: deps.cfg.reducerMaxTokens,
+            timeoutMs: deps.cfg.reducerTimeoutMs,
+        });
+        if (!side.ok) {
+            await ledger(false, 0, laneReason(side.reason));
+            return undefined;
+        }
+        // Defense in depth for the inherited-route hole: side-query provenance.
+        if (side.inheritedRoute) {
+            await ledger(false, 0, 'lane-inherited');
+            return undefined;
+        }
+        let raw;
+        try {
+            raw = JSON.parse(side.text);
+        }
+        catch {
+            await ledger(false, 0, 'malformed');
+            return undefined;
+        }
+        const receipt = parseReceipt(raw);
+        if (receipt === null) {
+            await ledger(false, 0, 'malformed');
+            return undefined;
+        }
+        receiptBodyRef = renderReceipt(receipt);
+        // Verify against the SAME view used for extraction (§3.4).
+        const verdict = verifyReceipt(view, receipt, deps.isError, deps.estimate, {
+            minSavingsRatio: deps.cfg.reducerMinSavingsRatio,
+        });
+        if (!verdict.ok) {
+            const tokensAfter = deps.estimate(receiptBodyRef);
+            await ledger(false, tokensAfter, `verify:${verdict.reason}`, undefined, receiptBodyRef.length);
+            return undefined;
+        }
+        const tokensAfter = deps.estimate(receiptBodyRef);
+        if (deps.mode !== 'on') {
+            // Dry-run (§3.6): produce + verify only — no store.put, no substitution.
+            await ledger(false, tokensAfter, undefined, undefined, receiptBodyRef.length);
+            return undefined;
+        }
+        if (deps.projectKey === undefined)
+            return undefined;
+        // The FULL original text goes to the store, never the truncated view.
+        const hash = await deps.put(deps.projectKey, originalText);
+        // The LAST line is the verbatim pinned marker contract (§3.5): TUS
+        // isCrusherStub and the microcompact guard recognize it unchanged.
+        const replacementText = `${receiptBodyRef}\n${buildMarker(tokensBefore, tokensAfter, hash)}`;
+        await ledger(true, tokensAfter, undefined, hash, replacementText.length);
+        return replacementText;
+    }
+    catch (error) {
+        // Fail-soft (§3.7): any internal throw degrades to unchanged passthrough.
+        deps.ctx.logger.warn(`context-crusher: reducer stage degraded to passthrough: ${String(error)}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=reducer.js.map

package/lib/reducer.js.map

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

package/lib/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAoB,MAAM,2BAA2B,CAAA;AAEpF,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE/D,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,EAA+B,iBAAiB,CAAA;AAE/E,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,MAAM,aAAa,GAAG,SAAS,CAAA;AAE5D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,cAAc,CAWnF"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAGlE,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE/D,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,EAA+B,iBAAiB,CAAA;AAE/E,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,MAAM,aAAa,GAAG,SAAS,CAAA;AAE5D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,cAAc,CAanF"}

package/lib/settings.js

@@ -4,6 +4,7 @@
  * scope is re-read on EVERY use so a settings write applies immediately.
  * @module @dsh-cc/context-crusher/settings
  */
+import { registerNamespaceSafe } from '@dsh-cc/settings-ns';
 import { Config, SettingsSchema } from "./config.js";
 /** The settings namespace carrying the live crusher overlay. */
 export const SETTINGS_NAMESPACE = 'cc-context-compression';
@@ -16,8 +17,7 @@ export const SETTINGS_NAMESPACE = 'cc-context-compression';
  * @returns the live scope reader.
  */
 export function registerSettings(ctx, base) {
-    const settings = ctx.get('settings');
-    const scope = settings?.register(SETTINGS_NAMESPACE, SettingsSchema, {
+    const read = registerNamespaceSafe(ctx, SETTINGS_NAMESPACE, SettingsSchema, {
         validate: (value) => {
             // Re-run the same cross-field validation as the config layer so a
             // half-written scope is rejected at write time.
@@ -25,6 +25,9 @@ export function registerSettings(ctx, base) {
             Config(merged);
         },
     });
-    return () => scope?.get?.();
+    return () => {
+        const value = read();
+        return value === undefined ? undefined : { ...base, ...value };
+    };
 }
 //# sourceMappingURL=settings.js.map

package/lib/settings.js.map

@@ -1 +1 @@
-{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGpD,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAA6C,CAAA;AAK/E;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY,EAAE,IAAoB;IACjE,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,CAAiC,CAAA;IACpE,MAAM,KAAK,GAAG,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,EAAE,cAAc,EAAE;QACnE,QAAQ,EAAE,CAAC,KAAoB,EAAE,EAAE;YACjC,kEAAkE;YAClE,gDAAgD;YAChD,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAmB,CAAA;YACrD,MAAM,CAAC,MAAM,CAAC,CAAA;QAChB,CAAC;KACF,CAAC,CAAA;IACF,OAAO,GAAG,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAA+B,CAAA;AAC1D,CAAC"}
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGpD,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAA6C,CAAA;AAK/E;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY,EAAE,IAAoB;IACjE,MAAM,IAAI,GAAG,qBAAqB,CAAgB,GAAG,EAAE,kBAAkB,EAAE,cAAc,EAAE;QACzF,QAAQ,EAAE,CAAC,KAAoB,EAAE,EAAE;YACjC,kEAAkE;YAClE,gDAAgD;YAChD,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAmB,CAAA;YACrD,MAAM,CAAC,MAAM,CAAC,CAAA;QAChB,CAAC;KACF,CAAC,CAAA;IACF,OAAO,GAAG,EAAE;QACV,MAAM,KAAK,GAAG,IAAI,EAAE,CAAA;QACpB,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,CAAA;IAChE,CAAC,CAAA;AACH,CAAC"}

package/lib/types.d.ts

@@ -28,6 +28,39 @@ export interface CrusherConfig {
      * explicitly set list replaces the defaults entirely (not a union).
      */
     'protected-tools'?: string[];
+    /** Evidence-preserving reducer master flag (§3.2). Defaults to `false`. */
+    'reducer-enabled'?: boolean;
+    /** Regex sources matched against the invocation command line (§3.2). */
+    'reducer-commands'?: string[];
+    /** Head/tail truncation threshold in tokens (§3.3). Defaults to 30000. */
+    'reducer-max-input-tokens'?: number;
+    /** Verifier size-gain ratio (§3.4.4). Defaults to 0.5. */
+    'reducer-min-savings-ratio'?: number;
+    /** Side-query output token cap (§3.3). Defaults to 1024. */
+    'reducer-max-tokens'?: number;
+    /** Side-query wall-clock budget in ms (§3.3). Defaults to 10000. */
+    'reducer-timeout-ms'?: number;
+    /** Cheap-lane alias for the side query (§3.3). Defaults to 'haiku'. */
+    'reducer-alias'?: string;
+    /**
+     * Deferred externalization residency (design §3.6): eligible results are
+     * stored immediately but enter the session UNMODIFIED, and are swapped to
+     * the standard stub after this many counted main-loop sends
+     * (`2` = paper parity). `0` (default) disables deferral — behavior is
+     * byte-identical to immediate mode.
+     */
+    'defer-requests'?: number;
+    /** Suffix-cost gate multiplier for the deferred swap. Defaults to `1.5`. */
+    'defer-margin'?: number;
+    /** Sweep age (ms) for residents that never swapped. Defaults to `1_800_000`. */
+    'defer-max-age-ms'?: number;
+    /**
+     * Window-pressure override distance in tokens: when the session estimate
+     * comes within this distance of the model window, residents swap
+     * regardless of the gate. Unset = inactive (also inactive without a
+     * window source).
+     */
+    'defer-urgency-tokens'?: number;
 }
 /** Validated, detached, deeply immutable configuration. */
 export interface ResolvedConfig {
@@ -36,6 +69,18 @@ export interface ResolvedConfig {
     readonly minBytes: number;
     readonly minSavingsRatio: number;
     readonly protectedTools: readonly string[];
+    /** Compiled command patterns (§3.2); invalid user regexes are dropped at resolve time. */
+    readonly reducerEnabled: boolean;
+    readonly reducerCommands: readonly RegExp[];
+    readonly reducerMaxInputTokens: number;
+    readonly reducerMinSavingsRatio: number;
+    readonly reducerMaxTokens: number;
+    readonly reducerTimeoutMs: number;
+    readonly reducerAlias: string;
+    readonly deferRequests: number;
+    readonly deferMargin: number;
+    readonly deferMaxAgeMs: number;
+    readonly deferUrgencyTokens?: number;
 }
 /** One append-only savings-ledger row (`savings.jsonl`). */
 export interface LedgerRow {
@@ -43,7 +88,13 @@ export interface LedgerRow {
     readonly sessionId: string;
     readonly tool: string;
     /** Router kind that fired, or the reason a gate passed through. */
-    readonly kind: 'search' | 'log';
+    readonly kind: 'search' | 'log' | 'receipt';
+    /**
+     * Reducer-only detail: why the attempt did not apply (§3.4) —
+     * `lane-missing`, `lane-inherited`, `lane-timeout`, `lane-error`,
+     * `malformed`, or `verify:<check>`. Absent on plain router rows.
+     */
+    readonly reason?: string;
     readonly charsBefore: number;
     readonly charsAfter: number;
     readonly tokensBefore: number;

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,IAAI,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,wEAAwE;IACxE,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,SAAS,GAAG,SAAS,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/lib/verifier.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic receipt verifier for the evidence-preserving reducer.
+ * @module @dsh-cc/context-crusher/verifier
+ */
+/** Rejection reasons are ledgered as `verify:<reason>`. */
+export type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Pure verifier (plan §3.4) — no I/O, no service imports. `estimate` is
+ * injected (the call site binds the tokenMeter estimator; Phase 0 tests use a
+ * deterministic stub). Checks run in order, first failure wins:
+ *
+ * 1. `schema` — parse + explicit unknown-key rejection;
+ * 2. `quote` — every evidence/key_output string (≥ 8 chars, NFC-normalized)
+ *    is a verbatim substring of the view;
+ * 3. `exit` — `exit.ok === !isError`, and an `exit.code` is present only when
+ *    the view's tail (last 64 lines) verifiably carries that exact code;
+ * 4. `size` — `estimate(rendered)` < `minSavingsRatio` (default 0.5) ×
+ *    `estimate(view)`;
+ * 5. `counts` — when `counts` present, `fail` must equal `failures.length`.
+ */
+export declare function verifyReceipt(view: string, receipt: unknown, isError: boolean, estimate: (text: string) => number, opts?: {
+    minSavingsRatio?: number;
+}): VerifyResult;
+//# sourceMappingURL=verifier.d.ts.map

package/lib/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAWvE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAClC,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC,YAAY,CA4Bd"}

package/lib/verifier.js

@@ -0,0 +1,57 @@
+/**
+ * Deterministic receipt verifier for the evidence-preserving reducer.
+ * @module @dsh-cc/context-crusher/verifier
+ */
+import { parseReceipt, renderReceipt } from "./receipt.js";
+/** Exit-code patterns the view's tail may carry (plan §3.4.3b, conservative set). */
+const EXIT_CODE_PATTERNS = [/exit(?:ed with)? code (\d+)/i, /make.*Error (\d+)/];
+/** Number of trailing lines considered for exit-code verification. */
+const TAIL_LINES = 64;
+/** Minimum quote length for evidence / key_output entries (stops vacuous matches). */
+const MIN_QUOTE_LENGTH = 8;
+/**
+ * Pure verifier (plan §3.4) — no I/O, no service imports. `estimate` is
+ * injected (the call site binds the tokenMeter estimator; Phase 0 tests use a
+ * deterministic stub). Checks run in order, first failure wins:
+ *
+ * 1. `schema` — parse + explicit unknown-key rejection;
+ * 2. `quote` — every evidence/key_output string (≥ 8 chars, NFC-normalized)
+ *    is a verbatim substring of the view;
+ * 3. `exit` — `exit.ok === !isError`, and an `exit.code` is present only when
+ *    the view's tail (last 64 lines) verifiably carries that exact code;
+ * 4. `size` — `estimate(rendered)` < `minSavingsRatio` (default 0.5) ×
+ *    `estimate(view)`;
+ * 5. `counts` — when `counts` present, `fail` must equal `failures.length`.
+ */
+export function verifyReceipt(view, receipt, isError, estimate, opts) {
+    // 1. schema (types + exact key sets at every object level).
+    const r = parseReceipt(receipt);
+    if (r === null)
+        return { ok: false, reason: 'schema' };
+    // 2. exact quotes, NFC-normalized on both sides.
+    const normView = view.normalize('NFC');
+    for (const q of [...r.failures.map((f) => f.evidence), ...r.key_output]) {
+        if (q.length < MIN_QUOTE_LENGTH)
+            return { ok: false, reason: 'quote' };
+        if (!normView.includes(q.normalize('NFC')))
+            return { ok: false, reason: 'quote' };
+    }
+    // 3. exit consistency: exactly two decidable rules.
+    if (r.exit.ok !== !isError)
+        return { ok: false, reason: 'exit' };
+    if (r.exit.code !== undefined) {
+        const tail = normView.split('\n').slice(-TAIL_LINES).join('\n');
+        const match = EXIT_CODE_PATTERNS.map((p) => p.exec(tail)).find((m) => m !== null);
+        if (match === undefined || Number(match[1]) !== r.exit.code)
+            return { ok: false, reason: 'exit' };
+    }
+    // 4. size gain against the view (the same text the quotes verified against).
+    const ratio = opts?.minSavingsRatio ?? 0.5;
+    if (estimate(renderReceipt(r)) >= ratio * estimate(view))
+        return { ok: false, reason: 'size' };
+    // 5. count consistency.
+    if (r.counts && r.counts.fail !== r.failures.length)
+        return { ok: false, reason: 'counts' };
+    return { ok: true };
+}
+//# sourceMappingURL=verifier.js.map

package/lib/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAM1D,qFAAqF;AACrF,MAAM,kBAAkB,GAAG,CAAC,8BAA8B,EAAE,mBAAmB,CAAC,CAAA;AAEhF,sEAAsE;AACtE,MAAM,UAAU,GAAG,EAAE,CAAA;AAErB,sFAAsF;AACtF,MAAM,gBAAgB,GAAG,CAAC,CAAA;AAE1B;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,OAAgB,EAChB,OAAgB,EAChB,QAAkC,EAClC,IAAmC;IAEnC,4DAA4D;IAC5D,MAAM,CAAC,GAAmB,YAAY,CAAC,OAAO,CAAC,CAAA;IAC/C,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;IAEtD,iDAAiD;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;QACxE,IAAI,CAAC,CAAC,MAAM,GAAG,gBAAgB;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;QACtE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IACnF,CAAC;IAED,oDAAoD;IACpD,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,OAAO;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA;IAChE,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC/D,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAA;QACjF,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA;IACnG,CAAC;IAED,6EAA6E;IAC7E,MAAM,KAAK,GAAG,IAAI,EAAE,eAAe,IAAI,GAAG,CAAA;IAC1C,IAAI,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA;IAE9F,wBAAwB;IACxB,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;IAE3F,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;AACrB,CAAC"}