@graphorin/memory 0.5.0 → 0.6.1

package/dist/consolidator/types.d.ts

@@ -1,8 +1,9 @@
 import { MemoryStoreAdapter } from "../internal/storage-adapter.js";
 import { ContextualRetrievalMode } from "../internal/contextualize.js";
 import { EpisodicMemory } from "../tiers/episodic-memory.js";
-import { SemanticMemory } from "../tiers/semantic-memory.js";
 import { SalienceWeights } from "./decay.js";
+import { SemanticMemory } from "../tiers/semantic-memory.js";
+import { WorkingMemory } from "../tiers/working-memory.js";
 import { Provider, SessionScope, Tracer } from "@graphorin/core";
 
 //#region src/consolidator/types.d.ts
@@ -17,7 +18,7 @@ import { Provider, SessionScope, Tracer } from "@graphorin/core";
 type ConsolidatorTriggerSpec = `turn:${number}` | `idle:${string}` | `cron:${string}` | `event:${string}` | `budget:${number}`;
 /**
  * Tier preset that selects a consolidator behaviour bundle. The
- * `'free'` preset is the default per DEC-144 / ADR-038 — no LLM call
+ * `'free'` preset is the default per DEC-144 / ADR-038 - no LLM call
  * fires until the operator opts in.
  *
  * @stable
@@ -33,7 +34,12 @@ interface ConsolidatorTriggerReason {
   readonly value?: string | number;
 }
 /**
- * Hard cost ceilings enforced atomically per UTC day. The default
+ * Daily cost ceilings, tracked per budget window. How a breach is
+ * handled depends on {@link OnBudgetExceed}: `'pause'` / `'throw'`
+ * enforce, `'log'` (the shipped standard/full presets) only WARNs and
+ * keeps running. The USD leg accumulates only when a `priceUsage`
+ * pricer is configured (memory-consolidation-02) - without one every
+ * call prices at $0 and `maxCostPerDay` can never trip. The default
  * ceiling shape per tier is captured in
  * {@link CONSOLIDATOR_TIER_DEFAULTS}.
  *
@@ -61,7 +67,7 @@ interface ConsolidatorCeilings {
 }
 /**
  * Behaviour applied by the budget enforcer when a ceiling is hit
- * mid-run. `'pause'` is the conservative default — the consolidator
+ * mid-run. `'pause'` is the conservative default - the consolidator
  * skips subsequent runs until the next budget reset; `'log'` keeps
  * running with a WARN; `'throw'` raises a typed
  * {@link BudgetExceededError}.
@@ -87,14 +93,14 @@ interface ConsolidatorConfig {
   readonly ceilings: ConsolidatorCeilings;
   readonly onExceed: OnBudgetExceed;
   /**
-   * Advisory label for the standard phase's model — recorded on spans /
+   * Advisory label for the standard phase's model - recorded on spans /
    * run telemetry only (MCON-7). Routing happens via
    * `CreateConsolidatorOptions.cheapProvider`; this string disables
    * nothing.
    */
   readonly cheapModel: string | null;
   /**
-   * Advisory label for the deep phase's model — telemetry only
+   * Advisory label for the deep phase's model - telemetry only
    * (MCON-7). Routing happens via
    * `CreateConsolidatorOptions.deepProvider`.
    */
@@ -107,7 +113,7 @@ interface ConsolidatorConfig {
   /**
    * Capacity-bounded eviction target for the light phase (X-1). When set,
    * each light pass archives the lowest-salience live facts in the LRU
-   * decay window down to this many — **cost / staleness control, not an
+   * decay window down to this many - **cost / staleness control, not an
    * accuracy lever**. `null` (the default at every tier) leaves storage
    * unbounded, so behaviour is identical to pre-X-1. Archiving is a soft,
    * recoverable move; nothing is hard-deleted.
@@ -135,9 +141,9 @@ interface ConsolidatorConfig {
   readonly formEpisodes: boolean;
   /**
    * Ask the episode-summarization call for an LLM importance score
-   * (1–10, normalized to `[0, 1]`) so episodic triple-signal retrieval
+   * (1-10, normalized to `[0, 1]`) so episodic triple-signal retrieval
    * (recency × relevance × importance) runs on all three signals
-   * (P1-2). Importance is always a *soft* signal — it never gates
+   * (P1-2). Importance is always a *soft* signal - it never gates
    * retention. Defaults track {@link formEpisodes}.
    */
   readonly importanceScoring: boolean;
@@ -146,7 +152,7 @@ interface ConsolidatorConfig {
    * injection-clean **extraction** fact as `active` instead of quarantined, so
    * routine distillation surfaces in default recall without a manual
    * `memory review --promote`. Injection-flagged facts always stay quarantined
-   * — the security gate is preserved — and episodes / insights / induced
+   * - the security gate is preserved - and episodes / insights / induced
    * procedures are unaffected (they remain quarantined-until-validated).
    * Defaults **off** at every tier: it trades the fail-safe default for
    * convenience and is an explicit operator opt-in.
@@ -158,7 +164,7 @@ interface ConsolidatorConfig {
    * higher-order, cited insights over recent memories (Generative
    * Agents). Insights land quarantined + `provenance: 'reflection'` and
    * are ranked below the facts they cite. Defaults **on at the `full`
-   * tier only** (off at `free` / `cheap` / `standard` / `custom`) — it
+   * tier only** (off at `free` / `cheap` / `standard` / `custom`) - it
    * is the most LLM-intensive phase. A no-op without an episodic tier
    * or an insight-capable storage adapter.
    */
@@ -175,14 +181,25 @@ interface ConsolidatorConfig {
    * Contextual retrieval for facts written by the standard phase (P1-3).
    * `'late-chunk'` (default at every tier) relies on the offline
    * situating-context prefix the shared {@link SemanticMemory} computes
-   * for every write — no extra LLM call. `'llm'` is the opt-in
+   * for every write - no extra LLM call. `'llm'` is the opt-in
    * enrichment: the standard phase spends one budgeted cheap-model call
-   * per additive write to author a 1–2 sentence situating prefix, then
+   * per additive write to author a 1-2 sentence situating prefix, then
    * passes it as the write's index text. `'off'` indexes the bare text.
-   * The `'llm'` mode is **consolidator-only** by construction — the hot
+   * The `'llm'` mode is **consolidator-only** by construction - the hot
    * write path never has a provider for contextualization.
    */
   readonly contextualRetrieval: ContextualRetrievalMode;
+  /**
+   * Maintain the learned-context digest block (D3): after the deep
+   * phase, one budgeted LLM call rewrites the reserved
+   * `learned_context` working block from the previous digest + recent
+   * episodes / active insights / active procedures, so the system
+   * prompt carries a compact standing summary. Defaults **off at every
+   * tier** (Wave-D trial) - a no-op without a working tier handle.
+   */
+  readonly learnedContext: boolean;
+  /** Character bound enforced on the learned-context digest. Default `1200`. */
+  readonly learnedContextMaxChars: number;
 }
 /**
  * Per-phase last-run snapshot surfaced inside
@@ -216,7 +233,7 @@ interface ConsolidatorBudgetSnapshot {
  * Status snapshot returned by {@link Consolidator.status}.
  *
  * Public shape: `{ tier, queueDepth, dlqSize, lastRuns,
- * budgetRemaining, deferredRuns }` — extended with a few additional
+ * budgetRemaining, deferredRuns }` - extended with a few additional
  * fields the server health endpoint and the
  * `graphorin consolidator status` CLI consume.
  *
@@ -245,7 +262,7 @@ interface ConsolidatorStatus {
   readonly deferredRuns: number;
   readonly emptyExtractions: number;
   readonly budget: ConsolidatorBudgetSnapshot;
-  /** Spec alias — surfaces remaining-budget figures at the top level. */
+  /** Spec alias - surfaces remaining-budget figures at the top level. */
   readonly budgetRemaining: {
     readonly tokens: number;
     readonly costUsd: number;
@@ -267,6 +284,8 @@ interface PhaseOutcome {
   readonly episodesFormed: number;
   /** Insights synthesized by the deep-phase reflection pass (P1-1). */
   readonly insightsCreated: number;
+  /** True when the learned-context digest block was rewritten (D3). */
+  readonly learnedContextUpdated?: boolean;
   readonly noiseFilteredCount: number;
   readonly emptyExtractions: number;
   readonly llmTokensUsed: number;
@@ -290,7 +309,7 @@ type PhaseListener = (outcome: PhaseOutcome & {
  */
 interface CreateConsolidatorOptions {
   /**
-   * Storage adapter — supplies the consolidator state, runs, DLQ,
+   * Storage adapter - supplies the consolidator state, runs, DLQ,
    * and per-tier helpers. The default `@graphorin/store-sqlite`
    * adapter exposes everything by construction.
    */
@@ -309,6 +328,13 @@ interface CreateConsolidatorOptions {
    * processed slice (P1-2). Omitted ⇒ episode formation is skipped.
    */
   readonly episodic?: EpisodicMemory;
+  /**
+   * The {@link WorkingMemory} tier instance from the parent
+   * `createMemory(...)` facade (D3). Required for the learned-context
+   * pass - without it the pass is a silent no-op even when
+   * `learnedContext` is enabled.
+   */
+  readonly working?: WorkingMemory;
   /**
    * Provider used by the standard + deep phases. Required when the
    * tier enables either phase; ignored when the active phases
@@ -316,15 +342,31 @@ interface CreateConsolidatorOptions {
    */
   readonly provider?: Provider | null;
   readonly tracer?: Tracer;
-  /** Override the wall clock — used by tests. */
+  /** Override the wall clock - used by tests. */
   readonly now?: () => number;
-  /** Random source for stable run ids — used by tests. */
+  /** Random source for stable run ids - used by tests. */
   readonly randomId?: () => string;
   readonly triggers?: ReadonlyArray<ConsolidatorTriggerSpec>;
   readonly tier?: ConsolidatorTier;
   readonly phases?: ReadonlyArray<ConsolidatorPhase>;
   readonly ceilings?: Partial<ConsolidatorCeilings>;
   readonly onExceed?: OnBudgetExceed;
+  /**
+   * USD pricer for phase LLM usage (memory-consolidation-02). Wire it
+   * to `@graphorin/pricing`'s `calculateCost` (or any per-token rate)
+   * so the `maxCostPerDay` ceiling can actually accumulate spend -
+   * without it every phase prices its calls at $0 and the USD ceiling
+   * never trips at any tier.
+   *
+   * ```ts
+   * priceUsage: ({ promptTokens, completionTokens }) =>
+   *   (promptTokens * 3 + completionTokens * 15) / 1_000_000
+   * ```
+   */
+  readonly priceUsage?: (usage: {
+    promptTokens: number;
+    completionTokens: number;
+  }) => number;
   /**
    * Provider routed to the standard phase (extraction / episode /
    * reconcile / situating-context calls) when set (MCON-7). Falls back
@@ -369,11 +411,15 @@ interface CreateConsolidatorOptions {
   readonly reflectionMaxQuestions?: number;
   /** Override the per-tier {@link ConsolidatorConfig.contextualRetrieval} default (P1-3). */
   readonly contextualRetrieval?: ContextualRetrievalMode;
+  /** Override the per-tier {@link ConsolidatorConfig.learnedContext} default (D3). */
+  readonly learnedContext?: boolean;
+  /** Override the {@link ConsolidatorConfig.learnedContextMaxChars} default (D3). */
+  readonly learnedContextMaxChars?: number;
   /** Default scope used by event triggers + the manual `fireNow` path. */
   readonly defaultScope?: SessionScope;
 }
 /**
- * Tier preset table. The defaults follow ADR-038 §4 — `'free'`
+ * Tier preset table. The defaults follow ADR-038 §4 - `'free'`
  * disables every LLM phase and pins zero ceilings, the upper tiers
  * widen the budget envelope progressively.
  *
@@ -391,6 +437,8 @@ declare const CONSOLIDATOR_TIER_DEFAULTS: Readonly<Record<ConsolidatorTier, {
   readonly importanceThreshold: number;
   readonly reflectionMaxQuestions: number;
   readonly contextualRetrieval: ContextualRetrievalMode;
+  readonly learnedContext: boolean;
+  readonly learnedContextMaxChars: number;
 }>>;
 //#endregion
 export { CONSOLIDATOR_TIER_DEFAULTS, ConsolidatorBudgetSnapshot, ConsolidatorCeilings, ConsolidatorConfig, ConsolidatorLastRuns, ConsolidatorPhase, ConsolidatorStatus, ConsolidatorTier, ConsolidatorTriggerReason, ConsolidatorTriggerSpec, CreateConsolidatorOptions, OnBudgetExceed, PhaseListener, PhaseOutcome };

package/dist/consolidator/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/consolidator/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;AA8MuD,KAnL3C,uBAAA,GAmL2C,QAAA,MAAA,EAAA,GAAA,QAAA,MAAA,EAAA,GAAA,QAAA,MAAA,EAAA,GAAA,SAAA,MAAA,EAAA,GAAA,UAAA,MAAA,EAAA;AAWvD;AAcA;AAsBA;;;;;AAGmB,KAvNP,gBAAA,GAuNO,MAAA,GAAA,OAAA,GAAA,UAAA,GAAA,MAAA,GAAA,QAAA;;;;;AA6BnB;AAuBY,UApQK,yBAAA,CAoQQ;EACd,SAAA,IAAA,EAAA,MAAA,GAAA,MAAA,GAAA,MAAA,GAAA,OAAA,GAAA,QAAA,GAAA,QAAA;EACS,SAAA,KAAA,CAAA,EAAA,MAAA,GAAA,MAAA;;;AAUpB;;;;;;AAgCoC,UApSnB,oBAAA,CAoSmB;EAAd,SAAA,eAAA,EAAA,MAAA;EACJ,SAAA,aAAA,EAAA,MAAA;EACgB;;;;;;EAaR,SAAA,iBAAA,EAAA,MAAA;EAIA,SAAA,gBAAA,EAAA,MAAA;EAOG;;;;AAkC7B;;;EAKqC,SAAA,UAAA,EAAA,MAAA;;;;;;;;;;;KAvUzB,cAAA;;;;;;KAOA,iBAAA;;;;;;UAOK,kBAAA;qBACI,cAAc;iBAClB;mBACE,cAAc;qBACZ;qBACA;;;;;;;;;;;;;;;yBAeI;;;;;;;;;;;;;;;;;;;4BAmBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCA+DI;;;;;;;;;;UAWf,oBAAA;;;;;;;;;;;;;UAcA,0BAAA;;;;;;;;;;;;;;;;;;;;;UAsBA,kBAAA;iBACA;qBACI,cAAc;mBAChB,cAAc;;;;;;uBAMV;;qBAEF;;;;;;;mBAOF;;;;;;;;;;;;;UAcF,YAAA;kBACC;;;;;;;;;;;;;;;;;;;;;KAsBN,aAAA,aACD;kBACS;oBACE;;;;;;;UASL,yBAAA;;;;;;kBAMC;;;;;;;qBAOG;;;;;;;sBAOC;;;;;;sBAMA;oBACF;;;;;sBAKE,cAAc;kBAClB;oBACE,cAAc;sBACZ,QAAQ;sBACR;;;;;;2BAMK;;;;;0BAKD;;;;0BAIA;;;;;;;6BAOG;;;;;;;;;;;;;;;;;;;;;;iCAsBI;;0BAEP;;;;;;;;;cAUb,4BAA4B,SACvC,OACE;qBAEqB;mBACF,cAAc;;;qBAGZ;;;;;;gCAMW"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/consolidator/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;AAoNuD,KAxL3C,uBAAA,GAwL2C,QAAA,MAAA,EAAA,GAAA,QAAA,MAAA,EAAA,GAAA,QAAA,MAAA,EAAA,GAAA,SAAA,MAAA,EAAA,GAAA,UAAA,MAAA,EAAA;AAsBvD;AAcA;AAsBA;;;;;AAGmB,KAvOP,gBAAA,GAuOO,MAAA,GAAA,OAAA,GAAA,UAAA,GAAA,MAAA,GAAA,QAAA;;;;;AA6BnB;AAyBY,UAtRK,yBAAA,CAsRQ;EACd,SAAA,IAAA,EAAA,MAAA,GAAA,MAAA,GAAA,MAAA,GAAA,OAAA,GAAA,QAAA,GAAA,QAAA;EACS,SAAA,KAAA,CAAA,EAAA,MAAA,GAAA,MAAA;;;AAUpB;;;;;;;;;;;AAyCoB,UA1TH,oBAAA,CA0TG;EACU,SAAA,eAAA,EAAA,MAAA;EAAR,SAAA,aAAA,EAAA,MAAA;EACA;;;;;;EA+DI,SAAA,iBAAA,EAAA,MAAA;EAAY,SAAA,gBAAA,EAAA,MAAA;EAUzB;;;;;;;EACX,SAAA,UAAA,EAAA,MAAA;;;;;;;;;;;KAxWU,cAAA;;;;;;KAOA,iBAAA;;;;;;UAOK,kBAAA;qBACI,cAAc;iBAClB;mBACE,cAAc;qBACZ;qBACA;;;;;;;;;;;;;;;yBAeI;;;;;;;;;;;;;;;;;;;4BAmBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCA+DI;;;;;;;;;;;;;;;;;;;;;UAsBf,oBAAA;;;;;;;;;;;;;UAcA,0BAAA;;;;;;;;;;;;;;;;;;;;;UAsBA,kBAAA;iBACA;qBACI,cAAc;mBAChB,cAAc;;;;;;uBAMV;;qBAEF;;;;;;;mBAOF;;;;;;;;;;;;;UAcF,YAAA;kBACC;;;;;;;;;;;;;;;;;;;;;;;KAwBN,aAAA,aACD;kBACS;oBACE;;;;;;;UASL,yBAAA;;;;;;kBAMC;;;;;;;qBAOG;;;;;;;sBAOC;;;;;;;qBAOD;;;;;;sBAMC;oBACF;;;;;sBAKE,cAAc;kBAClB;oBACE,cAAc;sBACZ,QAAQ;sBACR;;;;;;;;;;;;;;;;;;;;;;2BAmBK;;;;;0BAKD;;;;0BAIA;;;;;;;6BAOG;;;;;;;;;;;;;;;;;;;;;;iCAsBI;;;;;;0BAMP;;;;;;;;;cAUb,4BAA4B,SACvC,OACE;qBAEqB;mBACF,cAAc;;;qBAGZ;;;;;;gCAMW"}

package/dist/consolidator/types.js

@@ -1,6 +1,6 @@
 //#region src/consolidator/types.ts
 /**
-* Tier preset table. The defaults follow ADR-038 §4 — `'free'`
+* Tier preset table. The defaults follow ADR-038 §4 - `'free'`
 * disables every LLM phase and pins zero ceilings, the upper tiers
 * widen the budget envelope progressively.
 *
@@ -24,7 +24,9 @@ const CONSOLIDATOR_TIER_DEFAULTS = Object.freeze({
 		reflection: false,
 		importanceThreshold: 3,
 		reflectionMaxQuestions: 3,
-		contextualRetrieval: "late-chunk"
+		contextualRetrieval: "late-chunk",
+		learnedContext: false,
+		learnedContextMaxChars: 1200
 	},
 	cheap: {
 		ceilings: {
@@ -43,7 +45,9 @@ const CONSOLIDATOR_TIER_DEFAULTS = Object.freeze({
 		reflection: false,
 		importanceThreshold: 3,
 		reflectionMaxQuestions: 3,
-		contextualRetrieval: "late-chunk"
+		contextualRetrieval: "late-chunk",
+		learnedContext: false,
+		learnedContextMaxChars: 1200
 	},
 	standard: {
 		ceilings: {
@@ -66,7 +70,9 @@ const CONSOLIDATOR_TIER_DEFAULTS = Object.freeze({
 		reflection: false,
 		importanceThreshold: 3,
 		reflectionMaxQuestions: 3,
-		contextualRetrieval: "late-chunk"
+		contextualRetrieval: "late-chunk",
+		learnedContext: false,
+		learnedContextMaxChars: 1200
 	},
 	full: {
 		ceilings: {
@@ -89,7 +95,9 @@ const CONSOLIDATOR_TIER_DEFAULTS = Object.freeze({
 		reflection: true,
 		importanceThreshold: 3,
 		reflectionMaxQuestions: 3,
-		contextualRetrieval: "late-chunk"
+		contextualRetrieval: "late-chunk",
+		learnedContext: false,
+		learnedContextMaxChars: 1200
 	},
 	custom: {
 		ceilings: {
@@ -108,7 +116,9 @@ const CONSOLIDATOR_TIER_DEFAULTS = Object.freeze({
 		reflection: false,
 		importanceThreshold: 3,
 		reflectionMaxQuestions: 3,
-		contextualRetrieval: "late-chunk"
+		contextualRetrieval: "late-chunk",
+		learnedContext: false,
+		learnedContextMaxChars: 1200
 	}
 });
 

package/dist/consolidator/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":["CONSOLIDATOR_TIER_DEFAULTS: Readonly<\n  Record<\n    ConsolidatorTier,\n    {\n      readonly ceilings: ConsolidatorCeilings;\n      readonly phases: ReadonlyArray<ConsolidatorPhase>;\n      readonly cheapModel: string | null;\n      readonly deepModel: string | null;\n      readonly onExceed: OnBudgetExceed;\n      readonly formEpisodes: boolean;\n      readonly importanceScoring: boolean;\n      readonly reflection: boolean;\n      readonly importanceThreshold: number;\n      readonly reflectionMaxQuestions: number;\n      readonly contextualRetrieval: ContextualRetrievalMode;\n    }\n  >\n>"],"sources":["../../src/consolidator/types.ts"],"sourcesContent":["/**\n * Public types for the Phase 10c consolidator runtime.\n *\n * The consolidator is the background pipeline that turns raw\n * conversation turns into long-lived facts and episodes. The runtime\n * has three phases (`light` / `standard` / `deep`), an explicit cost\n * envelope, an idempotent cursor, a wait-then-defer lock, and a\n * dead-letter queue for retry-able failures. The binding architecture\n * references are DEC-133 / DEC-134 / ADR-038.\n *\n * @packageDocumentation\n */\n\nimport type { Provider, SessionScope, Tracer } from '@graphorin/core';\nimport type { ContextualRetrievalMode } from '../internal/contextualize.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\nimport type { EpisodicMemory } from '../tiers/episodic-memory.js';\nimport type { SemanticMemory } from '../tiers/semantic-memory.js';\nimport type { SalienceWeights } from './decay.js';\n\n/**\n * Trigger discriminator. The `'turn:N'` and `'idle:Xm'` variants are\n * the production defaults per DEC-133. `'cron:EXPR'`, `'event:NAME'`\n * and `'budget:N'` are opt-in.\n *\n * @stable\n */\nexport type ConsolidatorTriggerSpec =\n  | `turn:${number}`\n  | `idle:${string}`\n  | `cron:${string}`\n  | `event:${string}`\n  | `budget:${number}`;\n\n/**\n * Tier preset that selects a consolidator behaviour bundle. The\n * `'free'` preset is the default per DEC-144 / ADR-038 — no LLM call\n * fires until the operator opts in.\n *\n * @stable\n */\nexport type ConsolidatorTier = 'free' | 'cheap' | 'standard' | 'full' | 'custom';\n\n/**\n * Triggering reason surfaced through `Consolidator.trigger(...)`.\n *\n * @stable\n */\nexport interface ConsolidatorTriggerReason {\n  readonly kind: 'turn' | 'idle' | 'cron' | 'event' | 'budget' | 'manual';\n  readonly value?: string | number;\n}\n\n/**\n * Hard cost ceilings enforced atomically per UTC day. The default\n * ceiling shape per tier is captured in\n * {@link CONSOLIDATOR_TIER_DEFAULTS}.\n *\n * @stable\n */\nexport interface ConsolidatorCeilings {\n  readonly maxTokensPerDay: number;\n  readonly maxCostPerDay: number;\n  /**\n   * ADVISORY (MCON-8): the per-scope lock serializes runs, so effective\n   * concurrency is always 1 per scope regardless of this value. The\n   * field is retained for forward compatibility; it enforces nothing\n   * today.\n   */\n  readonly maxConcurrentRuns: number;\n  readonly maxRunDurationMs: number;\n  /**\n   * Minimum quiet period between non-manual runs per scope (MCON-8).\n   * After each run the runtime persists `nextEligibleAt = now +\n   * cooldownMs`; trigger-driven runs (`turn` / `idle` / `cron` /\n   * `event` / `budget`) inside that window defer with reason\n   * `'cooldown'`. Manual `fireNow(...)` and DLQ replays bypass it.\n   */\n  readonly cooldownMs: number;\n}\n\n/**\n * Behaviour applied by the budget enforcer when a ceiling is hit\n * mid-run. `'pause'` is the conservative default — the consolidator\n * skips subsequent runs until the next budget reset; `'log'` keeps\n * running with a WARN; `'throw'` raises a typed\n * {@link BudgetExceededError}.\n *\n * @stable\n */\nexport type OnBudgetExceed = 'pause' | 'log' | 'throw';\n\n/**\n * Phase identifier used by the runtime + audit rows.\n *\n * @stable\n */\nexport type ConsolidatorPhase = 'light' | 'standard' | 'deep';\n\n/**\n * Locked-down configuration accepted by `createConsolidator(...)`.\n *\n * @stable\n */\nexport interface ConsolidatorConfig {\n  readonly triggers: ReadonlyArray<ConsolidatorTriggerSpec>;\n  readonly tier: ConsolidatorTier;\n  readonly phases: ReadonlyArray<ConsolidatorPhase>;\n  readonly ceilings: ConsolidatorCeilings;\n  readonly onExceed: OnBudgetExceed;\n  /**\n   * Advisory label for the standard phase's model — recorded on spans /\n   * run telemetry only (MCON-7). Routing happens via\n   * `CreateConsolidatorOptions.cheapProvider`; this string disables\n   * nothing.\n   */\n  readonly cheapModel: string | null;\n  /**\n   * Advisory label for the deep phase's model — telemetry only\n   * (MCON-7). Routing happens via\n   * `CreateConsolidatorOptions.deepProvider`.\n   */\n  readonly deepModel: string | null;\n  readonly budgetResetSemantics: 'utc' | 'local' | 'sliding-24h';\n  readonly noiseFilters: ReadonlyArray<'default' | 'minimal' | 'none'>;\n  readonly lockWaitMs: number;\n  readonly decayTauDays: number;\n  readonly decayArchiveThreshold: number;\n  /**\n   * Capacity-bounded eviction target for the light phase (X-1). When set,\n   * each light pass archives the lowest-salience live facts in the LRU\n   * decay window down to this many — **cost / staleness control, not an\n   * accuracy lever**. `null` (the default at every tier) leaves storage\n   * unbounded, so behaviour is identical to pre-X-1. Archiving is a soft,\n   * recoverable move; nothing is hard-deleted.\n   */\n  readonly decayCapacity: number | null;\n  /**\n   * Weights for the multi-signal salience score (X-1) that orders both\n   * threshold archiving and capacity eviction. Defaults to\n   * {@link DEFAULT_SALIENCE_WEIGHTS}; with neutral importance, active\n   * status, and first-party provenance salience equals plain retention.\n   */\n  readonly salienceWeights: SalienceWeights;\n  readonly maxStandardBatchSize: number;\n  readonly maxDeepConflictsPerRun: number;\n  readonly dlqMaxRetries: number;\n  readonly dlqBaseBackoffMs: number;\n  readonly dlqMaxBackoffMs: number;\n  /**\n   * Auto-form a quarantined episode from each processed standard-phase\n   * slice (P1-2). Defaults on at the `standard`+ tiers, off at `free` /\n   * `cheap` / `custom`. The episode summary is one budgeted LLM call;\n   * when the budget is exhausted (or no episodic tier is wired) the\n   * phase degrades to fact-only behaviour.\n   */\n  readonly formEpisodes: boolean;\n  /**\n   * Ask the episode-summarization call for an LLM importance score\n   * (1–10, normalized to `[0, 1]`) so episodic triple-signal retrieval\n   * (recency × relevance × importance) runs on all three signals\n   * (P1-2). Importance is always a *soft* signal — it never gates\n   * retention. Defaults track {@link formEpisodes}.\n   */\n  readonly importanceScoring: boolean;\n  /**\n   * Auto-promotion policy (MCON-2). When `true`, the standard phase admits an\n   * injection-clean **extraction** fact as `active` instead of quarantined, so\n   * routine distillation surfaces in default recall without a manual\n   * `memory review --promote`. Injection-flagged facts always stay quarantined\n   * — the security gate is preserved — and episodes / insights / induced\n   * procedures are unaffected (they remain quarantined-until-validated).\n   * Defaults **off** at every tier: it trades the fail-safe default for\n   * convenience and is an explicit operator opt-in.\n   */\n  readonly autoPromoteExtraction: boolean;\n  /**\n   * Run the deep-phase reflection pass (P1-1): when accumulated episode\n   * importance crosses {@link importanceThreshold}, synthesize\n   * higher-order, cited insights over recent memories (Generative\n   * Agents). Insights land quarantined + `provenance: 'reflection'` and\n   * are ranked below the facts they cite. Defaults **on at the `full`\n   * tier only** (off at `free` / `cheap` / `standard` / `custom`) — it\n   * is the most LLM-intensive phase. A no-op without an episodic tier\n   * or an insight-capable storage adapter.\n   */\n  readonly reflection: boolean;\n  /**\n   * Sum of recent episode importance (each in `[0, 1]`) at or above\n   * which {@link reflection} fires. Below it the pass makes no LLM\n   * call. Defaults to `3`.\n   */\n  readonly importanceThreshold: number;\n  /** Upper bound on salient questions reflection asks per pass. Defaults to `3`. */\n  readonly reflectionMaxQuestions: number;\n  /**\n   * Contextual retrieval for facts written by the standard phase (P1-3).\n   * `'late-chunk'` (default at every tier) relies on the offline\n   * situating-context prefix the shared {@link SemanticMemory} computes\n   * for every write — no extra LLM call. `'llm'` is the opt-in\n   * enrichment: the standard phase spends one budgeted cheap-model call\n   * per additive write to author a 1–2 sentence situating prefix, then\n   * passes it as the write's index text. `'off'` indexes the bare text.\n   * The `'llm'` mode is **consolidator-only** by construction — the hot\n   * write path never has a provider for contextualization.\n   */\n  readonly contextualRetrieval: ContextualRetrievalMode;\n}\n\n/**\n * Per-phase last-run snapshot surfaced inside\n * {@link ConsolidatorStatus.lastRuns}. Each entry carries the\n * timestamp of the most recent **completed** invocation for that\n * phase (`undefined` when the phase has never run).\n *\n * @stable\n */\nexport interface ConsolidatorLastRuns {\n  readonly light?: string;\n  readonly standard?: string;\n  readonly deep?: string;\n}\n\n/**\n * Budget snapshot block of {@link ConsolidatorStatus}. Surfaces\n * both the absolute usage and the remaining envelope so consumers\n * (CLI, server health endpoint) can render the operator dashboard\n * without doing the math themselves.\n *\n * @stable\n */\nexport interface ConsolidatorBudgetSnapshot {\n  readonly tokensUsedToday: number;\n  readonly costUsedToday: number;\n  readonly tokensRemaining: number;\n  readonly costRemaining: number;\n  readonly resetAt: string;\n}\n\n/**\n * Status snapshot returned by {@link Consolidator.status}.\n *\n * Public shape: `{ tier, queueDepth, dlqSize, lastRuns,\n * budgetRemaining, deferredRuns }` — extended with a few additional\n * fields the server health endpoint and the\n * `graphorin consolidator status` CLI consume.\n *\n * `queueDepth` is an alias for {@link pendingConflicts} (the size\n * of the deep-phase queue); both fields are populated for backwards\n * compatibility.\n *\n * @stable\n */\nexport interface ConsolidatorStatus {\n  readonly tier: ConsolidatorTier;\n  readonly triggers: ReadonlyArray<ConsolidatorTriggerSpec>;\n  readonly phases: ReadonlyArray<ConsolidatorPhase>;\n  readonly running: boolean;\n  readonly paused: boolean;\n  /** Most recent completed run timestamp (any phase). */\n  readonly lastRunAt?: string;\n  /** Phase of the most recent completed run. */\n  readonly lastPhase?: ConsolidatorPhase;\n  /** Per-phase last-completed timestamps surfaced for CLI / dashboard. */\n  readonly lastRuns: ConsolidatorLastRuns;\n  /** Spec alias for {@link pendingConflicts}. */\n  readonly queueDepth: number;\n  readonly pendingConflicts: number;\n  readonly dlqSize: number;\n  readonly deferredRuns: number;\n  readonly emptyExtractions: number;\n  readonly budget: ConsolidatorBudgetSnapshot;\n  /** Spec alias — surfaces remaining-budget figures at the top level. */\n  readonly budgetRemaining: {\n    readonly tokens: number;\n    readonly costUsd: number;\n  };\n}\n\n/**\n * Outcome surfaced by every phase invocation. Recorded into\n * `consolidator_runs` and emitted on the AISpan.\n *\n * @stable\n */\nexport interface PhaseOutcome {\n  readonly phase: ConsolidatorPhase;\n  readonly status: 'completed' | 'failed' | 'deferred' | 'partial';\n  readonly factsCreated: number;\n  readonly factsUpdated: number;\n  readonly conflictsResolved: number;\n  /** Episodes auto-formed from the processed slice (P1-2). */\n  readonly episodesFormed: number;\n  /** Insights synthesized by the deep-phase reflection pass (P1-1). */\n  readonly insightsCreated: number;\n  readonly noiseFilteredCount: number;\n  readonly emptyExtractions: number;\n  readonly llmTokensUsed: number;\n  readonly llmCostUsd: number | null;\n  readonly errorMessage: string | null;\n}\n\n/**\n * Listener callback subscribed via\n * {@link Consolidator.onPhaseFinished}. Useful for tests + observers.\n *\n * @stable\n */\nexport type PhaseListener = (\n  outcome: PhaseOutcome & {\n    readonly scope: SessionScope;\n    readonly trigger: ConsolidatorTriggerReason;\n  },\n) => void;\n\n/**\n * Options accepted by {@link createConsolidator}.\n *\n * @stable\n */\nexport interface CreateConsolidatorOptions {\n  /**\n   * Storage adapter — supplies the consolidator state, runs, DLQ,\n   * and per-tier helpers. The default `@graphorin/store-sqlite`\n   * adapter exposes everything by construction.\n   */\n  readonly store: MemoryStoreAdapter;\n  /**\n   * The {@link SemanticMemory} tier instance from the parent\n   * `createMemory(...)` facade. The standard phase routes every\n   * extracted fact through `semantic.remember(...)` so the conflict\n   * pipeline (Phase 10b) handles dedup / supersede.\n   */\n  readonly semantic: SemanticMemory;\n  /**\n   * The {@link EpisodicMemory} tier instance from the parent\n   * `createMemory(...)` facade. When supplied (and `formEpisodes` is\n   * on) the standard phase auto-forms a quarantined episode per\n   * processed slice (P1-2). Omitted ⇒ episode formation is skipped.\n   */\n  readonly episodic?: EpisodicMemory;\n  /**\n   * Provider used by the standard + deep phases. Required when the\n   * tier enables either phase; ignored when the active phases\n   * collapse to `['light']`.\n   */\n  readonly provider?: Provider | null;\n  readonly tracer?: Tracer;\n  /** Override the wall clock — used by tests. */\n  readonly now?: () => number;\n  /** Random source for stable run ids — used by tests. */\n  readonly randomId?: () => string;\n  readonly triggers?: ReadonlyArray<ConsolidatorTriggerSpec>;\n  readonly tier?: ConsolidatorTier;\n  readonly phases?: ReadonlyArray<ConsolidatorPhase>;\n  readonly ceilings?: Partial<ConsolidatorCeilings>;\n  readonly onExceed?: OnBudgetExceed;\n  /**\n   * Provider routed to the standard phase (extraction / episode /\n   * reconcile / situating-context calls) when set (MCON-7). Falls back\n   * to `provider`. Pair with `cheapModel` for the telemetry label.\n   */\n  readonly cheapProvider?: Provider | null;\n  /**\n   * Provider routed to the deep phase (conflict judge) and the\n   * reflection pass when set (MCON-7). Falls back to `provider`.\n   */\n  readonly deepProvider?: Provider | null;\n  readonly cheapModel?: string | null;\n  readonly deepModel?: string | null;\n  readonly budgetResetSemantics?: 'utc' | 'local' | 'sliding-24h';\n  readonly noiseFilters?: ReadonlyArray<'default' | 'minimal' | 'none'>;\n  readonly lockWaitMs?: number;\n  readonly decayTauDays?: number;\n  readonly decayArchiveThreshold?: number;\n  /** Override the {@link ConsolidatorConfig.decayCapacity} default (X-1). */\n  readonly decayCapacity?: number | null;\n  /** Override the {@link ConsolidatorConfig.salienceWeights} default (X-1). */\n  readonly salienceWeights?: SalienceWeights;\n  readonly maxStandardBatchSize?: number;\n  readonly maxDeepConflictsPerRun?: number;\n  readonly dlqMaxRetries?: number;\n  readonly dlqBaseBackoffMs?: number;\n  readonly dlqMaxBackoffMs?: number;\n  /** Override the per-tier {@link ConsolidatorConfig.formEpisodes} default (P1-2). */\n  readonly formEpisodes?: boolean;\n  /** Override the per-tier {@link ConsolidatorConfig.importanceScoring} default (P1-2). */\n  readonly importanceScoring?: boolean;\n  /**\n   * Opt in to auto-promotion of injection-clean extraction facts (MCON-2).\n   * Defaults `false`. See {@link ConsolidatorConfig.autoPromoteExtraction}.\n   */\n  readonly autoPromoteExtraction?: boolean;\n  /** Override the per-tier {@link ConsolidatorConfig.reflection} default (P1-1). */\n  readonly reflection?: boolean;\n  /** Override the {@link ConsolidatorConfig.importanceThreshold} default (P1-1). */\n  readonly importanceThreshold?: number;\n  /** Override the {@link ConsolidatorConfig.reflectionMaxQuestions} default (P1-1). */\n  readonly reflectionMaxQuestions?: number;\n  /** Override the per-tier {@link ConsolidatorConfig.contextualRetrieval} default (P1-3). */\n  readonly contextualRetrieval?: ContextualRetrievalMode;\n  /** Default scope used by event triggers + the manual `fireNow` path. */\n  readonly defaultScope?: SessionScope;\n}\n\n/**\n * Tier preset table. The defaults follow ADR-038 §4 — `'free'`\n * disables every LLM phase and pins zero ceilings, the upper tiers\n * widen the budget envelope progressively.\n *\n * @stable\n */\nexport const CONSOLIDATOR_TIER_DEFAULTS: Readonly<\n  Record<\n    ConsolidatorTier,\n    {\n      readonly ceilings: ConsolidatorCeilings;\n      readonly phases: ReadonlyArray<ConsolidatorPhase>;\n      readonly cheapModel: string | null;\n      readonly deepModel: string | null;\n      readonly onExceed: OnBudgetExceed;\n      readonly formEpisodes: boolean;\n      readonly importanceScoring: boolean;\n      readonly reflection: boolean;\n      readonly importanceThreshold: number;\n      readonly reflectionMaxQuestions: number;\n      readonly contextualRetrieval: ContextualRetrievalMode;\n    }\n  >\n> = Object.freeze({\n  free: {\n    ceilings: {\n      maxTokensPerDay: 0,\n      maxCostPerDay: 0,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 5 * 60 * 1000,\n      cooldownMs: 60_000,\n    },\n    phases: ['light'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'pause',\n    formEpisodes: false,\n    importanceScoring: false,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n  },\n  cheap: {\n    ceilings: {\n      maxTokensPerDay: 50_000,\n      maxCostPerDay: 0.2,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 5 * 60 * 1000,\n      cooldownMs: 60_000,\n    },\n    phases: ['light', 'standard'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'pause',\n    formEpisodes: false,\n    importanceScoring: false,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n  },\n  standard: {\n    ceilings: {\n      maxTokensPerDay: 200_000,\n      maxCostPerDay: 1.0,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 10 * 60 * 1000,\n      cooldownMs: 30_000,\n    },\n    phases: ['light', 'standard', 'deep'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'log',\n    formEpisodes: true,\n    importanceScoring: true,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n  },\n  full: {\n    ceilings: {\n      maxTokensPerDay: 1_000_000,\n      maxCostPerDay: 5.0,\n      maxConcurrentRuns: 2,\n      maxRunDurationMs: 15 * 60 * 1000,\n      cooldownMs: 10_000,\n    },\n    phases: ['light', 'standard', 'deep'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'log',\n    formEpisodes: true,\n    importanceScoring: true,\n    reflection: true,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n  },\n  custom: {\n    ceilings: {\n      maxTokensPerDay: 0,\n      maxCostPerDay: 0,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 5 * 60 * 1000,\n      cooldownMs: 60_000,\n    },\n    phases: ['light'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'pause',\n    formEpisodes: false,\n    importanceScoring: false,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n  },\n});\n"],"mappings":";;;;;;;;AA4ZA,MAAaA,6BAiBT,OAAO,OAAO;CAChB,MAAM;EACJ,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAS;GAC3B,YAAY;GACb;EACD,QAAQ,CAAC,QAAQ;EACjB,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACtB;CACD,OAAO;EACL,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAS;GAC3B,YAAY;GACb;EACD,QAAQ,CAAC,SAAS,WAAW;EAC7B,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACtB;CACD,UAAU;EACR,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAU;GAC5B,YAAY;GACb;EACD,QAAQ;GAAC;GAAS;GAAY;GAAO;EACrC,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACtB;CACD,MAAM;EACJ,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAU;GAC5B,YAAY;GACb;EACD,QAAQ;GAAC;GAAS;GAAY;GAAO;EACrC,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACtB;CACD,QAAQ;EACN,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAS;GAC3B,YAAY;GACb;EACD,QAAQ,CAAC,QAAQ;EACjB,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACtB;CACF,CAAC"}
+{"version":3,"file":"types.js","names":["CONSOLIDATOR_TIER_DEFAULTS: Readonly<\n  Record<\n    ConsolidatorTier,\n    {\n      readonly ceilings: ConsolidatorCeilings;\n      readonly phases: ReadonlyArray<ConsolidatorPhase>;\n      readonly cheapModel: string | null;\n      readonly deepModel: string | null;\n      readonly onExceed: OnBudgetExceed;\n      readonly formEpisodes: boolean;\n      readonly importanceScoring: boolean;\n      readonly reflection: boolean;\n      readonly importanceThreshold: number;\n      readonly reflectionMaxQuestions: number;\n      readonly contextualRetrieval: ContextualRetrievalMode;\n      readonly learnedContext: boolean;\n      readonly learnedContextMaxChars: number;\n    }\n  >\n>"],"sources":["../../src/consolidator/types.ts"],"sourcesContent":["/**\n * Public types for the Phase 10c consolidator runtime.\n *\n * The consolidator is the background pipeline that turns raw\n * conversation turns into long-lived facts and episodes. The runtime\n * has three phases (`light` / `standard` / `deep`), an explicit cost\n * envelope, an idempotent cursor, a wait-then-defer lock, and a\n * dead-letter queue for retry-able failures. The binding architecture\n * references are DEC-133 / DEC-134 / ADR-038.\n *\n * @packageDocumentation\n */\n\nimport type { Provider, SessionScope, Tracer } from '@graphorin/core';\nimport type { ContextualRetrievalMode } from '../internal/contextualize.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\nimport type { EpisodicMemory } from '../tiers/episodic-memory.js';\nimport type { SemanticMemory } from '../tiers/semantic-memory.js';\nimport type { WorkingMemory } from '../tiers/working-memory.js';\nimport type { SalienceWeights } from './decay.js';\n\n/**\n * Trigger discriminator. The `'turn:N'` and `'idle:Xm'` variants are\n * the production defaults per DEC-133. `'cron:EXPR'`, `'event:NAME'`\n * and `'budget:N'` are opt-in.\n *\n * @stable\n */\nexport type ConsolidatorTriggerSpec =\n  | `turn:${number}`\n  | `idle:${string}`\n  | `cron:${string}`\n  | `event:${string}`\n  | `budget:${number}`;\n\n/**\n * Tier preset that selects a consolidator behaviour bundle. The\n * `'free'` preset is the default per DEC-144 / ADR-038 - no LLM call\n * fires until the operator opts in.\n *\n * @stable\n */\nexport type ConsolidatorTier = 'free' | 'cheap' | 'standard' | 'full' | 'custom';\n\n/**\n * Triggering reason surfaced through `Consolidator.trigger(...)`.\n *\n * @stable\n */\nexport interface ConsolidatorTriggerReason {\n  readonly kind: 'turn' | 'idle' | 'cron' | 'event' | 'budget' | 'manual';\n  readonly value?: string | number;\n}\n\n/**\n * Daily cost ceilings, tracked per budget window. How a breach is\n * handled depends on {@link OnBudgetExceed}: `'pause'` / `'throw'`\n * enforce, `'log'` (the shipped standard/full presets) only WARNs and\n * keeps running. The USD leg accumulates only when a `priceUsage`\n * pricer is configured (memory-consolidation-02) - without one every\n * call prices at $0 and `maxCostPerDay` can never trip. The default\n * ceiling shape per tier is captured in\n * {@link CONSOLIDATOR_TIER_DEFAULTS}.\n *\n * @stable\n */\nexport interface ConsolidatorCeilings {\n  readonly maxTokensPerDay: number;\n  readonly maxCostPerDay: number;\n  /**\n   * ADVISORY (MCON-8): the per-scope lock serializes runs, so effective\n   * concurrency is always 1 per scope regardless of this value. The\n   * field is retained for forward compatibility; it enforces nothing\n   * today.\n   */\n  readonly maxConcurrentRuns: number;\n  readonly maxRunDurationMs: number;\n  /**\n   * Minimum quiet period between non-manual runs per scope (MCON-8).\n   * After each run the runtime persists `nextEligibleAt = now +\n   * cooldownMs`; trigger-driven runs (`turn` / `idle` / `cron` /\n   * `event` / `budget`) inside that window defer with reason\n   * `'cooldown'`. Manual `fireNow(...)` and DLQ replays bypass it.\n   */\n  readonly cooldownMs: number;\n}\n\n/**\n * Behaviour applied by the budget enforcer when a ceiling is hit\n * mid-run. `'pause'` is the conservative default - the consolidator\n * skips subsequent runs until the next budget reset; `'log'` keeps\n * running with a WARN; `'throw'` raises a typed\n * {@link BudgetExceededError}.\n *\n * @stable\n */\nexport type OnBudgetExceed = 'pause' | 'log' | 'throw';\n\n/**\n * Phase identifier used by the runtime + audit rows.\n *\n * @stable\n */\nexport type ConsolidatorPhase = 'light' | 'standard' | 'deep';\n\n/**\n * Locked-down configuration accepted by `createConsolidator(...)`.\n *\n * @stable\n */\nexport interface ConsolidatorConfig {\n  readonly triggers: ReadonlyArray<ConsolidatorTriggerSpec>;\n  readonly tier: ConsolidatorTier;\n  readonly phases: ReadonlyArray<ConsolidatorPhase>;\n  readonly ceilings: ConsolidatorCeilings;\n  readonly onExceed: OnBudgetExceed;\n  /**\n   * Advisory label for the standard phase's model - recorded on spans /\n   * run telemetry only (MCON-7). Routing happens via\n   * `CreateConsolidatorOptions.cheapProvider`; this string disables\n   * nothing.\n   */\n  readonly cheapModel: string | null;\n  /**\n   * Advisory label for the deep phase's model - telemetry only\n   * (MCON-7). Routing happens via\n   * `CreateConsolidatorOptions.deepProvider`.\n   */\n  readonly deepModel: string | null;\n  readonly budgetResetSemantics: 'utc' | 'local' | 'sliding-24h';\n  readonly noiseFilters: ReadonlyArray<'default' | 'minimal' | 'none'>;\n  readonly lockWaitMs: number;\n  readonly decayTauDays: number;\n  readonly decayArchiveThreshold: number;\n  /**\n   * Capacity-bounded eviction target for the light phase (X-1). When set,\n   * each light pass archives the lowest-salience live facts in the LRU\n   * decay window down to this many - **cost / staleness control, not an\n   * accuracy lever**. `null` (the default at every tier) leaves storage\n   * unbounded, so behaviour is identical to pre-X-1. Archiving is a soft,\n   * recoverable move; nothing is hard-deleted.\n   */\n  readonly decayCapacity: number | null;\n  /**\n   * Weights for the multi-signal salience score (X-1) that orders both\n   * threshold archiving and capacity eviction. Defaults to\n   * {@link DEFAULT_SALIENCE_WEIGHTS}; with neutral importance, active\n   * status, and first-party provenance salience equals plain retention.\n   */\n  readonly salienceWeights: SalienceWeights;\n  readonly maxStandardBatchSize: number;\n  readonly maxDeepConflictsPerRun: number;\n  readonly dlqMaxRetries: number;\n  readonly dlqBaseBackoffMs: number;\n  readonly dlqMaxBackoffMs: number;\n  /**\n   * Auto-form a quarantined episode from each processed standard-phase\n   * slice (P1-2). Defaults on at the `standard`+ tiers, off at `free` /\n   * `cheap` / `custom`. The episode summary is one budgeted LLM call;\n   * when the budget is exhausted (or no episodic tier is wired) the\n   * phase degrades to fact-only behaviour.\n   */\n  readonly formEpisodes: boolean;\n  /**\n   * Ask the episode-summarization call for an LLM importance score\n   * (1-10, normalized to `[0, 1]`) so episodic triple-signal retrieval\n   * (recency × relevance × importance) runs on all three signals\n   * (P1-2). Importance is always a *soft* signal - it never gates\n   * retention. Defaults track {@link formEpisodes}.\n   */\n  readonly importanceScoring: boolean;\n  /**\n   * Auto-promotion policy (MCON-2). When `true`, the standard phase admits an\n   * injection-clean **extraction** fact as `active` instead of quarantined, so\n   * routine distillation surfaces in default recall without a manual\n   * `memory review --promote`. Injection-flagged facts always stay quarantined\n   * - the security gate is preserved - and episodes / insights / induced\n   * procedures are unaffected (they remain quarantined-until-validated).\n   * Defaults **off** at every tier: it trades the fail-safe default for\n   * convenience and is an explicit operator opt-in.\n   */\n  readonly autoPromoteExtraction: boolean;\n  /**\n   * Run the deep-phase reflection pass (P1-1): when accumulated episode\n   * importance crosses {@link importanceThreshold}, synthesize\n   * higher-order, cited insights over recent memories (Generative\n   * Agents). Insights land quarantined + `provenance: 'reflection'` and\n   * are ranked below the facts they cite. Defaults **on at the `full`\n   * tier only** (off at `free` / `cheap` / `standard` / `custom`) - it\n   * is the most LLM-intensive phase. A no-op without an episodic tier\n   * or an insight-capable storage adapter.\n   */\n  readonly reflection: boolean;\n  /**\n   * Sum of recent episode importance (each in `[0, 1]`) at or above\n   * which {@link reflection} fires. Below it the pass makes no LLM\n   * call. Defaults to `3`.\n   */\n  readonly importanceThreshold: number;\n  /** Upper bound on salient questions reflection asks per pass. Defaults to `3`. */\n  readonly reflectionMaxQuestions: number;\n  /**\n   * Contextual retrieval for facts written by the standard phase (P1-3).\n   * `'late-chunk'` (default at every tier) relies on the offline\n   * situating-context prefix the shared {@link SemanticMemory} computes\n   * for every write - no extra LLM call. `'llm'` is the opt-in\n   * enrichment: the standard phase spends one budgeted cheap-model call\n   * per additive write to author a 1-2 sentence situating prefix, then\n   * passes it as the write's index text. `'off'` indexes the bare text.\n   * The `'llm'` mode is **consolidator-only** by construction - the hot\n   * write path never has a provider for contextualization.\n   */\n  readonly contextualRetrieval: ContextualRetrievalMode;\n  /**\n   * Maintain the learned-context digest block (D3): after the deep\n   * phase, one budgeted LLM call rewrites the reserved\n   * `learned_context` working block from the previous digest + recent\n   * episodes / active insights / active procedures, so the system\n   * prompt carries a compact standing summary. Defaults **off at every\n   * tier** (Wave-D trial) - a no-op without a working tier handle.\n   */\n  readonly learnedContext: boolean;\n  /** Character bound enforced on the learned-context digest. Default `1200`. */\n  readonly learnedContextMaxChars: number;\n}\n\n/**\n * Per-phase last-run snapshot surfaced inside\n * {@link ConsolidatorStatus.lastRuns}. Each entry carries the\n * timestamp of the most recent **completed** invocation for that\n * phase (`undefined` when the phase has never run).\n *\n * @stable\n */\nexport interface ConsolidatorLastRuns {\n  readonly light?: string;\n  readonly standard?: string;\n  readonly deep?: string;\n}\n\n/**\n * Budget snapshot block of {@link ConsolidatorStatus}. Surfaces\n * both the absolute usage and the remaining envelope so consumers\n * (CLI, server health endpoint) can render the operator dashboard\n * without doing the math themselves.\n *\n * @stable\n */\nexport interface ConsolidatorBudgetSnapshot {\n  readonly tokensUsedToday: number;\n  readonly costUsedToday: number;\n  readonly tokensRemaining: number;\n  readonly costRemaining: number;\n  readonly resetAt: string;\n}\n\n/**\n * Status snapshot returned by {@link Consolidator.status}.\n *\n * Public shape: `{ tier, queueDepth, dlqSize, lastRuns,\n * budgetRemaining, deferredRuns }` - extended with a few additional\n * fields the server health endpoint and the\n * `graphorin consolidator status` CLI consume.\n *\n * `queueDepth` is an alias for {@link pendingConflicts} (the size\n * of the deep-phase queue); both fields are populated for backwards\n * compatibility.\n *\n * @stable\n */\nexport interface ConsolidatorStatus {\n  readonly tier: ConsolidatorTier;\n  readonly triggers: ReadonlyArray<ConsolidatorTriggerSpec>;\n  readonly phases: ReadonlyArray<ConsolidatorPhase>;\n  readonly running: boolean;\n  readonly paused: boolean;\n  /** Most recent completed run timestamp (any phase). */\n  readonly lastRunAt?: string;\n  /** Phase of the most recent completed run. */\n  readonly lastPhase?: ConsolidatorPhase;\n  /** Per-phase last-completed timestamps surfaced for CLI / dashboard. */\n  readonly lastRuns: ConsolidatorLastRuns;\n  /** Spec alias for {@link pendingConflicts}. */\n  readonly queueDepth: number;\n  readonly pendingConflicts: number;\n  readonly dlqSize: number;\n  readonly deferredRuns: number;\n  readonly emptyExtractions: number;\n  readonly budget: ConsolidatorBudgetSnapshot;\n  /** Spec alias - surfaces remaining-budget figures at the top level. */\n  readonly budgetRemaining: {\n    readonly tokens: number;\n    readonly costUsd: number;\n  };\n}\n\n/**\n * Outcome surfaced by every phase invocation. Recorded into\n * `consolidator_runs` and emitted on the AISpan.\n *\n * @stable\n */\nexport interface PhaseOutcome {\n  readonly phase: ConsolidatorPhase;\n  readonly status: 'completed' | 'failed' | 'deferred' | 'partial';\n  readonly factsCreated: number;\n  readonly factsUpdated: number;\n  readonly conflictsResolved: number;\n  /** Episodes auto-formed from the processed slice (P1-2). */\n  readonly episodesFormed: number;\n  /** Insights synthesized by the deep-phase reflection pass (P1-1). */\n  readonly insightsCreated: number;\n  /** True when the learned-context digest block was rewritten (D3). */\n  readonly learnedContextUpdated?: boolean;\n  readonly noiseFilteredCount: number;\n  readonly emptyExtractions: number;\n  readonly llmTokensUsed: number;\n  readonly llmCostUsd: number | null;\n  readonly errorMessage: string | null;\n}\n\n/**\n * Listener callback subscribed via\n * {@link Consolidator.onPhaseFinished}. Useful for tests + observers.\n *\n * @stable\n */\nexport type PhaseListener = (\n  outcome: PhaseOutcome & {\n    readonly scope: SessionScope;\n    readonly trigger: ConsolidatorTriggerReason;\n  },\n) => void;\n\n/**\n * Options accepted by {@link createConsolidator}.\n *\n * @stable\n */\nexport interface CreateConsolidatorOptions {\n  /**\n   * Storage adapter - supplies the consolidator state, runs, DLQ,\n   * and per-tier helpers. The default `@graphorin/store-sqlite`\n   * adapter exposes everything by construction.\n   */\n  readonly store: MemoryStoreAdapter;\n  /**\n   * The {@link SemanticMemory} tier instance from the parent\n   * `createMemory(...)` facade. The standard phase routes every\n   * extracted fact through `semantic.remember(...)` so the conflict\n   * pipeline (Phase 10b) handles dedup / supersede.\n   */\n  readonly semantic: SemanticMemory;\n  /**\n   * The {@link EpisodicMemory} tier instance from the parent\n   * `createMemory(...)` facade. When supplied (and `formEpisodes` is\n   * on) the standard phase auto-forms a quarantined episode per\n   * processed slice (P1-2). Omitted ⇒ episode formation is skipped.\n   */\n  readonly episodic?: EpisodicMemory;\n  /**\n   * The {@link WorkingMemory} tier instance from the parent\n   * `createMemory(...)` facade (D3). Required for the learned-context\n   * pass - without it the pass is a silent no-op even when\n   * `learnedContext` is enabled.\n   */\n  readonly working?: WorkingMemory;\n  /**\n   * Provider used by the standard + deep phases. Required when the\n   * tier enables either phase; ignored when the active phases\n   * collapse to `['light']`.\n   */\n  readonly provider?: Provider | null;\n  readonly tracer?: Tracer;\n  /** Override the wall clock - used by tests. */\n  readonly now?: () => number;\n  /** Random source for stable run ids - used by tests. */\n  readonly randomId?: () => string;\n  readonly triggers?: ReadonlyArray<ConsolidatorTriggerSpec>;\n  readonly tier?: ConsolidatorTier;\n  readonly phases?: ReadonlyArray<ConsolidatorPhase>;\n  readonly ceilings?: Partial<ConsolidatorCeilings>;\n  readonly onExceed?: OnBudgetExceed;\n  /**\n   * USD pricer for phase LLM usage (memory-consolidation-02). Wire it\n   * to `@graphorin/pricing`'s `calculateCost` (or any per-token rate)\n   * so the `maxCostPerDay` ceiling can actually accumulate spend -\n   * without it every phase prices its calls at $0 and the USD ceiling\n   * never trips at any tier.\n   *\n   * ```ts\n   * priceUsage: ({ promptTokens, completionTokens }) =>\n   *   (promptTokens * 3 + completionTokens * 15) / 1_000_000\n   * ```\n   */\n  readonly priceUsage?: (usage: { promptTokens: number; completionTokens: number }) => number;\n  /**\n   * Provider routed to the standard phase (extraction / episode /\n   * reconcile / situating-context calls) when set (MCON-7). Falls back\n   * to `provider`. Pair with `cheapModel` for the telemetry label.\n   */\n  readonly cheapProvider?: Provider | null;\n  /**\n   * Provider routed to the deep phase (conflict judge) and the\n   * reflection pass when set (MCON-7). Falls back to `provider`.\n   */\n  readonly deepProvider?: Provider | null;\n  readonly cheapModel?: string | null;\n  readonly deepModel?: string | null;\n  readonly budgetResetSemantics?: 'utc' | 'local' | 'sliding-24h';\n  readonly noiseFilters?: ReadonlyArray<'default' | 'minimal' | 'none'>;\n  readonly lockWaitMs?: number;\n  readonly decayTauDays?: number;\n  readonly decayArchiveThreshold?: number;\n  /** Override the {@link ConsolidatorConfig.decayCapacity} default (X-1). */\n  readonly decayCapacity?: number | null;\n  /** Override the {@link ConsolidatorConfig.salienceWeights} default (X-1). */\n  readonly salienceWeights?: SalienceWeights;\n  readonly maxStandardBatchSize?: number;\n  readonly maxDeepConflictsPerRun?: number;\n  readonly dlqMaxRetries?: number;\n  readonly dlqBaseBackoffMs?: number;\n  readonly dlqMaxBackoffMs?: number;\n  /** Override the per-tier {@link ConsolidatorConfig.formEpisodes} default (P1-2). */\n  readonly formEpisodes?: boolean;\n  /** Override the per-tier {@link ConsolidatorConfig.importanceScoring} default (P1-2). */\n  readonly importanceScoring?: boolean;\n  /**\n   * Opt in to auto-promotion of injection-clean extraction facts (MCON-2).\n   * Defaults `false`. See {@link ConsolidatorConfig.autoPromoteExtraction}.\n   */\n  readonly autoPromoteExtraction?: boolean;\n  /** Override the per-tier {@link ConsolidatorConfig.reflection} default (P1-1). */\n  readonly reflection?: boolean;\n  /** Override the {@link ConsolidatorConfig.importanceThreshold} default (P1-1). */\n  readonly importanceThreshold?: number;\n  /** Override the {@link ConsolidatorConfig.reflectionMaxQuestions} default (P1-1). */\n  readonly reflectionMaxQuestions?: number;\n  /** Override the per-tier {@link ConsolidatorConfig.contextualRetrieval} default (P1-3). */\n  readonly contextualRetrieval?: ContextualRetrievalMode;\n  /** Override the per-tier {@link ConsolidatorConfig.learnedContext} default (D3). */\n  readonly learnedContext?: boolean;\n  /** Override the {@link ConsolidatorConfig.learnedContextMaxChars} default (D3). */\n  readonly learnedContextMaxChars?: number;\n  /** Default scope used by event triggers + the manual `fireNow` path. */\n  readonly defaultScope?: SessionScope;\n}\n\n/**\n * Tier preset table. The defaults follow ADR-038 §4 - `'free'`\n * disables every LLM phase and pins zero ceilings, the upper tiers\n * widen the budget envelope progressively.\n *\n * @stable\n */\nexport const CONSOLIDATOR_TIER_DEFAULTS: Readonly<\n  Record<\n    ConsolidatorTier,\n    {\n      readonly ceilings: ConsolidatorCeilings;\n      readonly phases: ReadonlyArray<ConsolidatorPhase>;\n      readonly cheapModel: string | null;\n      readonly deepModel: string | null;\n      readonly onExceed: OnBudgetExceed;\n      readonly formEpisodes: boolean;\n      readonly importanceScoring: boolean;\n      readonly reflection: boolean;\n      readonly importanceThreshold: number;\n      readonly reflectionMaxQuestions: number;\n      readonly contextualRetrieval: ContextualRetrievalMode;\n      readonly learnedContext: boolean;\n      readonly learnedContextMaxChars: number;\n    }\n  >\n> = Object.freeze({\n  free: {\n    ceilings: {\n      maxTokensPerDay: 0,\n      maxCostPerDay: 0,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 5 * 60 * 1000,\n      cooldownMs: 60_000,\n    },\n    phases: ['light'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'pause',\n    formEpisodes: false,\n    importanceScoring: false,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n    learnedContext: false,\n    learnedContextMaxChars: 1200,\n  },\n  cheap: {\n    ceilings: {\n      maxTokensPerDay: 50_000,\n      maxCostPerDay: 0.2,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 5 * 60 * 1000,\n      cooldownMs: 60_000,\n    },\n    phases: ['light', 'standard'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'pause',\n    formEpisodes: false,\n    importanceScoring: false,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n    learnedContext: false,\n    learnedContextMaxChars: 1200,\n  },\n  standard: {\n    ceilings: {\n      maxTokensPerDay: 200_000,\n      maxCostPerDay: 1.0,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 10 * 60 * 1000,\n      cooldownMs: 30_000,\n    },\n    phases: ['light', 'standard', 'deep'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'log',\n    formEpisodes: true,\n    importanceScoring: true,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n    learnedContext: false,\n    learnedContextMaxChars: 1200,\n  },\n  full: {\n    ceilings: {\n      maxTokensPerDay: 1_000_000,\n      maxCostPerDay: 5.0,\n      maxConcurrentRuns: 2,\n      maxRunDurationMs: 15 * 60 * 1000,\n      cooldownMs: 10_000,\n    },\n    phases: ['light', 'standard', 'deep'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'log',\n    formEpisodes: true,\n    importanceScoring: true,\n    reflection: true,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n    learnedContext: false,\n    learnedContextMaxChars: 1200,\n  },\n  custom: {\n    ceilings: {\n      maxTokensPerDay: 0,\n      maxCostPerDay: 0,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 5 * 60 * 1000,\n      cooldownMs: 60_000,\n    },\n    phases: ['light'],\n    cheapModel: null,\n    deepModel: null,\n    onExceed: 'pause',\n    formEpisodes: false,\n    importanceScoring: false,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n    learnedContext: false,\n    learnedContextMaxChars: 1200,\n  },\n});\n"],"mappings":";;;;;;;;AAucA,MAAaA,6BAmBT,OAAO,OAAO;CAChB,MAAM;EACJ,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAS;GAC3B,YAAY;GACb;EACD,QAAQ,CAAC,QAAQ;EACjB,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACrB,gBAAgB;EAChB,wBAAwB;EACzB;CACD,OAAO;EACL,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAS;GAC3B,YAAY;GACb;EACD,QAAQ,CAAC,SAAS,WAAW;EAC7B,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACrB,gBAAgB;EAChB,wBAAwB;EACzB;CACD,UAAU;EACR,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAU;GAC5B,YAAY;GACb;EACD,QAAQ;GAAC;GAAS;GAAY;GAAO;EACrC,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACrB,gBAAgB;EAChB,wBAAwB;EACzB;CACD,MAAM;EACJ,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAU;GAC5B,YAAY;GACb;EACD,QAAQ;GAAC;GAAS;GAAY;GAAO;EACrC,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACrB,gBAAgB;EAChB,wBAAwB;EACzB;CACD,QAAQ;EACN,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAS;GAC3B,YAAY;GACb;EACD,QAAQ,CAAC,QAAQ;EACjB,YAAY;EACZ,WAAW;EACX,UAAU;EACV,cAAc;EACd,mBAAmB;EACnB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACrB,gBAAgB;EAChB,wBAAwB;EACzB;CACF,CAAC"}

package/dist/context-engine/annotations.d.ts

@@ -8,16 +8,16 @@
  * Every {@link MessageContent} part assembled by the ContextEngine
  * carries two **independent** annotations:
  *
- * - `graphorin.content.origin` — where the content came from. Used
+ * - `graphorin.content.origin` - where the content came from. Used
  *   by D3 (`withRedaction`) under `scanScope: 'untrusted'` to
  *   decide whether to re-scan a part that already passed the D2
  *   sensitivity-tier filter.
- * - `graphorin.content.inbound.trust` — what trust class the source
+ * - `graphorin.content.inbound.trust` - what trust class the source
  *   carries. Used by D4 (`withInboundSanitization`) and by Phase 12
  *   (agent runtime) to gate the per-step preamble injection.
  *
  * Both annotations live as **span attributes only** (observability)
- * — they are never serialized to the wire payload. The wire-stable
+ * - they are never serialized to the wire payload. The wire-stable
  * `ProviderRequest` shape is unchanged by Phase 10d.
  *
  * @packageDocumentation
@@ -49,18 +49,18 @@ type ContentOrigin = 'memory:tier-filtered' | 'system:framework' | 'agent:instru
  * Trust-class discriminator for an assembled message-content part.
  * Sibling axis to {@link ContentOrigin}; the two are independent.
  *
- * - `'trusted'` — built-in framework tools + trusted-skill-bundled
+ * - `'trusted'` - built-in framework tools + trusted-skill-bundled
  *   tools; D4 preamble does NOT fire on steps containing only
  *   these parts.
- * - `'user-defined'` — tools registered via `tool({...})` from user
+ * - `'user-defined'` - tools registered via `tool({...})` from user
  *   application code; D4 preamble fires.
- * - `'untrusted-skill'` — tools bundled by an untrusted skill; D4
+ * - `'untrusted-skill'` - tools bundled by an untrusted skill; D4
  *   preamble fires; default policy is strip-and-wrap.
- * - `'mcp'` — every `Tool` produced by `MCPClient.toTools(...)`; D4
+ * - `'mcp'` - every `Tool` produced by `MCPClient.toTools(...)`; D4
  *   preamble fires; default policy is strip-and-wrap.
- * - `'web-search'` — built-in `web_search` adapter; D4 preamble
+ * - `'web-search'` - built-in `web_search` adapter; D4 preamble
  *   fires; default policy is strip-and-wrap.
- * - `'n/a'` — non-tool-result parts for which the inbound-trust
+ * - `'n/a'` - non-tool-result parts for which the inbound-trust
  *   axis is meaningless (`'user:input'`, `'memory:tier-filtered'`,
  *   `'system:framework'`, `'agent:instructions'`,
  *   `'tool-call:args'`).

package/dist/context-engine/annotations.js

@@ -8,16 +8,16 @@
 * Every {@link MessageContent} part assembled by the ContextEngine
 * carries two **independent** annotations:
 *
-* - `graphorin.content.origin` — where the content came from. Used
+* - `graphorin.content.origin` - where the content came from. Used
 *   by D3 (`withRedaction`) under `scanScope: 'untrusted'` to
 *   decide whether to re-scan a part that already passed the D2
 *   sensitivity-tier filter.
-* - `graphorin.content.inbound.trust` — what trust class the source
+* - `graphorin.content.inbound.trust` - what trust class the source
 *   carries. Used by D4 (`withInboundSanitization`) and by Phase 12
 *   (agent runtime) to gate the per-step preamble injection.
 *
 * Both annotations live as **span attributes only** (observability)
-* — they are never serialized to the wire payload. The wire-stable
+* - they are never serialized to the wire payload. The wire-stable
 * `ProviderRequest` shape is unchanged by Phase 10d.
 *
 * @packageDocumentation

package/dist/context-engine/annotations.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.js","names":["NON_INBOUND_ORIGINS: ReadonlySet<ContentOrigin>"],"sources":["../../src/context-engine/annotations.ts"],"sourcesContent":["/**\n * Cooperation contract between the {@link ContextEngine} and the\n * outbound prompt-redaction middleware (D3, see ADR-045 / DEC-157)\n * + the inbound tool-result sanitization middleware (D4, see\n * RB-43 / DEC-159).\n *\n * Every {@link MessageContent} part assembled by the ContextEngine\n * carries two **independent** annotations:\n *\n * - `graphorin.content.origin` — where the content came from. Used\n *   by D3 (`withRedaction`) under `scanScope: 'untrusted'` to\n *   decide whether to re-scan a part that already passed the D2\n *   sensitivity-tier filter.\n * - `graphorin.content.inbound.trust` — what trust class the source\n *   carries. Used by D4 (`withInboundSanitization`) and by Phase 12\n *   (agent runtime) to gate the per-step preamble injection.\n *\n * Both annotations live as **span attributes only** (observability)\n * — they are never serialized to the wire payload. The wire-stable\n * `ProviderRequest` shape is unchanged by Phase 10d.\n *\n * @packageDocumentation\n */\n\n/**\n * Span-attribute key for the origin axis.\n *\n * @stable\n */\nexport const CONTENT_ORIGIN_ATTR = 'graphorin.content.origin' as const;\n\n/**\n * Span-attribute key for the inbound-trust axis.\n *\n * @stable\n */\nexport const INBOUND_TRUST_ATTR = 'graphorin.content.inbound.trust' as const;\n\n/**\n * Origin discriminator for an assembled message-content part. The\n * non-ContextEngine origins (`'user:input'`, `'tool:result'`,\n * `'mcp:response'`, `'tool-call:args'`) are tagged by Phase 12\n * (agent runtime) when the corresponding payload enters\n * `session_messages`; the ContextEngine then propagates the tag\n * through the assembled message list.\n *\n * @stable\n */\nexport type ContentOrigin =\n  | 'memory:tier-filtered'\n  | 'system:framework'\n  | 'agent:instructions'\n  | 'skill:content'\n  | 'user:input'\n  | 'tool:result'\n  | 'mcp:response'\n  | 'tool-call:args';\n\n/**\n * Trust-class discriminator for an assembled message-content part.\n * Sibling axis to {@link ContentOrigin}; the two are independent.\n *\n * - `'trusted'` — built-in framework tools + trusted-skill-bundled\n *   tools; D4 preamble does NOT fire on steps containing only\n *   these parts.\n * - `'user-defined'` — tools registered via `tool({...})` from user\n *   application code; D4 preamble fires.\n * - `'untrusted-skill'` — tools bundled by an untrusted skill; D4\n *   preamble fires; default policy is strip-and-wrap.\n * - `'mcp'` — every `Tool` produced by `MCPClient.toTools(...)`; D4\n *   preamble fires; default policy is strip-and-wrap.\n * - `'web-search'` — built-in `web_search` adapter; D4 preamble\n *   fires; default policy is strip-and-wrap.\n * - `'n/a'` — non-tool-result parts for which the inbound-trust\n *   axis is meaningless (`'user:input'`, `'memory:tier-filtered'`,\n *   `'system:framework'`, `'agent:instructions'`,\n *   `'tool-call:args'`).\n *\n * @stable\n */\nexport type InboundTrust =\n  | 'trusted'\n  | 'user-defined'\n  | 'untrusted-skill'\n  | 'mcp'\n  | 'web-search'\n  | 'n/a';\n\n/**\n * Origins for which the inbound-trust axis is meaningless and is\n * always set to `'n/a'`. Surfaced as a frozen constant so consumers\n * can introspect the contract without re-implementing the rule.\n *\n * @stable\n */\nexport const NON_INBOUND_ORIGINS: ReadonlySet<ContentOrigin> = Object.freeze(\n  new Set<ContentOrigin>([\n    'memory:tier-filtered',\n    'system:framework',\n    'agent:instructions',\n    'user:input',\n    'tool-call:args',\n  ]),\n);\n\n/**\n * Single typed annotation for an assembled message-content part.\n *\n * @stable\n */\nexport interface ContentAnnotation {\n  readonly origin: ContentOrigin;\n  readonly inboundTrust: InboundTrust;\n}\n\n/**\n * Build an annotation, enforcing the rule that\n * non-tool-result origins always carry `inboundTrust: 'n/a'`. A\n * caller that requests a non-`'n/a'` value for a non-inbound origin\n * is silently corrected (defense-in-depth: the rule is enforced\n * here so callers cannot accidentally violate it).\n *\n * @stable\n */\nexport function annotate(origin: ContentOrigin, inboundTrust: InboundTrust): ContentAnnotation {\n  if (NON_INBOUND_ORIGINS.has(origin)) {\n    return Object.freeze({ origin, inboundTrust: 'n/a' });\n  }\n  return Object.freeze({ origin, inboundTrust });\n}\n\n/**\n * Convert a {@link ContentAnnotation} to a span-attributes record\n * suitable for `AISpan.setAttributes(...)`.\n *\n * @stable\n */\nexport function toSpanAttributes(annotation: ContentAnnotation): Readonly<Record<string, string>> {\n  return Object.freeze({\n    [CONTENT_ORIGIN_ATTR]: annotation.origin,\n    [INBOUND_TRUST_ATTR]: annotation.inboundTrust,\n  });\n}\n\n/**\n * Decide whether the per-step inbound-sanitization preamble (D4)\n * should fire for an assembled message list. The preamble fires\n * iff at least one part carries an inbound-trust value other than\n * `'trusted'` and `'n/a'`. Trusted-only steps skip the preamble for\n * cache-friendliness; preamble is emitted exactly once per step\n * regardless of how many untrusted parts the step carries.\n *\n * @stable\n */\nexport function shouldFireInboundPreamble(annotations: ReadonlyArray<ContentAnnotation>): boolean {\n  for (const annotation of annotations) {\n    const trust = annotation.inboundTrust;\n    if (trust !== 'trusted' && trust !== 'n/a') return true;\n  }\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,sBAAsB;;;;;;AAOnC,MAAa,qBAAqB;;;;;;;;AA2DlC,MAAaA,sBAAkD,OAAO,OACpE,IAAI,IAAmB;CACrB;CACA;CACA;CACA;CACA;CACD,CAAC,CACH;;;;;;;;;;AAqBD,SAAgB,SAAS,QAAuB,cAA+C;AAC7F,KAAI,oBAAoB,IAAI,OAAO,CACjC,QAAO,OAAO,OAAO;EAAE;EAAQ,cAAc;EAAO,CAAC;AAEvD,QAAO,OAAO,OAAO;EAAE;EAAQ;EAAc,CAAC;;;;;;;;AAShD,SAAgB,iBAAiB,YAAiE;AAChG,QAAO,OAAO,OAAO;GAClB,sBAAsB,WAAW;GACjC,qBAAqB,WAAW;EAClC,CAAC;;;;;;;;;;;;AAaJ,SAAgB,0BAA0B,aAAwD;AAChG,MAAK,MAAM,cAAc,aAAa;EACpC,MAAM,QAAQ,WAAW;AACzB,MAAI,UAAU,aAAa,UAAU,MAAO,QAAO;;AAErD,QAAO"}
+{"version":3,"file":"annotations.js","names":["NON_INBOUND_ORIGINS: ReadonlySet<ContentOrigin>"],"sources":["../../src/context-engine/annotations.ts"],"sourcesContent":["/**\n * Cooperation contract between the {@link ContextEngine} and the\n * outbound prompt-redaction middleware (D3, see ADR-045 / DEC-157)\n * + the inbound tool-result sanitization middleware (D4, see\n * RB-43 / DEC-159).\n *\n * Every {@link MessageContent} part assembled by the ContextEngine\n * carries two **independent** annotations:\n *\n * - `graphorin.content.origin` - where the content came from. Used\n *   by D3 (`withRedaction`) under `scanScope: 'untrusted'` to\n *   decide whether to re-scan a part that already passed the D2\n *   sensitivity-tier filter.\n * - `graphorin.content.inbound.trust` - what trust class the source\n *   carries. Used by D4 (`withInboundSanitization`) and by Phase 12\n *   (agent runtime) to gate the per-step preamble injection.\n *\n * Both annotations live as **span attributes only** (observability)\n * - they are never serialized to the wire payload. The wire-stable\n * `ProviderRequest` shape is unchanged by Phase 10d.\n *\n * @packageDocumentation\n */\n\n/**\n * Span-attribute key for the origin axis.\n *\n * @stable\n */\nexport const CONTENT_ORIGIN_ATTR = 'graphorin.content.origin' as const;\n\n/**\n * Span-attribute key for the inbound-trust axis.\n *\n * @stable\n */\nexport const INBOUND_TRUST_ATTR = 'graphorin.content.inbound.trust' as const;\n\n/**\n * Origin discriminator for an assembled message-content part. The\n * non-ContextEngine origins (`'user:input'`, `'tool:result'`,\n * `'mcp:response'`, `'tool-call:args'`) are tagged by Phase 12\n * (agent runtime) when the corresponding payload enters\n * `session_messages`; the ContextEngine then propagates the tag\n * through the assembled message list.\n *\n * @stable\n */\nexport type ContentOrigin =\n  | 'memory:tier-filtered'\n  | 'system:framework'\n  | 'agent:instructions'\n  | 'skill:content'\n  | 'user:input'\n  | 'tool:result'\n  | 'mcp:response'\n  | 'tool-call:args';\n\n/**\n * Trust-class discriminator for an assembled message-content part.\n * Sibling axis to {@link ContentOrigin}; the two are independent.\n *\n * - `'trusted'` - built-in framework tools + trusted-skill-bundled\n *   tools; D4 preamble does NOT fire on steps containing only\n *   these parts.\n * - `'user-defined'` - tools registered via `tool({...})` from user\n *   application code; D4 preamble fires.\n * - `'untrusted-skill'` - tools bundled by an untrusted skill; D4\n *   preamble fires; default policy is strip-and-wrap.\n * - `'mcp'` - every `Tool` produced by `MCPClient.toTools(...)`; D4\n *   preamble fires; default policy is strip-and-wrap.\n * - `'web-search'` - built-in `web_search` adapter; D4 preamble\n *   fires; default policy is strip-and-wrap.\n * - `'n/a'` - non-tool-result parts for which the inbound-trust\n *   axis is meaningless (`'user:input'`, `'memory:tier-filtered'`,\n *   `'system:framework'`, `'agent:instructions'`,\n *   `'tool-call:args'`).\n *\n * @stable\n */\nexport type InboundTrust =\n  | 'trusted'\n  | 'user-defined'\n  | 'untrusted-skill'\n  | 'mcp'\n  | 'web-search'\n  | 'n/a';\n\n/**\n * Origins for which the inbound-trust axis is meaningless and is\n * always set to `'n/a'`. Surfaced as a frozen constant so consumers\n * can introspect the contract without re-implementing the rule.\n *\n * @stable\n */\nexport const NON_INBOUND_ORIGINS: ReadonlySet<ContentOrigin> = Object.freeze(\n  new Set<ContentOrigin>([\n    'memory:tier-filtered',\n    'system:framework',\n    'agent:instructions',\n    'user:input',\n    'tool-call:args',\n  ]),\n);\n\n/**\n * Single typed annotation for an assembled message-content part.\n *\n * @stable\n */\nexport interface ContentAnnotation {\n  readonly origin: ContentOrigin;\n  readonly inboundTrust: InboundTrust;\n}\n\n/**\n * Build an annotation, enforcing the rule that\n * non-tool-result origins always carry `inboundTrust: 'n/a'`. A\n * caller that requests a non-`'n/a'` value for a non-inbound origin\n * is silently corrected (defense-in-depth: the rule is enforced\n * here so callers cannot accidentally violate it).\n *\n * @stable\n */\nexport function annotate(origin: ContentOrigin, inboundTrust: InboundTrust): ContentAnnotation {\n  if (NON_INBOUND_ORIGINS.has(origin)) {\n    return Object.freeze({ origin, inboundTrust: 'n/a' });\n  }\n  return Object.freeze({ origin, inboundTrust });\n}\n\n/**\n * Convert a {@link ContentAnnotation} to a span-attributes record\n * suitable for `AISpan.setAttributes(...)`.\n *\n * @stable\n */\nexport function toSpanAttributes(annotation: ContentAnnotation): Readonly<Record<string, string>> {\n  return Object.freeze({\n    [CONTENT_ORIGIN_ATTR]: annotation.origin,\n    [INBOUND_TRUST_ATTR]: annotation.inboundTrust,\n  });\n}\n\n/**\n * Decide whether the per-step inbound-sanitization preamble (D4)\n * should fire for an assembled message list. The preamble fires\n * iff at least one part carries an inbound-trust value other than\n * `'trusted'` and `'n/a'`. Trusted-only steps skip the preamble for\n * cache-friendliness; preamble is emitted exactly once per step\n * regardless of how many untrusted parts the step carries.\n *\n * @stable\n */\nexport function shouldFireInboundPreamble(annotations: ReadonlyArray<ContentAnnotation>): boolean {\n  for (const annotation of annotations) {\n    const trust = annotation.inboundTrust;\n    if (trust !== 'trusted' && trust !== 'n/a') return true;\n  }\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,sBAAsB;;;;;;AAOnC,MAAa,qBAAqB;;;;;;;;AA2DlC,MAAaA,sBAAkD,OAAO,OACpE,IAAI,IAAmB;CACrB;CACA;CACA;CACA;CACA;CACD,CAAC,CACH;;;;;;;;;;AAqBD,SAAgB,SAAS,QAAuB,cAA+C;AAC7F,KAAI,oBAAoB,IAAI,OAAO,CACjC,QAAO,OAAO,OAAO;EAAE;EAAQ,cAAc;EAAO,CAAC;AAEvD,QAAO,OAAO,OAAO;EAAE;EAAQ;EAAc,CAAC;;;;;;;;AAShD,SAAgB,iBAAiB,YAAiE;AAChG,QAAO,OAAO,OAAO;GAClB,sBAAsB,WAAW;GACjC,qBAAqB,WAAW;EAClC,CAAC;;;;;;;;;;;;AAaJ,SAAgB,0BAA0B,aAAwD;AAChG,MAAK,MAAM,cAAc,aAAa;EACpC,MAAM,QAAQ,WAAW;AACzB,MAAI,UAAU,aAAa,UAAU,MAAO,QAAO;;AAErD,QAAO"}

package/dist/context-engine/auto-recall.js.map

@@ -1 +1 @@
-{"version":3,"file":"auto-recall.js","names":[],"sources":["../../src/context-engine/auto-recall.ts"],"sourcesContent":["/**\n * Auto-recall heuristic — opt-in regex-based pre-call that injects\n * the top-K facts into Layer 6 when the last user message matches one\n * of the configured trigger phrases. (Episode auto-recall is not\n * implemented; episodes are reachable via the `recall_episodes` tool.)\n *\n * The framework ships English defaults; per-locale trigger\n * phrases extend the default via {@link defineContextLocalePack}.\n * Application code can also register a fully-custom strategy via\n * {@link defineAutoRecallStrategy}.\n *\n * @packageDocumentation\n */\n\nimport type { ContextLocalePack } from './locale-packs/index.js';\n\n/**\n * Per-call scope passed to a custom strategy.\n *\n * @stable\n */\nexport interface AutoRecallStrategyContext {\n  readonly locale: string;\n  readonly lastUserMessage: string;\n}\n\n/**\n * Outcome of a strategy invocation.\n *\n * @stable\n */\nexport interface AutoRecallTriggerResult {\n  readonly factsTriggered: boolean;\n  /** Optional reason surfaced in spans / metadata. */\n  readonly reason?: string;\n}\n\n/**\n * Pluggable strategy signature.\n *\n * @stable\n */\nexport type AutoRecallStrategy = (ctx: AutoRecallStrategyContext) => AutoRecallTriggerResult;\n\n/**\n * Build a locale-driven heuristic strategy. The default for every\n * configured locale.\n *\n * @stable\n */\nexport function defaultLocaleHeuristicStrategy(pack: ContextLocalePack): AutoRecallStrategy {\n  const factTriggers = pack.autoRecallTriggers.factTriggers;\n  return (ctx) => {\n    const text = ctx.lastUserMessage ?? '';\n    if (text.length === 0) {\n      return { factsTriggered: false };\n    }\n    const factsTriggered = factTriggers.some((re) => re.test(text));\n    if (factsTriggered) {\n      return { factsTriggered, reason: 'locale-heuristic-trigger-matched' };\n    }\n    return { factsTriggered: false };\n  };\n}\n\n/**\n * Builder for application-supplied custom strategies. Accepts a\n * raw function and returns a tagged version so the engine can\n * surface the strategy name on spans.\n *\n * @stable\n */\nexport function defineAutoRecallStrategy(opts: {\n  readonly id: string;\n  readonly evaluate: AutoRecallStrategy;\n}): AutoRecallStrategy & { readonly id: string } {\n  if (typeof opts.id !== 'string' || opts.id.length === 0) {\n    throw new TypeError(\n      '[graphorin/memory] defineAutoRecallStrategy: `id` must be a non-empty string.',\n    );\n  }\n  if (typeof opts.evaluate !== 'function') {\n    throw new TypeError(\n      '[graphorin/memory] defineAutoRecallStrategy: `evaluate` must be a function.',\n    );\n  }\n  const wrapped = ((ctx: AutoRecallStrategyContext) => opts.evaluate(ctx)) as AutoRecallStrategy & {\n    readonly id: string;\n  };\n  Object.defineProperty(wrapped, 'id', { value: opts.id, enumerable: true });\n  return wrapped;\n}\n"],"mappings":";;;;;;;AAkDA,SAAgB,+BAA+B,MAA6C;CAC1F,MAAM,eAAe,KAAK,mBAAmB;AAC7C,SAAQ,QAAQ;EACd,MAAM,OAAO,IAAI,mBAAmB;AACpC,MAAI,KAAK,WAAW,EAClB,QAAO,EAAE,gBAAgB,OAAO;EAElC,MAAM,iBAAiB,aAAa,MAAM,OAAO,GAAG,KAAK,KAAK,CAAC;AAC/D,MAAI,eACF,QAAO;GAAE;GAAgB,QAAQ;GAAoC;AAEvE,SAAO,EAAE,gBAAgB,OAAO;;;;;;;;;;AAWpC,SAAgB,yBAAyB,MAGQ;AAC/C,KAAI,OAAO,KAAK,OAAO,YAAY,KAAK,GAAG,WAAW,EACpD,OAAM,IAAI,UACR,gFACD;AAEH,KAAI,OAAO,KAAK,aAAa,WAC3B,OAAM,IAAI,UACR,8EACD;CAEH,MAAM,YAAY,QAAmC,KAAK,SAAS,IAAI;AAGvE,QAAO,eAAe,SAAS,MAAM;EAAE,OAAO,KAAK;EAAI,YAAY;EAAM,CAAC;AAC1E,QAAO"}
+{"version":3,"file":"auto-recall.js","names":[],"sources":["../../src/context-engine/auto-recall.ts"],"sourcesContent":["/**\n * Auto-recall heuristic - opt-in regex-based pre-call that injects\n * the top-K facts into Layer 6 when the last user message matches one\n * of the configured trigger phrases. (Episode auto-recall is not\n * implemented; episodes are reachable via the `recall_episodes` tool.)\n *\n * The framework ships English defaults; per-locale trigger\n * phrases extend the default via {@link defineContextLocalePack}.\n * Application code can also register a fully-custom strategy via\n * {@link defineAutoRecallStrategy}.\n *\n * @packageDocumentation\n */\n\nimport type { ContextLocalePack } from './locale-packs/index.js';\n\n/**\n * Per-call scope passed to a custom strategy.\n *\n * @stable\n */\nexport interface AutoRecallStrategyContext {\n  readonly locale: string;\n  readonly lastUserMessage: string;\n}\n\n/**\n * Outcome of a strategy invocation.\n *\n * @stable\n */\nexport interface AutoRecallTriggerResult {\n  readonly factsTriggered: boolean;\n  /** Optional reason surfaced in spans / metadata. */\n  readonly reason?: string;\n}\n\n/**\n * Pluggable strategy signature.\n *\n * @stable\n */\nexport type AutoRecallStrategy = (ctx: AutoRecallStrategyContext) => AutoRecallTriggerResult;\n\n/**\n * Build a locale-driven heuristic strategy. The default for every\n * configured locale.\n *\n * @stable\n */\nexport function defaultLocaleHeuristicStrategy(pack: ContextLocalePack): AutoRecallStrategy {\n  const factTriggers = pack.autoRecallTriggers.factTriggers;\n  return (ctx) => {\n    const text = ctx.lastUserMessage ?? '';\n    if (text.length === 0) {\n      return { factsTriggered: false };\n    }\n    const factsTriggered = factTriggers.some((re) => re.test(text));\n    if (factsTriggered) {\n      return { factsTriggered, reason: 'locale-heuristic-trigger-matched' };\n    }\n    return { factsTriggered: false };\n  };\n}\n\n/**\n * Builder for application-supplied custom strategies. Accepts a\n * raw function and returns a tagged version so the engine can\n * surface the strategy name on spans.\n *\n * @stable\n */\nexport function defineAutoRecallStrategy(opts: {\n  readonly id: string;\n  readonly evaluate: AutoRecallStrategy;\n}): AutoRecallStrategy & { readonly id: string } {\n  if (typeof opts.id !== 'string' || opts.id.length === 0) {\n    throw new TypeError(\n      '[graphorin/memory] defineAutoRecallStrategy: `id` must be a non-empty string.',\n    );\n  }\n  if (typeof opts.evaluate !== 'function') {\n    throw new TypeError(\n      '[graphorin/memory] defineAutoRecallStrategy: `evaluate` must be a function.',\n    );\n  }\n  const wrapped = ((ctx: AutoRecallStrategyContext) => opts.evaluate(ctx)) as AutoRecallStrategy & {\n    readonly id: string;\n  };\n  Object.defineProperty(wrapped, 'id', { value: opts.id, enumerable: true });\n  return wrapped;\n}\n"],"mappings":";;;;;;;AAkDA,SAAgB,+BAA+B,MAA6C;CAC1F,MAAM,eAAe,KAAK,mBAAmB;AAC7C,SAAQ,QAAQ;EACd,MAAM,OAAO,IAAI,mBAAmB;AACpC,MAAI,KAAK,WAAW,EAClB,QAAO,EAAE,gBAAgB,OAAO;EAElC,MAAM,iBAAiB,aAAa,MAAM,OAAO,GAAG,KAAK,KAAK,CAAC;AAC/D,MAAI,eACF,QAAO;GAAE;GAAgB,QAAQ;GAAoC;AAEvE,SAAO,EAAE,gBAAgB,OAAO;;;;;;;;;;AAWpC,SAAgB,yBAAyB,MAGQ;AAC/C,KAAI,OAAO,KAAK,OAAO,YAAY,KAAK,GAAG,WAAW,EACpD,OAAM,IAAI,UACR,gFACD;AAEH,KAAI,OAAO,KAAK,aAAa,WAC3B,OAAM,IAAI,UACR,8EACD;CAEH,MAAM,YAAY,QAAmC,KAAK,SAAS,IAAI;AAGvE,QAAO,eAAe,SAAS,MAAM;EAAE,OAAO,KAAK;EAAI,YAAY;EAAM,CAAC;AAC1E,QAAO"}

package/dist/context-engine/compaction/clear-tool-results.d.ts

@@ -3,7 +3,7 @@ import { Message } from "@graphorin/core";
 
 //#region src/context-engine/compaction/clear-tool-results.d.ts
 
-/** Placeholder prefix on a cleared tool result — makes clearing idempotent. */
+/** Placeholder prefix on a cleared tool result - makes clearing idempotent. */
 declare const CLEARED_TOOL_RESULT_MARKER = "[cleared tool result";
 /** Knobs for {@link clearOldToolResults} (mirrors the strategy variant). */
 interface ClearToolResultsOptions {
@@ -20,7 +20,7 @@ interface ClearToolResultsOptions {
     readonly clearedTokens: number;
   }) => string;
   /**
-   * A6 / SOTA-2 — recoverable clearing. When provided, the original tool-result
+   * A6 / SOTA-2 - recoverable clearing. When provided, the original tool-result
    * text of each cleared message is handed to this callback (wire it to a spill
    * store / the `read_result` handle registry) and the placeholder references the
    * returned handle id + preview, so the model can re-fetch the full result via
@@ -36,6 +36,21 @@ interface ClearToolResultsOptions {
     readonly handleId: string;
     readonly preview?: string;
   }>;
+  /**
+   * C4 (context-engine-11): the tool the externalized-handle placeholder
+   * advertises. The memory package cannot know whether the agent
+   * registered `read_result` (that depends on spill wiring), so callers
+   * whose runtime does NOT expose it pass `null` and the placeholder
+   * degrades to a tool-neutral phrasing instead of promising a tool the
+   * model cannot call. Default `'read_result'` (the agent built-in).
+   */
+  readonly readResultToolName?: string | null;
+  /**
+   * C4 (clear_tool_uses_20250919 parity): additionally blank the PAIRED
+   * assistant message's tool-call arguments for every cleared result,
+   * reclaiming the input side of verbose calls too. Default `false`.
+   */
+  readonly clearToolInputs?: boolean;
 }
 /** Result of a clearing pass. `clearedIndices` empty ⇒ nothing changed. */
 interface ClearToolResultsOutcome {
@@ -45,7 +60,7 @@ interface ClearToolResultsOutcome {
 }
 /**
  * Replace the oldest clearable tool results with placeholders. Returns the new
- * buffer (same length — content is replaced in place, never removed) plus the
+ * buffer (same length - content is replaced in place, never removed) plus the
  * cleared indices and reclaimed token count. Idempotent: already-cleared
  * placeholders are skipped on a second pass.
  */

package/dist/context-engine/compaction/clear-tool-results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clear-tool-results.d.ts","names":[],"sources":["../../../src/context-engine/compaction/clear-tool-results.ts"],"sourcesContent":[],"mappings":";;;;;;AA8FW,cAzEE,0BAAA,GAyEF,sBAAA;;UAnEM,uBAAA;;;;;;0BAMS;;;;;;;;;;;;;;;;;;;;QAuBnB;;;;;;UAIU,uBAAA;qBACI,cAAc;2BACR;;;;;;;;;iBA6BL,mBAAA,WACV,cAAc,mBACf,kCACA,sBACR,QAAQ"}
+{"version":3,"file":"clear-tool-results.d.ts","names":[],"sources":["../../../src/context-engine/compaction/clear-tool-results.ts"],"sourcesContent":[],"mappings":";;;;;;AAoHW,cA/FE,0BAAA,GA+FF,sBAAA;;UAzFM,uBAAA;;;;;;0BAMS;;;;;;;;;;;;;;;;;;;;QAuBnB;;;;;;;;;;;;;;;;;;;;;UAmBU,uBAAA;qBACI,cAAc;2BACR;;;;;;;;;iBAoCL,mBAAA,WACV,cAAc,mBACf,kCACA,sBACR,QAAQ"}