@graphorin/memory 0.5.0 → 0.6.1

package/dist/facade.d.ts

@@ -3,10 +3,11 @@ import { ConflictPipeline, ConflictPipelineOptions } from "./conflict/types.js";
 import "./conflict/index.js";
 import { ContextualRetrievalMode } from "./internal/contextualize.js";
 import { EpisodicMemory } from "./tiers/episodic-memory.js";
+import { SalienceWeights } from "./consolidator/decay.js";
 import { EntityResolutionConfig } from "./graph/entity-resolver.js";
 import { ReRanker } from "./search/types.js";
 import { SemanticMemory } from "./tiers/semantic-memory.js";
-import { SalienceWeights } from "./consolidator/decay.js";
+import { BlockDefinition, WorkingMemory } from "./tiers/working-memory.js";
 import { ConsolidatorCeilings, ConsolidatorPhase, ConsolidatorTier, ConsolidatorTriggerSpec, OnBudgetExceed, PhaseListener } from "./consolidator/types.js";
 import { Consolidator } from "./consolidator/runtime.js";
 import "./consolidator/index.js";
@@ -16,7 +17,6 @@ import { InsightMemory } from "./tiers/insight-memory.js";
 import { ProceduralMemory } from "./tiers/procedural-memory.js";
 import { SessionMemory } from "./tiers/session-memory.js";
 import { SharedMemory } from "./tiers/shared-memory.js";
-import { BlockDefinition, WorkingMemory } from "./tiers/working-memory.js";
 import { ScopeResolver } from "./tools/types.js";
 import "./tools/index.js";
 import { EmbedderProvider, MemoryMetadata, Provider, SessionScope, Tool, Tracer } from "@graphorin/core";
@@ -33,9 +33,9 @@ interface CreateMemoryOptions {
   readonly store: MemoryStoreAdapter;
   /** Embedder registry. The default sqlite store exposes one as `sqlite.embeddings`. */
   readonly embeddings: EmbeddingMetaRegistryLike;
-  /** Embedder provider (default: none — vector search is disabled). */
+  /** Embedder provider (default: none - vector search is disabled). */
   readonly embedder?: EmbedderProvider;
-  /** Pre-declared working blocks (idempotent — re-defining is a no-op). */
+  /** Pre-declared working blocks (idempotent - re-defining is a no-op). */
   readonly workingBlocks?: ReadonlyArray<BlockDefinition>;
   /**
    * Tracer used for every `memory.*` span. Defaults to the no-op
@@ -52,7 +52,7 @@ interface CreateMemoryOptions {
    * structured fields) to the text that is embedded + FTS-indexed, so a
    * terse fact stays findable; the canonical `text` is preserved. `'off'`
    * indexes the bare text. The `'llm'` enrichment is **not** available on
-   * the hot path — it is a consolidator-only opt-in configured via
+   * the hot path - it is a consolidator-only opt-in configured via
    * `consolidator: { contextualRetrieval: 'llm' }`.
    */
   readonly contextualRetrieval?: 'off' | 'late-chunk';
@@ -60,7 +60,7 @@ interface CreateMemoryOptions {
    * Query transformation for retrieval (P2-3, opt-in). When supplied,
    * `SemanticMemory.search(..., { multiQuery })` fans the query into
    * reworded variants (multi-query / RAG-Fusion) and `{ hyde }` adds a
-   * hypothetical-answer embedding — both via one cheap LLM call on the
+   * hypothetical-answer embedding - both via one cheap LLM call on the
    * given provider, fused through the existing RRF reranker. Omitted (the
    * default) ⇒ search stays **offline + single-shot** and the
    * `multiQuery` / `hyde` search options become silent no-ops. Reserve it
@@ -101,7 +101,7 @@ interface CreateMemoryOptions {
    * when memory is insufficient. Omitted (the default) ⇒ `searchIterative`
    * stays a single difficulty-gated pass with **no provider call**, and
    * `deep_recall` is **not** registered (the tool surface stays at the
-   * canonical eleven). Reserve it for hard multi-hop / temporal recall —
+   * canonical eleven). Reserve it for hard multi-hop / temporal recall -
    * it adds provider latency per pass.
    */
   readonly iterativeRetrieval?: {
@@ -118,7 +118,7 @@ interface CreateMemoryOptions {
    * trajectory and stores it **quarantined** + `provenance: 'induction'`.
    * Omitted (the default) ⇒ `induce(...)` throws
    * {@link ProcedureInductionNotConfiguredError} and the procedural tier
-   * stays pure offline CRUD — no provider call.
+   * stays pure offline CRUD - no provider call.
    */
   readonly procedureInduction?: {
     /** Provider used to abstract trajectory values into a procedure. */
@@ -128,7 +128,7 @@ interface CreateMemoryOptions {
   };
   /**
    * Promotion-by-demonstrated-success for quarantined induced
-   * procedures (MCON-2 part 4). Fully offline — orthogonal to
+   * procedures (MCON-2 part 4). Fully offline - orthogonal to
    * `procedureInduction` (no provider needed). When configured,
    * `procedural.recordOutcome(scope, id, true)` increments the rule's
    * persistent success counter and promotes it into `activate()` once
@@ -140,9 +140,19 @@ interface CreateMemoryOptions {
     /** Successful demonstrated reuses required before promotion (≥ 1). */
     readonly afterSuccesses: number;
   };
+  /**
+   * Register the gated `runbook_search` tool (D3) so the model can look
+   * up validated procedures by task description (content recall over
+   * procedural memory, returning whole runbooks). Fully offline - the
+   * default `@graphorin/store-sqlite` adapter serves it from the rules
+   * FTS index (migration 028); adapters without the index degrade to an
+   * in-memory lexical scan. Default `false` - the tool surface stays at
+   * the canonical eleven.
+   */
+  readonly runbookSearch?: boolean;
   /**
    * Resolver that produces the live {@link SessionScope} for each
-   * memory-tool invocation. Defaults to a closure that throws — the
+   * memory-tool invocation. Defaults to a closure that throws - the
    * agent runtime overrides it in Phase 12.
    */
   readonly resolveScope?: ScopeResolver;
@@ -150,8 +160,8 @@ interface CreateMemoryOptions {
    * Consolidator configuration. When omitted, empty, or
    * `enabled: false`, the facade installs the Phase 10a no-op
    * placeholder so consumers can still type their interactions without
-   * paying the runtime cost. ANY other setting — including offline
-   * knobs like `decayCapacity` or `contextualRetrieval` — implicitly
+   * paying the runtime cost. ANY other setting - including offline
+   * knobs like `decayCapacity` or `contextualRetrieval` - implicitly
    * enables the production runtime (MST-4); `enabled: false` together
    * with other settings warns once and keeps the placeholder.
    */
@@ -162,6 +172,14 @@ interface CreateMemoryOptions {
     readonly phases?: ReadonlyArray<ConsolidatorPhase>;
     readonly ceilings?: Partial<ConsolidatorCeilings>;
     readonly onExceed?: OnBudgetExceed;
+    /**
+     * USD pricer for phase LLM usage (memory-consolidation-02) - wire
+     * to `@graphorin/pricing` so `maxCostPerDay` can actually trip.
+     */
+    readonly priceUsage?: (usage: {
+      promptTokens: number;
+      completionTokens: number;
+    }) => number;
     /** Provider routed to the standard phase when set (MCON-7); falls back to `provider`. */
     readonly cheapProvider?: Provider | null;
     /** Provider routed to the deep + reflection passes when set (MCON-7). */
@@ -200,11 +218,22 @@ interface CreateMemoryOptions {
      * and `'off'` defer to the write-path mode. Per-tier default.
      */
     readonly contextualRetrieval?: ContextualRetrievalMode;
+    /**
+     * Maintain the learned-context digest block (D3): after each deep
+     * phase, one budgeted LLM call rewrites the reserved
+     * `learned_context` working block (previous digest + recent
+     * episodes / active insights / procedures), so the assembled system
+     * prompt carries a compact standing summary. Default `false` at
+     * every tier (Wave-D trial).
+     */
+    readonly learnedContext?: boolean;
+    /** Character bound for the learned-context digest (D3). Default `1200`. */
+    readonly learnedContextMaxChars?: number;
     readonly defaultScope?: SessionScope;
     readonly provider?: Provider | null;
-    /** Override the wall clock — used by tests. */
+    /** Override the wall clock - used by tests. */
     readonly now?: () => number;
-    /** Stable id seed — used by tests. */
+    /** Stable id seed - used by tests. */
     readonly randomId?: () => string;
     /** Subscribe to phase-finished events. */
     readonly onPhaseFinished?: PhaseListener;
@@ -271,7 +300,7 @@ interface Memory {
  * @stable
  */
 declare function createMemory(options: CreateMemoryOptions): Memory;
-/** @internal — test seam for the one-time disabled-config warning. */
+/** @internal - test seam for the one-time disabled-config warning. */
 declare function _resetConsolidatorConfigWarningForTesting(): void;
 //#endregion
 export { CreateMemoryOptions, Memory, _resetConsolidatorConfigWarningForTesting, createMemory };

package/dist/facade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facade.d.ts","names":[],"sources":["../src/facade.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAuEA;;;;;AAQ2B,UARV,mBAAA,CAQU;EAMP;EAEE,SAAA,KAAA,EAdJ,kBAcI;EAyBC;EAiBJ,SAAA,UAAA,EAtDI,yBAsDJ;EAIK;EAgBD,SAAA,QAAA,CAAA,EAxED,gBAwEC;EAgBA;EAuBG,SAAA,aAAA,CAAA,EA7GC,aA6GD,CA7Ge,eA6Gf,CAAA;EAYY;;;;;EAGN,SAAA,MAAA,CAAA,EAtHZ,MAsHY;EAAR;EACA,SAAA,QAAA,CAAA,EArHF,QAqHE;EAEK;;;;;;;;;;EA6DiB,SAAA,mBAAA,CAAA,EAAA,KAAA,GAAA,YAAA;EAQ7B;;;;;;;;;;;EAgBY,SAAA,cAAA,CAAA,EAAA;IAEH;IAEL,SAAA,QAAA,EAvLE,QAuLF;IASJ;IAAwB,SAAA,WAAA,CAAA,EAAA,MAAA;IAAyB;IAAR,SAAA,SAAA,CAAA,EAAA,MAAA;EAExC,CAAA;EAAuB;;;AASzC;AAuWA;;;;;;;mBAjiBmB;;;;wBAIK;;;;;;;;;;;;;;;;uBAgBD;;;;;;;;;;;;;;;;uBAgBA;;;;;;;;;;;;;;;;;;;;;;;0BAuBG;;;;;;;;;;;;wBAYF,cAAc;oBAClB;sBACE,cAAc;wBACZ,QAAQ;wBACR;;6BAEK;;4BAED;;;4BAGA;;;;;;;+BAOG;;;;;;;;;;;;;;;;;;;;;;;;mCAwBI;4BACP;wBACJ;;;;;;+BAMO;;;;;;;;8BAQD;;;;;;;;;2BASH;;;;;;;UAQV,MAAA;oBACG;oBACA;qBACC;qBACA;uBACE;mBACJ;;;;;;qBAME;kBACH,cAAc;yBACP;;6BAEI;;0BAEH;;qBAEL;;;;;;;;;iBASJ,wBAAwB,iBAAiB,QAAQ;;kBAEhD,eAAe,QAAQ;;;;;;;;iBASzB,YAAA,UAAsB,sBAAsB;;iBAuW5C,yCAAA,CAAA"}
+{"version":3,"file":"facade.d.ts","names":[],"sources":["../src/facade.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAuEA;;;;;AAQ2B,UARV,mBAAA,CAQU;EAMP;EAEE,SAAA,KAAA,EAdJ,kBAcI;EAyBC;EAiBJ,SAAA,UAAA,EAtDI,yBAsDJ;EAIK;EAgBD,SAAA,QAAA,CAAA,EAxED,gBAwEC;EAgBA;EAiCG,SAAA,aAAA,CAAA,EAvHC,aAuHD,CAvHe,eAuHf,CAAA;EAYY;;;;;EAGN,SAAA,MAAA,CAAA,EAhIZ,MAgIY;EAAR;EACA,SAAA,QAAA,CAAA,EA/HF,QA+HE;EAOK;;;;;;;;;;EAwEiB,SAAA,mBAAA,CAAA,EAAA,KAAA,GAAA,YAAA;EAQ7B;;;;;;;;;;;EAgBY,SAAA,cAAA,CAAA,EAAA;IAEH;IAEL,SAAA,QAAA,EAjNE,QAiNF;IASJ;IAAwB,SAAA,WAAA,CAAA,EAAA,MAAA;IAAyB;IAAR,SAAA,SAAA,CAAA,EAAA,MAAA;EAExC,CAAA;EAAuB;;;AASzC;AAwXA;;;;;;;mBA5kBmB;;;;wBAIK;;;;;;;;;;;;;;;;uBAgBD;;;;;;;;;;;;;;;;uBAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAiCG;;;;;;;;;;;;wBAYF,cAAc;oBAClB;sBACE,cAAc;wBACZ,QAAQ;wBACR;;;;;;;;;;6BAOK;;4BAED;;;4BAGA;;;;;;;+BAOG;;;;;;;;;;;;;;;;;;;;;;;;mCAwBI;;;;;;;;;;;;4BAYP;wBACJ;;;;;;+BAMO;;;;;;;;8BAQD;;;;;;;;;2BASH;;;;;;;UAQV,MAAA;oBACG;oBACA;qBACC;qBACA;uBACE;mBACJ;;;;;;qBAME;kBACH,cAAc;yBACP;;6BAEI;;0BAEH;;qBAEL;;;;;;;;;iBASJ,wBAAwB,iBAAiB,QAAQ;;kBAEhD,eAAe,QAAQ;;;;;;;;iBASzB,YAAA,UAAsB,sBAAsB;;iBAwX5C,yCAAA,CAAA"}

package/dist/facade.js

@@ -1,6 +1,7 @@
 import { createConflictPipeline } from "./conflict/pipeline.js";
 import "./conflict/index.js";
 import { createProviderWorkflowInducer } from "./consolidator/phases/induce.js";
+import { WorkingMemory } from "./tiers/working-memory.js";
 import { createConsolidator } from "./consolidator/runtime.js";
 import { createConsolidatorPlaceholder } from "./consolidator/index.js";
 import { enLocalePack } from "./context-engine/locale-packs/en.js";
@@ -21,7 +22,6 @@ import { ProceduralMemory } from "./tiers/procedural-memory.js";
 import { SemanticMemory } from "./tiers/semantic-memory.js";
 import { SessionMemory } from "./tiers/session-memory.js";
 import { SharedMemory } from "./tiers/shared-memory.js";
-import { WorkingMemory } from "./tiers/working-memory.js";
 import { buildMemoryTools } from "./tools/index.js";
 import { NOOP_TRACER } from "@graphorin/core";
 
@@ -36,7 +36,7 @@ function createMemory(options) {
 	const tracer = options.tracer ?? NOOP_TRACER;
 	const reranker = options.reranker ?? new RRFReranker();
 	const resolveScope = options.resolveScope ?? (() => {
-		throw new TypeError("[graphorin/memory] memory tool invoked without a scope resolver. Pass `resolveScope` to createMemory({...}) — the agent runtime supplies one in Phase 12.");
+		throw new TypeError("[graphorin/memory] memory tool invoked without a scope resolver. Pass `resolveScope` to createMemory({...}) - the agent runtime supplies one in Phase 12.");
 	});
 	let activeEmbedderId = null;
 	if (options.embedder !== void 0) activeEmbedderId = bindEmbedder(options.embedder, options.embeddings);
@@ -86,7 +86,8 @@ function createMemory(options) {
 		...queryTransformer !== null ? { queryTransformer } : {},
 		...entityResolver !== null ? { entityResolver } : {},
 		...grader !== null ? { grader } : {},
-		...options.iterativeRetrieval?.maxIterations !== void 0 ? { iterativeMaxIterations: options.iterativeRetrieval.maxIterations } : {}
+		...options.iterativeRetrieval?.maxIterations !== void 0 ? { iterativeMaxIterations: options.iterativeRetrieval.maxIterations } : {},
+		...options.consolidator?.salienceWeights !== void 0 ? { trustWeights: options.consolidator.salienceWeights } : {}
 	});
 	let consolidatorForSpend = null;
 	const inducer = options.procedureInduction !== void 0 ? createProviderWorkflowInducer(options.procedureInduction.provider, {
@@ -117,9 +118,12 @@ function createMemory(options) {
 		procedural,
 		shared,
 		resolveScope
-	}, { includeDeepRecall: grader !== null });
+	}, {
+		includeDeepRecall: grader !== null,
+		includeRunbookSearch: options.runbookSearch === true
+	});
 	const consolidatorOpts = options.consolidator;
-	const consolidator = buildConsolidator(consolidatorOpts, options.store, semantic, episodic, tracer);
+	const consolidator = buildConsolidator(consolidatorOpts, options.store, semantic, episodic, working, tracer);
 	consolidatorForSpend = consolidator;
 	const contextEngineConfig = options.contextEngine ?? {};
 	const contextEngine = createContextEngine(contextEngineConfig);
@@ -196,7 +200,7 @@ function renderWorkingBlocksXml(blocks) {
 function escapeXml(value) {
 	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function buildConsolidator(opts, store, semantic, episodic, tracer) {
+function buildConsolidator(opts, store, semantic, episodic, working, tracer) {
 	if (opts === void 0) return createConsolidatorPlaceholder();
 	if (!shouldEnableConsolidator(opts)) return createConsolidatorPlaceholder({
 		...opts.triggers !== void 0 ? { triggers: opts.triggers } : {},
@@ -206,6 +210,7 @@ function buildConsolidator(opts, store, semantic, episodic, tracer) {
 		store,
 		semantic,
 		episodic,
+		working,
 		tracer,
 		...opts.provider !== void 0 ? { provider: opts.provider } : {},
 		...opts.now !== void 0 ? { now: opts.now } : {},
@@ -215,6 +220,7 @@ function buildConsolidator(opts, store, semantic, episodic, tracer) {
 		...opts.phases !== void 0 ? { phases: opts.phases } : {},
 		...opts.ceilings !== void 0 ? { ceilings: opts.ceilings } : {},
 		...opts.onExceed !== void 0 ? { onExceed: opts.onExceed } : {},
+		...opts.priceUsage !== void 0 ? { priceUsage: opts.priceUsage } : {},
 		...opts.cheapProvider !== void 0 ? { cheapProvider: opts.cheapProvider } : {},
 		...opts.deepProvider !== void 0 ? { deepProvider: opts.deepProvider } : {},
 		...opts.cheapModel !== void 0 ? { cheapModel: opts.cheapModel } : {},
@@ -237,13 +243,15 @@ function buildConsolidator(opts, store, semantic, episodic, tracer) {
 		...opts.importanceThreshold !== void 0 ? { importanceThreshold: opts.importanceThreshold } : {},
 		...opts.reflectionMaxQuestions !== void 0 ? { reflectionMaxQuestions: opts.reflectionMaxQuestions } : {},
 		...opts.contextualRetrieval !== void 0 ? { contextualRetrieval: opts.contextualRetrieval } : {},
+		...opts.learnedContext !== void 0 ? { learnedContext: opts.learnedContext } : {},
+		...opts.learnedContextMaxChars !== void 0 ? { learnedContextMaxChars: opts.learnedContextMaxChars } : {},
 		...opts.defaultScope !== void 0 ? { defaultScope: opts.defaultScope } : {}
 	});
 	if (opts.onPhaseFinished !== void 0) consolidator.onPhaseFinished(opts.onPhaseFinished);
 	return consolidator;
 }
 let consolidatorConfigIgnoredWarned = false;
-/** @internal — test seam for the one-time disabled-config warning. */
+/** @internal - test seam for the one-time disabled-config warning. */
 function _resetConsolidatorConfigWarningForTesting() {
 	consolidatorConfigIgnoredWarned = false;
 }
@@ -252,7 +260,7 @@ function shouldEnableConsolidator(opts) {
 	if (opts.enabled === false) {
 		if (keys.length > 0 && !consolidatorConfigIgnoredWarned) {
 			consolidatorConfigIgnoredWarned = true;
-			process.stderr.write(`[graphorin/memory] consolidator config (${keys.join(", ")}) was supplied together with enabled: false — the settings are ignored until the consolidator is enabled.\n`);
+			process.stderr.write(`[graphorin/memory] consolidator config (${keys.join(", ")}) was supplied together with enabled: false - the settings are ignored until the consolidator is enabled.\n`);
 		}
 		return false;
 	}

package/dist/facade.js.map

@@ -1 +1 @@
-{"version":3,"file":"facade.js","names":["reranker: ReRanker","resolveScope: ScopeResolver","activeEmbedderId: string | null","consolidatorForSpend: Consolidator | null","consolidator: Consolidator","contextEngine: ContextEngine","out: { -readonly [K in keyof MemoryContextBlocks]: MemoryContextBlocks[K] }","blocksKept: ReadonlyArray<(typeof blocks)[number]>","rulesKept: ReadonlyArray<(typeof rules)[number]>","filterContext: Parameters<typeof partitionBySensitivity>[1]","partitionBySensitivity"],"sources":["../src/facade.ts"],"sourcesContent":["/**\n * `createMemory()` — the facade that wires every tier sub-module (the\n * seven-tier system) + the eleven (+1 gated) memory tools + the search\n * reranker + the context engine\n * stubs + the consolidator placeholder.\n *\n * @packageDocumentation\n */\n\nimport type {\n  EmbedderProvider,\n  MemoryMetadata,\n  Provider,\n  SessionScope,\n  Tool,\n  Tracer,\n} from '@graphorin/core';\nimport { NOOP_TRACER } from '@graphorin/core';\nimport {\n  type ConflictPipeline,\n  type ConflictPipelineOptions,\n  createConflictPipeline,\n} from './conflict/index.js';\nimport {\n  type Consolidator,\n  type ConsolidatorCeilings,\n  type ConsolidatorPhase,\n  type ConsolidatorTier,\n  type ConsolidatorTriggerSpec,\n  createConsolidator,\n  createConsolidatorPlaceholder,\n  createProviderWorkflowInducer,\n  type OnBudgetExceed,\n  type PhaseListener,\n  type SalienceWeights,\n} from './consolidator/index.js';\nimport { createContextEngine } from './context-engine/engine.js';\nimport type {\n  CompileOptions,\n  CompileScope,\n  ContextEngine,\n  ContextEngineConfig,\n  MemoryContextBlocks,\n} from './context-engine/index.js';\nimport { enLocalePack } from './context-engine/locale-packs/index.js';\nimport { resolveLocalePack } from './context-engine/locale-packs/resolver.js';\nimport { gatherMemoryMetadata, renderMetadataBlock } from './context-engine/metadata.js';\nimport { partition as partitionBySensitivity } from './context-engine/privacy-filter.js';\nimport { composeLayer1 } from './context-engine/templates/composer.js';\nimport { type EntityResolutionConfig, EntityResolver } from './graph/entity-resolver.js';\nimport type { ContextualRetrievalMode } from './internal/contextualize.js';\nimport { bindEmbedder } from './internal/embedder-binding.js';\nimport type { EmbeddingMetaRegistryLike, MemoryStoreAdapter } from './internal/storage-adapter.js';\nimport { createProviderRetrievalGrader } from './search/iterative.js';\nimport { createProviderQueryTransformer } from './search/query-transform.js';\nimport { RRFReranker } from './search/rrf.js';\nimport type { ReRanker } from './search/types.js';\nimport { EpisodicMemory } from './tiers/episodic-memory.js';\nimport { InsightMemory } from './tiers/insight-memory.js';\nimport { ProceduralMemory } from './tiers/procedural-memory.js';\nimport { SemanticMemory } from './tiers/semantic-memory.js';\nimport { SessionMemory } from './tiers/session-memory.js';\nimport { SharedMemory } from './tiers/shared-memory.js';\nimport { type BlockDefinition, WorkingMemory } from './tiers/working-memory.js';\nimport { buildMemoryTools, type ScopeResolver } from './tools/index.js';\n\n/**\n * Options accepted by {@link createMemory}.\n *\n * @stable\n */\nexport interface CreateMemoryOptions {\n  /** Storage adapter (default: `@graphorin/store-sqlite`'s `MemoryStore`). */\n  readonly store: MemoryStoreAdapter;\n  /** Embedder registry. The default sqlite store exposes one as `sqlite.embeddings`. */\n  readonly embeddings: EmbeddingMetaRegistryLike;\n  /** Embedder provider (default: none — vector search is disabled). */\n  readonly embedder?: EmbedderProvider;\n  /** Pre-declared working blocks (idempotent — re-defining is a no-op). */\n  readonly workingBlocks?: ReadonlyArray<BlockDefinition>;\n  /**\n   * Tracer used for every `memory.*` span. Defaults to the no-op\n   * tracer from `@graphorin/core` so unit tests do not need to wire\n   * the observability stack.\n   */\n  readonly tracer?: Tracer;\n  /** Override the reranker used by `SemanticMemory.search`. */\n  readonly reranker?: ReRanker;\n  /**\n   * Contextual-retrieval mode for the write path (P1-3). `'late-chunk'`\n   * (default) prepends a deterministic, offline situating context\n   * (entities / timeframe / topics, derived from the fact's own\n   * structured fields) to the text that is embedded + FTS-indexed, so a\n   * terse fact stays findable; the canonical `text` is preserved. `'off'`\n   * indexes the bare text. The `'llm'` enrichment is **not** available on\n   * the hot path — it is a consolidator-only opt-in configured via\n   * `consolidator: { contextualRetrieval: 'llm' }`.\n   */\n  readonly contextualRetrieval?: 'off' | 'late-chunk';\n  /**\n   * Query transformation for retrieval (P2-3, opt-in). When supplied,\n   * `SemanticMemory.search(..., { multiQuery })` fans the query into\n   * reworded variants (multi-query / RAG-Fusion) and `{ hyde }` adds a\n   * hypothetical-answer embedding — both via one cheap LLM call on the\n   * given provider, fused through the existing RRF reranker. Omitted (the\n   * default) ⇒ search stays **offline + single-shot** and the\n   * `multiQuery` / `hyde` search options become silent no-ops. Reserve it\n   * for retrieval-heavy recall, not every search (it adds provider\n   * latency).\n   */\n  readonly queryTransform?: {\n    /** Cheap provider used to rewrite the query / write the HyDE passage. */\n    readonly provider: Provider;\n    /** Hard ceiling on reworded variants requested per call. Default 5. */\n    readonly maxVariants?: number;\n    /** Output-token ceiling per transform call. Default 256. */\n    readonly maxTokens?: number;\n  };\n  /**\n   * Relation-graph entity resolution (P2-1). When `entityResolution` is\n   * `true` **and** the storage adapter exposes a `graph` surface (the\n   * default `@graphorin/store-sqlite` does), `remember(...)` resolves a\n   * fact's subject / object to canonical entities and links them, so\n   * `search(..., { expandHops: 1 })` can traverse relationships. Omitted\n   * (the default) ⇒ facts still carry s/p/o but form no entity links and\n   * the write path stays offline + unchanged. Dedup is lexical +\n   * embedding (offline, via the configured embedder); LLM adjudication of\n   * ambiguous merges is a further opt-in that needs `provider`.\n   */\n  readonly graph?: EntityResolutionConfig & {\n    /** Enable entity resolution + linking on write. Default `false`. */\n    readonly entityResolution?: boolean;\n    /** Provider for opt-in LLM adjudication of ambiguous merges. */\n    readonly provider?: Provider;\n  };\n  /**\n   * Agentic / iterative retrieval (P2-4, opt-in). When supplied,\n   * `SemanticMemory.searchIterative(...)` and the gated `deep_recall`\n   * tool can grade a retrieved set on the given provider and, for queries\n   * judged hard, reformulate + retrieve again (widening to one-hop graph\n   * expansion) up to `maxIterations`, abstaining instead of confabulating\n   * when memory is insufficient. Omitted (the default) ⇒ `searchIterative`\n   * stays a single difficulty-gated pass with **no provider call**, and\n   * `deep_recall` is **not** registered (the tool surface stays at the\n   * canonical eleven). Reserve it for hard multi-hop / temporal recall —\n   * it adds provider latency per pass.\n   */\n  readonly iterativeRetrieval?: {\n    /** Cheap provider used to grade retrieved memories + reformulate. */\n    readonly provider: Provider;\n    /** Default total-pass cap (clamped to `[1, 5]`). Default 3. */\n    readonly maxIterations?: number;\n    /** Output-token ceiling per grade call. Default 256. */\n    readonly maxTokens?: number;\n  };\n  /**\n   * Opt-in workflow induction (P2-2). When set, `ProceduralMemory.induce(...)`\n   * distils a reusable, value-abstracted procedure from a successful agent\n   * trajectory and stores it **quarantined** + `provenance: 'induction'`.\n   * Omitted (the default) ⇒ `induce(...)` throws\n   * {@link ProcedureInductionNotConfiguredError} and the procedural tier\n   * stays pure offline CRUD — no provider call.\n   */\n  readonly procedureInduction?: {\n    /** Provider used to abstract trajectory values into a procedure. */\n    readonly provider: Provider;\n    /** Output-token ceiling per induction call. Default 512. */\n    readonly maxTokens?: number;\n  };\n  /**\n   * Promotion-by-demonstrated-success for quarantined induced\n   * procedures (MCON-2 part 4). Fully offline — orthogonal to\n   * `procedureInduction` (no provider needed). When configured,\n   * `procedural.recordOutcome(scope, id, true)` increments the rule's\n   * persistent success counter and promotes it into `activate()` once\n   * `afterSuccesses` verified reuses accumulate; the injection gate\n   * still refuses flagged texts. Omitted ⇒ outcomes are counted but\n   * nothing auto-promotes.\n   */\n  readonly procedurePromotion?: {\n    /** Successful demonstrated reuses required before promotion (≥ 1). */\n    readonly afterSuccesses: number;\n  };\n  /**\n   * Resolver that produces the live {@link SessionScope} for each\n   * memory-tool invocation. Defaults to a closure that throws — the\n   * agent runtime overrides it in Phase 12.\n   */\n  readonly resolveScope?: ScopeResolver;\n  /**\n   * Consolidator configuration. When omitted, empty, or\n   * `enabled: false`, the facade installs the Phase 10a no-op\n   * placeholder so consumers can still type their interactions without\n   * paying the runtime cost. ANY other setting — including offline\n   * knobs like `decayCapacity` or `contextualRetrieval` — implicitly\n   * enables the production runtime (MST-4); `enabled: false` together\n   * with other settings warns once and keeps the placeholder.\n   */\n  readonly consolidator?: {\n    readonly enabled?: boolean;\n    readonly triggers?: ReadonlyArray<ConsolidatorTriggerSpec>;\n    readonly tier?: ConsolidatorTier;\n    readonly phases?: ReadonlyArray<ConsolidatorPhase>;\n    readonly ceilings?: Partial<ConsolidatorCeilings>;\n    readonly onExceed?: OnBudgetExceed;\n    /** Provider routed to the standard phase when set (MCON-7); falls back to `provider`. */\n    readonly cheapProvider?: Provider | null;\n    /** Provider routed to the deep + reflection passes when set (MCON-7). */\n    readonly deepProvider?: Provider | null;\n    readonly cheapModel?: string | null;\n    readonly deepModel?: string | null;\n    readonly noiseFilters?: ReadonlyArray<'default' | 'minimal' | 'none'>;\n    readonly lockWaitMs?: number;\n    readonly decayTauDays?: number;\n    readonly decayArchiveThreshold?: number;\n    /** Capacity-bounded eviction target for the light phase (X-1). Default unbounded. */\n    readonly decayCapacity?: number | null;\n    /** Weights for the multi-signal salience score (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    /** Auto-form quarantined episodes from processed slices (P1-2). Per-tier default. */\n    readonly formEpisodes?: boolean;\n    /** Score episode importance via the consolidator LLM (P1-2). Per-tier default. */\n    readonly importanceScoring?: boolean;\n    /** Opt in to auto-promotion of injection-clean extraction facts (MCON-2). Default off. */\n    readonly autoPromoteExtraction?: boolean;\n    /** Run the deep-phase reflection pass synthesizing cited insights (P1-1). Per-tier default. */\n    readonly reflection?: boolean;\n    /** Accumulated-importance threshold at which reflection fires (P1-1). */\n    readonly importanceThreshold?: number;\n    /** Upper bound on salient questions reflection asks per pass (P1-1). */\n    readonly reflectionMaxQuestions?: number;\n    /**\n     * Contextual retrieval for standard-phase fact writes (P1-3).\n     * `'llm'` opts into one budgeted cheap-model call per write to author\n     * a situating prefix (consolidator-only); `'late-chunk'` (default)\n     * and `'off'` defer to the write-path mode. Per-tier default.\n     */\n    readonly contextualRetrieval?: ContextualRetrievalMode;\n    readonly defaultScope?: SessionScope;\n    readonly provider?: Provider | null;\n    /** Override the wall clock — used by tests. */\n    readonly now?: () => number;\n    /** Stable id seed — used by tests. */\n    readonly randomId?: () => string;\n    /** Subscribe to phase-finished events. */\n    readonly onPhaseFinished?: PhaseListener;\n  };\n  /**\n   * Conflict pipeline configuration (Phase 10b). Default: enabled,\n   * English locale pack, thresholds `0.95 / 0.85 / 0.4`. Pass\n   * `{ mode: 'off' }` to bypass the pipeline entirely (logs a one-shot\n   * WARN per process per the spec).\n   */\n  readonly conflictPipeline?: ConflictPipelineOptions;\n  /**\n   * Context engine configuration (Phase 10d). The engine assembles\n   * the layered six-layer system prompt; `memory.compile(scope)`\n   * delegates to it for the working blocks + rules + metadata\n   * fragments. When omitted, a default engine is created (English\n   * locale; `'full'` base mode; no auto-recall; conservative\n   * `'public-tls'` provider trust).\n   */\n  readonly contextEngine?: ContextEngineConfig;\n}\n\n/**\n * The facade returned by {@link createMemory}.\n *\n * @stable\n */\nexport interface Memory {\n  readonly working: WorkingMemory;\n  readonly session: SessionMemory;\n  readonly episodic: EpisodicMemory;\n  readonly semantic: SemanticMemory;\n  readonly procedural: ProceduralMemory;\n  readonly shared: SharedMemory;\n  /**\n   * Read surface over reflection insights (P1-1). A no-op (returns\n   * empty) when the storage adapter does not expose the optional\n   * insight surface.\n   */\n  readonly insights: InsightMemory;\n  readonly tools: ReadonlyArray<Tool>;\n  readonly consolidator: Consolidator;\n  /** The configured conflict pipeline. Surfaced for tests + CLI tooling. */\n  readonly conflictPipeline: ConflictPipeline;\n  /** The configured context engine (Phase 10d). */\n  readonly contextEngine: ContextEngine;\n  /** The active embedder, when configured. `null` otherwise. */\n  readonly embedder: EmbedderProvider | null;\n  /** The canonical id of the active embedder, when configured. */\n  embedderId(): string | null;\n  /**\n   * Compile a system-prompt block bundle. The bundle carries the\n   * static fragments per memory tier; the agent runtime consumes\n   * the {@link ContextEngine} surface (`memory.contextEngine`)\n   * directly for the full six-layer assembly.\n   */\n  compile(scope: CompileScope, options?: CompileOptions): Promise<MemoryContextBlocks>;\n  /** Counter snapshot consumed by Phase 10d's metadata layer. */\n  metadata(scope: SessionScope): Promise<MemoryMetadata>;\n}\n\n/**\n * Wire every memory subsystem in one call. Returns the typed\n * `Memory` facade ready to be passed into `createAgent({...})`.\n *\n * @stable\n */\nexport function createMemory(options: CreateMemoryOptions): Memory {\n  const tracer = options.tracer ?? NOOP_TRACER;\n  const reranker: ReRanker = options.reranker ?? new RRFReranker();\n  const resolveScope: ScopeResolver =\n    options.resolveScope ??\n    (() => {\n      throw new TypeError(\n        '[graphorin/memory] memory tool invoked without a scope resolver. ' +\n          'Pass `resolveScope` to createMemory({...}) — the agent runtime supplies one in Phase 12.',\n      );\n    });\n\n  let activeEmbedderId: string | null = null;\n  if (options.embedder !== undefined) {\n    activeEmbedderId = bindEmbedder(options.embedder, options.embeddings);\n  }\n  const embedder = options.embedder ?? null;\n  const embedderIdProvider = (): string | null => activeEmbedderId;\n\n  const working = new WorkingMemory({ store: options.store, tracer });\n  for (const block of options.workingBlocks ?? []) {\n    working.define(block);\n  }\n  const session = new SessionMemory({ store: options.store, tracer });\n  const episodic = new EpisodicMemory({\n    store: options.store,\n    tracer,\n    embedder,\n    embedderIdProvider,\n  });\n  const conflictPipeline = createConflictPipeline(options.conflictPipeline ?? {});\n  // P2-3: build the (opt-in) query transformer from the supplied provider.\n  // Absent ⇒ `null` ⇒ search stays offline + single-shot.\n  const queryTransformer =\n    options.queryTransform !== undefined\n      ? createProviderQueryTransformer(options.queryTransform.provider, {\n          ...(options.queryTransform.maxVariants !== undefined\n            ? { maxVariants: options.queryTransform.maxVariants }\n            : {}),\n          ...(options.queryTransform.maxTokens !== undefined\n            ? { maxTokens: options.queryTransform.maxTokens }\n            : {}),\n        })\n      : null;\n  // P2-1: build the (opt-in) entity resolver. Requires `graph.entityResolution`\n  // *and* a graph-capable adapter; absent ⇒ `null` ⇒ writes carry s/p/o but\n  // form no entity links and the write path stays offline + unchanged.\n  const graphStore = options.store.graph;\n  const entityResolver =\n    options.graph?.entityResolution === true && graphStore !== undefined\n      ? new EntityResolver({\n          store: graphStore,\n          embedder,\n          embedderId: embedderIdProvider,\n          ...(options.graph.provider !== undefined ? { provider: options.graph.provider } : {}),\n          config: {\n            ...(options.graph.mergeThreshold !== undefined\n              ? { mergeThreshold: options.graph.mergeThreshold }\n              : {}),\n            ...(options.graph.adjudicateThreshold !== undefined\n              ? { adjudicateThreshold: options.graph.adjudicateThreshold }\n              : {}),\n            ...(options.graph.llmAdjudication !== undefined\n              ? { llmAdjudication: options.graph.llmAdjudication }\n              : {}),\n          },\n        })\n      : null;\n  // P2-4: build the (opt-in) retrieval grader. Absent ⇒ `null` ⇒\n  // `searchIterative` runs a single difficulty-gated pass (no provider\n  // call) and the `deep_recall` tool is not registered.\n  const grader =\n    options.iterativeRetrieval !== undefined\n      ? createProviderRetrievalGrader(options.iterativeRetrieval.provider, {\n          ...(options.iterativeRetrieval.maxTokens !== undefined\n            ? { maxTokens: options.iterativeRetrieval.maxTokens }\n            : {}),\n        })\n      : null;\n  const semantic = new SemanticMemory({\n    store: options.store,\n    tracer,\n    embedder,\n    embedderIdProvider,\n    reranker,\n    conflictPipeline,\n    ...(options.contextualRetrieval !== undefined\n      ? { contextualRetrieval: options.contextualRetrieval }\n      : {}),\n    ...(queryTransformer !== null ? { queryTransformer } : {}),\n    ...(entityResolver !== null ? { entityResolver } : {}),\n    ...(grader !== null ? { grader } : {}),\n    ...(options.iterativeRetrieval?.maxIterations !== undefined\n      ? { iterativeMaxIterations: options.iterativeRetrieval.maxIterations }\n      : {}),\n  });\n  // P2-2: build the (opt-in) workflow inducer. Absent ⇒ `null` ⇒\n  // `ProceduralMemory.induce(...)` throws and the tier stays offline CRUD.\n  // MCON-15: induction spend is recorded into the consolidator budget —\n  // the consolidator is constructed AFTER the inducer, so the callback\n  // routes through a slot filled below (placeholder ⇒ no-op).\n  let consolidatorForSpend: Consolidator | null = null;\n  const inducer =\n    options.procedureInduction !== undefined\n      ? createProviderWorkflowInducer(options.procedureInduction.provider, {\n          ...(options.procedureInduction.maxTokens !== undefined\n            ? { maxTokens: options.procedureInduction.maxTokens }\n            : {}),\n          onUsage: (usage) => {\n            consolidatorForSpend?.recordExternalSpend(usage.promptTokens + usage.completionTokens);\n          },\n        })\n      : null;\n  const procedural = new ProceduralMemory({\n    store: options.store,\n    tracer,\n    ...(inducer !== null ? { inducer } : {}),\n    // MCON-2 part 4: opt-in promotion-by-demonstrated-success.\n    ...(options.procedurePromotion?.afterSuccesses !== undefined\n      ? { promoteAfterSuccesses: options.procedurePromotion.afterSuccesses }\n      : {}),\n  });\n  const shared = new SharedMemory({ store: options.store, tracer });\n  const insights = new InsightMemory({ store: options.store, tracer });\n\n  const tools = buildMemoryTools(\n    {\n      working,\n      session,\n      episodic,\n      semantic,\n      procedural,\n      shared,\n      resolveScope,\n    },\n    // P2-4: the gated `deep_recall` tool is registered only when a grader\n    // is configured — the offline default stays at exactly eleven tools.\n    { includeDeepRecall: grader !== null },\n  );\n\n  const consolidatorOpts = options.consolidator;\n  const consolidator: Consolidator = buildConsolidator(\n    consolidatorOpts,\n    options.store,\n    semantic,\n    episodic,\n    tracer,\n  );\n  consolidatorForSpend = consolidator;\n  const contextEngineConfig = options.contextEngine ?? {};\n  const contextEngine: ContextEngine = createContextEngine(contextEngineConfig);\n  const resolved = contextEngine.config();\n  const localePack =\n    contextEngineConfig.locale === undefined\n      ? enLocalePack\n      : typeof contextEngineConfig.locale === 'string'\n        ? contextEngineConfig.locale === enLocalePack.id\n          ? enLocalePack\n          : resolveLocalePack({ id: contextEngineConfig.locale })\n        : resolveLocalePack(contextEngineConfig.locale);\n\n  // The facade's `compile(...)` is the static-fragment surface\n  // consumed by callers that do not know the active provider yet\n  // (the agent runtime calls `memory.contextEngine.assemble(...)`\n  // with full provider context when `autoAssembleContext` is\n  // enabled). The privacy filter only fires\n  // when the caller explicitly passes `providerAcceptsSensitivity`\n  // OR the operator opted into the engine's `privacy` block.\n  const privacyOptedIn =\n    contextEngineConfig.privacy !== undefined &&\n    (contextEngineConfig.privacy.providerAcceptsSensitivity !== undefined ||\n      contextEngineConfig.privacy.cloudUploadConsent !== undefined ||\n      contextEngineConfig.privacy.providerTrust !== undefined);\n\n  async function compile(\n    scope: CompileScope,\n    compileOptions: CompileOptions = {},\n  ): Promise<MemoryContextBlocks> {\n    const out: { -readonly [K in keyof MemoryContextBlocks]: MemoryContextBlocks[K] } = {};\n    const blocks = await options.store.working.list(scope);\n    // Quarantined (e.g. P2-2-induced) procedures are provisional and must not\n    // reach the system prompt — `activate()` already excludes them, and\n    // compile() (public `@stable`) must agree or a compile()-based prompt\n    // builder ingests unvalidated induction procedures (MST-3).\n    const rules = (await options.store.procedural.list(scope)).filter(\n      (rule) => rule.status !== 'quarantined',\n    );\n    const shouldFilter = privacyOptedIn || compileOptions.providerAcceptsSensitivity !== undefined;\n    let blocksKept: ReadonlyArray<(typeof blocks)[number]> = blocks;\n    let rulesKept: ReadonlyArray<(typeof rules)[number]> = rules;\n    if (shouldFilter) {\n      const filterContext: Parameters<typeof partitionBySensitivity>[1] = {\n        providerTrust: resolved.providerTrust,\n        cloudUploadConsent: resolved.cloudUploadConsent,\n        defaultSensitivity: resolved.defaultSensitivity,\n      };\n      if (compileOptions.providerAcceptsSensitivity !== undefined) {\n        (\n          filterContext as {\n            providerAcceptsSensitivity?: ReadonlyArray<'public' | 'internal' | 'secret'>;\n          }\n        ).providerAcceptsSensitivity = compileOptions.providerAcceptsSensitivity;\n      }\n      blocksKept = partitionBySensitivity(blocks, filterContext).kept;\n      rulesKept = partitionBySensitivity(rules, filterContext).kept;\n    }\n    const blocksXml = renderWorkingBlocksXml(blocksKept);\n    if (blocksXml.length > 0) {\n      out.workingBlocks = blocksXml;\n    }\n    if (rulesKept.length > 0) {\n      const lines = ['<memory_rules>'];\n      for (const rule of rulesKept) {\n        lines.push(`  <rule priority=\"${rule.priority}\">${escapeXml(rule.text)}</rule>`);\n      }\n      lines.push('</memory_rules>');\n      out.rules = lines.join('\\n');\n    }\n    if (compileOptions.includeMetadata !== false) {\n      const meta = await metadata(scope);\n      out.metadata = renderMetadataBlock(meta);\n    }\n    out.base = composeLayer1(localePack, resolved.memoryBaseMode);\n    return Object.freeze(out);\n  }\n\n  async function metadata(scope: SessionScope): Promise<MemoryMetadata> {\n    return gatherMemoryMetadata(scope, {\n      store: options.store,\n      consolidator,\n      embedderId: embedderIdProvider,\n      localeId: resolved.localeId,\n    });\n  }\n\n  return Object.freeze({\n    working,\n    session,\n    episodic,\n    semantic,\n    procedural,\n    shared,\n    insights,\n    tools,\n    consolidator,\n    conflictPipeline,\n    contextEngine,\n    embedder,\n    embedderId: embedderIdProvider,\n    compile,\n    metadata,\n  });\n}\n\nfunction renderWorkingBlocksXml(\n  blocks: ReadonlyArray<{\n    readonly label: string;\n    readonly value: string;\n    readonly description?: string;\n  }>,\n): string {\n  if (blocks.length === 0) return '';\n  const lines = ['<memory_blocks>'];\n  for (const block of blocks) {\n    const description =\n      block.description !== undefined ? ` description=\"${escapeXml(block.description)}\"` : '';\n    lines.push(`  <block label=\"${escapeXml(block.label)}\"${description}>`);\n    lines.push(`    ${escapeXml(block.value)}`);\n    lines.push('  </block>');\n  }\n  lines.push('</memory_blocks>');\n  return lines.join('\\n');\n}\n\nfunction escapeXml(value: string): string {\n  return value\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n\nfunction buildConsolidator(\n  opts: CreateMemoryOptions['consolidator'],\n  store: CreateMemoryOptions['store'],\n  semantic: SemanticMemory,\n  episodic: EpisodicMemory,\n  tracer: Tracer,\n): Consolidator {\n  if (opts === undefined) {\n    return createConsolidatorPlaceholder();\n  }\n  const enabled = shouldEnableConsolidator(opts);\n  if (!enabled) {\n    return createConsolidatorPlaceholder({\n      ...(opts.triggers !== undefined ? { triggers: opts.triggers } : {}),\n      ...(opts.tier !== undefined ? { tier: opts.tier } : {}),\n    });\n  }\n  const consolidator = createConsolidator({\n    store,\n    semantic,\n    episodic,\n    tracer,\n    ...(opts.provider !== undefined ? { provider: opts.provider } : {}),\n    ...(opts.now !== undefined ? { now: opts.now } : {}),\n    ...(opts.randomId !== undefined ? { randomId: opts.randomId } : {}),\n    ...(opts.triggers !== undefined ? { triggers: opts.triggers } : {}),\n    ...(opts.tier !== undefined ? { tier: opts.tier } : {}),\n    ...(opts.phases !== undefined ? { phases: opts.phases } : {}),\n    ...(opts.ceilings !== undefined ? { ceilings: opts.ceilings } : {}),\n    ...(opts.onExceed !== undefined ? { onExceed: opts.onExceed } : {}),\n    ...(opts.cheapProvider !== undefined ? { cheapProvider: opts.cheapProvider } : {}),\n    ...(opts.deepProvider !== undefined ? { deepProvider: opts.deepProvider } : {}),\n    ...(opts.cheapModel !== undefined ? { cheapModel: opts.cheapModel } : {}),\n    ...(opts.deepModel !== undefined ? { deepModel: opts.deepModel } : {}),\n    ...(opts.noiseFilters !== undefined ? { noiseFilters: opts.noiseFilters } : {}),\n    ...(opts.lockWaitMs !== undefined ? { lockWaitMs: opts.lockWaitMs } : {}),\n    ...(opts.decayTauDays !== undefined ? { decayTauDays: opts.decayTauDays } : {}),\n    ...(opts.decayArchiveThreshold !== undefined\n      ? { decayArchiveThreshold: opts.decayArchiveThreshold }\n      : {}),\n    ...(opts.decayCapacity !== undefined ? { decayCapacity: opts.decayCapacity } : {}),\n    ...(opts.salienceWeights !== undefined ? { salienceWeights: opts.salienceWeights } : {}),\n    ...(opts.maxStandardBatchSize !== undefined\n      ? { maxStandardBatchSize: opts.maxStandardBatchSize }\n      : {}),\n    ...(opts.maxDeepConflictsPerRun !== undefined\n      ? { maxDeepConflictsPerRun: opts.maxDeepConflictsPerRun }\n      : {}),\n    ...(opts.dlqMaxRetries !== undefined ? { dlqMaxRetries: opts.dlqMaxRetries } : {}),\n    ...(opts.dlqBaseBackoffMs !== undefined ? { dlqBaseBackoffMs: opts.dlqBaseBackoffMs } : {}),\n    ...(opts.dlqMaxBackoffMs !== undefined ? { dlqMaxBackoffMs: opts.dlqMaxBackoffMs } : {}),\n    ...(opts.formEpisodes !== undefined ? { formEpisodes: opts.formEpisodes } : {}),\n    ...(opts.importanceScoring !== undefined ? { importanceScoring: opts.importanceScoring } : {}),\n    ...(opts.autoPromoteExtraction !== undefined\n      ? { autoPromoteExtraction: opts.autoPromoteExtraction }\n      : {}),\n    ...(opts.reflection !== undefined ? { reflection: opts.reflection } : {}),\n    ...(opts.importanceThreshold !== undefined\n      ? { importanceThreshold: opts.importanceThreshold }\n      : {}),\n    ...(opts.reflectionMaxQuestions !== undefined\n      ? { reflectionMaxQuestions: opts.reflectionMaxQuestions }\n      : {}),\n    ...(opts.contextualRetrieval !== undefined\n      ? { contextualRetrieval: opts.contextualRetrieval }\n      : {}),\n    ...(opts.defaultScope !== undefined ? { defaultScope: opts.defaultScope } : {}),\n  });\n  if (opts.onPhaseFinished !== undefined) {\n    consolidator.onPhaseFinished(opts.onPhaseFinished);\n  }\n  return consolidator;\n}\n\nlet consolidatorConfigIgnoredWarned = false;\n\n/** @internal — test seam for the one-time disabled-config warning. */\nexport function _resetConsolidatorConfigWarningForTesting(): void {\n  consolidatorConfigIgnoredWarned = false;\n}\n\nfunction shouldEnableConsolidator(opts: NonNullable<CreateMemoryOptions['consolidator']>): boolean {\n  // MST-4: ANY non-empty consolidator config implicitly enables — the old\n  // allow-list silently ignored offline knobs (`decayCapacity`,\n  // `formEpisodes`, `reflection`, `contextualRetrieval`, …): the caller\n  // got a no-op placeholder while believing the feature was on.\n  const keys = Object.keys(opts).filter(\n    (k) => k !== 'enabled' && (opts as Record<string, unknown>)[k] !== undefined,\n  );\n  if (opts.enabled === false) {\n    if (keys.length > 0 && !consolidatorConfigIgnoredWarned) {\n      consolidatorConfigIgnoredWarned = true;\n      process.stderr.write(\n        `[graphorin/memory] consolidator config (${keys.join(', ')}) was supplied together with enabled: false — the settings are ignored until the consolidator is enabled.\\n`,\n      );\n    }\n    return false;\n  }\n  if (opts.enabled === true) return true;\n  return keys.length > 0;\n}\n"],"mappings":"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"}
+{"version":3,"file":"facade.js","names":["reranker: ReRanker","resolveScope: ScopeResolver","activeEmbedderId: string | null","consolidatorForSpend: Consolidator | null","consolidator: Consolidator","contextEngine: ContextEngine","out: { -readonly [K in keyof MemoryContextBlocks]: MemoryContextBlocks[K] }","blocksKept: ReadonlyArray<(typeof blocks)[number]>","rulesKept: ReadonlyArray<(typeof rules)[number]>","filterContext: Parameters<typeof partitionBySensitivity>[1]","partitionBySensitivity"],"sources":["../src/facade.ts"],"sourcesContent":["/**\n * `createMemory()` - the facade that wires every tier sub-module (the\n * seven-tier system) + the eleven (+1 gated) memory tools + the search\n * reranker + the context engine\n * stubs + the consolidator placeholder.\n *\n * @packageDocumentation\n */\n\nimport type {\n  EmbedderProvider,\n  MemoryMetadata,\n  Provider,\n  SessionScope,\n  Tool,\n  Tracer,\n} from '@graphorin/core';\nimport { NOOP_TRACER } from '@graphorin/core';\nimport {\n  type ConflictPipeline,\n  type ConflictPipelineOptions,\n  createConflictPipeline,\n} from './conflict/index.js';\nimport {\n  type Consolidator,\n  type ConsolidatorCeilings,\n  type ConsolidatorPhase,\n  type ConsolidatorTier,\n  type ConsolidatorTriggerSpec,\n  createConsolidator,\n  createConsolidatorPlaceholder,\n  createProviderWorkflowInducer,\n  type OnBudgetExceed,\n  type PhaseListener,\n  type SalienceWeights,\n} from './consolidator/index.js';\nimport { createContextEngine } from './context-engine/engine.js';\nimport type {\n  CompileOptions,\n  CompileScope,\n  ContextEngine,\n  ContextEngineConfig,\n  MemoryContextBlocks,\n} from './context-engine/index.js';\nimport { enLocalePack } from './context-engine/locale-packs/index.js';\nimport { resolveLocalePack } from './context-engine/locale-packs/resolver.js';\nimport { gatherMemoryMetadata, renderMetadataBlock } from './context-engine/metadata.js';\nimport { partition as partitionBySensitivity } from './context-engine/privacy-filter.js';\nimport { composeLayer1 } from './context-engine/templates/composer.js';\nimport { type EntityResolutionConfig, EntityResolver } from './graph/entity-resolver.js';\nimport type { ContextualRetrievalMode } from './internal/contextualize.js';\nimport { bindEmbedder } from './internal/embedder-binding.js';\nimport type { EmbeddingMetaRegistryLike, MemoryStoreAdapter } from './internal/storage-adapter.js';\nimport { createProviderRetrievalGrader } from './search/iterative.js';\nimport { createProviderQueryTransformer } from './search/query-transform.js';\nimport { RRFReranker } from './search/rrf.js';\nimport type { ReRanker } from './search/types.js';\nimport { EpisodicMemory } from './tiers/episodic-memory.js';\nimport { InsightMemory } from './tiers/insight-memory.js';\nimport { ProceduralMemory } from './tiers/procedural-memory.js';\nimport { SemanticMemory } from './tiers/semantic-memory.js';\nimport { SessionMemory } from './tiers/session-memory.js';\nimport { SharedMemory } from './tiers/shared-memory.js';\nimport { type BlockDefinition, WorkingMemory } from './tiers/working-memory.js';\nimport { buildMemoryTools, type ScopeResolver } from './tools/index.js';\n\n/**\n * Options accepted by {@link createMemory}.\n *\n * @stable\n */\nexport interface CreateMemoryOptions {\n  /** Storage adapter (default: `@graphorin/store-sqlite`'s `MemoryStore`). */\n  readonly store: MemoryStoreAdapter;\n  /** Embedder registry. The default sqlite store exposes one as `sqlite.embeddings`. */\n  readonly embeddings: EmbeddingMetaRegistryLike;\n  /** Embedder provider (default: none - vector search is disabled). */\n  readonly embedder?: EmbedderProvider;\n  /** Pre-declared working blocks (idempotent - re-defining is a no-op). */\n  readonly workingBlocks?: ReadonlyArray<BlockDefinition>;\n  /**\n   * Tracer used for every `memory.*` span. Defaults to the no-op\n   * tracer from `@graphorin/core` so unit tests do not need to wire\n   * the observability stack.\n   */\n  readonly tracer?: Tracer;\n  /** Override the reranker used by `SemanticMemory.search`. */\n  readonly reranker?: ReRanker;\n  /**\n   * Contextual-retrieval mode for the write path (P1-3). `'late-chunk'`\n   * (default) prepends a deterministic, offline situating context\n   * (entities / timeframe / topics, derived from the fact's own\n   * structured fields) to the text that is embedded + FTS-indexed, so a\n   * terse fact stays findable; the canonical `text` is preserved. `'off'`\n   * indexes the bare text. The `'llm'` enrichment is **not** available on\n   * the hot path - it is a consolidator-only opt-in configured via\n   * `consolidator: { contextualRetrieval: 'llm' }`.\n   */\n  readonly contextualRetrieval?: 'off' | 'late-chunk';\n  /**\n   * Query transformation for retrieval (P2-3, opt-in). When supplied,\n   * `SemanticMemory.search(..., { multiQuery })` fans the query into\n   * reworded variants (multi-query / RAG-Fusion) and `{ hyde }` adds a\n   * hypothetical-answer embedding - both via one cheap LLM call on the\n   * given provider, fused through the existing RRF reranker. Omitted (the\n   * default) ⇒ search stays **offline + single-shot** and the\n   * `multiQuery` / `hyde` search options become silent no-ops. Reserve it\n   * for retrieval-heavy recall, not every search (it adds provider\n   * latency).\n   */\n  readonly queryTransform?: {\n    /** Cheap provider used to rewrite the query / write the HyDE passage. */\n    readonly provider: Provider;\n    /** Hard ceiling on reworded variants requested per call. Default 5. */\n    readonly maxVariants?: number;\n    /** Output-token ceiling per transform call. Default 256. */\n    readonly maxTokens?: number;\n  };\n  /**\n   * Relation-graph entity resolution (P2-1). When `entityResolution` is\n   * `true` **and** the storage adapter exposes a `graph` surface (the\n   * default `@graphorin/store-sqlite` does), `remember(...)` resolves a\n   * fact's subject / object to canonical entities and links them, so\n   * `search(..., { expandHops: 1 })` can traverse relationships. Omitted\n   * (the default) ⇒ facts still carry s/p/o but form no entity links and\n   * the write path stays offline + unchanged. Dedup is lexical +\n   * embedding (offline, via the configured embedder); LLM adjudication of\n   * ambiguous merges is a further opt-in that needs `provider`.\n   */\n  readonly graph?: EntityResolutionConfig & {\n    /** Enable entity resolution + linking on write. Default `false`. */\n    readonly entityResolution?: boolean;\n    /** Provider for opt-in LLM adjudication of ambiguous merges. */\n    readonly provider?: Provider;\n  };\n  /**\n   * Agentic / iterative retrieval (P2-4, opt-in). When supplied,\n   * `SemanticMemory.searchIterative(...)` and the gated `deep_recall`\n   * tool can grade a retrieved set on the given provider and, for queries\n   * judged hard, reformulate + retrieve again (widening to one-hop graph\n   * expansion) up to `maxIterations`, abstaining instead of confabulating\n   * when memory is insufficient. Omitted (the default) ⇒ `searchIterative`\n   * stays a single difficulty-gated pass with **no provider call**, and\n   * `deep_recall` is **not** registered (the tool surface stays at the\n   * canonical eleven). Reserve it for hard multi-hop / temporal recall -\n   * it adds provider latency per pass.\n   */\n  readonly iterativeRetrieval?: {\n    /** Cheap provider used to grade retrieved memories + reformulate. */\n    readonly provider: Provider;\n    /** Default total-pass cap (clamped to `[1, 5]`). Default 3. */\n    readonly maxIterations?: number;\n    /** Output-token ceiling per grade call. Default 256. */\n    readonly maxTokens?: number;\n  };\n  /**\n   * Opt-in workflow induction (P2-2). When set, `ProceduralMemory.induce(...)`\n   * distils a reusable, value-abstracted procedure from a successful agent\n   * trajectory and stores it **quarantined** + `provenance: 'induction'`.\n   * Omitted (the default) ⇒ `induce(...)` throws\n   * {@link ProcedureInductionNotConfiguredError} and the procedural tier\n   * stays pure offline CRUD - no provider call.\n   */\n  readonly procedureInduction?: {\n    /** Provider used to abstract trajectory values into a procedure. */\n    readonly provider: Provider;\n    /** Output-token ceiling per induction call. Default 512. */\n    readonly maxTokens?: number;\n  };\n  /**\n   * Promotion-by-demonstrated-success for quarantined induced\n   * procedures (MCON-2 part 4). Fully offline - orthogonal to\n   * `procedureInduction` (no provider needed). When configured,\n   * `procedural.recordOutcome(scope, id, true)` increments the rule's\n   * persistent success counter and promotes it into `activate()` once\n   * `afterSuccesses` verified reuses accumulate; the injection gate\n   * still refuses flagged texts. Omitted ⇒ outcomes are counted but\n   * nothing auto-promotes.\n   */\n  readonly procedurePromotion?: {\n    /** Successful demonstrated reuses required before promotion (≥ 1). */\n    readonly afterSuccesses: number;\n  };\n  /**\n   * Register the gated `runbook_search` tool (D3) so the model can look\n   * up validated procedures by task description (content recall over\n   * procedural memory, returning whole runbooks). Fully offline - the\n   * default `@graphorin/store-sqlite` adapter serves it from the rules\n   * FTS index (migration 028); adapters without the index degrade to an\n   * in-memory lexical scan. Default `false` - the tool surface stays at\n   * the canonical eleven.\n   */\n  readonly runbookSearch?: boolean;\n  /**\n   * Resolver that produces the live {@link SessionScope} for each\n   * memory-tool invocation. Defaults to a closure that throws - the\n   * agent runtime overrides it in Phase 12.\n   */\n  readonly resolveScope?: ScopeResolver;\n  /**\n   * Consolidator configuration. When omitted, empty, or\n   * `enabled: false`, the facade installs the Phase 10a no-op\n   * placeholder so consumers can still type their interactions without\n   * paying the runtime cost. ANY other setting - including offline\n   * knobs like `decayCapacity` or `contextualRetrieval` - implicitly\n   * enables the production runtime (MST-4); `enabled: false` together\n   * with other settings warns once and keeps the placeholder.\n   */\n  readonly consolidator?: {\n    readonly enabled?: boolean;\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\n     * to `@graphorin/pricing` so `maxCostPerDay` can actually trip.\n     */\n    readonly priceUsage?: (usage: { promptTokens: number; completionTokens: number }) => number;\n    /** Provider routed to the standard phase when set (MCON-7); falls back to `provider`. */\n    readonly cheapProvider?: Provider | null;\n    /** Provider routed to the deep + reflection passes when set (MCON-7). */\n    readonly deepProvider?: Provider | null;\n    readonly cheapModel?: string | null;\n    readonly deepModel?: string | null;\n    readonly noiseFilters?: ReadonlyArray<'default' | 'minimal' | 'none'>;\n    readonly lockWaitMs?: number;\n    readonly decayTauDays?: number;\n    readonly decayArchiveThreshold?: number;\n    /** Capacity-bounded eviction target for the light phase (X-1). Default unbounded. */\n    readonly decayCapacity?: number | null;\n    /** Weights for the multi-signal salience score (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    /** Auto-form quarantined episodes from processed slices (P1-2). Per-tier default. */\n    readonly formEpisodes?: boolean;\n    /** Score episode importance via the consolidator LLM (P1-2). Per-tier default. */\n    readonly importanceScoring?: boolean;\n    /** Opt in to auto-promotion of injection-clean extraction facts (MCON-2). Default off. */\n    readonly autoPromoteExtraction?: boolean;\n    /** Run the deep-phase reflection pass synthesizing cited insights (P1-1). Per-tier default. */\n    readonly reflection?: boolean;\n    /** Accumulated-importance threshold at which reflection fires (P1-1). */\n    readonly importanceThreshold?: number;\n    /** Upper bound on salient questions reflection asks per pass (P1-1). */\n    readonly reflectionMaxQuestions?: number;\n    /**\n     * Contextual retrieval for standard-phase fact writes (P1-3).\n     * `'llm'` opts into one budgeted cheap-model call per write to author\n     * a situating prefix (consolidator-only); `'late-chunk'` (default)\n     * and `'off'` defer to the write-path mode. Per-tier default.\n     */\n    readonly contextualRetrieval?: ContextualRetrievalMode;\n    /**\n     * Maintain the learned-context digest block (D3): after each deep\n     * phase, one budgeted LLM call rewrites the reserved\n     * `learned_context` working block (previous digest + recent\n     * episodes / active insights / procedures), so the assembled system\n     * prompt carries a compact standing summary. Default `false` at\n     * every tier (Wave-D trial).\n     */\n    readonly learnedContext?: boolean;\n    /** Character bound for the learned-context digest (D3). Default `1200`. */\n    readonly learnedContextMaxChars?: number;\n    readonly defaultScope?: SessionScope;\n    readonly provider?: Provider | null;\n    /** Override the wall clock - used by tests. */\n    readonly now?: () => number;\n    /** Stable id seed - used by tests. */\n    readonly randomId?: () => string;\n    /** Subscribe to phase-finished events. */\n    readonly onPhaseFinished?: PhaseListener;\n  };\n  /**\n   * Conflict pipeline configuration (Phase 10b). Default: enabled,\n   * English locale pack, thresholds `0.95 / 0.85 / 0.4`. Pass\n   * `{ mode: 'off' }` to bypass the pipeline entirely (logs a one-shot\n   * WARN per process per the spec).\n   */\n  readonly conflictPipeline?: ConflictPipelineOptions;\n  /**\n   * Context engine configuration (Phase 10d). The engine assembles\n   * the layered six-layer system prompt; `memory.compile(scope)`\n   * delegates to it for the working blocks + rules + metadata\n   * fragments. When omitted, a default engine is created (English\n   * locale; `'full'` base mode; no auto-recall; conservative\n   * `'public-tls'` provider trust).\n   */\n  readonly contextEngine?: ContextEngineConfig;\n}\n\n/**\n * The facade returned by {@link createMemory}.\n *\n * @stable\n */\nexport interface Memory {\n  readonly working: WorkingMemory;\n  readonly session: SessionMemory;\n  readonly episodic: EpisodicMemory;\n  readonly semantic: SemanticMemory;\n  readonly procedural: ProceduralMemory;\n  readonly shared: SharedMemory;\n  /**\n   * Read surface over reflection insights (P1-1). A no-op (returns\n   * empty) when the storage adapter does not expose the optional\n   * insight surface.\n   */\n  readonly insights: InsightMemory;\n  readonly tools: ReadonlyArray<Tool>;\n  readonly consolidator: Consolidator;\n  /** The configured conflict pipeline. Surfaced for tests + CLI tooling. */\n  readonly conflictPipeline: ConflictPipeline;\n  /** The configured context engine (Phase 10d). */\n  readonly contextEngine: ContextEngine;\n  /** The active embedder, when configured. `null` otherwise. */\n  readonly embedder: EmbedderProvider | null;\n  /** The canonical id of the active embedder, when configured. */\n  embedderId(): string | null;\n  /**\n   * Compile a system-prompt block bundle. The bundle carries the\n   * static fragments per memory tier; the agent runtime consumes\n   * the {@link ContextEngine} surface (`memory.contextEngine`)\n   * directly for the full six-layer assembly.\n   */\n  compile(scope: CompileScope, options?: CompileOptions): Promise<MemoryContextBlocks>;\n  /** Counter snapshot consumed by Phase 10d's metadata layer. */\n  metadata(scope: SessionScope): Promise<MemoryMetadata>;\n}\n\n/**\n * Wire every memory subsystem in one call. Returns the typed\n * `Memory` facade ready to be passed into `createAgent({...})`.\n *\n * @stable\n */\nexport function createMemory(options: CreateMemoryOptions): Memory {\n  const tracer = options.tracer ?? NOOP_TRACER;\n  const reranker: ReRanker = options.reranker ?? new RRFReranker();\n  const resolveScope: ScopeResolver =\n    options.resolveScope ??\n    (() => {\n      throw new TypeError(\n        '[graphorin/memory] memory tool invoked without a scope resolver. ' +\n          'Pass `resolveScope` to createMemory({...}) - the agent runtime supplies one in Phase 12.',\n      );\n    });\n\n  let activeEmbedderId: string | null = null;\n  if (options.embedder !== undefined) {\n    activeEmbedderId = bindEmbedder(options.embedder, options.embeddings);\n  }\n  const embedder = options.embedder ?? null;\n  const embedderIdProvider = (): string | null => activeEmbedderId;\n\n  const working = new WorkingMemory({ store: options.store, tracer });\n  for (const block of options.workingBlocks ?? []) {\n    working.define(block);\n  }\n  const session = new SessionMemory({ store: options.store, tracer });\n  const episodic = new EpisodicMemory({\n    store: options.store,\n    tracer,\n    embedder,\n    embedderIdProvider,\n  });\n  const conflictPipeline = createConflictPipeline(options.conflictPipeline ?? {});\n  // P2-3: build the (opt-in) query transformer from the supplied provider.\n  // Absent ⇒ `null` ⇒ search stays offline + single-shot.\n  const queryTransformer =\n    options.queryTransform !== undefined\n      ? createProviderQueryTransformer(options.queryTransform.provider, {\n          ...(options.queryTransform.maxVariants !== undefined\n            ? { maxVariants: options.queryTransform.maxVariants }\n            : {}),\n          ...(options.queryTransform.maxTokens !== undefined\n            ? { maxTokens: options.queryTransform.maxTokens }\n            : {}),\n        })\n      : null;\n  // P2-1: build the (opt-in) entity resolver. Requires `graph.entityResolution`\n  // *and* a graph-capable adapter; absent ⇒ `null` ⇒ writes carry s/p/o but\n  // form no entity links and the write path stays offline + unchanged.\n  const graphStore = options.store.graph;\n  const entityResolver =\n    options.graph?.entityResolution === true && graphStore !== undefined\n      ? new EntityResolver({\n          store: graphStore,\n          embedder,\n          embedderId: embedderIdProvider,\n          ...(options.graph.provider !== undefined ? { provider: options.graph.provider } : {}),\n          config: {\n            ...(options.graph.mergeThreshold !== undefined\n              ? { mergeThreshold: options.graph.mergeThreshold }\n              : {}),\n            ...(options.graph.adjudicateThreshold !== undefined\n              ? { adjudicateThreshold: options.graph.adjudicateThreshold }\n              : {}),\n            ...(options.graph.llmAdjudication !== undefined\n              ? { llmAdjudication: options.graph.llmAdjudication }\n              : {}),\n          },\n        })\n      : null;\n  // P2-4: build the (opt-in) retrieval grader. Absent ⇒ `null` ⇒\n  // `searchIterative` runs a single difficulty-gated pass (no provider\n  // call) and the `deep_recall` tool is not registered.\n  const grader =\n    options.iterativeRetrieval !== undefined\n      ? createProviderRetrievalGrader(options.iterativeRetrieval.provider, {\n          ...(options.iterativeRetrieval.maxTokens !== undefined\n            ? { maxTokens: options.iterativeRetrieval.maxTokens }\n            : {}),\n        })\n      : null;\n  const semantic = new SemanticMemory({\n    store: options.store,\n    tracer,\n    embedder,\n    embedderIdProvider,\n    reranker,\n    conflictPipeline,\n    ...(options.contextualRetrieval !== undefined\n      ? { contextualRetrieval: options.contextualRetrieval }\n      : {}),\n    ...(queryTransformer !== null ? { queryTransformer } : {}),\n    ...(entityResolver !== null ? { entityResolver } : {}),\n    ...(grader !== null ? { grader } : {}),\n    ...(options.iterativeRetrieval?.maxIterations !== undefined\n      ? { iterativeMaxIterations: options.iterativeRetrieval.maxIterations }\n      : {}),\n    // C5: the same weights drive eviction salience and rank-time trust.\n    ...(options.consolidator?.salienceWeights !== undefined\n      ? { trustWeights: options.consolidator.salienceWeights }\n      : {}),\n  });\n  // P2-2: build the (opt-in) workflow inducer. Absent ⇒ `null` ⇒\n  // `ProceduralMemory.induce(...)` throws and the tier stays offline CRUD.\n  // MCON-15: induction spend is recorded into the consolidator budget -\n  // the consolidator is constructed AFTER the inducer, so the callback\n  // routes through a slot filled below (placeholder ⇒ no-op).\n  let consolidatorForSpend: Consolidator | null = null;\n  const inducer =\n    options.procedureInduction !== undefined\n      ? createProviderWorkflowInducer(options.procedureInduction.provider, {\n          ...(options.procedureInduction.maxTokens !== undefined\n            ? { maxTokens: options.procedureInduction.maxTokens }\n            : {}),\n          onUsage: (usage) => {\n            consolidatorForSpend?.recordExternalSpend(usage.promptTokens + usage.completionTokens);\n          },\n        })\n      : null;\n  const procedural = new ProceduralMemory({\n    store: options.store,\n    tracer,\n    ...(inducer !== null ? { inducer } : {}),\n    // MCON-2 part 4: opt-in promotion-by-demonstrated-success.\n    ...(options.procedurePromotion?.afterSuccesses !== undefined\n      ? { promoteAfterSuccesses: options.procedurePromotion.afterSuccesses }\n      : {}),\n  });\n  const shared = new SharedMemory({ store: options.store, tracer });\n  const insights = new InsightMemory({ store: options.store, tracer });\n\n  const tools = buildMemoryTools(\n    {\n      working,\n      session,\n      episodic,\n      semantic,\n      procedural,\n      shared,\n      resolveScope,\n    },\n    // P2-4: the gated `deep_recall` tool is registered only when a grader\n    // is configured - the offline default stays at exactly eleven tools.\n    // D3: `runbook_search` is a second gated appendix, opt-in via\n    // `runbookSearch: true`.\n    {\n      includeDeepRecall: grader !== null,\n      includeRunbookSearch: options.runbookSearch === true,\n    },\n  );\n\n  const consolidatorOpts = options.consolidator;\n  const consolidator: Consolidator = buildConsolidator(\n    consolidatorOpts,\n    options.store,\n    semantic,\n    episodic,\n    working,\n    tracer,\n  );\n  consolidatorForSpend = consolidator;\n  const contextEngineConfig = options.contextEngine ?? {};\n  const contextEngine: ContextEngine = createContextEngine(contextEngineConfig);\n  const resolved = contextEngine.config();\n  const localePack =\n    contextEngineConfig.locale === undefined\n      ? enLocalePack\n      : typeof contextEngineConfig.locale === 'string'\n        ? contextEngineConfig.locale === enLocalePack.id\n          ? enLocalePack\n          : resolveLocalePack({ id: contextEngineConfig.locale })\n        : resolveLocalePack(contextEngineConfig.locale);\n\n  // The facade's `compile(...)` is the static-fragment surface\n  // consumed by callers that do not know the active provider yet\n  // (the agent runtime calls `memory.contextEngine.assemble(...)`\n  // with full provider context when `autoAssembleContext` is\n  // enabled). The privacy filter only fires\n  // when the caller explicitly passes `providerAcceptsSensitivity`\n  // OR the operator opted into the engine's `privacy` block.\n  const privacyOptedIn =\n    contextEngineConfig.privacy !== undefined &&\n    (contextEngineConfig.privacy.providerAcceptsSensitivity !== undefined ||\n      contextEngineConfig.privacy.cloudUploadConsent !== undefined ||\n      contextEngineConfig.privacy.providerTrust !== undefined);\n\n  async function compile(\n    scope: CompileScope,\n    compileOptions: CompileOptions = {},\n  ): Promise<MemoryContextBlocks> {\n    const out: { -readonly [K in keyof MemoryContextBlocks]: MemoryContextBlocks[K] } = {};\n    const blocks = await options.store.working.list(scope);\n    // Quarantined (e.g. P2-2-induced) procedures are provisional and must not\n    // reach the system prompt - `activate()` already excludes them, and\n    // compile() (public `@stable`) must agree or a compile()-based prompt\n    // builder ingests unvalidated induction procedures (MST-3).\n    const rules = (await options.store.procedural.list(scope)).filter(\n      (rule) => rule.status !== 'quarantined',\n    );\n    const shouldFilter = privacyOptedIn || compileOptions.providerAcceptsSensitivity !== undefined;\n    let blocksKept: ReadonlyArray<(typeof blocks)[number]> = blocks;\n    let rulesKept: ReadonlyArray<(typeof rules)[number]> = rules;\n    if (shouldFilter) {\n      const filterContext: Parameters<typeof partitionBySensitivity>[1] = {\n        providerTrust: resolved.providerTrust,\n        cloudUploadConsent: resolved.cloudUploadConsent,\n        defaultSensitivity: resolved.defaultSensitivity,\n      };\n      if (compileOptions.providerAcceptsSensitivity !== undefined) {\n        (\n          filterContext as {\n            providerAcceptsSensitivity?: ReadonlyArray<'public' | 'internal' | 'secret'>;\n          }\n        ).providerAcceptsSensitivity = compileOptions.providerAcceptsSensitivity;\n      }\n      blocksKept = partitionBySensitivity(blocks, filterContext).kept;\n      rulesKept = partitionBySensitivity(rules, filterContext).kept;\n    }\n    const blocksXml = renderWorkingBlocksXml(blocksKept);\n    if (blocksXml.length > 0) {\n      out.workingBlocks = blocksXml;\n    }\n    if (rulesKept.length > 0) {\n      const lines = ['<memory_rules>'];\n      for (const rule of rulesKept) {\n        lines.push(`  <rule priority=\"${rule.priority}\">${escapeXml(rule.text)}</rule>`);\n      }\n      lines.push('</memory_rules>');\n      out.rules = lines.join('\\n');\n    }\n    if (compileOptions.includeMetadata !== false) {\n      const meta = await metadata(scope);\n      out.metadata = renderMetadataBlock(meta);\n    }\n    out.base = composeLayer1(localePack, resolved.memoryBaseMode);\n    return Object.freeze(out);\n  }\n\n  async function metadata(scope: SessionScope): Promise<MemoryMetadata> {\n    return gatherMemoryMetadata(scope, {\n      store: options.store,\n      consolidator,\n      embedderId: embedderIdProvider,\n      localeId: resolved.localeId,\n    });\n  }\n\n  return Object.freeze({\n    working,\n    session,\n    episodic,\n    semantic,\n    procedural,\n    shared,\n    insights,\n    tools,\n    consolidator,\n    conflictPipeline,\n    contextEngine,\n    embedder,\n    embedderId: embedderIdProvider,\n    compile,\n    metadata,\n  });\n}\n\nfunction renderWorkingBlocksXml(\n  blocks: ReadonlyArray<{\n    readonly label: string;\n    readonly value: string;\n    readonly description?: string;\n  }>,\n): string {\n  if (blocks.length === 0) return '';\n  const lines = ['<memory_blocks>'];\n  for (const block of blocks) {\n    const description =\n      block.description !== undefined ? ` description=\"${escapeXml(block.description)}\"` : '';\n    lines.push(`  <block label=\"${escapeXml(block.label)}\"${description}>`);\n    lines.push(`    ${escapeXml(block.value)}`);\n    lines.push('  </block>');\n  }\n  lines.push('</memory_blocks>');\n  return lines.join('\\n');\n}\n\nfunction escapeXml(value: string): string {\n  return value\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n\nfunction buildConsolidator(\n  opts: CreateMemoryOptions['consolidator'],\n  store: CreateMemoryOptions['store'],\n  semantic: SemanticMemory,\n  episodic: EpisodicMemory,\n  working: WorkingMemory,\n  tracer: Tracer,\n): Consolidator {\n  if (opts === undefined) {\n    return createConsolidatorPlaceholder();\n  }\n  const enabled = shouldEnableConsolidator(opts);\n  if (!enabled) {\n    return createConsolidatorPlaceholder({\n      ...(opts.triggers !== undefined ? { triggers: opts.triggers } : {}),\n      ...(opts.tier !== undefined ? { tier: opts.tier } : {}),\n    });\n  }\n  const consolidator = createConsolidator({\n    store,\n    semantic,\n    episodic,\n    working,\n    tracer,\n    ...(opts.provider !== undefined ? { provider: opts.provider } : {}),\n    ...(opts.now !== undefined ? { now: opts.now } : {}),\n    ...(opts.randomId !== undefined ? { randomId: opts.randomId } : {}),\n    ...(opts.triggers !== undefined ? { triggers: opts.triggers } : {}),\n    ...(opts.tier !== undefined ? { tier: opts.tier } : {}),\n    ...(opts.phases !== undefined ? { phases: opts.phases } : {}),\n    ...(opts.ceilings !== undefined ? { ceilings: opts.ceilings } : {}),\n    ...(opts.onExceed !== undefined ? { onExceed: opts.onExceed } : {}),\n    ...(opts.priceUsage !== undefined ? { priceUsage: opts.priceUsage } : {}),\n    ...(opts.cheapProvider !== undefined ? { cheapProvider: opts.cheapProvider } : {}),\n    ...(opts.deepProvider !== undefined ? { deepProvider: opts.deepProvider } : {}),\n    ...(opts.cheapModel !== undefined ? { cheapModel: opts.cheapModel } : {}),\n    ...(opts.deepModel !== undefined ? { deepModel: opts.deepModel } : {}),\n    ...(opts.noiseFilters !== undefined ? { noiseFilters: opts.noiseFilters } : {}),\n    ...(opts.lockWaitMs !== undefined ? { lockWaitMs: opts.lockWaitMs } : {}),\n    ...(opts.decayTauDays !== undefined ? { decayTauDays: opts.decayTauDays } : {}),\n    ...(opts.decayArchiveThreshold !== undefined\n      ? { decayArchiveThreshold: opts.decayArchiveThreshold }\n      : {}),\n    ...(opts.decayCapacity !== undefined ? { decayCapacity: opts.decayCapacity } : {}),\n    ...(opts.salienceWeights !== undefined ? { salienceWeights: opts.salienceWeights } : {}),\n    ...(opts.maxStandardBatchSize !== undefined\n      ? { maxStandardBatchSize: opts.maxStandardBatchSize }\n      : {}),\n    ...(opts.maxDeepConflictsPerRun !== undefined\n      ? { maxDeepConflictsPerRun: opts.maxDeepConflictsPerRun }\n      : {}),\n    ...(opts.dlqMaxRetries !== undefined ? { dlqMaxRetries: opts.dlqMaxRetries } : {}),\n    ...(opts.dlqBaseBackoffMs !== undefined ? { dlqBaseBackoffMs: opts.dlqBaseBackoffMs } : {}),\n    ...(opts.dlqMaxBackoffMs !== undefined ? { dlqMaxBackoffMs: opts.dlqMaxBackoffMs } : {}),\n    ...(opts.formEpisodes !== undefined ? { formEpisodes: opts.formEpisodes } : {}),\n    ...(opts.importanceScoring !== undefined ? { importanceScoring: opts.importanceScoring } : {}),\n    ...(opts.autoPromoteExtraction !== undefined\n      ? { autoPromoteExtraction: opts.autoPromoteExtraction }\n      : {}),\n    ...(opts.reflection !== undefined ? { reflection: opts.reflection } : {}),\n    ...(opts.importanceThreshold !== undefined\n      ? { importanceThreshold: opts.importanceThreshold }\n      : {}),\n    ...(opts.reflectionMaxQuestions !== undefined\n      ? { reflectionMaxQuestions: opts.reflectionMaxQuestions }\n      : {}),\n    ...(opts.contextualRetrieval !== undefined\n      ? { contextualRetrieval: opts.contextualRetrieval }\n      : {}),\n    ...(opts.learnedContext !== undefined ? { learnedContext: opts.learnedContext } : {}),\n    ...(opts.learnedContextMaxChars !== undefined\n      ? { learnedContextMaxChars: opts.learnedContextMaxChars }\n      : {}),\n    ...(opts.defaultScope !== undefined ? { defaultScope: opts.defaultScope } : {}),\n  });\n  if (opts.onPhaseFinished !== undefined) {\n    consolidator.onPhaseFinished(opts.onPhaseFinished);\n  }\n  return consolidator;\n}\n\nlet consolidatorConfigIgnoredWarned = false;\n\n/** @internal - test seam for the one-time disabled-config warning. */\nexport function _resetConsolidatorConfigWarningForTesting(): void {\n  consolidatorConfigIgnoredWarned = false;\n}\n\nfunction shouldEnableConsolidator(opts: NonNullable<CreateMemoryOptions['consolidator']>): boolean {\n  // MST-4: ANY non-empty consolidator config implicitly enables - the old\n  // allow-list silently ignored offline knobs (`decayCapacity`,\n  // `formEpisodes`, `reflection`, `contextualRetrieval`, …): the caller\n  // got a no-op placeholder while believing the feature was on.\n  const keys = Object.keys(opts).filter(\n    (k) => k !== 'enabled' && (opts as Record<string, unknown>)[k] !== undefined,\n  );\n  if (opts.enabled === false) {\n    if (keys.length > 0 && !consolidatorConfigIgnoredWarned) {\n      consolidatorConfigIgnoredWarned = true;\n      process.stderr.write(\n        `[graphorin/memory] consolidator config (${keys.join(', ')}) was supplied together with enabled: false - the settings are ignored until the consolidator is enabled.\\n`,\n      );\n    }\n    return false;\n  }\n  if (opts.enabled === true) return true;\n  return keys.length > 0;\n}\n"],"mappings":"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"}

package/dist/graph/entity-resolver.d.ts

@@ -5,7 +5,7 @@ import { EmbedderProvider, Fact, Provider, ProviderRequest, SessionScope } from
 
 /** Cosine `≥` this auto-reuses an existing entity (embedding match). */
 declare const DEFAULT_MERGE_THRESHOLD = 0.92;
-/** Cosine in `[this, merge)` is *ambiguous* — adjudicate or mint new. */
+/** Cosine in `[this, merge)` is *ambiguous* - adjudicate or mint new. */
 declare const DEFAULT_ADJUDICATE_THRESHOLD = 0.82;
 /**
  * Outcome of the pure resolution policy. `match` reuses an existing
@@ -34,7 +34,7 @@ interface ResolutionCandidate {
   /**
    * MST-11: the embedder that produced `vector`. When both this and the
    * query's `vectorEmbedderId` are known and differ, the candidate is skipped
-   * for embedding comparison — vectors from different models live in different
+   * for embedding comparison - vectors from different models live in different
    * spaces, so their cosine is meaningless. Absent on either side ⇒ compared
    * (byte-identical to the prior behaviour).
    */

package/dist/graph/entity-resolver.js

@@ -1,7 +1,7 @@
 //#region src/graph/entity-resolver.ts
 /** Cosine `≥` this auto-reuses an existing entity (embedding match). */
 const DEFAULT_MERGE_THRESHOLD = .92;
-/** Cosine in `[this, merge)` is *ambiguous* — adjudicate or mint new. */
+/** Cosine in `[this, merge)` is *ambiguous* - adjudicate or mint new. */
 const DEFAULT_ADJUDICATE_THRESHOLD = .82;
 /**
 * Fold an entity surface form into a canonical lexical key: Unicode
@@ -76,7 +76,7 @@ function resolveEntityDecision(input) {
 	};
 	return { kind: "new" };
 }
-const ADJUDICATION_SYSTEM_PROMPT = "You decide whether two short names refer to the SAME real-world entity (person, place, org, thing). Reply with a single word: \"yes\" or \"no\". Be conservative — answer \"no\" unless they are clearly the same entity.";
+const ADJUDICATION_SYSTEM_PROMPT = "You decide whether two short names refer to the SAME real-world entity (person, place, org, thing). Reply with a single word: \"yes\" or \"no\". Be conservative - answer \"no\" unless they are clearly the same entity.";
 /** Build the (pure) adjudication request. Exposed for testing. */
 function buildAdjudicationRequest(nameA, nameB, options = {}) {
 	return {

package/dist/graph/entity-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity-resolver.js","names":["bestId: string | null","#store","#embedder","#embedderId","#provider","#mergeThreshold","#adjudicateThreshold","#llmAdjudication","#embed","#create","#adjudicate"],"sources":["../../src/graph/entity-resolver.ts"],"sourcesContent":["/**\n * Entity resolution for the lightweight in-SQLite relation graph (P2-1).\n *\n * Raw `subject` / `object` strings on facts fragment (\"Anna\", \"Anna S.\",\n * \"my sister\" become unrelated rows), which kills multi-hop recall. This\n * module folds them into **canonical entities** so the one-hop CTE can\n * traverse relationships. Resolution is layered, cheapest first:\n *\n *   1. **lexical** — exact match on the folded {@link normalizeEntityName}.\n *   2. **embedding** — cosine over candidate name vectors; `≥ mergeThreshold`\n *      reuses the match.\n *   3. **adjudication** — a middle similarity band (`[adjudicate, merge)`)\n *      is *ambiguous*; an opt-in LLM call (provider + `llmAdjudication`)\n *      decides. **Offline / by default the ambiguous band mints a new\n *      entity** — the resolver never auto-merges on weak evidence, because\n *      a wrong merge fuses two distinct people (the stated P2-1 risk).\n *\n * The pure policy ({@link resolveEntityDecision}) is provider-agnostic and\n * does no I/O; {@link EntityResolver} wires it to an injected store +\n * embedder + optional provider. With no embedder it degrades to\n * lexical-only — still useful, and still fully offline.\n *\n * @packageDocumentation\n */\n\nimport type {\n  EmbedderProvider,\n  Fact,\n  Provider,\n  ProviderRequest,\n  SessionScope,\n} from '@graphorin/core';\nimport type { EntityWithEmbedding, GraphMemoryStoreExt } from '../internal/storage-adapter.js';\n\n/** Cosine `≥` this auto-reuses an existing entity (embedding match). */\nexport const DEFAULT_MERGE_THRESHOLD = 0.92;\n/** Cosine in `[this, merge)` is *ambiguous* — adjudicate or mint new. */\nexport const DEFAULT_ADJUDICATE_THRESHOLD = 0.82;\n\n/**\n * Outcome of the pure resolution policy. `match` reuses an existing\n * entity; `ambiguous` flags a middle-similarity candidate for the caller\n * to adjudicate (or conservatively reject); `new` mints a fresh entity.\n *\n * @stable\n */\nexport type EntityResolveDecision =\n  | {\n      readonly kind: 'match';\n      readonly entityId: string;\n      readonly similarity: number;\n      readonly via: 'lexical' | 'embedding';\n    }\n  | { readonly kind: 'ambiguous'; readonly entityId: string; readonly similarity: number }\n  | { readonly kind: 'new' };\n\n/** Minimal candidate shape the pure policy compares against. */\nexport interface ResolutionCandidate {\n  readonly id: string;\n  readonly normalizedName: string;\n  readonly vector: Float32Array | null;\n  /**\n   * MST-11: the embedder that produced `vector`. When both this and the\n   * query's `vectorEmbedderId` are known and differ, the candidate is skipped\n   * for embedding comparison — vectors from different models live in different\n   * spaces, so their cosine is meaningless. Absent on either side ⇒ compared\n   * (byte-identical to the prior behaviour).\n   */\n  readonly embedderId?: string | null;\n}\n\n/** Inputs to {@link resolveEntityDecision} (all provided by the caller). */\nexport interface ResolveDecisionInput {\n  readonly normalizedName: string;\n  readonly vector?: Float32Array | null;\n  /** MST-11: the embedder that produced `vector` (gates cross-embedder cosine). */\n  readonly vectorEmbedderId?: string | null;\n  readonly candidates: ReadonlyArray<ResolutionCandidate>;\n  readonly mergeThreshold: number;\n  readonly adjudicateThreshold: number;\n}\n\n/**\n * Fold an entity surface form into a canonical lexical key: Unicode\n * NFKC, lowercased, internal whitespace collapsed, surrounding\n * punctuation stripped. `\"  Anna S. \"` → `\"anna s\"`. Returns `''` for a\n * name with no letters/digits (the resolver treats that as \"no entity\").\n *\n * @stable\n */\nexport function normalizeEntityName(name: string): string {\n  return name\n    .normalize('NFKC')\n    .toLowerCase()\n    .replace(/\\s+/g, ' ')\n    .trim()\n    .replace(/^[^\\p{L}\\p{N}]+|[^\\p{L}\\p{N}]+$/gu, '');\n}\n\n/**\n * Cosine similarity of two embeddings in `[-1, 1]`. Compares over the\n * shorter length and returns `0` when either vector is empty / zero-norm.\n *\n * @stable\n */\nexport function cosineSimilarity(a: Float32Array, b: Float32Array): number {\n  const len = Math.min(a.length, b.length);\n  let dot = 0;\n  let na = 0;\n  let nb = 0;\n  for (let i = 0; i < len; i++) {\n    const ai = a[i] ?? 0;\n    const bi = b[i] ?? 0;\n    dot += ai * bi;\n    na += ai * ai;\n    nb += bi * bi;\n  }\n  if (na === 0 || nb === 0) return 0;\n  return dot / Math.sqrt(na * nb);\n}\n\n/**\n * Pure resolution policy: lexical exact match → embedding cosine →\n * ambiguous band → new. No I/O; deterministic. The caller decides what\n * to do with `ambiguous` (LLM adjudicate, or conservatively mint new).\n *\n * @stable\n */\nexport function resolveEntityDecision(input: ResolveDecisionInput): EntityResolveDecision {\n  // 1. Exact lexical match is the cheapest + strongest signal.\n  for (const c of input.candidates) {\n    if (c.normalizedName === input.normalizedName) {\n      return { kind: 'match', entityId: c.id, similarity: 1, via: 'lexical' };\n    }\n  }\n  // 2. Embedding similarity (only when both sides have a vector).\n  const v = input.vector;\n  if (v === undefined || v === null || v.length === 0) return { kind: 'new' };\n  let bestId: string | null = null;\n  let bestSim = Number.NEGATIVE_INFINITY;\n  for (const c of input.candidates) {\n    if (c.vector === null || c.vector.length === 0) continue;\n    // MST-11: never compare vectors across embedders — different models live\n    // in different vector spaces, so their cosine is meaningless. Skip only\n    // when both embedder ids are known and differ.\n    if (\n      input.vectorEmbedderId != null &&\n      c.embedderId != null &&\n      c.embedderId !== input.vectorEmbedderId\n    ) {\n      continue;\n    }\n    const sim = cosineSimilarity(v, c.vector);\n    if (sim > bestSim) {\n      bestSim = sim;\n      bestId = c.id;\n    }\n  }\n  if (bestId === null) return { kind: 'new' };\n  if (bestSim >= input.mergeThreshold) {\n    return { kind: 'match', entityId: bestId, similarity: bestSim, via: 'embedding' };\n  }\n  if (bestSim >= input.adjudicateThreshold) {\n    return { kind: 'ambiguous', entityId: bestId, similarity: bestSim };\n  }\n  return { kind: 'new' };\n}\n\n/** Tunable thresholds + LLM-adjudication switch for {@link EntityResolver}. */\nexport interface EntityResolutionConfig {\n  /** Cosine `≥` this auto-reuses a match. Default {@link DEFAULT_MERGE_THRESHOLD}. */\n  readonly mergeThreshold?: number;\n  /** Cosine in `[this, merge)` is ambiguous. Default {@link DEFAULT_ADJUDICATE_THRESHOLD}. */\n  readonly adjudicateThreshold?: number;\n  /**\n   * Resolve the ambiguous band with one provider call. Requires a\n   * `provider`. Default `false` ⇒ ambiguous mints a new entity (no\n   * network call; never auto-merges on weak evidence).\n   */\n  readonly llmAdjudication?: boolean;\n}\n\n/** Construction deps for {@link EntityResolver}. */\nexport interface EntityResolverDeps {\n  readonly store: GraphMemoryStoreExt;\n  readonly embedder?: EmbedderProvider | null;\n  readonly embedderId?: () => string | null;\n  readonly provider?: Provider | null;\n  readonly config?: EntityResolutionConfig;\n}\n\nconst ADJUDICATION_SYSTEM_PROMPT =\n  'You decide whether two short names refer to the SAME real-world entity ' +\n  '(person, place, org, thing). Reply with a single word: \"yes\" or \"no\". ' +\n  'Be conservative — answer \"no\" unless they are clearly the same entity.';\n\n/** Build the (pure) adjudication request. Exposed for testing. */\nexport function buildAdjudicationRequest(\n  nameA: string,\n  nameB: string,\n  options: { readonly signal?: AbortSignal } = {},\n): ProviderRequest {\n  return {\n    messages: [{ role: 'user', content: `Name A: ${nameA}\\nName B: ${nameB}\\nSame entity?` }],\n    systemMessage: ADJUDICATION_SYSTEM_PROMPT,\n    temperature: 0,\n    maxTokens: 4,\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n  };\n}\n\n/** Parse a yes/no adjudication reply. Conservative: only a clear yes is `true`. */\nexport function parseAdjudication(text: string): boolean {\n  return /^\\s*(yes|true|same)\\b/i.test(text);\n}\n\n/**\n * Resolves a fact's subject / object strings to canonical entity ids and\n * links them, applying {@link resolveEntityDecision} backed by an\n * injected store + embedder (+ optional provider for adjudication).\n * Constructed only when entity resolution is opted in\n * (`createMemory({ graph: { entityResolution: true } })`); otherwise the\n * write path skips it and behaviour is unchanged + offline.\n *\n * @stable\n */\nexport class EntityResolver {\n  readonly #store: GraphMemoryStoreExt;\n  readonly #embedder: EmbedderProvider | null;\n  readonly #embedderId: () => string | null;\n  readonly #provider: Provider | null;\n  readonly #mergeThreshold: number;\n  readonly #adjudicateThreshold: number;\n  readonly #llmAdjudication: boolean;\n\n  constructor(deps: EntityResolverDeps) {\n    this.#store = deps.store;\n    this.#embedder = deps.embedder ?? null;\n    this.#embedderId = deps.embedderId ?? (() => null);\n    this.#provider = deps.provider ?? null;\n    this.#mergeThreshold = deps.config?.mergeThreshold ?? DEFAULT_MERGE_THRESHOLD;\n    this.#adjudicateThreshold = deps.config?.adjudicateThreshold ?? DEFAULT_ADJUDICATE_THRESHOLD;\n    this.#llmAdjudication = deps.config?.llmAdjudication ?? false;\n  }\n\n  /**\n   * Resolve a single name to a canonical entity id (find-or-create),\n   * deduping via lexical + embedding similarity. Returns `null` for a\n   * name that normalizes to empty (no entity).\n   */\n  async resolve(\n    scope: SessionScope,\n    rawName: string,\n    opts: { readonly signal?: AbortSignal } = {},\n  ): Promise<string | null> {\n    const normalizedName = normalizeEntityName(rawName);\n    if (normalizedName.length === 0) return null;\n    // 1. Exact lexical match — the cheapest, strongest signal. Resolve it via\n    //    an uncapped indexed lookup so an alias of an arbitrarily-old entity\n    //    dedups without scanning (and deserializing) the bounded candidate\n    //    window, and short-circuits before any embedding call (CS-11). Stores\n    //    that don't implement it fall through to the capped lexical scan below.\n    const exact = await this.#store.findEntityByNormalizedName?.(scope, normalizedName);\n    if (exact != null) return exact.id;\n    const vector = await this.#embed(rawName, opts.signal);\n    // 2. Without a query vector, embedding dedup is impossible — skip the\n    //    BLOB-deserializing candidate scan entirely and mint a new entity.\n    if (vector === null || vector.length === 0) {\n      return this.#create(scope, rawName, normalizedName, vector);\n    }\n    const candidates = await this.#store.listEntities(scope);\n    const decision = resolveEntityDecision({\n      normalizedName,\n      vector,\n      vectorEmbedderId: this.#embedderId(),\n      candidates,\n      mergeThreshold: this.#mergeThreshold,\n      adjudicateThreshold: this.#adjudicateThreshold,\n    });\n    if (decision.kind === 'match') return decision.entityId;\n    if (decision.kind === 'ambiguous') {\n      if (this.#llmAdjudication && this.#provider !== null) {\n        const same = await this.#adjudicate(rawName, decision.entityId, candidates, opts.signal);\n        if (same) return decision.entityId;\n      }\n      // Conservative default: weak evidence ⇒ a distinct new entity.\n    }\n    return this.#create(scope, rawName, normalizedName, vector);\n  }\n\n  /**\n   * Resolve + link a fact's subject and object (the predicate is a\n   * relation label, never an entity). Idempotent on re-link.\n   */\n  async linkFact(\n    scope: SessionScope,\n    fact: Fact,\n    opts: { readonly signal?: AbortSignal } = {},\n  ): Promise<void> {\n    if (fact.subject !== undefined) {\n      const id = await this.resolve(scope, fact.subject, opts);\n      if (id !== null) await this.#store.linkFactEntity(fact.id, id, 'subject');\n    }\n    if (fact.object !== undefined) {\n      const id = await this.resolve(scope, fact.object, opts);\n      if (id !== null) await this.#store.linkFactEntity(fact.id, id, 'object');\n    }\n  }\n\n  async #embed(name: string, signal?: AbortSignal): Promise<Float32Array | null> {\n    const embedder = this.#embedder;\n    if (embedder === null || this.#embedderId() === null) return null;\n    void signal;\n    try {\n      const [vector] = await embedder.embed([name]);\n      return vector ?? null;\n    } catch {\n      return null;\n    }\n  }\n\n  async #create(\n    scope: SessionScope,\n    name: string,\n    normalizedName: string,\n    vector: Float32Array | null,\n  ): Promise<string> {\n    const embedderId = this.#embedderId();\n    return this.#store.upsertEntity(scope, {\n      name,\n      normalizedName,\n      ...(vector !== null ? { vector } : {}),\n      ...(vector !== null && embedderId !== null ? { embedderId } : {}),\n    });\n  }\n\n  async #adjudicate(\n    name: string,\n    candidateId: string,\n    candidates: ReadonlyArray<EntityWithEmbedding>,\n    signal?: AbortSignal,\n  ): Promise<boolean> {\n    const provider = this.#provider;\n    if (provider === null) return false;\n    const candidate = candidates.find((c) => c.id === candidateId);\n    if (candidate === undefined) return false;\n    try {\n      const request = buildAdjudicationRequest(name, candidate.name, {\n        ...(signal !== undefined ? { signal } : {}),\n      });\n      const response = await provider.generate(request);\n      return parseAdjudication(response.text ?? '');\n    } catch {\n      return false;\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"entity-resolver.js","names":["bestId: string | null","#store","#embedder","#embedderId","#provider","#mergeThreshold","#adjudicateThreshold","#llmAdjudication","#embed","#create","#adjudicate"],"sources":["../../src/graph/entity-resolver.ts"],"sourcesContent":["/**\n * Entity resolution for the lightweight in-SQLite relation graph (P2-1).\n *\n * Raw `subject` / `object` strings on facts fragment (\"Anna\", \"Anna S.\",\n * \"my sister\" become unrelated rows), which kills multi-hop recall. This\n * module folds them into **canonical entities** so the one-hop CTE can\n * traverse relationships. Resolution is layered, cheapest first:\n *\n *   1. **lexical** - exact match on the folded {@link normalizeEntityName}.\n *   2. **embedding** - cosine over candidate name vectors; `≥ mergeThreshold`\n *      reuses the match.\n *   3. **adjudication** - a middle similarity band (`[adjudicate, merge)`)\n *      is *ambiguous*; an opt-in LLM call (provider + `llmAdjudication`)\n *      decides. **Offline / by default the ambiguous band mints a new\n *      entity** - the resolver never auto-merges on weak evidence, because\n *      a wrong merge fuses two distinct people (the stated P2-1 risk).\n *\n * The pure policy ({@link resolveEntityDecision}) is provider-agnostic and\n * does no I/O; {@link EntityResolver} wires it to an injected store +\n * embedder + optional provider. With no embedder it degrades to\n * lexical-only - still useful, and still fully offline.\n *\n * @packageDocumentation\n */\n\nimport type {\n  EmbedderProvider,\n  Fact,\n  Provider,\n  ProviderRequest,\n  SessionScope,\n} from '@graphorin/core';\nimport type { EntityWithEmbedding, GraphMemoryStoreExt } from '../internal/storage-adapter.js';\n\n/** Cosine `≥` this auto-reuses an existing entity (embedding match). */\nexport const DEFAULT_MERGE_THRESHOLD = 0.92;\n/** Cosine in `[this, merge)` is *ambiguous* - adjudicate or mint new. */\nexport const DEFAULT_ADJUDICATE_THRESHOLD = 0.82;\n\n/**\n * Outcome of the pure resolution policy. `match` reuses an existing\n * entity; `ambiguous` flags a middle-similarity candidate for the caller\n * to adjudicate (or conservatively reject); `new` mints a fresh entity.\n *\n * @stable\n */\nexport type EntityResolveDecision =\n  | {\n      readonly kind: 'match';\n      readonly entityId: string;\n      readonly similarity: number;\n      readonly via: 'lexical' | 'embedding';\n    }\n  | { readonly kind: 'ambiguous'; readonly entityId: string; readonly similarity: number }\n  | { readonly kind: 'new' };\n\n/** Minimal candidate shape the pure policy compares against. */\nexport interface ResolutionCandidate {\n  readonly id: string;\n  readonly normalizedName: string;\n  readonly vector: Float32Array | null;\n  /**\n   * MST-11: the embedder that produced `vector`. When both this and the\n   * query's `vectorEmbedderId` are known and differ, the candidate is skipped\n   * for embedding comparison - vectors from different models live in different\n   * spaces, so their cosine is meaningless. Absent on either side ⇒ compared\n   * (byte-identical to the prior behaviour).\n   */\n  readonly embedderId?: string | null;\n}\n\n/** Inputs to {@link resolveEntityDecision} (all provided by the caller). */\nexport interface ResolveDecisionInput {\n  readonly normalizedName: string;\n  readonly vector?: Float32Array | null;\n  /** MST-11: the embedder that produced `vector` (gates cross-embedder cosine). */\n  readonly vectorEmbedderId?: string | null;\n  readonly candidates: ReadonlyArray<ResolutionCandidate>;\n  readonly mergeThreshold: number;\n  readonly adjudicateThreshold: number;\n}\n\n/**\n * Fold an entity surface form into a canonical lexical key: Unicode\n * NFKC, lowercased, internal whitespace collapsed, surrounding\n * punctuation stripped. `\"  Anna S. \"` → `\"anna s\"`. Returns `''` for a\n * name with no letters/digits (the resolver treats that as \"no entity\").\n *\n * @stable\n */\nexport function normalizeEntityName(name: string): string {\n  return name\n    .normalize('NFKC')\n    .toLowerCase()\n    .replace(/\\s+/g, ' ')\n    .trim()\n    .replace(/^[^\\p{L}\\p{N}]+|[^\\p{L}\\p{N}]+$/gu, '');\n}\n\n/**\n * Cosine similarity of two embeddings in `[-1, 1]`. Compares over the\n * shorter length and returns `0` when either vector is empty / zero-norm.\n *\n * @stable\n */\nexport function cosineSimilarity(a: Float32Array, b: Float32Array): number {\n  const len = Math.min(a.length, b.length);\n  let dot = 0;\n  let na = 0;\n  let nb = 0;\n  for (let i = 0; i < len; i++) {\n    const ai = a[i] ?? 0;\n    const bi = b[i] ?? 0;\n    dot += ai * bi;\n    na += ai * ai;\n    nb += bi * bi;\n  }\n  if (na === 0 || nb === 0) return 0;\n  return dot / Math.sqrt(na * nb);\n}\n\n/**\n * Pure resolution policy: lexical exact match → embedding cosine →\n * ambiguous band → new. No I/O; deterministic. The caller decides what\n * to do with `ambiguous` (LLM adjudicate, or conservatively mint new).\n *\n * @stable\n */\nexport function resolveEntityDecision(input: ResolveDecisionInput): EntityResolveDecision {\n  // 1. Exact lexical match is the cheapest + strongest signal.\n  for (const c of input.candidates) {\n    if (c.normalizedName === input.normalizedName) {\n      return { kind: 'match', entityId: c.id, similarity: 1, via: 'lexical' };\n    }\n  }\n  // 2. Embedding similarity (only when both sides have a vector).\n  const v = input.vector;\n  if (v === undefined || v === null || v.length === 0) return { kind: 'new' };\n  let bestId: string | null = null;\n  let bestSim = Number.NEGATIVE_INFINITY;\n  for (const c of input.candidates) {\n    if (c.vector === null || c.vector.length === 0) continue;\n    // MST-11: never compare vectors across embedders - different models live\n    // in different vector spaces, so their cosine is meaningless. Skip only\n    // when both embedder ids are known and differ.\n    if (\n      input.vectorEmbedderId != null &&\n      c.embedderId != null &&\n      c.embedderId !== input.vectorEmbedderId\n    ) {\n      continue;\n    }\n    const sim = cosineSimilarity(v, c.vector);\n    if (sim > bestSim) {\n      bestSim = sim;\n      bestId = c.id;\n    }\n  }\n  if (bestId === null) return { kind: 'new' };\n  if (bestSim >= input.mergeThreshold) {\n    return { kind: 'match', entityId: bestId, similarity: bestSim, via: 'embedding' };\n  }\n  if (bestSim >= input.adjudicateThreshold) {\n    return { kind: 'ambiguous', entityId: bestId, similarity: bestSim };\n  }\n  return { kind: 'new' };\n}\n\n/** Tunable thresholds + LLM-adjudication switch for {@link EntityResolver}. */\nexport interface EntityResolutionConfig {\n  /** Cosine `≥` this auto-reuses a match. Default {@link DEFAULT_MERGE_THRESHOLD}. */\n  readonly mergeThreshold?: number;\n  /** Cosine in `[this, merge)` is ambiguous. Default {@link DEFAULT_ADJUDICATE_THRESHOLD}. */\n  readonly adjudicateThreshold?: number;\n  /**\n   * Resolve the ambiguous band with one provider call. Requires a\n   * `provider`. Default `false` ⇒ ambiguous mints a new entity (no\n   * network call; never auto-merges on weak evidence).\n   */\n  readonly llmAdjudication?: boolean;\n}\n\n/** Construction deps for {@link EntityResolver}. */\nexport interface EntityResolverDeps {\n  readonly store: GraphMemoryStoreExt;\n  readonly embedder?: EmbedderProvider | null;\n  readonly embedderId?: () => string | null;\n  readonly provider?: Provider | null;\n  readonly config?: EntityResolutionConfig;\n}\n\nconst ADJUDICATION_SYSTEM_PROMPT =\n  'You decide whether two short names refer to the SAME real-world entity ' +\n  '(person, place, org, thing). Reply with a single word: \"yes\" or \"no\". ' +\n  'Be conservative - answer \"no\" unless they are clearly the same entity.';\n\n/** Build the (pure) adjudication request. Exposed for testing. */\nexport function buildAdjudicationRequest(\n  nameA: string,\n  nameB: string,\n  options: { readonly signal?: AbortSignal } = {},\n): ProviderRequest {\n  return {\n    messages: [{ role: 'user', content: `Name A: ${nameA}\\nName B: ${nameB}\\nSame entity?` }],\n    systemMessage: ADJUDICATION_SYSTEM_PROMPT,\n    temperature: 0,\n    maxTokens: 4,\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n  };\n}\n\n/** Parse a yes/no adjudication reply. Conservative: only a clear yes is `true`. */\nexport function parseAdjudication(text: string): boolean {\n  return /^\\s*(yes|true|same)\\b/i.test(text);\n}\n\n/**\n * Resolves a fact's subject / object strings to canonical entity ids and\n * links them, applying {@link resolveEntityDecision} backed by an\n * injected store + embedder (+ optional provider for adjudication).\n * Constructed only when entity resolution is opted in\n * (`createMemory({ graph: { entityResolution: true } })`); otherwise the\n * write path skips it and behaviour is unchanged + offline.\n *\n * @stable\n */\nexport class EntityResolver {\n  readonly #store: GraphMemoryStoreExt;\n  readonly #embedder: EmbedderProvider | null;\n  readonly #embedderId: () => string | null;\n  readonly #provider: Provider | null;\n  readonly #mergeThreshold: number;\n  readonly #adjudicateThreshold: number;\n  readonly #llmAdjudication: boolean;\n\n  constructor(deps: EntityResolverDeps) {\n    this.#store = deps.store;\n    this.#embedder = deps.embedder ?? null;\n    this.#embedderId = deps.embedderId ?? (() => null);\n    this.#provider = deps.provider ?? null;\n    this.#mergeThreshold = deps.config?.mergeThreshold ?? DEFAULT_MERGE_THRESHOLD;\n    this.#adjudicateThreshold = deps.config?.adjudicateThreshold ?? DEFAULT_ADJUDICATE_THRESHOLD;\n    this.#llmAdjudication = deps.config?.llmAdjudication ?? false;\n  }\n\n  /**\n   * Resolve a single name to a canonical entity id (find-or-create),\n   * deduping via lexical + embedding similarity. Returns `null` for a\n   * name that normalizes to empty (no entity).\n   */\n  async resolve(\n    scope: SessionScope,\n    rawName: string,\n    opts: { readonly signal?: AbortSignal } = {},\n  ): Promise<string | null> {\n    const normalizedName = normalizeEntityName(rawName);\n    if (normalizedName.length === 0) return null;\n    // 1. Exact lexical match - the cheapest, strongest signal. Resolve it via\n    //    an uncapped indexed lookup so an alias of an arbitrarily-old entity\n    //    dedups without scanning (and deserializing) the bounded candidate\n    //    window, and short-circuits before any embedding call (CS-11). Stores\n    //    that don't implement it fall through to the capped lexical scan below.\n    const exact = await this.#store.findEntityByNormalizedName?.(scope, normalizedName);\n    if (exact != null) return exact.id;\n    const vector = await this.#embed(rawName, opts.signal);\n    // 2. Without a query vector, embedding dedup is impossible - skip the\n    //    BLOB-deserializing candidate scan entirely and mint a new entity.\n    if (vector === null || vector.length === 0) {\n      return this.#create(scope, rawName, normalizedName, vector);\n    }\n    const candidates = await this.#store.listEntities(scope);\n    const decision = resolveEntityDecision({\n      normalizedName,\n      vector,\n      vectorEmbedderId: this.#embedderId(),\n      candidates,\n      mergeThreshold: this.#mergeThreshold,\n      adjudicateThreshold: this.#adjudicateThreshold,\n    });\n    if (decision.kind === 'match') return decision.entityId;\n    if (decision.kind === 'ambiguous') {\n      if (this.#llmAdjudication && this.#provider !== null) {\n        const same = await this.#adjudicate(rawName, decision.entityId, candidates, opts.signal);\n        if (same) return decision.entityId;\n      }\n      // Conservative default: weak evidence ⇒ a distinct new entity.\n    }\n    return this.#create(scope, rawName, normalizedName, vector);\n  }\n\n  /**\n   * Resolve + link a fact's subject and object (the predicate is a\n   * relation label, never an entity). Idempotent on re-link.\n   */\n  async linkFact(\n    scope: SessionScope,\n    fact: Fact,\n    opts: { readonly signal?: AbortSignal } = {},\n  ): Promise<void> {\n    if (fact.subject !== undefined) {\n      const id = await this.resolve(scope, fact.subject, opts);\n      if (id !== null) await this.#store.linkFactEntity(fact.id, id, 'subject');\n    }\n    if (fact.object !== undefined) {\n      const id = await this.resolve(scope, fact.object, opts);\n      if (id !== null) await this.#store.linkFactEntity(fact.id, id, 'object');\n    }\n  }\n\n  async #embed(name: string, signal?: AbortSignal): Promise<Float32Array | null> {\n    const embedder = this.#embedder;\n    if (embedder === null || this.#embedderId() === null) return null;\n    void signal;\n    try {\n      const [vector] = await embedder.embed([name]);\n      return vector ?? null;\n    } catch {\n      return null;\n    }\n  }\n\n  async #create(\n    scope: SessionScope,\n    name: string,\n    normalizedName: string,\n    vector: Float32Array | null,\n  ): Promise<string> {\n    const embedderId = this.#embedderId();\n    return this.#store.upsertEntity(scope, {\n      name,\n      normalizedName,\n      ...(vector !== null ? { vector } : {}),\n      ...(vector !== null && embedderId !== null ? { embedderId } : {}),\n    });\n  }\n\n  async #adjudicate(\n    name: string,\n    candidateId: string,\n    candidates: ReadonlyArray<EntityWithEmbedding>,\n    signal?: AbortSignal,\n  ): Promise<boolean> {\n    const provider = this.#provider;\n    if (provider === null) return false;\n    const candidate = candidates.find((c) => c.id === candidateId);\n    if (candidate === undefined) return false;\n    try {\n      const request = buildAdjudicationRequest(name, candidate.name, {\n        ...(signal !== undefined ? { signal } : {}),\n      });\n      const response = await provider.generate(request);\n      return parseAdjudication(response.text ?? '');\n    } catch {\n      return false;\n    }\n  }\n}\n"],"mappings":"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"}