@graphorin/memory 0.5.0 → 0.6.0

package/dist/consolidator/scheduler.js.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.js","names":["catchupPolicy: ConsolidatorCatchupPolicy","registered: Array<{ id: string; kind: ParsedTrigger['kind']; raw: string }>","skipped: Array<{ raw: string; reason: 'unsupported-by-scheduler' | 'filtered-out' }>","declaration: TriggerDeclarationLike"],"sources":["../../src/consolidator/scheduler.ts"],"sourcesContent":["/**\n * Bridge helpers — wire a {@link Consolidator} into the\n * `@graphorin/triggers` Scheduler so trigger declarations fire on\n * the documented schedule (DEC-150 — \"same code path lib + server\").\n *\n * The bridge is structural: any object that exposes the same shape\n * as `@graphorin/triggers`'s `Scheduler` (a `register(declaration)`\n * method) works. The structural import keeps `@graphorin/memory`\n * dependency-free at the type level — the workspace consumer\n * supplies the actual scheduler at runtime.\n *\n * @packageDocumentation\n */\n\nimport type { SessionScope } from '@graphorin/core';\nimport type { Consolidator } from './runtime.js';\nimport { type ParsedTrigger, parseTriggerSpec, reasonFromTrigger } from './triggers.js';\nimport type { ConsolidatorTriggerSpec } from './types.js';\n\n/**\n * Catch-up policy applied when a trigger missed one or more fires\n * while the scheduler was offline. Mirrors\n * `@graphorin/triggers`'s `CatchupPolicy` — duplicated here so the\n * memory package stays import-free at the type level.\n *\n * @stable\n */\nexport type ConsolidatorCatchupPolicy = 'none' | 'last' | 'all';\n\n/**\n * Subset of the `@graphorin/triggers` Scheduler surface the bridge\n * needs. Defined structurally so consumers can inject mocks in\n * tests without taking the package dependency.\n *\n * @stable\n */\nexport interface SchedulerLike {\n  register(declaration: TriggerDeclarationLike): Promise<unknown>;\n  unregister?(id: string): Promise<void>;\n}\n\n/**\n * Subset of `@graphorin/triggers`'s `TriggerDeclaration` accepted\n * by {@link SchedulerLike.register}. Field names mirror the\n * upstream shape exactly so the structural type is interchangeable\n * with the real export.\n *\n * @stable\n */\nexport interface TriggerDeclarationLike {\n  readonly id: string;\n  readonly kind: 'cron' | 'interval' | 'idle' | 'event';\n  readonly spec: string;\n  readonly callback: (payload?: unknown) => void | Promise<void>;\n  readonly options: {\n    readonly catchupPolicy?: ConsolidatorCatchupPolicy;\n    readonly maxCatchupRuns?: number;\n    readonly catchupWindowMs?: number;\n    readonly tags?: ReadonlyArray<string>;\n    readonly acknowledgeLibMode?: boolean;\n  };\n}\n\n/** Options accepted by {@link registerConsolidatorTriggers}. */\nexport interface RegisterTriggersOptions {\n  /**\n   * Scope passed to `consolidator.trigger(...)` for every fire. The\n   * consolidator only operates on a single user/session at a time\n   * (DEC-005 single-user-per-process); multi-tenant deployments\n   * register one scheduler-trigger pair per scope.\n   */\n  readonly scope: SessionScope;\n  /**\n   * Catch-up policy applied to every registered trigger. Defaults\n   * to `'none'` per DEC-150 — safest for personal-assistant\n   * scenarios.\n   */\n  readonly catchupPolicy?: ConsolidatorCatchupPolicy;\n  /** Suppress the per-process library-mode WARN. Defaults to `true`. */\n  readonly acknowledgeLibMode?: boolean;\n  /** Optional id prefix — useful when multiple scopes share a scheduler. */\n  readonly idPrefix?: string;\n  /** Optional tags forwarded to the scheduler. */\n  readonly tags?: ReadonlyArray<string>;\n  /**\n   * Filter — only register the supplied subset of triggers. By\n   * default every parseable trigger declared on the consolidator is\n   * registered (turn / event triggers are skipped because the\n   * Scheduler has no way to fire them on its own).\n   */\n  readonly include?: ReadonlyArray<ConsolidatorTriggerSpec>;\n}\n\n/**\n * Outcome of {@link registerConsolidatorTriggers}.\n *\n * @stable\n */\nexport interface RegisterTriggersResult {\n  readonly registered: ReadonlyArray<{\n    readonly id: string;\n    readonly kind: ParsedTrigger['kind'];\n    readonly raw: string;\n  }>;\n  readonly skipped: ReadonlyArray<{\n    readonly raw: string;\n    readonly reason: 'unsupported-by-scheduler' | 'filtered-out';\n  }>;\n}\n\n/**\n * Register every cron / idle / interval trigger declared on the\n * supplied consolidator with the scheduler. Each trigger fires\n * `consolidator.trigger(reason, scope)` so the lib-mode + server\n * paths converge on the same handler.\n *\n * Turn triggers (`turn:N`) and event triggers (`event:NAME`) are\n * skipped — the scheduler cannot count user turns autonomously, and\n * event triggers fire from the consumer's emit path. The runtime\n * caller is responsible for those (e.g. invoking\n * `consolidator.trigger(...)` from the agent loop).\n *\n * @stable\n */\nexport async function registerConsolidatorTriggers(\n  consolidator: Consolidator,\n  scheduler: SchedulerLike,\n  options: RegisterTriggersOptions,\n): Promise<RegisterTriggersResult> {\n  const config = consolidator.config();\n  const include = options.include ?? config.triggers;\n  const acknowledgeLibMode = options.acknowledgeLibMode ?? true;\n  const catchupPolicy: ConsolidatorCatchupPolicy = options.catchupPolicy ?? 'none';\n  const registered: Array<{ id: string; kind: ParsedTrigger['kind']; raw: string }> = [];\n  const skipped: Array<{ raw: string; reason: 'unsupported-by-scheduler' | 'filtered-out' }> = [];\n  const seenSet = new Set(include);\n  for (const spec of config.triggers) {\n    if (!seenSet.has(spec)) {\n      skipped.push({ raw: spec, reason: 'filtered-out' });\n      continue;\n    }\n    const parsed = parseTriggerSpec(spec);\n    if (parsed.kind === 'turn' || parsed.kind === 'event' || parsed.kind === 'budget') {\n      skipped.push({ raw: parsed.raw, reason: 'unsupported-by-scheduler' });\n      continue;\n    }\n    const id = `${options.idPrefix ?? 'consolidator'}:${parsed.raw}`;\n    const kind: 'cron' | 'idle' | 'interval' = parsed.kind === 'cron' ? 'cron' : 'idle';\n    const declaration: TriggerDeclarationLike = {\n      id,\n      kind,\n      spec: parsed.kind === 'cron' ? parsed.expression : String(parsed.idleMs),\n      async callback() {\n        await consolidator.trigger(reasonFromTrigger(parsed), options.scope);\n      },\n      options: {\n        catchupPolicy,\n        acknowledgeLibMode,\n        ...(options.tags !== undefined ? { tags: options.tags } : {}),\n      },\n    };\n    await scheduler.register(declaration);\n    registered.push({ id, kind: parsed.kind, raw: parsed.raw });\n  }\n  return Object.freeze({\n    registered: Object.freeze(registered),\n    skipped: Object.freeze(skipped),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA4HA,eAAsB,6BACpB,cACA,WACA,SACiC;CACjC,MAAM,SAAS,aAAa,QAAQ;CACpC,MAAM,UAAU,QAAQ,WAAW,OAAO;CAC1C,MAAM,qBAAqB,QAAQ,sBAAsB;CACzD,MAAMA,gBAA2C,QAAQ,iBAAiB;CAC1E,MAAMC,aAA8E,EAAE;CACtF,MAAMC,UAAuF,EAAE;CAC/F,MAAM,UAAU,IAAI,IAAI,QAAQ;AAChC,MAAK,MAAM,QAAQ,OAAO,UAAU;AAClC,MAAI,CAAC,QAAQ,IAAI,KAAK,EAAE;AACtB,WAAQ,KAAK;IAAE,KAAK;IAAM,QAAQ;IAAgB,CAAC;AACnD;;EAEF,MAAM,SAAS,iBAAiB,KAAK;AACrC,MAAI,OAAO,SAAS,UAAU,OAAO,SAAS,WAAW,OAAO,SAAS,UAAU;AACjF,WAAQ,KAAK;IAAE,KAAK,OAAO;IAAK,QAAQ;IAA4B,CAAC;AACrE;;EAEF,MAAM,KAAK,GAAG,QAAQ,YAAY,eAAe,GAAG,OAAO;EAE3D,MAAMC,cAAsC;GAC1C;GACA,MAHyC,OAAO,SAAS,SAAS,SAAS;GAI3E,MAAM,OAAO,SAAS,SAAS,OAAO,aAAa,OAAO,OAAO,OAAO;GACxE,MAAM,WAAW;AACf,UAAM,aAAa,QAAQ,kBAAkB,OAAO,EAAE,QAAQ,MAAM;;GAEtE,SAAS;IACP;IACA;IACA,GAAI,QAAQ,SAAS,SAAY,EAAE,MAAM,QAAQ,MAAM,GAAG,EAAE;IAC7D;GACF;AACD,QAAM,UAAU,SAAS,YAAY;AACrC,aAAW,KAAK;GAAE;GAAI,MAAM,OAAO;GAAM,KAAK,OAAO;GAAK,CAAC;;AAE7D,QAAO,OAAO,OAAO;EACnB,YAAY,OAAO,OAAO,WAAW;EACrC,SAAS,OAAO,OAAO,QAAQ;EAChC,CAAC"}
+{"version":3,"file":"scheduler.js","names":["catchupPolicy: ConsolidatorCatchupPolicy","registered: Array<{ id: string; kind: ParsedTrigger['kind']; raw: string }>","skipped: Array<{ raw: string; reason: 'unsupported-by-scheduler' | 'filtered-out' }>","declaration: TriggerDeclarationLike"],"sources":["../../src/consolidator/scheduler.ts"],"sourcesContent":["/**\n * Bridge helpers - wire a {@link Consolidator} into the\n * `@graphorin/triggers` Scheduler so trigger declarations fire on\n * the documented schedule (DEC-150 - \"same code path lib + server\").\n *\n * The bridge is structural: any object that exposes the same shape\n * as `@graphorin/triggers`'s `Scheduler` (a `register(declaration)`\n * method) works. The structural import keeps `@graphorin/memory`\n * dependency-free at the type level - the workspace consumer\n * supplies the actual scheduler at runtime.\n *\n * @packageDocumentation\n */\n\nimport type { SessionScope } from '@graphorin/core';\nimport type { Consolidator } from './runtime.js';\nimport { type ParsedTrigger, parseTriggerSpec, reasonFromTrigger } from './triggers.js';\nimport type { ConsolidatorTriggerSpec } from './types.js';\n\n/**\n * Catch-up policy applied when a trigger missed one or more fires\n * while the scheduler was offline. Mirrors\n * `@graphorin/triggers`'s `CatchupPolicy` - duplicated here so the\n * memory package stays import-free at the type level.\n *\n * @stable\n */\nexport type ConsolidatorCatchupPolicy = 'none' | 'last' | 'all';\n\n/**\n * Subset of the `@graphorin/triggers` Scheduler surface the bridge\n * needs. Defined structurally so consumers can inject mocks in\n * tests without taking the package dependency.\n *\n * @stable\n */\nexport interface SchedulerLike {\n  register(declaration: TriggerDeclarationLike): Promise<unknown>;\n  unregister?(id: string): Promise<void>;\n}\n\n/**\n * Subset of `@graphorin/triggers`'s `TriggerDeclaration` accepted\n * by {@link SchedulerLike.register}. Field names mirror the\n * upstream shape exactly so the structural type is interchangeable\n * with the real export.\n *\n * @stable\n */\nexport interface TriggerDeclarationLike {\n  readonly id: string;\n  readonly kind: 'cron' | 'interval' | 'idle' | 'event';\n  readonly spec: string;\n  readonly callback: (payload?: unknown) => void | Promise<void>;\n  readonly options: {\n    readonly catchupPolicy?: ConsolidatorCatchupPolicy;\n    readonly maxCatchupRuns?: number;\n    readonly catchupWindowMs?: number;\n    readonly tags?: ReadonlyArray<string>;\n    readonly acknowledgeLibMode?: boolean;\n  };\n}\n\n/** Options accepted by {@link registerConsolidatorTriggers}. */\nexport interface RegisterTriggersOptions {\n  /**\n   * Scope passed to `consolidator.trigger(...)` for every fire. The\n   * consolidator only operates on a single user/session at a time\n   * (DEC-005 single-user-per-process); multi-tenant deployments\n   * register one scheduler-trigger pair per scope.\n   */\n  readonly scope: SessionScope;\n  /**\n   * Catch-up policy applied to every registered trigger. Defaults\n   * to `'none'` per DEC-150 - safest for personal-assistant\n   * scenarios.\n   */\n  readonly catchupPolicy?: ConsolidatorCatchupPolicy;\n  /** Suppress the per-process library-mode WARN. Defaults to `true`. */\n  readonly acknowledgeLibMode?: boolean;\n  /** Optional id prefix - useful when multiple scopes share a scheduler. */\n  readonly idPrefix?: string;\n  /** Optional tags forwarded to the scheduler. */\n  readonly tags?: ReadonlyArray<string>;\n  /**\n   * Filter - only register the supplied subset of triggers. By\n   * default every parseable trigger declared on the consolidator is\n   * registered (turn / event triggers are skipped because the\n   * Scheduler has no way to fire them on its own).\n   */\n  readonly include?: ReadonlyArray<ConsolidatorTriggerSpec>;\n}\n\n/**\n * Outcome of {@link registerConsolidatorTriggers}.\n *\n * @stable\n */\nexport interface RegisterTriggersResult {\n  readonly registered: ReadonlyArray<{\n    readonly id: string;\n    readonly kind: ParsedTrigger['kind'];\n    readonly raw: string;\n  }>;\n  readonly skipped: ReadonlyArray<{\n    readonly raw: string;\n    readonly reason: 'unsupported-by-scheduler' | 'filtered-out';\n  }>;\n}\n\n/**\n * Register every cron / idle / interval trigger declared on the\n * supplied consolidator with the scheduler. Each trigger fires\n * `consolidator.trigger(reason, scope)` so the lib-mode + server\n * paths converge on the same handler.\n *\n * Turn triggers (`turn:N`) and event triggers (`event:NAME`) are\n * skipped - the scheduler cannot count user turns autonomously, and\n * event triggers fire from the consumer's emit path. The runtime\n * caller is responsible for those (e.g. invoking\n * `consolidator.trigger(...)` from the agent loop).\n *\n * @stable\n */\nexport async function registerConsolidatorTriggers(\n  consolidator: Consolidator,\n  scheduler: SchedulerLike,\n  options: RegisterTriggersOptions,\n): Promise<RegisterTriggersResult> {\n  const config = consolidator.config();\n  const include = options.include ?? config.triggers;\n  const acknowledgeLibMode = options.acknowledgeLibMode ?? true;\n  const catchupPolicy: ConsolidatorCatchupPolicy = options.catchupPolicy ?? 'none';\n  const registered: Array<{ id: string; kind: ParsedTrigger['kind']; raw: string }> = [];\n  const skipped: Array<{ raw: string; reason: 'unsupported-by-scheduler' | 'filtered-out' }> = [];\n  const seenSet = new Set(include);\n  for (const spec of config.triggers) {\n    if (!seenSet.has(spec)) {\n      skipped.push({ raw: spec, reason: 'filtered-out' });\n      continue;\n    }\n    const parsed = parseTriggerSpec(spec);\n    if (parsed.kind === 'turn' || parsed.kind === 'event' || parsed.kind === 'budget') {\n      skipped.push({ raw: parsed.raw, reason: 'unsupported-by-scheduler' });\n      continue;\n    }\n    const id = `${options.idPrefix ?? 'consolidator'}:${parsed.raw}`;\n    const kind: 'cron' | 'idle' | 'interval' = parsed.kind === 'cron' ? 'cron' : 'idle';\n    const declaration: TriggerDeclarationLike = {\n      id,\n      kind,\n      spec: parsed.kind === 'cron' ? parsed.expression : String(parsed.idleMs),\n      async callback() {\n        await consolidator.trigger(reasonFromTrigger(parsed), options.scope);\n      },\n      options: {\n        catchupPolicy,\n        acknowledgeLibMode,\n        ...(options.tags !== undefined ? { tags: options.tags } : {}),\n      },\n    };\n    await scheduler.register(declaration);\n    registered.push({ id, kind: parsed.kind, raw: parsed.raw });\n  }\n  return Object.freeze({\n    registered: Object.freeze(registered),\n    skipped: Object.freeze(skipped),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA4HA,eAAsB,6BACpB,cACA,WACA,SACiC;CACjC,MAAM,SAAS,aAAa,QAAQ;CACpC,MAAM,UAAU,QAAQ,WAAW,OAAO;CAC1C,MAAM,qBAAqB,QAAQ,sBAAsB;CACzD,MAAMA,gBAA2C,QAAQ,iBAAiB;CAC1E,MAAMC,aAA8E,EAAE;CACtF,MAAMC,UAAuF,EAAE;CAC/F,MAAM,UAAU,IAAI,IAAI,QAAQ;AAChC,MAAK,MAAM,QAAQ,OAAO,UAAU;AAClC,MAAI,CAAC,QAAQ,IAAI,KAAK,EAAE;AACtB,WAAQ,KAAK;IAAE,KAAK;IAAM,QAAQ;IAAgB,CAAC;AACnD;;EAEF,MAAM,SAAS,iBAAiB,KAAK;AACrC,MAAI,OAAO,SAAS,UAAU,OAAO,SAAS,WAAW,OAAO,SAAS,UAAU;AACjF,WAAQ,KAAK;IAAE,KAAK,OAAO;IAAK,QAAQ;IAA4B,CAAC;AACrE;;EAEF,MAAM,KAAK,GAAG,QAAQ,YAAY,eAAe,GAAG,OAAO;EAE3D,MAAMC,cAAsC;GAC1C;GACA,MAHyC,OAAO,SAAS,SAAS,SAAS;GAI3E,MAAM,OAAO,SAAS,SAAS,OAAO,aAAa,OAAO,OAAO,OAAO;GACxE,MAAM,WAAW;AACf,UAAM,aAAa,QAAQ,kBAAkB,OAAO,EAAE,QAAQ,MAAM;;GAEtE,SAAS;IACP;IACA;IACA,GAAI,QAAQ,SAAS,SAAY,EAAE,MAAM,QAAQ,MAAM,GAAG,EAAE;IAC7D;GACF;AACD,QAAM,UAAU,SAAS,YAAY;AACrC,aAAW,KAAK;GAAE;GAAI,MAAM,OAAO;GAAM,KAAK,OAAO;GAAK,CAAC;;AAE7D,QAAO,OAAO,OAAO;EACnB,YAAY,OAAO,OAAO,WAAW;EACrC,SAAS,OAAO,OAAO,QAAQ;EAChC,CAAC"}

package/dist/consolidator/triggers.js

@@ -4,13 +4,13 @@ const IDLE_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/u;
 function parseTriggerSpec(spec) {
 	if (typeof spec !== "string" || spec.length === 0) throw new TypeError(`[graphorin/memory] consolidator trigger spec must be a non-empty string, got ${typeof spec}`);
 	const colon = spec.indexOf(":");
-	if (colon < 0) throw new TypeError(`[graphorin/memory] invalid trigger spec '${spec}' — expected 'kind:value'`);
+	if (colon < 0) throw new TypeError(`[graphorin/memory] invalid trigger spec '${spec}' - expected 'kind:value'`);
 	const kind = spec.slice(0, colon);
 	const value = spec.slice(colon + 1);
 	switch (kind) {
 		case "turn": {
 			const count = Number.parseInt(value, 10);
-			if (!Number.isFinite(count) || count <= 0) throw new TypeError(`[graphorin/memory] invalid turn trigger '${spec}' — expected positive integer`);
+			if (!Number.isFinite(count) || count <= 0) throw new TypeError(`[graphorin/memory] invalid turn trigger '${spec}' - expected positive integer`);
 			return {
 				kind: "turn",
 				count,
@@ -19,9 +19,9 @@ function parseTriggerSpec(spec) {
 		}
 		case "idle": {
 			const match = IDLE_PATTERN.exec(value);
-			if (match === null) throw new TypeError(`[graphorin/memory] invalid idle trigger '${spec}' — expected '5m' / '30s' / '1h'`);
+			if (match === null) throw new TypeError(`[graphorin/memory] invalid idle trigger '${spec}' - expected '5m' / '30s' / '1h'`);
 			const idleMs = toMs(Number.parseFloat(match[1] ?? "NaN"), match[2] ?? "ms");
-			if (!Number.isFinite(idleMs) || idleMs <= 0) throw new TypeError(`[graphorin/memory] invalid idle trigger '${spec}' — non-positive duration`);
+			if (!Number.isFinite(idleMs) || idleMs <= 0) throw new TypeError(`[graphorin/memory] invalid idle trigger '${spec}' - non-positive duration`);
 			return {
 				kind: "idle",
 				idleMs,
@@ -29,14 +29,14 @@ function parseTriggerSpec(spec) {
 			};
 		}
 		case "cron":
-			if (value.trim().length === 0) throw new TypeError(`[graphorin/memory] invalid cron trigger '${spec}' — empty expression`);
+			if (value.trim().length === 0) throw new TypeError(`[graphorin/memory] invalid cron trigger '${spec}' - empty expression`);
 			return {
 				kind: "cron",
 				expression: value,
 				raw: spec
 			};
 		case "event":
-			if (value.length === 0) throw new TypeError(`[graphorin/memory] invalid event trigger '${spec}' — empty event name`);
+			if (value.length === 0) throw new TypeError(`[graphorin/memory] invalid event trigger '${spec}' - empty event name`);
 			return {
 				kind: "event",
 				name: value,
@@ -44,7 +44,7 @@ function parseTriggerSpec(spec) {
 			};
 		case "budget": {
 			const threshold = Number.parseFloat(value);
-			if (!Number.isFinite(threshold) || threshold <= 0 || threshold >= 1) throw new TypeError(`[graphorin/memory] invalid budget trigger '${spec}' — expected fraction between 0 and 1`);
+			if (!Number.isFinite(threshold) || threshold <= 0 || threshold >= 1) throw new TypeError(`[graphorin/memory] invalid budget trigger '${spec}' - expected fraction between 0 and 1`);
 			return {
 				kind: "budget",
 				threshold,

package/dist/consolidator/triggers.js.map

@@ -1 +1 @@
-{"version":3,"file":"triggers.js","names":[],"sources":["../../src/consolidator/triggers.ts"],"sourcesContent":["/**\n * Trigger spec parser. Translates the human-friendly\n * `'turn:N'` / `'idle:Xm'` / `'cron:EXPR'` / `'event:NAME'` /\n * `'budget:N'` declarations into the runtime structure used by the\n * consolidator.\n *\n * The parser is exhaustive: every shape recognised here must be\n * matched in {@link parseTriggerSpec}; unrecognised shapes throw a\n * `TypeError` so misconfigured triggers fail at registration time\n * rather than silently never firing.\n *\n * @packageDocumentation\n */\n\nimport type { ConsolidatorTriggerReason, ConsolidatorTriggerSpec } from './types.js';\n\n/**\n * Parsed trigger declaration. The `kind` discriminator drives the\n * runtime dispatch; the `value` carries the spec-specific argument\n * already converted to a `number` (turns / millis / threshold) or a\n * string (cron expr / event name).\n *\n * @stable\n */\nexport type ParsedTrigger =\n  | { readonly kind: 'turn'; readonly count: number; readonly raw: string }\n  | { readonly kind: 'idle'; readonly idleMs: number; readonly raw: string }\n  | { readonly kind: 'cron'; readonly expression: string; readonly raw: string }\n  | { readonly kind: 'event'; readonly name: string; readonly raw: string }\n  | { readonly kind: 'budget'; readonly threshold: number; readonly raw: string };\n\nconst IDLE_PATTERN = /^(\\d+(?:\\.\\d+)?)(ms|s|m|h)?$/u;\n\n/** Parse a {@link ConsolidatorTriggerSpec} into a {@link ParsedTrigger}. */\nexport function parseTriggerSpec(spec: ConsolidatorTriggerSpec): ParsedTrigger {\n  if (typeof spec !== 'string' || spec.length === 0) {\n    throw new TypeError(\n      `[graphorin/memory] consolidator trigger spec must be a non-empty string, got ${typeof spec}`,\n    );\n  }\n  const colon = spec.indexOf(':');\n  if (colon < 0) {\n    throw new TypeError(\n      `[graphorin/memory] invalid trigger spec '${spec}' — expected 'kind:value'`,\n    );\n  }\n  const kind = spec.slice(0, colon);\n  const value = spec.slice(colon + 1);\n\n  switch (kind) {\n    case 'turn': {\n      const count = Number.parseInt(value, 10);\n      if (!Number.isFinite(count) || count <= 0) {\n        throw new TypeError(\n          `[graphorin/memory] invalid turn trigger '${spec}' — expected positive integer`,\n        );\n      }\n      return { kind: 'turn', count, raw: spec };\n    }\n    case 'idle': {\n      const match = IDLE_PATTERN.exec(value);\n      if (match === null) {\n        throw new TypeError(\n          `[graphorin/memory] invalid idle trigger '${spec}' — expected '5m' / '30s' / '1h'`,\n        );\n      }\n      const num = Number.parseFloat(match[1] ?? 'NaN');\n      const unit = match[2] ?? 'ms';\n      const idleMs = toMs(num, unit);\n      if (!Number.isFinite(idleMs) || idleMs <= 0) {\n        throw new TypeError(\n          `[graphorin/memory] invalid idle trigger '${spec}' — non-positive duration`,\n        );\n      }\n      return { kind: 'idle', idleMs, raw: spec };\n    }\n    case 'cron': {\n      if (value.trim().length === 0) {\n        throw new TypeError(`[graphorin/memory] invalid cron trigger '${spec}' — empty expression`);\n      }\n      return { kind: 'cron', expression: value, raw: spec };\n    }\n    case 'event': {\n      if (value.length === 0) {\n        throw new TypeError(\n          `[graphorin/memory] invalid event trigger '${spec}' — empty event name`,\n        );\n      }\n      return { kind: 'event', name: value, raw: spec };\n    }\n    case 'budget': {\n      const threshold = Number.parseFloat(value);\n      if (!Number.isFinite(threshold) || threshold <= 0 || threshold >= 1) {\n        throw new TypeError(\n          `[graphorin/memory] invalid budget trigger '${spec}' — expected fraction between 0 and 1`,\n        );\n      }\n      return { kind: 'budget', threshold, raw: spec };\n    }\n    default:\n      throw new TypeError(`[graphorin/memory] unknown consolidator trigger kind '${kind}'`);\n  }\n}\n\n/** Build a {@link ConsolidatorTriggerReason} from a parsed trigger. */\nexport function reasonFromTrigger(trigger: ParsedTrigger): ConsolidatorTriggerReason {\n  switch (trigger.kind) {\n    case 'turn':\n      return { kind: 'turn', value: trigger.count };\n    case 'idle':\n      return { kind: 'idle', value: trigger.raw };\n    case 'cron':\n      return { kind: 'cron', value: trigger.expression };\n    case 'event':\n      return { kind: 'event', value: trigger.name };\n    case 'budget':\n      return { kind: 'budget', value: trigger.threshold };\n  }\n}\n\nfunction toMs(value: number, unit: string): number {\n  switch (unit) {\n    case 'ms':\n      return value;\n    case 's':\n      return value * 1000;\n    case 'm':\n      return value * 60 * 1000;\n    case 'h':\n      return value * 60 * 60 * 1000;\n    default:\n      return Number.NaN;\n  }\n}\n"],"mappings":";AA+BA,MAAM,eAAe;;AAGrB,SAAgB,iBAAiB,MAA8C;AAC7E,KAAI,OAAO,SAAS,YAAY,KAAK,WAAW,EAC9C,OAAM,IAAI,UACR,gFAAgF,OAAO,OACxF;CAEH,MAAM,QAAQ,KAAK,QAAQ,IAAI;AAC/B,KAAI,QAAQ,EACV,OAAM,IAAI,UACR,4CAA4C,KAAK,2BAClD;CAEH,MAAM,OAAO,KAAK,MAAM,GAAG,MAAM;CACjC,MAAM,QAAQ,KAAK,MAAM,QAAQ,EAAE;AAEnC,SAAQ,MAAR;EACE,KAAK,QAAQ;GACX,MAAM,QAAQ,OAAO,SAAS,OAAO,GAAG;AACxC,OAAI,CAAC,OAAO,SAAS,MAAM,IAAI,SAAS,EACtC,OAAM,IAAI,UACR,4CAA4C,KAAK,+BAClD;AAEH,UAAO;IAAE,MAAM;IAAQ;IAAO,KAAK;IAAM;;EAE3C,KAAK,QAAQ;GACX,MAAM,QAAQ,aAAa,KAAK,MAAM;AACtC,OAAI,UAAU,KACZ,OAAM,IAAI,UACR,4CAA4C,KAAK,kCAClD;GAIH,MAAM,SAAS,KAFH,OAAO,WAAW,MAAM,MAAM,MAAM,EACnC,MAAM,MAAM,KACK;AAC9B,OAAI,CAAC,OAAO,SAAS,OAAO,IAAI,UAAU,EACxC,OAAM,IAAI,UACR,4CAA4C,KAAK,2BAClD;AAEH,UAAO;IAAE,MAAM;IAAQ;IAAQ,KAAK;IAAM;;EAE5C,KAAK;AACH,OAAI,MAAM,MAAM,CAAC,WAAW,EAC1B,OAAM,IAAI,UAAU,4CAA4C,KAAK,sBAAsB;AAE7F,UAAO;IAAE,MAAM;IAAQ,YAAY;IAAO,KAAK;IAAM;EAEvD,KAAK;AACH,OAAI,MAAM,WAAW,EACnB,OAAM,IAAI,UACR,6CAA6C,KAAK,sBACnD;AAEH,UAAO;IAAE,MAAM;IAAS,MAAM;IAAO,KAAK;IAAM;EAElD,KAAK,UAAU;GACb,MAAM,YAAY,OAAO,WAAW,MAAM;AAC1C,OAAI,CAAC,OAAO,SAAS,UAAU,IAAI,aAAa,KAAK,aAAa,EAChE,OAAM,IAAI,UACR,8CAA8C,KAAK,uCACpD;AAEH,UAAO;IAAE,MAAM;IAAU;IAAW,KAAK;IAAM;;EAEjD,QACE,OAAM,IAAI,UAAU,yDAAyD,KAAK,GAAG;;;;AAK3F,SAAgB,kBAAkB,SAAmD;AACnF,SAAQ,QAAQ,MAAhB;EACE,KAAK,OACH,QAAO;GAAE,MAAM;GAAQ,OAAO,QAAQ;GAAO;EAC/C,KAAK,OACH,QAAO;GAAE,MAAM;GAAQ,OAAO,QAAQ;GAAK;EAC7C,KAAK,OACH,QAAO;GAAE,MAAM;GAAQ,OAAO,QAAQ;GAAY;EACpD,KAAK,QACH,QAAO;GAAE,MAAM;GAAS,OAAO,QAAQ;GAAM;EAC/C,KAAK,SACH,QAAO;GAAE,MAAM;GAAU,OAAO,QAAQ;GAAW;;;AAIzD,SAAS,KAAK,OAAe,MAAsB;AACjD,SAAQ,MAAR;EACE,KAAK,KACH,QAAO;EACT,KAAK,IACH,QAAO,QAAQ;EACjB,KAAK,IACH,QAAO,QAAQ,KAAK;EACtB,KAAK,IACH,QAAO,QAAQ,KAAK,KAAK;EAC3B,QACE,QAAO"}
+{"version":3,"file":"triggers.js","names":[],"sources":["../../src/consolidator/triggers.ts"],"sourcesContent":["/**\n * Trigger spec parser. Translates the human-friendly\n * `'turn:N'` / `'idle:Xm'` / `'cron:EXPR'` / `'event:NAME'` /\n * `'budget:N'` declarations into the runtime structure used by the\n * consolidator.\n *\n * The parser is exhaustive: every shape recognised here must be\n * matched in {@link parseTriggerSpec}; unrecognised shapes throw a\n * `TypeError` so misconfigured triggers fail at registration time\n * rather than silently never firing.\n *\n * @packageDocumentation\n */\n\nimport type { ConsolidatorTriggerReason, ConsolidatorTriggerSpec } from './types.js';\n\n/**\n * Parsed trigger declaration. The `kind` discriminator drives the\n * runtime dispatch; the `value` carries the spec-specific argument\n * already converted to a `number` (turns / millis / threshold) or a\n * string (cron expr / event name).\n *\n * @stable\n */\nexport type ParsedTrigger =\n  | { readonly kind: 'turn'; readonly count: number; readonly raw: string }\n  | { readonly kind: 'idle'; readonly idleMs: number; readonly raw: string }\n  | { readonly kind: 'cron'; readonly expression: string; readonly raw: string }\n  | { readonly kind: 'event'; readonly name: string; readonly raw: string }\n  | { readonly kind: 'budget'; readonly threshold: number; readonly raw: string };\n\nconst IDLE_PATTERN = /^(\\d+(?:\\.\\d+)?)(ms|s|m|h)?$/u;\n\n/** Parse a {@link ConsolidatorTriggerSpec} into a {@link ParsedTrigger}. */\nexport function parseTriggerSpec(spec: ConsolidatorTriggerSpec): ParsedTrigger {\n  if (typeof spec !== 'string' || spec.length === 0) {\n    throw new TypeError(\n      `[graphorin/memory] consolidator trigger spec must be a non-empty string, got ${typeof spec}`,\n    );\n  }\n  const colon = spec.indexOf(':');\n  if (colon < 0) {\n    throw new TypeError(\n      `[graphorin/memory] invalid trigger spec '${spec}' - expected 'kind:value'`,\n    );\n  }\n  const kind = spec.slice(0, colon);\n  const value = spec.slice(colon + 1);\n\n  switch (kind) {\n    case 'turn': {\n      const count = Number.parseInt(value, 10);\n      if (!Number.isFinite(count) || count <= 0) {\n        throw new TypeError(\n          `[graphorin/memory] invalid turn trigger '${spec}' - expected positive integer`,\n        );\n      }\n      return { kind: 'turn', count, raw: spec };\n    }\n    case 'idle': {\n      const match = IDLE_PATTERN.exec(value);\n      if (match === null) {\n        throw new TypeError(\n          `[graphorin/memory] invalid idle trigger '${spec}' - expected '5m' / '30s' / '1h'`,\n        );\n      }\n      const num = Number.parseFloat(match[1] ?? 'NaN');\n      const unit = match[2] ?? 'ms';\n      const idleMs = toMs(num, unit);\n      if (!Number.isFinite(idleMs) || idleMs <= 0) {\n        throw new TypeError(\n          `[graphorin/memory] invalid idle trigger '${spec}' - non-positive duration`,\n        );\n      }\n      return { kind: 'idle', idleMs, raw: spec };\n    }\n    case 'cron': {\n      if (value.trim().length === 0) {\n        throw new TypeError(`[graphorin/memory] invalid cron trigger '${spec}' - empty expression`);\n      }\n      return { kind: 'cron', expression: value, raw: spec };\n    }\n    case 'event': {\n      if (value.length === 0) {\n        throw new TypeError(\n          `[graphorin/memory] invalid event trigger '${spec}' - empty event name`,\n        );\n      }\n      return { kind: 'event', name: value, raw: spec };\n    }\n    case 'budget': {\n      const threshold = Number.parseFloat(value);\n      if (!Number.isFinite(threshold) || threshold <= 0 || threshold >= 1) {\n        throw new TypeError(\n          `[graphorin/memory] invalid budget trigger '${spec}' - expected fraction between 0 and 1`,\n        );\n      }\n      return { kind: 'budget', threshold, raw: spec };\n    }\n    default:\n      throw new TypeError(`[graphorin/memory] unknown consolidator trigger kind '${kind}'`);\n  }\n}\n\n/** Build a {@link ConsolidatorTriggerReason} from a parsed trigger. */\nexport function reasonFromTrigger(trigger: ParsedTrigger): ConsolidatorTriggerReason {\n  switch (trigger.kind) {\n    case 'turn':\n      return { kind: 'turn', value: trigger.count };\n    case 'idle':\n      return { kind: 'idle', value: trigger.raw };\n    case 'cron':\n      return { kind: 'cron', value: trigger.expression };\n    case 'event':\n      return { kind: 'event', value: trigger.name };\n    case 'budget':\n      return { kind: 'budget', value: trigger.threshold };\n  }\n}\n\nfunction toMs(value: number, unit: string): number {\n  switch (unit) {\n    case 'ms':\n      return value;\n    case 's':\n      return value * 1000;\n    case 'm':\n      return value * 60 * 1000;\n    case 'h':\n      return value * 60 * 60 * 1000;\n    default:\n      return Number.NaN;\n  }\n}\n"],"mappings":";AA+BA,MAAM,eAAe;;AAGrB,SAAgB,iBAAiB,MAA8C;AAC7E,KAAI,OAAO,SAAS,YAAY,KAAK,WAAW,EAC9C,OAAM,IAAI,UACR,gFAAgF,OAAO,OACxF;CAEH,MAAM,QAAQ,KAAK,QAAQ,IAAI;AAC/B,KAAI,QAAQ,EACV,OAAM,IAAI,UACR,4CAA4C,KAAK,2BAClD;CAEH,MAAM,OAAO,KAAK,MAAM,GAAG,MAAM;CACjC,MAAM,QAAQ,KAAK,MAAM,QAAQ,EAAE;AAEnC,SAAQ,MAAR;EACE,KAAK,QAAQ;GACX,MAAM,QAAQ,OAAO,SAAS,OAAO,GAAG;AACxC,OAAI,CAAC,OAAO,SAAS,MAAM,IAAI,SAAS,EACtC,OAAM,IAAI,UACR,4CAA4C,KAAK,+BAClD;AAEH,UAAO;IAAE,MAAM;IAAQ;IAAO,KAAK;IAAM;;EAE3C,KAAK,QAAQ;GACX,MAAM,QAAQ,aAAa,KAAK,MAAM;AACtC,OAAI,UAAU,KACZ,OAAM,IAAI,UACR,4CAA4C,KAAK,kCAClD;GAIH,MAAM,SAAS,KAFH,OAAO,WAAW,MAAM,MAAM,MAAM,EACnC,MAAM,MAAM,KACK;AAC9B,OAAI,CAAC,OAAO,SAAS,OAAO,IAAI,UAAU,EACxC,OAAM,IAAI,UACR,4CAA4C,KAAK,2BAClD;AAEH,UAAO;IAAE,MAAM;IAAQ;IAAQ,KAAK;IAAM;;EAE5C,KAAK;AACH,OAAI,MAAM,MAAM,CAAC,WAAW,EAC1B,OAAM,IAAI,UAAU,4CAA4C,KAAK,sBAAsB;AAE7F,UAAO;IAAE,MAAM;IAAQ,YAAY;IAAO,KAAK;IAAM;EAEvD,KAAK;AACH,OAAI,MAAM,WAAW,EACnB,OAAM,IAAI,UACR,6CAA6C,KAAK,sBACnD;AAEH,UAAO;IAAE,MAAM;IAAS,MAAM;IAAO,KAAK;IAAM;EAElD,KAAK,UAAU;GACb,MAAM,YAAY,OAAO,WAAW,MAAM;AAC1C,OAAI,CAAC,OAAO,SAAS,UAAU,IAAI,aAAa,KAAK,aAAa,EAChE,OAAM,IAAI,UACR,8CAA8C,KAAK,uCACpD;AAEH,UAAO;IAAE,MAAM;IAAU;IAAW,KAAK;IAAM;;EAEjD,QACE,OAAM,IAAI,UAAU,yDAAyD,KAAK,GAAG;;;;AAK3F,SAAgB,kBAAkB,SAAmD;AACnF,SAAQ,QAAQ,MAAhB;EACE,KAAK,OACH,QAAO;GAAE,MAAM;GAAQ,OAAO,QAAQ;GAAO;EAC/C,KAAK,OACH,QAAO;GAAE,MAAM;GAAQ,OAAO,QAAQ;GAAK;EAC7C,KAAK,OACH,QAAO;GAAE,MAAM;GAAQ,OAAO,QAAQ;GAAY;EACpD,KAAK,QACH,QAAO;GAAE,MAAM;GAAS,OAAO,QAAQ;GAAM;EAC/C,KAAK,SACH,QAAO;GAAE,MAAM;GAAU,OAAO,QAAQ;GAAW;;;AAIzD,SAAS,KAAK,OAAe,MAAsB;AACjD,SAAQ,MAAR;EACE,KAAK,KACH,QAAO;EACT,KAAK,IACH,QAAO,QAAQ;EACjB,KAAK,IACH,QAAO,QAAQ,KAAK;EACtB,KAAK,IACH,QAAO,QAAQ,KAAK,KAAK;EAC3B,QACE,QAAO"}

package/dist/consolidator/types.d.ts

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

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

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

package/dist/consolidator/types.js

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

package/dist/consolidator/types.js.map

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

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

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

package/dist/context-engine/annotations.js

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