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

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm check:readme --write
-README.md: 1a5f04928fd09d495217a4792b36ec6cf672f20d
-README.zh.md: 7b77e3b5e7d77cc841805df0842a7b86ed97a8e8
+README.md: d0ce4a85fa2ce5c6942cb4b14b7983ad19f88391
+README.zh.md: edeca1f5c2009bdad6cef61b4b98baad4d2bbe58

package/README.md

@@ -32,6 +32,10 @@ Namespace `cc-context-compression` (settings overlay re-read on every use; confi
 | `min-savings-ratio` | `0.4` | Minimum token saving fraction. |
 | `protected-tools` | over-inclusive default list | Tools never crushed. |
 
+## foldCounters convention
+
+This package exports `foldCounters(materials)` for `@dsh-cc/token-efficiency`; any change to the marker/ledger shape MUST update the fold and its tests in the same PR.
+
 ## Caveats
 
 - The transcript keeps the COMPRESSED form forever: TUI replay and `command-export` show the compressed blob (the original lives only in the store + ledger).

package/README.zh.md

@@ -32,6 +32,10 @@ CCR（Compress-Cache-Retrieve）可逆的工具输出压缩。一个 `tools/post
 | `min-savings-ratio` | `0.4` | 最小 token 节省比例。 |
 | `protected-tools` | 过宽的默认列表 | 永不压缩的工具。 |
 
+## foldCounters 约定
+
+本包为 `@dsh-cc/token-efficiency` 导出 `foldCounters(materials)`；标记/台账形态的任何变更必须在同一个 PR 中同步更新该 fold 及其测试。
+
 ## 注意事项
 
 - 转录中永久保留的是压缩后的形态：TUI 回放与 `command-export` 展示压缩块（原文只在存储与台账中）。

package/lib/config.d.ts

@@ -10,6 +10,12 @@ import type { CrusherConfig, ResolvedConfig } from './types.ts';
  * until ledger data proves a narrower list is safe).
  */
 export declare const DEFAULT_PROTECTED_TOOLS: readonly string[];
+/**
+ * Default reducer command patterns (plan §3.2): regex sources matched
+ * against the bash invocation command line. `make\b` also matches `cmake` —
+ * accepted as an eligibility-only over-trigger.
+ */
+export declare const DEFAULT_REDUCER_COMMANDS: readonly string[];
 export declare const DEFAULTS: ResolvedConfig;
 /** Row-level deployment-default schema (cordis `static Config`). */
 export declare const Config: z<CrusherConfig>;
@@ -20,7 +26,9 @@ export declare const SettingsSchema: z<CrusherConfig>;
  * @param config - raw row config.
  * @returns a detached deeply immutable configuration.
  */
-export declare function resolveConfig(config?: CrusherConfig): ResolvedConfig;
+export declare function resolveConfig(config?: CrusherConfig, options?: {
+    log?: (message: string) => void;
+}): ResolvedConfig;
 /**
  * Overlay the live settings scope onto the config defaults. `protected-tools`
  * uses REPLACE semantics: an explicitly set settings list replaces the

package/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,KAAK,EAAE,aAAa,EAAe,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAIpD,CAAA;AAED,eAAO,MAAM,QAAQ,EAAE,cAMrB,CAAA;AAIF,oEAAoE;AACpE,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,aAAa,CAMlC,CAAA;AAEF,kEAAkE;AAClE,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAU,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,aAAkB,GAAG,cAAc,CAkBxE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,cAAc,CAStG"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,KAAK,EAAE,aAAa,EAAe,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAIpD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAMrD,CAAA;AAED,eAAO,MAAM,QAAQ,EAAE,cAgBrB,CAAA;AAIF,oEAAoE;AACpE,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,aAAa,CAiBlC,CAAA;AAEF,kEAAkE;AAClE,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAAU,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,aAAkB,EAAE,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAAG,cAAc,CAyEvH;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,cAAc,CAgCtG"}

package/lib/config.js

@@ -14,12 +14,34 @@ export const DEFAULT_PROTECTED_TOOLS = [
     'enter_worktree', 'exit_worktree', 'subagent_fork', 'send_message',
     'task', 'interrupt_agent',
 ];
+/**
+ * Default reducer command patterns (plan §3.2): regex sources matched
+ * against the bash invocation command line. `make\b` also matches `cmake` —
+ * accepted as an eligibility-only over-trigger.
+ */
+export const DEFAULT_REDUCER_COMMANDS = [
+    'pnpm .* (build|test|vitest|tsc|lint)',
+    'npm (run )?(build|test)',
+    'yarn (build|test)',
+    'npx (vitest|jest|tsc|eslint)',
+    'vitest|jest|mocha|pytest|go test|cargo test|make\\b',
+];
 export const DEFAULTS = deepFreeze({
     enabled: false,
     mode: 'dry-run',
     minBytes: 8192,
     minSavingsRatio: 0.4,
     protectedTools: DEFAULT_PROTECTED_TOOLS,
+    reducerEnabled: false,
+    reducerCommands: DEFAULT_REDUCER_COMMANDS.map((source) => new RegExp(source)),
+    reducerMaxInputTokens: 30_000,
+    reducerMinSavingsRatio: 0.5,
+    reducerMaxTokens: 1024,
+    reducerTimeoutMs: 10_000,
+    reducerAlias: 'haiku',
+    deferRequests: 0,
+    deferMargin: 1.5,
+    deferMaxAgeMs: 1_800_000,
 });
 const MODES = ['dry-run', 'on'];
 /** Row-level deployment-default schema (cordis `static Config`). */
@@ -29,6 +51,17 @@ export const Config = z.object({
     'min-bytes': z.number().step(1).min(1),
     'min-savings-ratio': z.number().min(0).max(1),
     'protected-tools': z.array(z.string()),
+    'reducer-enabled': z.boolean(),
+    'reducer-commands': z.array(z.string()),
+    'reducer-max-input-tokens': z.number().step(1).min(1),
+    'reducer-min-savings-ratio': z.number().min(0).max(1),
+    'reducer-max-tokens': z.number().step(1).min(1),
+    'reducer-timeout-ms': z.number().step(1).min(1),
+    'reducer-alias': z.string(),
+    'defer-requests': z.number().step(1).min(0),
+    'defer-margin': z.number().min(0),
+    'defer-max-age-ms': z.number().step(1).min(1),
+    'defer-urgency-tokens': z.number().step(1).min(1),
 });
 /** Settings namespace schema (same shape as the config layer). */
 export const SettingsSchema = Config;
@@ -37,7 +70,7 @@ export const SettingsSchema = Config;
  * @param config - raw row config.
  * @returns a detached deeply immutable configuration.
  */
-export function resolveConfig(config = {}) {
+export function resolveConfig(config = {}, options) {
     if (config.mode !== undefined && !MODES.includes(config.mode)) {
         throw new Error(`context-crusher: mode must be one of ${MODES.join(', ')}`);
     }
@@ -48,12 +81,68 @@ export function resolveConfig(config = {}) {
         && (!Number.isFinite(config['min-savings-ratio']) || config['min-savings-ratio'] < 0 || config['min-savings-ratio'] > 1)) {
         throw new Error('context-crusher: min-savings-ratio must be within [0, 1]');
     }
+    if (config['reducer-min-savings-ratio'] !== undefined
+        && (!Number.isFinite(config['reducer-min-savings-ratio']) || config['reducer-min-savings-ratio'] < 0 || config['reducer-min-savings-ratio'] > 1)) {
+        throw new Error('context-crusher: reducer-min-savings-ratio must be within [0, 1]');
+    }
+    for (const key of ['reducer-max-input-tokens', 'reducer-max-tokens', 'reducer-timeout-ms']) {
+        const value = config[key];
+        if (value !== undefined && (!Number.isFinite(value) || value < 1)) {
+            throw new Error(`context-crusher: ${key} must be a positive number`);
+        }
+    }
+    // Compile command patterns once at resolve time (§3.2): an invalid user
+    // regex is dropped with a debug log, never thrown and never recompiled on
+    // the hot path. An empty list falls back to the defaults (schemastery
+    // normalizes an ABSENT array to [] on the cordis config plane, so []
+    // cannot be distinguished from unset there).
+    const log = options?.log;
+    const rawCommands = config['reducer-commands'];
+    const commands = rawCommands !== undefined && rawCommands.length > 0 ? rawCommands : DEFAULT_REDUCER_COMMANDS;
+    const reducerCommands = commands.flatMap((source) => {
+        try {
+            return [new RegExp(source)];
+        }
+        catch {
+            log?.(`context-crusher: invalid reducer-commands pattern dropped: ${source}`);
+            return [];
+        }
+    });
+    if (config['defer-requests'] !== undefined
+        && (!Number.isInteger(config['defer-requests']) || config['defer-requests'] < 0)) {
+        throw new Error('context-crusher: defer-requests must be a non-negative integer');
+    }
+    if (config['defer-margin'] !== undefined
+        && (!Number.isFinite(config['defer-margin']) || config['defer-margin'] <= 0)) {
+        throw new Error('context-crusher: defer-margin must be a positive number');
+    }
+    if (config['defer-max-age-ms'] !== undefined
+        && (!Number.isFinite(config['defer-max-age-ms']) || config['defer-max-age-ms'] <= 0)) {
+        throw new Error('context-crusher: defer-max-age-ms must be a positive number');
+    }
+    if (config['defer-urgency-tokens'] !== undefined
+        && (!Number.isFinite(config['defer-urgency-tokens']) || config['defer-urgency-tokens'] <= 0)) {
+        throw new Error('context-crusher: defer-urgency-tokens must be a positive number');
+    }
     return deepFreeze({
         enabled: config.enabled ?? DEFAULTS.enabled,
         mode: config.mode ?? DEFAULTS.mode,
         minBytes: config['min-bytes'] ?? DEFAULTS.minBytes,
         minSavingsRatio: config['min-savings-ratio'] ?? DEFAULTS.minSavingsRatio,
         protectedTools: config['protected-tools'] ?? DEFAULTS.protectedTools,
+        reducerEnabled: config['reducer-enabled'] ?? DEFAULTS.reducerEnabled,
+        reducerCommands,
+        reducerMaxInputTokens: config['reducer-max-input-tokens'] ?? DEFAULTS.reducerMaxInputTokens,
+        reducerMinSavingsRatio: config['reducer-min-savings-ratio'] ?? DEFAULTS.reducerMinSavingsRatio,
+        reducerMaxTokens: config['reducer-max-tokens'] ?? DEFAULTS.reducerMaxTokens,
+        reducerTimeoutMs: config['reducer-timeout-ms'] ?? DEFAULTS.reducerTimeoutMs,
+        reducerAlias: config['reducer-alias'] ?? DEFAULTS.reducerAlias,
+        deferRequests: config['defer-requests'] ?? DEFAULTS.deferRequests,
+        deferMargin: config['defer-margin'] ?? DEFAULTS.deferMargin,
+        deferMaxAgeMs: config['defer-max-age-ms'] ?? DEFAULTS.deferMaxAgeMs,
+        ...(config['defer-urgency-tokens'] !== undefined
+            ? { deferUrgencyTokens: config['defer-urgency-tokens'] }
+            : {}),
     });
 }
 /**
@@ -73,6 +162,30 @@ export function overlaySettings(base, scope) {
         minBytes: scope['min-bytes'] ?? base.minBytes,
         minSavingsRatio: scope['min-savings-ratio'] ?? base.minSavingsRatio,
         protectedTools: scope['protected-tools'] ?? base.protectedTools,
+        // Every reducer key uses REPLACE semantics (§3.6): an explicitly set
+        // settings value replaces the config default wholesale (never a union).
+        reducerEnabled: scope['reducer-enabled'] ?? base.reducerEnabled,
+        reducerCommands: scope['reducer-commands'] !== undefined && scope['reducer-commands'].length > 0
+            ? scope['reducer-commands'].flatMap((source) => {
+                try {
+                    return [new RegExp(source)];
+                }
+                catch {
+                    return [];
+                }
+            })
+            : base.reducerCommands,
+        reducerMaxInputTokens: scope['reducer-max-input-tokens'] ?? base.reducerMaxInputTokens,
+        reducerMinSavingsRatio: scope['reducer-min-savings-ratio'] ?? base.reducerMinSavingsRatio,
+        reducerMaxTokens: scope['reducer-max-tokens'] ?? base.reducerMaxTokens,
+        reducerTimeoutMs: scope['reducer-timeout-ms'] ?? base.reducerTimeoutMs,
+        reducerAlias: scope['reducer-alias'] ?? base.reducerAlias,
+        deferRequests: scope['defer-requests'] ?? base.deferRequests,
+        deferMargin: scope['defer-margin'] ?? base.deferMargin,
+        deferMaxAgeMs: scope['defer-max-age-ms'] ?? base.deferMaxAgeMs,
+        ...(scope['defer-urgency-tokens'] !== undefined || base.deferUrgencyTokens !== undefined
+            ? { deferUrgencyTokens: scope['defer-urgency-tokens'] ?? base.deferUrgencyTokens }
+            : {}),
     };
 }
 //# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AAGzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB;IACpE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc;IAClE,MAAM,EAAE,iBAAiB;CAC1B,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAmB,UAAU,CAAC;IACjD,OAAO,EAAE,KAAK;IACd,IAAI,EAAE,SAAS;IACf,QAAQ,EAAE,IAAI;IACd,eAAe,EAAE,GAAG;IACpB,cAAc,EAAE,uBAAuB;CACxC,CAAC,CAAA;AAEF,MAAM,KAAK,GAA2B,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;AAEvD,oEAAoE;AACpE,MAAM,CAAC,MAAM,MAAM,GAAqB,CAAC,CAAC,MAAM,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,KAAmD,CAAC;IAClE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,iBAAiB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CACvC,CAAC,CAAA;AAEF,kEAAkE;AAClE,MAAM,CAAC,MAAM,cAAc,GAAqB,MAAM,CAAA;AAEtD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,SAAwB,EAAE;IACtD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,wCAAwC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC7E,CAAC;IACD,IAAI,MAAM,CAAC,WAAW,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC7G,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IACD,IAAI,MAAM,CAAC,mBAAmB,CAAC,KAAK,SAAS;WACxC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,IAAI,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAC3H,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAA;IAC7E,CAAC;IACD,OAAO,UAAU,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;QAC3C,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI;QAClC,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,QAAQ,CAAC,QAAQ;QAClD,eAAe,EAAE,MAAM,CAAC,mBAAmB,CAAC,IAAI,QAAQ,CAAC,eAAe;QACxE,cAAc,EAAE,MAAM,CAAC,iBAAiB,CAAC,IAAI,QAAQ,CAAC,cAAc;KACrE,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,IAAoB,EAAE,KAAgC;IACpF,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACjE,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;QACtC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;QAC7B,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ;QAC7C,eAAe,EAAE,KAAK,CAAC,mBAAmB,CAAC,IAAI,IAAI,CAAC,eAAe;QACnE,cAAc,EAAE,KAAK,CAAC,iBAAiB,CAAC,IAAI,IAAI,CAAC,cAAc;KAChE,CAAA;AACH,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/lib/defer/counter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * First-chunk send counting for deferred residents (design §3.2).
+ *
+ * A resident entry counts as sent when a provider request produces its FIRST
+ * chunk and the request's `options.messages` contain a tool-result block
+ * whose text fingerprint (sha256 first 16 hex — the same shape as the store
+ * hash) matches the stored full text. Counting at first chunk — not request
+ * start — excludes attempts that fail before reaching the provider.
+ *
+ * Purpose filtering is an ALLOWLIST: only main-loop requests count
+ * (`purpose` undefined; the harness purpose union is closed to
+ * `'compaction' | 'session-title'`). Subagent fan-outs are excluded as a
+ * fingerprint side effect (fresh history never contains the resident); the
+ * fork-inheriting corner is closed by requiring `options.sessionId` to be an
+ * owning session id.
+ *
+ * @module @dsh-cc/context-crusher/defer/counter
+ */
+import type { ContentBlock, GenerateOptions, Message, StreamChunk } from '@deepseek-ai/dsh-llm';
+/**
+ * Join text blocks; returns undefined when any block is non-text. Same rule
+ * as the crusher's insertion-time text extraction, so the fingerprint of a
+ * live tool-result block equals the store hash of the original.
+ */
+export declare function joinTextBlocks(blocks: readonly ContentBlock[]): string | undefined;
+/**
+ * Fingerprints of every fully-textual tool-result block in one outbound
+ * prompt. A request that contains the same resident twice still counts once
+ * (Set semantics).
+ */
+export declare function toolResultFingerprints(messages: readonly Message[]): Set<string>;
+/**
+ * The counting guard: main-loop purpose allowlist AND an owning session id.
+ * `owningSessionIds` is the in-memory set of sessions with defer state —
+ * never the ledger (§3.5 keeps the ledger session-id-free).
+ */
+export declare function shouldCountRequest(options: GenerateOptions, owningSessionIds: ReadonlySet<string>): boolean;
+/**
+ * Wrap one provider stream so `onFirstChunk` fires exactly when the first
+ * chunk is observed. A stream that throws before its first yield counts ZERO
+ * (Phase-0 pin) and the error propagates untouched to the caller.
+ */
+export declare function wrapStreamWithCounting(options: GenerateOptions, stream: AsyncIterable<StreamChunk>, onFirstChunk: (options: GenerateOptions) => void): AsyncIterable<StreamChunk>;
+//# sourceMappingURL=counter.d.ts.map

package/lib/defer/counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"counter.d.ts","sourceRoot":"","sources":["../../src/defer/counter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAG/F;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,GAAG,SAAS,CAOlF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAUhF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,eAAe,EACxB,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GACpC,OAAO,CAIT;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,EAClC,YAAY,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAC/C,aAAa,CAAC,WAAW,CAAC,CAW5B"}

package/lib/defer/counter.js

@@ -0,0 +1,81 @@
+/**
+ * First-chunk send counting for deferred residents (design §3.2).
+ *
+ * A resident entry counts as sent when a provider request produces its FIRST
+ * chunk and the request's `options.messages` contain a tool-result block
+ * whose text fingerprint (sha256 first 16 hex — the same shape as the store
+ * hash) matches the stored full text. Counting at first chunk — not request
+ * start — excludes attempts that fail before reaching the provider.
+ *
+ * Purpose filtering is an ALLOWLIST: only main-loop requests count
+ * (`purpose` undefined; the harness purpose union is closed to
+ * `'compaction' | 'session-title'`). Subagent fan-outs are excluded as a
+ * fingerprint side effect (fresh history never contains the resident); the
+ * fork-inheriting corner is closed by requiring `options.sessionId` to be an
+ * owning session id.
+ *
+ * @module @dsh-cc/context-crusher/defer/counter
+ */
+import { shortHash } from "../store.js";
+/**
+ * Join text blocks; returns undefined when any block is non-text. Same rule
+ * as the crusher's insertion-time text extraction, so the fingerprint of a
+ * live tool-result block equals the store hash of the original.
+ */
+export function joinTextBlocks(blocks) {
+    const parts = [];
+    for (const block of blocks) {
+        if (block.type !== 'text')
+            return undefined;
+        parts.push(block.text);
+    }
+    return parts.join('\n');
+}
+/**
+ * Fingerprints of every fully-textual tool-result block in one outbound
+ * prompt. A request that contains the same resident twice still counts once
+ * (Set semantics).
+ */
+export function toolResultFingerprints(messages) {
+    const out = new Set();
+    for (const message of messages) {
+        for (const block of message.content) {
+            if (block.type !== 'tool-result')
+                continue;
+            const text = joinTextBlocks(block.content);
+            if (text !== undefined)
+                out.add(shortHash(text));
+        }
+    }
+    return out;
+}
+/**
+ * The counting guard: main-loop purpose allowlist AND an owning session id.
+ * `owningSessionIds` is the in-memory set of sessions with defer state —
+ * never the ledger (§3.5 keeps the ledger session-id-free).
+ */
+export function shouldCountRequest(options, owningSessionIds) {
+    if (options.purpose !== undefined)
+        return false;
+    if (options.sessionId === undefined)
+        return false;
+    return owningSessionIds.has(String(options.sessionId));
+}
+/**
+ * Wrap one provider stream so `onFirstChunk` fires exactly when the first
+ * chunk is observed. A stream that throws before its first yield counts ZERO
+ * (Phase-0 pin) and the error propagates untouched to the caller.
+ */
+export function wrapStreamWithCounting(options, stream, onFirstChunk) {
+    return (async function* () {
+        let counted = false;
+        for await (const chunk of stream) {
+            if (!counted) {
+                counted = true;
+                onFirstChunk(options);
+            }
+            yield chunk;
+        }
+    })();
+}
+//# sourceMappingURL=counter.js.map

package/lib/defer/counter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"counter.js","sourceRoot":"","sources":["../../src/defer/counter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAA+B;IAC5D,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,SAAS,CAAA;QAC3C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAA4B;IACjE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;IAC7B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpC,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa;gBAAE,SAAQ;YAC1C,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;YAC1C,IAAI,IAAI,KAAK,SAAS;gBAAE,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;QAClD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAwB,EACxB,gBAAqC;IAErC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IAC/C,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACjD,OAAO,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAA;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAwB,EACxB,MAAkC,EAClC,YAAgD;IAEhD,OAAO,CAAC,KAAK,SAAS,CAAC;QACrB,IAAI,OAAO,GAAG,KAAK,CAAA;QACnB,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACjC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAA;gBACd,YAAY,CAAC,OAAO,CAAC,CAAA;YACvB,CAAC;YACD,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC,CAAC,EAAE,CAAA;AACN,CAAC"}

package/lib/defer/gate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure suffix-cost gate for the deferred swap (design §3.4). No I/O, no
+ * clock, no services — a table-testable fold over measured inputs.
+ *
+ * Prompt cache is a prefix: replacing the message at index k busts cache from
+ * k to the surface end, so the swap's rewrite price is the suffix measured AT
+ * SWAP TIME, not the stored prefix. With no price table resolved the
+ * comparison stays in token units — conservative in the direction of NOT
+ * swapping, the safe side.
+ *
+ * @module @dsh-cc/context-crusher/defer/gate
+ */
+export interface DeferGateInput {
+    /** tokensBefore − tokensAfter, recorded when the resident was stored. */
+    readonly tokensSaved: number;
+    /** Observed requests-per-step × pending todo steps; floored at 1 here too. */
+    readonly remainingRequestsEstimate: number;
+    /** `defer-margin` multiplier over the suffix cost. */
+    readonly margin: number;
+    /** Σ estimateMessage over surface nodes after the entry, at swap time. */
+    readonly suffixTokens: number;
+    /** `defer-urgency-tokens` window-pressure distance; unset = inactive. */
+    readonly urgencyTokens?: number;
+    /** Current session token estimate, when a meter is available. */
+    readonly sessionTokens?: number;
+    /** Routed model context window, when a window source advertised one. */
+    readonly contextWindow?: number;
+}
+export interface DeferGateOutcome {
+    readonly pass: boolean;
+    readonly projectedSavings: number;
+    readonly suffixCost: number;
+    readonly urgencyOverride: boolean;
+}
+/**
+ * Evaluate the swap gate for one eligible resident entry.
+ * @param input - measured gate inputs (suffix measured at swap time).
+ * @returns the decision with every intermediate term for the ledger.
+ */
+export declare function evaluateDeferGate(input: DeferGateInput): DeferGateOutcome;
+//# sourceMappingURL=gate.d.ts.map

package/lib/defer/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/defer/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAA;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAClC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB,CAazE"}

package/lib/defer/gate.js

@@ -0,0 +1,32 @@
+/**
+ * Pure suffix-cost gate for the deferred swap (design §3.4). No I/O, no
+ * clock, no services — a table-testable fold over measured inputs.
+ *
+ * Prompt cache is a prefix: replacing the message at index k busts cache from
+ * k to the surface end, so the swap's rewrite price is the suffix measured AT
+ * SWAP TIME, not the stored prefix. With no price table resolved the
+ * comparison stays in token units — conservative in the direction of NOT
+ * swapping, the safe side.
+ *
+ * @module @dsh-cc/context-crusher/defer/gate
+ */
+/**
+ * Evaluate the swap gate for one eligible resident entry.
+ * @param input - measured gate inputs (suffix measured at swap time).
+ * @returns the decision with every intermediate term for the ledger.
+ */
+export function evaluateDeferGate(input) {
+    const projectedSavings = input.tokensSaved * Math.max(1, input.remainingRequestsEstimate);
+    const suffixCost = input.margin * input.suffixTokens;
+    const urgencyOverride = input.urgencyTokens !== undefined
+        && input.sessionTokens !== undefined
+        && input.contextWindow !== undefined
+        && input.sessionTokens >= input.contextWindow - input.urgencyTokens;
+    return {
+        pass: urgencyOverride || projectedSavings > suffixCost,
+        projectedSavings,
+        suffixCost,
+        urgencyOverride,
+    };
+}
+//# sourceMappingURL=gate.js.map

package/lib/defer/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/defer/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAqB;IACrD,MAAM,gBAAgB,GAAG,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,yBAAyB,CAAC,CAAA;IACzF,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,YAAY,CAAA;IACpD,MAAM,eAAe,GAAG,KAAK,CAAC,aAAa,KAAK,SAAS;WACpD,KAAK,CAAC,aAAa,KAAK,SAAS;WACjC,KAAK,CAAC,aAAa,KAAK,SAAS;WACjC,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAA;IACrE,OAAO;QACL,IAAI,EAAE,eAAe,IAAI,gBAAgB,GAAG,UAAU;QACtD,gBAAgB;QAChB,UAAU;QACV,eAAe;KAChB,CAAA;AACH,CAAC"}

package/lib/defer/pass.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Deferred-mode orchestration (design §3): the `llm/stream` first-chunk
+ * counter, the `agent/pre-step` swap pass, resume-by-fingerprint, and the
+ * per-session ledger plumbing. Extracted from the crusher service to keep
+ * `index.ts` inside the file-size budget; the crusher wires one instance
+ * and forwards its post-execute hooks.
+ *
+ * @module @dsh-cc/context-crusher/defer/pass
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolExecution } from '@dsh-cc/tools';
+import type { CrusherStore } from '../store.ts';
+import type { ResolvedConfig } from '../types.ts';
+/** dsh-home path resolver (see the crusher's `dshHomePath` seam). */
+type HomeFn = (...segments: string[]) => string;
+export interface DeferralDeps {
+    readonly ctx: Context;
+    readonly store: () => CrusherStore | undefined;
+    readonly home: () => HomeFn | undefined;
+    readonly effectiveConfig: () => ResolvedConfig;
+}
+/**
+ * Owns all deferred-externalization state and listeners. Every failure
+ * degrades to a log line: observation must never break a request or a turn.
+ */
+export declare class Deferral {
+    private readonly deps;
+    private readonly table;
+    private readonly ledgers;
+    constructor(deps: DeferralDeps);
+    /**
+     * Deferred-mode seams (design §3): an `llm/stream` first-chunk counter
+     * (`{ global: true, prepend: true }` — the crusher runs in its own realm),
+     * an `agent/pre-step` swap pass, and state cleanup on session disposal.
+     */
+    registerListeners(): void;
+    /**
+     * First-chunk send counter (§3.2): one send per resident whose stored full
+     * text fingerprint appears in the outbound prompt. Main-loop purpose
+     * allowlist + owning-session guard live in {@link shouldCountRequest}.
+     */
+    private observeStreamFirstChunk;
+    /**
+     * One pre-step pass (§3.3): sweep aged residents, then evaluate every
+     * entry whose sent count crossed the residency threshold in one
+     * non-awaiting critical section per entry. No timers exist — eligibility
+     * is recomputed at this boundary. A failing entry never aborts the others
+     * (microcompact failure ordering).
+     */
+    private preStepPass;
+    /** Record one resident entry (post-execute, deferral applies). */
+    recordResident(exec: ToolExecution, hash: string, tokensSaved: number): Promise<void>;
+    /** Latest `todo_write` snapshot → the remaining-requests estimate inputs. */
+    observeTodoSnapshot(exec: ToolExecution): void;
+    /**
+     * Resume rebuild (§3.5), once per session: replay the per-session ledger
+     * and re-adopt entries whose stored text fingerprints the live surface.
+     * Session-id keying alone would strand residents across resume/fork, so
+     * the fingerprint — not the row — is the identity.
+     */
+    private ensureLoaded;
+    /** Per-session defer ledger (constructed lazily; all writes never throw). */
+    private ledgerFor;
+    /** Routed model context window via the token-meter pressure projection; absent = no window source. */
+    private contextWindowOf;
+    /** Token-based sizing, same estimator as the crusher's gates and markers. */
+    private estimate;
+}
+export {};
+//# sourceMappingURL=pass.d.ts.map

package/lib/defer/pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass.d.ts","sourceRoot":"","sources":["../../src/defer/pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAKlD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAYjD,qEAAqE;AACrE,KAAK,MAAM,GAAG,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;AAE/C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,YAAY,GAAG,SAAS,CAAA;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,cAAc,CAAA;CAC/C;AAED;;;GAGG;AACH,qBAAa,QAAQ;IAIP,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;gBAE5B,IAAI,EAAE,YAAY;IAE/C;;;;OAIG;IACH,iBAAiB,IAAI,IAAI;IAsBzB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAe/B;;;;;;OAMG;YACW,WAAW;IAsGzB,kEAAkE;IAC5D,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB3F,6EAA6E;IAC7E,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAS9C;;;;;OAKG;YACW,YAAY;IAqB1B,6EAA6E;IAC7E,OAAO,CAAC,SAAS;IAWjB,sGAAsG;IACtG,OAAO,CAAC,eAAe;IAavB,6EAA6E;IAC7E,OAAO,CAAC,QAAQ;CAMjB"}