@psiclawops/hypermem 0.7.0 → 0.8.1

package/dist/background-indexer.js

@@ -26,6 +26,9 @@ import { EpisodeStore } from './episode-store.js';
 import { TopicStore } from './topic-store.js';
 import { KnowledgeStore } from './knowledge-store.js';
 import { TemporalStore } from './temporal-store.js';
+import { ContradictionDetector } from './contradiction-detector.js';
+import { ContradictionAuditStore } from './contradiction-audit-store.js';
+import { DEFAULT_CONTRADICTION_POLICY } from './contradiction-resolution-policy.js';
 import { isSafeForSharedVisibility } from './secret-scanner.js';
 // ─── Agent-to-Domain Map ────────────────────────────────────────
 // Maps well-known agent IDs to their primary domain.
@@ -411,6 +414,8 @@ export class BackgroundIndexer {
     getCursor;
     config;
     dreamerConfig;
+    globalWritePolicy;
+    contradictionPolicy;
     intervalHandle = null;
     running = false;
     vectorStore = null;
@@ -420,7 +425,9 @@ export class BackgroundIndexer {
     consecutiveFailures = 0;
     /** True when the indexer is running in backoff mode due to repeated failures. */
     inBackoff = false;
-    constructor(config, getMessageDb, getLibraryDb, listAgents, getCursor, dreamerConfig) {
+    _conversationLastProcessed = new Map();
+    lastMaintenanceDiagnostics = null;
+    constructor(config, getMessageDb, getLibraryDb, listAgents, getCursor, dreamerConfig, globalWritePolicy, contradictionPolicy) {
         this.getMessageDb = getMessageDb;
         this.getLibraryDb = getLibraryDb;
         this.listAgents = listAgents;
@@ -451,8 +458,13 @@ export class BackgroundIndexer {
             periodicInterval: config?.periodicInterval ?? 60000, // 1 minute
             batchSize: config?.batchSize ?? 128,
             maxMessagesPerTick: config?.maxMessagesPerTick ?? 500,
+            maxActiveConversations: config?.maxActiveConversations ?? 5,
+            recentConversationCooldownMs: config?.recentConversationCooldownMs ?? 30000,
+            maxCandidatesPerPass: config?.maxCandidatesPerPass ?? 200,
         };
         this.dreamerConfig = dreamerConfig ?? {};
+        this.globalWritePolicy = globalWritePolicy ?? 'deny';
+        this.contradictionPolicy = contradictionPolicy ?? DEFAULT_CONTRADICTION_POLICY;
     }
     /**
      * Set the vector store for embedding new facts/episodes at index time.
@@ -686,27 +698,72 @@ export class BackgroundIndexer {
                 }
             }
             // Run proactive passes on each agent's message DB
+            const maintStart = Date.now();
+            let maintConsidered = 0;
+            let maintSkipped = 0;
+            let maintScanned = 0;
+            let maintMutated = 0;
+            let maintExitReason = 'complete';
+            const maxConvs = this.config.maxActiveConversations ?? 5;
+            const cooldownMs = this.config.recentConversationCooldownMs ?? 30000;
+            const maxCandidates = this.config.maxCandidatesPerPass ?? 200;
+            const now = Date.now();
             for (const agentId of agents) {
                 const messageDb = this.getMessageDb(agentId);
                 if (!messageDb)
                     continue;
-                // Get active conversations for this agent
                 let convRows;
                 try {
-                    convRows = messageDb.prepare(`SELECT id FROM conversations WHERE agent_id = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 10`).all(agentId);
+                    convRows = messageDb.prepare(`SELECT id FROM conversations WHERE agent_id = ? AND status = 'active' ORDER BY updated_at DESC LIMIT ?`).all(agentId, maxConvs);
                 }
                 catch {
                     continue;
                 }
+                if (convRows.length === 0) {
+                    if (maintExitReason === 'complete')
+                        maintExitReason = 'no-conversations';
+                    continue;
+                }
                 for (const conv of convRows) {
-                    const noiseSweepResult = runNoiseSweep(messageDb, conv.id);
-                    const toolDecayResult = runToolDecay(messageDb, conv.id);
-                    // Log only if something changed
-                    if (noiseSweepResult.messagesDeleted > 0 || toolDecayResult.messagesUpdated > 0) {
+                    maintConsidered++;
+                    const lastProcessed = this._conversationLastProcessed.get(conv.id) ?? 0;
+                    if (now - lastProcessed < cooldownMs) {
+                        maintSkipped++;
+                        continue;
+                    }
+                    maintScanned++;
+                    // Any successful scan means we're in a real working state —
+                    // clear any stale 'no-conversations' marker from an earlier agent.
+                    if (maintExitReason === 'no-conversations')
+                        maintExitReason = 'complete';
+                    const noiseSweepResult = runNoiseSweep(messageDb, conv.id, 20, maxCandidates);
+                    const toolDecayResult = runToolDecay(messageDb, conv.id, 40, maxCandidates);
+                    const changed = noiseSweepResult.messagesDeleted + toolDecayResult.messagesUpdated;
+                    if (changed > 0) {
+                        maintMutated += changed;
                         console.log(`[indexer] Proactive pass (conv ${conv.id}): swept ${noiseSweepResult.messagesDeleted} noise msgs, ` +
                             `decayed ${toolDecayResult.messagesUpdated} tool results (${toolDecayResult.bytesFreed} bytes freed)`);
                     }
+                    this._conversationLastProcessed.set(conv.id, now);
+                    if (maintMutated >= maxCandidates) {
+                        maintExitReason = 'cap-reached';
+                        break;
+                    }
                 }
+                if (maintExitReason === 'cap-reached')
+                    break;
+            }
+            this.lastMaintenanceDiagnostics = {
+                considered: maintConsidered,
+                skipped: maintSkipped,
+                scanned: maintScanned,
+                mutated: maintMutated,
+                durationMs: Date.now() - maintStart,
+                exitReason: maintExitReason,
+            };
+            if (maintScanned > 0) {
+                console.log(`[indexer] Maintenance: considered=${maintConsidered} skipped=${maintSkipped} scanned=${maintScanned} mutated=${maintMutated} ` +
+                    `duration=${this.lastMaintenanceDiagnostics.durationMs}ms exit=${maintExitReason}`);
             }
             // If we reach here, the tick completed without throwing.
             tickSucceeded = true;
@@ -758,6 +815,9 @@ export class BackgroundIndexer {
                 knowledgeUpserted: 0,
                 tombstoned,
                 postCursorMessages: 0,
+                contradictionAuditsLogged: 0,
+                contradictionsAutoSuperseded: 0,
+                contradictionsAutoInvalidated: 0,
                 elapsedMs: Date.now() - start,
             };
         }
@@ -791,7 +851,16 @@ export class BackgroundIndexer {
         let topicsUpdated = 0;
         let knowledgeUpserted = 0;
         let supersededFacts = 0;
+        let contradictionAuditsLogged = 0;
+        let contradictionsAutoSuperseded = 0;
+        let contradictionsAutoInvalidated = 0;
         let maxMessageId = lastProcessedId;
+        const contradictionDetector = new ContradictionDetector(factStore, this.vectorStore ?? undefined, {
+            autoResolve: false,
+            maxCandidates: 6,
+            minSimilarity: 0.45,
+        });
+        const contradictionAuditStore = new ContradictionAuditStore(libraryDb);
         for (const msg of ordered) {
             const content = msg.textContent || '';
             if (msg.id > maxMessageId)
@@ -803,15 +872,50 @@ export class BackgroundIndexer {
             const factCandidates = extractFactCandidates(content);
             for (const { content: factContent, confidence: factConfidence } of factCandidates) {
                 try {
+                    const factDomain = domainForAgent(agentId);
+                    // 1. Detect contradictions BEFORE addFact (operates on existing facts only)
+                    const contradictionResult = await contradictionDetector.detectOnIngest(agentId, {
+                        content: factContent,
+                        domain: factDomain,
+                    });
+                    const topContradictions = contradictionResult.contradictions.slice(0, 3);
+                    // 2. addFact first — we need fact.id for supersede linkage
                     const fact = factStore.addFact(agentId, factContent, {
                         scope: 'agent',
-                        domain: domainForAgent(agentId),
+                        domain: factDomain,
                         confidence: factConfidence,
                         sourceType: 'indexer',
                         sourceSessionKey: this.getSessionKeyForMessage(messageDb, msg.conversationId),
                         sourceRef: `msg:${msg.id}`,
                     });
                     factsExtracted++;
+                    // 3. Apply contradiction policy for each candidate (now we have fact.id)
+                    for (const candidate of topContradictions) {
+                        const score = candidate.contradictionScore;
+                        let auditStatus = 'pending';
+                        if (score >= this.contradictionPolicy.autoSupersedeThreshold) {
+                            const didSupersede = factStore.markSuperseded(candidate.existingFactId, fact.id);
+                            if (didSupersede) {
+                                contradictionsAutoSuperseded++;
+                                // Immediately remove stale vector so it cannot surface in KNN recall
+                                if (this.vectorStore) {
+                                    this.vectorStore.removeItem('facts', candidate.existingFactId);
+                                }
+                            }
+                            auditStatus = 'auto-superseded';
+                        }
+                        else if (score >= this.contradictionPolicy.autoInvalidateThreshold) {
+                            const didInvalidate = factStore.invalidateFact(candidate.existingFactId);
+                            if (didInvalidate) {
+                                contradictionsAutoInvalidated++;
+                            }
+                            auditStatus = 'auto-invalidated';
+                        }
+                        if (this.contradictionPolicy.alwaysAudit || auditStatus === 'pending') {
+                            contradictionAuditStore.recordFactAudit(agentId, { content: factContent, domain: factDomain }, candidate, { sourceRef: `msg:${msg.id}`, status: auditStatus });
+                            contradictionAuditsLogged++;
+                        }
+                    }
                     // ── Supersedes detection ─────────────────────────────────
                     // Check if the newly extracted fact supersedes an existing one.
                     // A supersede is detected when an existing active fact shares the
@@ -868,17 +972,18 @@ export class BackgroundIndexer {
             }
             // 3. Detect and update topics
             const topicName = detectTopic(content);
-            if (topicName) {
+            if (topicName && topicName.trim().length >= 3) {
                 try {
-                    const existingTopics = topicStore.getActive(agentId, 100);
-                    const existingTopic = existingTopics.find((t) => t.name.toLowerCase() === topicName.toLowerCase());
-                    if (!existingTopic) {
-                        topicStore.create(agentId, topicName, `Auto-detected from conversation`);
-                        topicsUpdated++;
-                    }
+                    const msgSessionKey = this.getSessionKeyForMessage(messageDb, msg.conversationId) || '';
+                    // findOrCreate handles case-insensitive dedup at the schema level;
+                    // always touch afterward so message_count reflects real activity
+                    // rather than sitting at 0 forever (which made every topic an orphan).
+                    const topic = topicStore.findOrCreate(agentId, topicName, `Auto-detected from conversation`);
+                    topicStore.touch(topic.id, msgSessionKey, 1);
+                    topicsUpdated++;
                 }
                 catch {
-                    // Skip topic creation errors
+                    // Skip topic creation/touch errors
                 }
             }
             // 4. Extract knowledge candidates
@@ -912,6 +1017,9 @@ export class BackgroundIndexer {
             topicsUpdated,
             knowledgeUpserted,
             tombstoned,
+            contradictionAuditsLogged,
+            contradictionsAutoSuperseded,
+            contradictionsAutoInvalidated,
             postCursorMessages: postCursor.length,
             elapsedMs: Date.now() - start,
         };
@@ -1146,8 +1254,8 @@ export class BackgroundIndexer {
  * Create and start a background indexer connected to hypermem databases.
  * Used by the hook or a standalone daemon.
  */
-export function createIndexer(getMessageDb, getLibraryDb, listAgents, config, getCursor, vectorStore, dreamerConfig) {
-    const indexer = new BackgroundIndexer(config, getMessageDb, getLibraryDb, listAgents, getCursor, dreamerConfig);
+export function createIndexer(getMessageDb, getLibraryDb, listAgents, config, getCursor, vectorStore, dreamerConfig, globalWritePolicy) {
+    const indexer = new BackgroundIndexer(config, getMessageDb, getLibraryDb, listAgents, getCursor, dreamerConfig, globalWritePolicy);
     if (vectorStore)
         indexer.setVectorStore(vectorStore);
     return indexer;

package/dist/budget-policy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonical budget policy for history-window trim and steady-state gradient caps.
+ *
+ * Phase C C0.1 centralizes these values so compose, afterTurn refresh, plugin
+ * trim guards, and regression tests all consume the same source of truth.
+ */
+export declare const TRIM_SOFT_TARGET = 0.65;
+export declare const TRIM_GROWTH_THRESHOLD = 0.05;
+export declare const TRIM_HEADROOM_FRACTION = 0.1;
+export interface TrimBudgetPolicy {
+    trimSoftTarget: number;
+    trimGrowthThreshold: number;
+    trimHeadroomFraction: number;
+}
+export interface ResolvedTrimBudgets extends TrimBudgetPolicy {
+    softBudget: number;
+    triggerBudget: number;
+    targetBudget: number;
+}
+export declare const TRIM_BUDGET_POLICY: TrimBudgetPolicy;
+export declare function resolveTrimBudgets(effectiveBudget: number): ResolvedTrimBudgets;
+//# sourceMappingURL=budget-policy.d.ts.map

package/dist/budget-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-policy.d.ts","sourceRoot":"","sources":["../src/budget-policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,sBAAsB,MAAO,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,EAAE,gBAI/B,CAAC;AAEH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,mBAAmB,CAW/E"}

package/dist/budget-policy.js

@@ -0,0 +1,27 @@
+/**
+ * Canonical budget policy for history-window trim and steady-state gradient caps.
+ *
+ * Phase C C0.1 centralizes these values so compose, afterTurn refresh, plugin
+ * trim guards, and regression tests all consume the same source of truth.
+ */
+export const TRIM_SOFT_TARGET = 0.65;
+export const TRIM_GROWTH_THRESHOLD = 0.05;
+export const TRIM_HEADROOM_FRACTION = 0.10;
+export const TRIM_BUDGET_POLICY = Object.freeze({
+    trimSoftTarget: TRIM_SOFT_TARGET,
+    trimGrowthThreshold: TRIM_GROWTH_THRESHOLD,
+    trimHeadroomFraction: TRIM_HEADROOM_FRACTION,
+});
+export function resolveTrimBudgets(effectiveBudget) {
+    const safeBudget = Math.max(0, Math.floor(effectiveBudget || 0));
+    const softBudget = Math.floor(safeBudget * TRIM_SOFT_TARGET);
+    const triggerBudget = Math.floor(softBudget * (1 + TRIM_GROWTH_THRESHOLD));
+    const targetBudget = Math.floor(softBudget * (1 - TRIM_HEADROOM_FRACTION));
+    return {
+        ...TRIM_BUDGET_POLICY,
+        softBudget,
+        triggerBudget,
+        targetBudget,
+    };
+}
+//# sourceMappingURL=budget-policy.js.map

package/dist/cache.d.ts

@@ -19,6 +19,17 @@ export interface WindowCacheMeta {
     warnings: string[];
     diagnostics: ComposeDiagnostics;
     composedAt: string;
+    /**
+     * Deterministic SHA-256 hash of the stable cacheable prefix at compose time.
+     * Stored so the C4 fast-exit can detect stable-prefix mutations even when
+     * the cursor (message id) has not advanced (e.g. system prompt / identity changed).
+     */
+    prefixHash?: string;
+    /**
+     * SHA-256 hash of the system + identity slot contents that fed the stable prefix.
+     * Used by C4 to cheaply detect slot mutations without re-running full compose.
+     */
+    prefixInputHash?: string;
 }
 export declare class CacheLayer {
     private db;

package/dist/cache.d.ts.map

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

package/dist/compositor-utils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * compositor-utils.ts — Utility functions for context window composition.
+ *
+ * Provides ordering strategies that improve LLM attention over retrieved
+ * documents placed into a prompt.
+ */
+/**
+ * Reorder documents using zigzag placement to mitigate
+ * "Lost in the Middle" attention degradation in LLMs.
+ *
+ * LLMs exhibit a U-shaped attention curve: items at the beginning and end
+ * of context receive ~30% more attention than items in the middle.
+ * This function places the most relevant items at the edges and the least
+ * relevant items near the center, maximising effective attention on the
+ * information that matters most.
+ *
+ * Reference: Liu et al., "Lost in the Middle: How Language Models Use Long
+ * Contexts", ICLR 2025. https://arxiv.org/abs/2307.03172
+ *
+ * Input:  [d1, d2, d3, d4, d5]  (sorted by relevance, descending)
+ * Output: [d1, d3, d5, d4, d2]  (most relevant at edges, least in middle)
+ *
+ * Algorithm:
+ *   - Items at even positions in the input (0, 2, 4, …) fill from the front.
+ *   - Items at odd positions in the input (1, 3, 5, …) fill from the back.
+ *
+ * @param docs - Array sorted by relevance (most relevant first).
+ * @returns A new array reordered so the most relevant items sit at the edges.
+ */
+export declare function zigzagOrder<T>(docs: T[]): T[];
+//# sourceMappingURL=compositor-utils.d.ts.map

package/dist/compositor-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositor-utils.d.ts","sourceRoot":"","sources":["../src/compositor-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAkB7C"}

package/dist/compositor-utils.js

@@ -0,0 +1,47 @@
+/**
+ * compositor-utils.ts — Utility functions for context window composition.
+ *
+ * Provides ordering strategies that improve LLM attention over retrieved
+ * documents placed into a prompt.
+ */
+/**
+ * Reorder documents using zigzag placement to mitigate
+ * "Lost in the Middle" attention degradation in LLMs.
+ *
+ * LLMs exhibit a U-shaped attention curve: items at the beginning and end
+ * of context receive ~30% more attention than items in the middle.
+ * This function places the most relevant items at the edges and the least
+ * relevant items near the center, maximising effective attention on the
+ * information that matters most.
+ *
+ * Reference: Liu et al., "Lost in the Middle: How Language Models Use Long
+ * Contexts", ICLR 2025. https://arxiv.org/abs/2307.03172
+ *
+ * Input:  [d1, d2, d3, d4, d5]  (sorted by relevance, descending)
+ * Output: [d1, d3, d5, d4, d2]  (most relevant at edges, least in middle)
+ *
+ * Algorithm:
+ *   - Items at even positions in the input (0, 2, 4, …) fill from the front.
+ *   - Items at odd positions in the input (1, 3, 5, …) fill from the back.
+ *
+ * @param docs - Array sorted by relevance (most relevant first).
+ * @returns A new array reordered so the most relevant items sit at the edges.
+ */
+export function zigzagOrder(docs) {
+    if (docs.length <= 2) {
+        return docs.slice();
+    }
+    const result = new Array(docs.length);
+    let front = 0;
+    let back = docs.length - 1;
+    for (let i = 0; i < docs.length; i++) {
+        if (i % 2 === 0) {
+            result[front++] = docs[i];
+        }
+        else {
+            result[back--] = docs[i];
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=compositor-utils.js.map

package/dist/compositor.d.ts

@@ -17,12 +17,80 @@ import { CacheLayer } from './cache.js';
 type AnyCache = CacheLayer;
 import { VectorStore } from './vector-store.js';
 import { type OrgRegistry } from './cross-agent.js';
+import { type DegradationReason } from './degradation.js';
 /**
  * Files that OpenClaw's contextInjection injects into the system prompt.
  * HyperMem must not re-inject these via doc chunk retrieval to avoid duplication.
  * Exported so plugin and other consumers can share the same dedup set.
  */
 export declare const OPENCLAW_BOOTSTRAP_FILES: Set<string>;
+/**
+ * B4: Compute model-aware lane budget fractions.
+ *
+ * Resolves the effective historyFraction and memoryFraction for a compose pass
+ * given the model and its effective budget. Uses the MECW catalog to blend
+ * away from fixed fractions when the budget approaches the MECW ceiling,
+ * so the compositor allocates proportionally for what the model can actually use.
+ *
+ * Returns:
+ *   historyFraction — fraction of effective budget to give history
+ *   memoryFraction  — fraction of effective budget to give memory pool
+ *   mecwProfile     — which MECW entry matched (undefined = no match / full window)
+ *   mecwApplied     — true when MECW adjustment changed the fractions
+ *   mecwBlend       — 0..1 blend factor (0 = below floor, 1 = at/above ceiling)
+ */
+export declare function resolveModelLaneBudgets(model: string | undefined, effectiveBudget: number, configHistoryFraction: number, configMemoryFraction: number): {
+    historyFraction: number;
+    memoryFraction: number;
+    mecwProfile: string | undefined;
+    mecwApplied: boolean;
+    mecwBlend: number;
+};
+/** Session classification labels — used for adaptive depth selection. */
+export type SessionType = 'plain-chat' | 'tool-heavy';
+/**
+ * Classify a session based on the ratio of tool messages in the recent sample.
+ * 'tool-heavy': >= 20% of sampled messages carry tool calls or tool results.
+ * 'plain-chat': below that threshold (text-only or occasional tool use).
+ *
+ * The 20% threshold is intentionally conservative: most tool-heavy agents
+ * have tool messages on every assistant turn, so the ratio quickly exceeds
+ * the threshold without false-positive risk for light tool users.
+ */
+export declare function classifySessionType(messages: NeutralMessage[]): SessionType;
+/**
+ * Estimate the average token cost per message from a recent message sample.
+ * Uses the same estimateMessageTokens heuristic as the compositor budget walk
+ * so the returned depth is directly comparable to the historyFillCap check.
+ *
+ * Returns a conservative floor (100 tokens) when the sample is empty to avoid
+ * returning Infinity when historyBudget is divided by density.
+ */
+export declare function estimateObservedMsgDensity(messages: NeutralMessage[]): number;
+/**
+ * Compute an adaptive history depth that pre-fits the session type.
+ *
+ * For plain-chat sessions: divides historyBudget by observed density to get a
+ * depth that fills the budget without overflow, bounded by the default maximum.
+ * Recall quality is preserved because the density estimate is honest for
+ * text-only turns.
+ *
+ * For tool-heavy sessions: applies a post-gradient compression factor
+ * (TOOL_GRADIENT_DENSITY_FACTOR = 0.30) to the observed pre-gradient density.
+ * This accounts for the gradient transform collapsing large tool payloads to
+ * prose stubs before the budget-fit walk runs. A tighter depth is chosen so
+ * the gradient-compressed messages fit inside historyFillCap without triggering
+ * a rescue trim.
+ *
+ * A 0.85 safety margin is applied to both paths so estimates that are
+ * slightly off don't cause immediate overflow on the first warm compose.
+ *
+ * Min/max bounds ensure the compositor always sees a meaningful window:
+ *   - plain-chat min: 20 messages (enough for short recent context)
+ *   - tool-heavy min: 15 messages (recent tool context + a few prior turns)
+ *   - shared max: config.maxHistoryMessages (never exceed the DB fetch ceiling)
+ */
+export declare function computeAdaptiveHistoryDepth(sessionType: SessionType, observedDensity: number, historyBudgetTokens: number, maxHistoryMessages: number): number;
 export { CollectionTrigger, DEFAULT_TRIGGERS, matchTriggers } from './trigger-registry.js';
 export { getTurnAge, applyToolGradient, appendToolSummary, truncateWithHeadTail, applyTierPayloadCap, evictLargeToolResults };
 /**
@@ -55,6 +123,78 @@ declare function applyTierPayloadCap(msg: NeutralMessage, perResultCap: number,
     usedChars: number;
 };
 declare function evictLargeToolResults<T extends NeutralMessage>(messages: T[]): T[];
+export declare function resolveArtifactOversizeThreshold(effectiveBudget: number): number;
+/**
+ * C2: Degrade an oversized doc chunk to a canonical ArtifactRef string.
+ *
+ * When a retrieved chunk's content exceeds the oversize threshold (in tokens),
+ * replace it with a fetchable canonical reference instead of injecting raw content.
+ * This preserves headroom in the lane instead of filling it with a large payload.
+ *
+ * Returns:
+ *   - `null`  → content is within the threshold; caller should inject as-is.
+ *   - `string` → canonical artifact reference; caller should inject this instead of raw content.
+ *
+ * The sizeTokens reported in the reference is the ACTUAL estimated size so downstream
+ * tooling can make informed decisions about whether to fetch.
+ */
+export declare function degradeOversizedDocChunk(chunkId: string, sourcePath: string, content: string, thresholdTokens: number): string | null;
+/**
+ * C2: Resolve oversized artifacts in a history message array.
+ *
+ * Scans the message array and replaces user/assistant messages whose text content
+ * exceeds the model-aware artifact oversize threshold with canonical ArtifactRef
+ * strings. System messages, tool-call messages, and tool-result messages are always
+ * passed through unchanged.
+ *
+ * @param messages — neutral message array (already-assembled history window)
+ * @param effectiveBudget — effective model budget from B4 (drives the threshold)
+ * @returns { messages, refCount, tokensSaved }
+ */
+export declare function resolveOversizedArtifacts<T extends NeutralMessage>(messages: T[], effectiveBudget: number): {
+    messages: T[];
+    refCount: number;
+    tokensSaved: number;
+};
+/**
+ * Result of a single tool-chain ejection pass.
+ * Returned by resolveToolChainEjections so callers can accumulate telemetry.
+ */
+export interface ToolChainEjectionResult<T extends NeutralMessage> {
+    /** The transformed message array (may contain stubs in place of results). */
+    messages: T[];
+    /** Number of tool-result messages fully co-ejected (removed from the array). */
+    coEjections: number;
+    /** Number of tool-result payloads replaced with a canonical stub string. */
+    stubReplacements: number;
+}
+/**
+ * C1: Centralized tool-chain dependency ejection.
+ *
+ * Given a set of tool-use message indices that are being ejected from the
+ * context window, this function ensures that no orphaned tool-results survive:
+ *
+ *   - For each ejected assistant message carrying toolCalls, collect the set
+ *     of call IDs being removed.
+ *   - Walk the remaining messages: if a message's toolResults reference any
+ *     of those ejected IDs:
+ *       a) If the message carries ONLY tool-results and no other text, co-eject
+ *          it (remove it entirely). This is the zero-cost path.
+ *       b) If the message also carries text content, replace only the dependent
+ *          toolResults entries with canonical ToolChainStub strings so the
+ *          message is not silently mutilated.
+ *
+ * The caller is responsible for removing the ejected messages by index BEFORE
+ * or AFTER calling this function; this function operates on the full array and
+ * marks the ejected indices for removal, returning the cleaned result.
+ *
+ * @param messages       Full message array (order preserved)
+ * @param ejectIndices   Set of indices into `messages` that are being ejected
+ *                       (these are the tool-use / assistant messages being removed).
+ * @param reason         DegradationReason to embed in any canonical stubs.
+ * @returns              Cleaned message array + telemetry counters.
+ */
+export declare function resolveToolChainEjections<T extends NeutralMessage>(messages: T[], ejectIndices: Set<number>, reason?: DegradationReason): ToolChainEjectionResult<T>;
 /**
  * Apply gradient tool treatment to a message array.
  *
@@ -96,6 +236,27 @@ export declare class Compositor {
      * Return the currently cached org registry.
      */
     get orgRegistry(): OrgRegistry;
+    /**
+     * Sprint 2.1: Hydrate tool-artifact stubs in the active turn.
+     *
+     * The active turn is the contiguous trailing block of tool-bearing messages
+     * at the tail of the assembled window (positional, NOT turn_id-based):
+     *   - Walk backward from the last message
+     *   - Collect tool-bearing messages (toolCalls != null OR toolResults != null)
+     *   - Plus the bounding user message that opened the turn
+     *   - Stop at the first plain message once at least one tool message was found
+     *
+     * For every toolResult stub with an `artifact=<id>` pointer, look up the
+     * full payload in ToolArtifactStore and replace the stub content in-place.
+     * Uses a single batched `WHERE id IN (...)` lookup (no N+1 queries).
+     * Touches `last_used_at` on every hydrated artifact in a single batch.
+     *
+     * Failure mode: if a lookup returns null (artifact missing), leave the stub
+     * unchanged and increment hydrationMisses.
+     *
+     * Returns diagnostics counters.
+     */
+    private hydrateActiveTurnArtifacts;
     /**
      * Compose a complete message array for sending to an LLM.
      *
@@ -122,7 +283,7 @@ export declare class Compositor {
         /** Model string for budget resolution. If omitted, falls back to defaultTokenBudget. */
         model?: string;
     }): Promise<void>;
-    refreshRedisGradient(agentId: string, sessionKey: string, db: DatabaseSync, tokenBudget?: number): Promise<void>;
+    refreshRedisGradient(agentId: string, sessionKey: string, db: DatabaseSync, tokenBudget?: number, historyDepth?: number): Promise<void>;
     /**
      * Get slot content: try Redis first, fall back to SQLite.
      */
@@ -145,6 +306,7 @@ export declare class Compositor {
      * Returns [content, factCount, scopeFilteredCount] or null if DB unavailable.
      */
     private buildFactsFromDb;
+    private buildFactSectionsFromDb;
     /**
      * Build knowledge content from library DB.
      * Prioritizes high-confidence, non-superseded entries.