@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.20

package/lib/engine.d.ts

@@ -0,0 +1,329 @@
+/**
+ * ChaptersCompactionEngine — the cordis-facing adapter over the pure
+ * engine-core logic. Mounted INSIDE a preset realm's compaction group (never
+ * the host plane beside `basic`: two engines double-fire across planes,
+ * FINDINGS § Phase 0b), it overrides exactly the sanctioned hook plus the two
+ * entry points whose results the finalizer needs.
+ *
+ * Everything decision-shaped lives in engine-core.ts, where it is
+ * harness-free testable. This file is glue: service resolution, durable
+ * reads/writes, and the never-break-the-caller containment the base's own
+ * listeners already model.
+ */
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+import type { BasicCompactionConfig } from '@deepseek-ai/dsh-compaction-basic';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compaction';
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand';
+import z from '@deepseek-ai/schemastery';
+import { type SummarizeInputLike, type SummarizeResultLike } from './engine-core.ts';
+/** Row config: the base's keys (so realm rows validate) plus the archive's own. */
+export interface ChaptersRowConfig extends BasicCompactionConfig {
+    /** Lines of the chapter index a continuation notice lists (0 = all). A fixed-size notice is what lets a
+     * boundary-sitting leg be captured and replayed at all (#56). */
+    noticeIndexCap?: number | undefined;
+    artifactStoreRoot?: string;
+    /** #85: pool-mirror root for rules/knowledge reads that produce model-visible text. */
+    knowledgeMirrorDir?: string;
+    /** #87: verbatim carry of the newest human turn, capped; the cap is stated, never silent. */
+    openRequestCarryMaxChars?: number;
+    /** #78 A: defer a node relief cannot coexist with, after a measured decline. */
+    lastResortArtifact?: boolean;
+    /** #95 follow-up: sink size cap; 0 = uncapped. */
+    diagnosticsMaxBytes?: number;
+    chapterTokenTarget?: number;
+    toolResultDeferFloorTokens?: number;
+    mergeThreshold?: number;
+    /** #61 Amendment A: the seventh archive moment, and its re-arm lag. */
+    childAutoArchive?: boolean | undefined;
+    childAutoArchiveMinTurns?: number | undefined;
+    chapterLimit?: number;
+    syncDebounceMs?: number;
+    toolResultArtifactTokens?: number;
+    /** Plans (docs/plans-carriage.md § 7): verbatim plan chars in a chapter's Plans
+     * block, and the tool-call-argument artifact floor (0 = off). */
+    planInlineChars?: number;
+    callArgArtifactTokens?: number;
+    /** Carry the operative plan into every checkpoint (plans-carriage § 9). */
+    plansInCheckpoint?: boolean;
+    planCheckpointChars?: number;
+    elicitedPlot?: boolean;
+    harnessId?: string;
+    sessionRulesEnabled?: boolean;
+    rulesMarkerPrefix?: string;
+    coreRulesBudgetTokens?: number;
+    projectRulesDisplayCap?: number;
+    sessionRulesDisplayCap?: number;
+    rulesRelevance?: boolean;
+    /** §7.5 model-mined rules; default ON. */
+    rulesEnrichment?: boolean;
+    /** §7.5 per-chapter cap on mined rules */
+    rulesMinedPerChapter?: number;
+    /** One auxiliary completion budget (annotation+mining, conflicts): must cover
+     * reasoning tokens as well as the visible answer — see enrich.ts. */
+    enrichmentMaxTokens?: number;
+    /** §7.5: mined rules govern on arrival unless false (then they wait for review).
+     * Default true — inferring what nobody spelled out is the whole point. */
+    rulesAutoActivate?: boolean;
+    /** §7.5: 'provider/model' for a dedicated mining call; '' ⇒ the annotation pass */
+    rulesModel?: string;
+    enrichmentEnabled?: boolean;
+    enrichmentModel?: string;
+    enrichmentTrigger?: 'afterPush' | 'idle' | 'both' | 'manual';
+    enrichmentIdleMs?: number;
+    enrichmentBatchCap?: number;
+    vocabApply?: boolean;
+    vocabCoMin?: number;
+    vocabOverlapMin?: number;
+    treedxFetchTimeoutMs?: number;
+    treedxWorkspaceTtlSeconds?: number;
+    treedxLeaseRetries?: number;
+    treedxLeaseRetryDelayMs?: number;
+}
+/**
+ * Per-turn deterministic signature listener (knowledge-repo.md §4.1), as a
+ * plain factory so the LOGIC is unit-testable against the real host Session
+ * shape without a full cordis Service context. Never-break containment: the
+ * handler reports through `warn`, it never throws into the session.
+ *
+ * r28 found the load-bearing fact: the host Session is a CLASS exposing
+ * snapshotEvents() — a `.events` property does not exist, and the first cut
+ * read `.events`, no-op'd silently in every real boot, and passed its L0
+ * test because the test stubbed the shape that does not exist.
+ */
+export declare function makeSignatureListener(deps: {
+    store: () => Promise<{
+        store: import('./store.ts').RegistryStore;
+    }>;
+    warn: (error: unknown) => void;
+    onCollected?: (id: string, sig: {
+        seqs: number[];
+        paths: string[];
+        terms: string[];
+        size: number;
+    }) => void;
+    /** Optional subprocess service for CodeGraph symbol verification. */
+    subprocess?: import('./codegraph.ts').SubprocessLike | undefined;
+    /** #61: `<store-root>` so the diagnostics sink can default to a file without any env setup. */
+    storeRoot?: string | undefined;
+}): (session: unknown, event: unknown) => void;
+/**
+ * Pull-on-first-turn (§5.1) as a plain factory, same testability discipline
+ * as the signature listener. Process-scoped "first turn seen" — a resumed
+ * old session pulling once more is harmless and bounded.
+ */
+export declare function makeFirstTurnPullListener(deps: {
+    pull: (cwd: string) => Promise<unknown>;
+}): (session: unknown, event: unknown) => void;
+/**
+ * #87 — carry the instruction that relief is about to shadow.
+ *
+ * Measured in the field: a `heavy` session whose thirteen compactions shadowed ten of the eleven
+ * copies of the human's follow-up question. What survives in the surface is the summary — a plot, not
+ * a request — so the model is never shown the thing it is being asked to do. Nothing errors; the user
+ * sees an agent that stopped answering.
+ *
+ * The fix stays inside our own seams and honors invariant 1 (nothing recorded is rewritten): WE author
+ * the summary text, so the newest human instruction travels INTO it, verbatim. Truncation is never
+ * silent — the cap is stated in the block. Injected scaffolding (workspace reminders, the host's own
+ * checkpoint preamble, our notices) is skipped: those are represented elsewhere, and carrying them
+ * would re-inject machine state as if it were a request.
+ */
+type SummaryPart = {
+    type: 'text';
+    text: string;
+};
+export declare function carryOpenRequest(parts: readonly SummaryPart[], messages: readonly unknown[], capChars: number): SummaryPart[];
+export declare class ChaptersCompactionEngine extends BasicCompactionEngine {
+    #private;
+    static inject: string[];
+    static Config: z<Schemastery.ObjectS<{
+        thresholdRatio: z<number, number>;
+        retainRatio: z<number, number>;
+        retainTokens: z<number, number>;
+        headroomTokens: z<number, number>;
+        summarizationProvider: z<string, string>;
+        summarizationModel: z<string, string>;
+        maxTokens: z<number, number>;
+        compactionRetries: z<number, number>;
+        maxOverflowRetries: z<number, number>;
+        modelPolicies: z<({
+            provider?: string | null;
+            model?: string | null;
+            thresholdRatio?: number | null;
+            retainRatio?: number | null;
+            retainTokens?: number | null;
+            headroomTokens?: number | null;
+            summarizationProvider?: string | null;
+            summarizationModel?: string | null;
+            maxTokens?: number | null;
+            compactionRetries?: number | null;
+            maxOverflowRetries?: number | null;
+        } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<{
+            provider: z<string, string>;
+            model: z<string, string>;
+            thresholdRatio: z<number, number>;
+            retainRatio: z<number, number>;
+            retainTokens: z<number, number>;
+            headroomTokens: z<number, number>;
+            summarizationProvider: z<string, string>;
+            summarizationModel: z<string, string>;
+            maxTokens: z<number, number>;
+            compactionRetries: z<number, number>;
+            maxOverflowRetries: z<number, number>;
+        }>[]>;
+        auto: z<boolean, boolean>;
+        artifactStoreRoot: z<string, string>;
+        knowledgeMirrorDir: z<string, string>;
+        openRequestCarryMaxChars: z<number, number>;
+        /** #78 A: the last-resort deferral switch. Operator-visible, default on. */
+        lastResortArtifact: z<boolean, boolean>;
+        /** #95 follow-up: diagnostics sink cap, bytes. 0 = uncapped. */
+        diagnosticsMaxBytes: z<number, number>;
+        chapterTokenTarget: z<number, number>;
+        toolResultDeferFloorTokens: z<number, number>;
+        mergeThreshold: z<number, number>;
+        chapterLimit: z<number, number>;
+        syncDebounceMs: z<number, number>;
+        toolResultArtifactTokens: z<number, number>;
+        childAutoArchive: z<boolean, boolean>;
+        childAutoArchiveMinTurns: z<number, number>;
+        elicitedPlot: z<boolean, boolean>;
+        harnessId: z<string, string>;
+        sessionRulesEnabled: z<boolean, boolean>;
+        rulesMarkerPrefix: z<string, string>;
+        coreRulesBudgetTokens: z<number, number>;
+        projectRulesDisplayCap: z<number, number>;
+        sessionRulesDisplayCap: z<number, number>;
+        rulesRelevance: z<boolean, boolean>;
+        rulesEnrichment: z<boolean, boolean>;
+        rulesMinedPerChapter: z<number, number>;
+        rulesAutoActivate: z<boolean, boolean>;
+        rulesModel: z<string, string>;
+        enrichmentEnabled: z<boolean, boolean>;
+        enrichmentModel: z<string, string>;
+        enrichmentTrigger: z<string, string>;
+        enrichmentIdleMs: z<number, number>;
+        enrichmentBatchCap: z<number, number>;
+        enrichmentMaxTokens: z<number, number>;
+        vocabApply: z<boolean, boolean>;
+        vocabCoMin: z<number, number>;
+        vocabOverlapMin: z<number, number>;
+        treedxFetchTimeoutMs: z<number, number>;
+        treedxWorkspaceTtlSeconds: z<number, number>;
+        treedxLeaseRetries: z<number, number>;
+        treedxLeaseRetryDelayMs: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        thresholdRatio: z<number, number>;
+        retainRatio: z<number, number>;
+        retainTokens: z<number, number>;
+        headroomTokens: z<number, number>;
+        summarizationProvider: z<string, string>;
+        summarizationModel: z<string, string>;
+        maxTokens: z<number, number>;
+        compactionRetries: z<number, number>;
+        maxOverflowRetries: z<number, number>;
+        modelPolicies: z<({
+            provider?: string | null;
+            model?: string | null;
+            thresholdRatio?: number | null;
+            retainRatio?: number | null;
+            retainTokens?: number | null;
+            headroomTokens?: number | null;
+            summarizationProvider?: string | null;
+            summarizationModel?: string | null;
+            maxTokens?: number | null;
+            compactionRetries?: number | null;
+            maxOverflowRetries?: number | null;
+        } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<{
+            provider: z<string, string>;
+            model: z<string, string>;
+            thresholdRatio: z<number, number>;
+            retainRatio: z<number, number>;
+            retainTokens: z<number, number>;
+            headroomTokens: z<number, number>;
+            summarizationProvider: z<string, string>;
+            summarizationModel: z<string, string>;
+            maxTokens: z<number, number>;
+            compactionRetries: z<number, number>;
+            maxOverflowRetries: z<number, number>;
+        }>[]>;
+        auto: z<boolean, boolean>;
+        artifactStoreRoot: z<string, string>;
+        knowledgeMirrorDir: z<string, string>;
+        openRequestCarryMaxChars: z<number, number>;
+        /** #78 A: the last-resort deferral switch. Operator-visible, default on. */
+        lastResortArtifact: z<boolean, boolean>;
+        /** #95 follow-up: diagnostics sink cap, bytes. 0 = uncapped. */
+        diagnosticsMaxBytes: z<number, number>;
+        chapterTokenTarget: z<number, number>;
+        toolResultDeferFloorTokens: z<number, number>;
+        mergeThreshold: z<number, number>;
+        chapterLimit: z<number, number>;
+        syncDebounceMs: z<number, number>;
+        toolResultArtifactTokens: z<number, number>;
+        childAutoArchive: z<boolean, boolean>;
+        childAutoArchiveMinTurns: z<number, number>;
+        elicitedPlot: z<boolean, boolean>;
+        harnessId: z<string, string>;
+        sessionRulesEnabled: z<boolean, boolean>;
+        rulesMarkerPrefix: z<string, string>;
+        coreRulesBudgetTokens: z<number, number>;
+        projectRulesDisplayCap: z<number, number>;
+        sessionRulesDisplayCap: z<number, number>;
+        rulesRelevance: z<boolean, boolean>;
+        rulesEnrichment: z<boolean, boolean>;
+        rulesMinedPerChapter: z<number, number>;
+        rulesAutoActivate: z<boolean, boolean>;
+        rulesModel: z<string, string>;
+        enrichmentEnabled: z<boolean, boolean>;
+        enrichmentModel: z<string, string>;
+        enrichmentTrigger: z<string, string>;
+        enrichmentIdleMs: z<number, number>;
+        enrichmentBatchCap: z<number, number>;
+        enrichmentMaxTokens: z<number, number>;
+        vocabApply: z<boolean, boolean>;
+        vocabCoMin: z<number, number>;
+        vocabOverlapMin: z<number, number>;
+        treedxFetchTimeoutMs: z<number, number>;
+        treedxWorkspaceTtlSeconds: z<number, number>;
+        treedxLeaseRetries: z<number, number>;
+        treedxLeaseRetryDelayMs: z<number, number>;
+    }>>;
+    private readonly chaptersConfig;
+    /** #50 §7.5/§7.3: capture + rendering numbers, host plane mirrored in. */
+    private ruleCfg;
+    private storePromise;
+    /** #52: the delegation-edge reader, built lazily because a field initializer
+     * cannot see the constructor parameter and the realm may hold neither service.
+     * null = not built yet; undefined = built and unavailable (registry edges only). */
+    private parentOfReader;
+    /** The reader the rule-ancestry walk uses. Absent ⇒ delegation contributes no edge. */
+    private ruleParentOf;
+    constructor(ctx: Context, config?: ChaptersRowConfig);
+    /**
+     * Per-turn deterministic signatures at turn/end (knowledge-repo §4.1):
+     * synchronous extraction, async store append, and never-break containment —
+     * a signature failure must never touch the compaction path (AGENTS hard
+     * rule: the listener reports, it never throws into the session). The base
+     * engine's own listeners model the same shape.
+     */
+    /** The realm's own scheduler (§5): same code as the host plane's; the file
+     * lock and debounce keep the two honest against each other. */
+    private syncDebounceMs;
+    private vocabCfg;
+    private enrichCfg;
+    private enrichPromise;
+    private lastCwd;
+    private lastRoute;
+    private lastWindowTokens;
+    private schedulerPromise;
+    /** Lazy, once. `storageDomain` is a host-plane singleton the realm resolves;
+     * acquire (never bare-open): a mounted tools-plugin may already own the reservation. */
+    private store;
+    protected summarize(input: SummarizeInputLike, agent: unknown, _signal?: AbortSignal): Promise<SummarizeResultLike>;
+    compactIfNeeded(agent: Agent, trigger: CompactionTrigger, signal: AbortSignal): Promise<CompactionResult | null>;
+    compactNow(agent: Agent, signal: AbortSignal, sourceCommandId?: CommandId): Promise<CompactionResult | null>;
+}
+export default ChaptersCompactionEngine;