@graphorin/memory 0.5.0

package/dist/consolidator/types.d.ts

@@ -0,0 +1,397 @@
+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 { Provider, SessionScope, Tracer } from "@graphorin/core";
+
+//#region src/consolidator/types.d.ts
+
+/**
+ * Trigger discriminator. The `'turn:N'` and `'idle:Xm'` variants are
+ * the production defaults per DEC-133. `'cron:EXPR'`, `'event:NAME'`
+ * and `'budget:N'` are opt-in.
+ *
+ * @stable
+ */
+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
+ * fires until the operator opts in.
+ *
+ * @stable
+ */
+type ConsolidatorTier = 'free' | 'cheap' | 'standard' | 'full' | 'custom';
+/**
+ * Triggering reason surfaced through `Consolidator.trigger(...)`.
+ *
+ * @stable
+ */
+interface ConsolidatorTriggerReason {
+  readonly kind: 'turn' | 'idle' | 'cron' | 'event' | 'budget' | 'manual';
+  readonly value?: string | number;
+}
+/**
+ * Hard cost ceilings enforced atomically per UTC day. The default
+ * ceiling shape per tier is captured in
+ * {@link CONSOLIDATOR_TIER_DEFAULTS}.
+ *
+ * @stable
+ */
+interface ConsolidatorCeilings {
+  readonly maxTokensPerDay: number;
+  readonly maxCostPerDay: number;
+  /**
+   * ADVISORY (MCON-8): the per-scope lock serializes runs, so effective
+   * concurrency is always 1 per scope regardless of this value. The
+   * field is retained for forward compatibility; it enforces nothing
+   * today.
+   */
+  readonly maxConcurrentRuns: number;
+  readonly maxRunDurationMs: number;
+  /**
+   * Minimum quiet period between non-manual runs per scope (MCON-8).
+   * After each run the runtime persists `nextEligibleAt = now +
+   * cooldownMs`; trigger-driven runs (`turn` / `idle` / `cron` /
+   * `event` / `budget`) inside that window defer with reason
+   * `'cooldown'`. Manual `fireNow(...)` and DLQ replays bypass it.
+   */
+  readonly cooldownMs: number;
+}
+/**
+ * Behaviour applied by the budget enforcer when a ceiling is hit
+ * 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}.
+ *
+ * @stable
+ */
+type OnBudgetExceed = 'pause' | 'log' | 'throw';
+/**
+ * Phase identifier used by the runtime + audit rows.
+ *
+ * @stable
+ */
+type ConsolidatorPhase = 'light' | 'standard' | 'deep';
+/**
+ * Locked-down configuration accepted by `createConsolidator(...)`.
+ *
+ * @stable
+ */
+interface ConsolidatorConfig {
+  readonly triggers: ReadonlyArray<ConsolidatorTriggerSpec>;
+  readonly tier: ConsolidatorTier;
+  readonly phases: ReadonlyArray<ConsolidatorPhase>;
+  readonly ceilings: ConsolidatorCeilings;
+  readonly onExceed: OnBudgetExceed;
+  /**
+   * 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
+   * (MCON-7). Routing happens via
+   * `CreateConsolidatorOptions.deepProvider`.
+   */
+  readonly deepModel: string | null;
+  readonly budgetResetSemantics: 'utc' | 'local' | 'sliding-24h';
+  readonly noiseFilters: ReadonlyArray<'default' | 'minimal' | 'none'>;
+  readonly lockWaitMs: number;
+  readonly decayTauDays: number;
+  readonly decayArchiveThreshold: number;
+  /**
+   * 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
+   * 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.
+   */
+  readonly decayCapacity: number | null;
+  /**
+   * Weights for the multi-signal salience score (X-1) that orders both
+   * threshold archiving and capacity eviction. Defaults to
+   * {@link DEFAULT_SALIENCE_WEIGHTS}; with neutral importance, active
+   * status, and first-party provenance salience equals plain retention.
+   */
+  readonly salienceWeights: SalienceWeights;
+  readonly maxStandardBatchSize: number;
+  readonly maxDeepConflictsPerRun: number;
+  readonly dlqMaxRetries: number;
+  readonly dlqBaseBackoffMs: number;
+  readonly dlqMaxBackoffMs: number;
+  /**
+   * Auto-form a quarantined episode from each processed standard-phase
+   * slice (P1-2). Defaults on at the `standard`+ tiers, off at `free` /
+   * `cheap` / `custom`. The episode summary is one budgeted LLM call;
+   * when the budget is exhausted (or no episodic tier is wired) the
+   * phase degrades to fact-only behaviour.
+   */
+  readonly formEpisodes: boolean;
+  /**
+   * Ask the episode-summarization call for an LLM importance score
+   * (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
+   * retention. Defaults track {@link formEpisodes}.
+   */
+  readonly importanceScoring: boolean;
+  /**
+   * Auto-promotion policy (MCON-2). When `true`, the standard phase admits an
+   * 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
+   * 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.
+   */
+  readonly autoPromoteExtraction: boolean;
+  /**
+   * Run the deep-phase reflection pass (P1-1): when accumulated episode
+   * importance crosses {@link importanceThreshold}, synthesize
+   * 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
+   * is the most LLM-intensive phase. A no-op without an episodic tier
+   * or an insight-capable storage adapter.
+   */
+  readonly reflection: boolean;
+  /**
+   * Sum of recent episode importance (each in `[0, 1]`) at or above
+   * which {@link reflection} fires. Below it the pass makes no LLM
+   * call. Defaults to `3`.
+   */
+  readonly importanceThreshold: number;
+  /** Upper bound on salient questions reflection asks per pass. Defaults to `3`. */
+  readonly reflectionMaxQuestions: number;
+  /**
+   * 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
+   * enrichment: the standard phase spends one budgeted cheap-model call
+   * 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
+   * write path never has a provider for contextualization.
+   */
+  readonly contextualRetrieval: ContextualRetrievalMode;
+}
+/**
+ * Per-phase last-run snapshot surfaced inside
+ * {@link ConsolidatorStatus.lastRuns}. Each entry carries the
+ * timestamp of the most recent **completed** invocation for that
+ * phase (`undefined` when the phase has never run).
+ *
+ * @stable
+ */
+interface ConsolidatorLastRuns {
+  readonly light?: string;
+  readonly standard?: string;
+  readonly deep?: string;
+}
+/**
+ * Budget snapshot block of {@link ConsolidatorStatus}. Surfaces
+ * both the absolute usage and the remaining envelope so consumers
+ * (CLI, server health endpoint) can render the operator dashboard
+ * without doing the math themselves.
+ *
+ * @stable
+ */
+interface ConsolidatorBudgetSnapshot {
+  readonly tokensUsedToday: number;
+  readonly costUsedToday: number;
+  readonly tokensRemaining: number;
+  readonly costRemaining: number;
+  readonly resetAt: string;
+}
+/**
+ * Status snapshot returned by {@link Consolidator.status}.
+ *
+ * Public shape: `{ tier, queueDepth, dlqSize, lastRuns,
+ * budgetRemaining, deferredRuns }` — extended with a few additional
+ * fields the server health endpoint and the
+ * `graphorin consolidator status` CLI consume.
+ *
+ * `queueDepth` is an alias for {@link pendingConflicts} (the size
+ * of the deep-phase queue); both fields are populated for backwards
+ * compatibility.
+ *
+ * @stable
+ */
+interface ConsolidatorStatus {
+  readonly tier: ConsolidatorTier;
+  readonly triggers: ReadonlyArray<ConsolidatorTriggerSpec>;
+  readonly phases: ReadonlyArray<ConsolidatorPhase>;
+  readonly running: boolean;
+  readonly paused: boolean;
+  /** Most recent completed run timestamp (any phase). */
+  readonly lastRunAt?: string;
+  /** Phase of the most recent completed run. */
+  readonly lastPhase?: ConsolidatorPhase;
+  /** Per-phase last-completed timestamps surfaced for CLI / dashboard. */
+  readonly lastRuns: ConsolidatorLastRuns;
+  /** Spec alias for {@link pendingConflicts}. */
+  readonly queueDepth: number;
+  readonly pendingConflicts: number;
+  readonly dlqSize: number;
+  readonly deferredRuns: number;
+  readonly emptyExtractions: number;
+  readonly budget: ConsolidatorBudgetSnapshot;
+  /** Spec alias — surfaces remaining-budget figures at the top level. */
+  readonly budgetRemaining: {
+    readonly tokens: number;
+    readonly costUsd: number;
+  };
+}
+/**
+ * Outcome surfaced by every phase invocation. Recorded into
+ * `consolidator_runs` and emitted on the AISpan.
+ *
+ * @stable
+ */
+interface PhaseOutcome {
+  readonly phase: ConsolidatorPhase;
+  readonly status: 'completed' | 'failed' | 'deferred' | 'partial';
+  readonly factsCreated: number;
+  readonly factsUpdated: number;
+  readonly conflictsResolved: number;
+  /** Episodes auto-formed from the processed slice (P1-2). */
+  readonly episodesFormed: number;
+  /** Insights synthesized by the deep-phase reflection pass (P1-1). */
+  readonly insightsCreated: number;
+  readonly noiseFilteredCount: number;
+  readonly emptyExtractions: number;
+  readonly llmTokensUsed: number;
+  readonly llmCostUsd: number | null;
+  readonly errorMessage: string | null;
+}
+/**
+ * Listener callback subscribed via
+ * {@link Consolidator.onPhaseFinished}. Useful for tests + observers.
+ *
+ * @stable
+ */
+type PhaseListener = (outcome: PhaseOutcome & {
+  readonly scope: SessionScope;
+  readonly trigger: ConsolidatorTriggerReason;
+}) => void;
+/**
+ * Options accepted by {@link createConsolidator}.
+ *
+ * @stable
+ */
+interface CreateConsolidatorOptions {
+  /**
+   * Storage adapter — supplies the consolidator state, runs, DLQ,
+   * and per-tier helpers. The default `@graphorin/store-sqlite`
+   * adapter exposes everything by construction.
+   */
+  readonly store: MemoryStoreAdapter;
+  /**
+   * The {@link SemanticMemory} tier instance from the parent
+   * `createMemory(...)` facade. The standard phase routes every
+   * extracted fact through `semantic.remember(...)` so the conflict
+   * pipeline (Phase 10b) handles dedup / supersede.
+   */
+  readonly semantic: SemanticMemory;
+  /**
+   * The {@link EpisodicMemory} tier instance from the parent
+   * `createMemory(...)` facade. When supplied (and `formEpisodes` is
+   * on) the standard phase auto-forms a quarantined episode per
+   * processed slice (P1-2). Omitted ⇒ episode formation is skipped.
+   */
+  readonly episodic?: EpisodicMemory;
+  /**
+   * Provider used by the standard + deep phases. Required when the
+   * tier enables either phase; ignored when the active phases
+   * collapse to `['light']`.
+   */
+  readonly provider?: Provider | null;
+  readonly tracer?: Tracer;
+  /** Override the wall clock — used by tests. */
+  readonly now?: () => number;
+  /** 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;
+  /**
+   * Provider routed to the standard phase (extraction / episode /
+   * reconcile / situating-context calls) when set (MCON-7). Falls back
+   * to `provider`. Pair with `cheapModel` for the telemetry label.
+   */
+  readonly cheapProvider?: Provider | null;
+  /**
+   * Provider routed to the deep phase (conflict judge) and the
+   * reflection pass when set (MCON-7). Falls back to `provider`.
+   */
+  readonly deepProvider?: Provider | null;
+  readonly cheapModel?: string | null;
+  readonly deepModel?: string | null;
+  readonly budgetResetSemantics?: 'utc' | 'local' | 'sliding-24h';
+  readonly noiseFilters?: ReadonlyArray<'default' | 'minimal' | 'none'>;
+  readonly lockWaitMs?: number;
+  readonly decayTauDays?: number;
+  readonly decayArchiveThreshold?: number;
+  /** Override the {@link ConsolidatorConfig.decayCapacity} default (X-1). */
+  readonly decayCapacity?: number | null;
+  /** Override the {@link ConsolidatorConfig.salienceWeights} default (X-1). */
+  readonly salienceWeights?: SalienceWeights;
+  readonly maxStandardBatchSize?: number;
+  readonly maxDeepConflictsPerRun?: number;
+  readonly dlqMaxRetries?: number;
+  readonly dlqBaseBackoffMs?: number;
+  readonly dlqMaxBackoffMs?: number;
+  /** Override the per-tier {@link ConsolidatorConfig.formEpisodes} default (P1-2). */
+  readonly formEpisodes?: boolean;
+  /** Override the per-tier {@link ConsolidatorConfig.importanceScoring} default (P1-2). */
+  readonly importanceScoring?: boolean;
+  /**
+   * Opt in to auto-promotion of injection-clean extraction facts (MCON-2).
+   * Defaults `false`. See {@link ConsolidatorConfig.autoPromoteExtraction}.
+   */
+  readonly autoPromoteExtraction?: boolean;
+  /** Override the per-tier {@link ConsolidatorConfig.reflection} default (P1-1). */
+  readonly reflection?: boolean;
+  /** Override the {@link ConsolidatorConfig.importanceThreshold} default (P1-1). */
+  readonly importanceThreshold?: number;
+  /** Override the {@link ConsolidatorConfig.reflectionMaxQuestions} default (P1-1). */
+  readonly reflectionMaxQuestions?: number;
+  /** Override the per-tier {@link ConsolidatorConfig.contextualRetrieval} default (P1-3). */
+  readonly contextualRetrieval?: ContextualRetrievalMode;
+  /** Default scope used by event triggers + the manual `fireNow` path. */
+  readonly defaultScope?: SessionScope;
+}
+/**
+ * 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.
+ *
+ * @stable
+ */
+declare const CONSOLIDATOR_TIER_DEFAULTS: Readonly<Record<ConsolidatorTier, {
+  readonly ceilings: ConsolidatorCeilings;
+  readonly phases: ReadonlyArray<ConsolidatorPhase>;
+  readonly cheapModel: string | null;
+  readonly deepModel: string | null;
+  readonly onExceed: OnBudgetExceed;
+  readonly formEpisodes: boolean;
+  readonly importanceScoring: boolean;
+  readonly reflection: boolean;
+  readonly importanceThreshold: number;
+  readonly reflectionMaxQuestions: number;
+  readonly contextualRetrieval: ContextualRetrievalMode;
+}>>;
+//#endregion
+export { CONSOLIDATOR_TIER_DEFAULTS, ConsolidatorBudgetSnapshot, ConsolidatorCeilings, ConsolidatorConfig, ConsolidatorLastRuns, ConsolidatorPhase, ConsolidatorStatus, ConsolidatorTier, ConsolidatorTriggerReason, ConsolidatorTriggerSpec, CreateConsolidatorOptions, OnBudgetExceed, PhaseListener, PhaseOutcome };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +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"}

package/dist/consolidator/types.js

@@ -0,0 +1,117 @@
+//#region src/consolidator/types.ts
+/**
+* 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.
+*
+* @stable
+*/
+const CONSOLIDATOR_TIER_DEFAULTS = Object.freeze({
+	free: {
+		ceilings: {
+			maxTokensPerDay: 0,
+			maxCostPerDay: 0,
+			maxConcurrentRuns: 1,
+			maxRunDurationMs: 300 * 1e3,
+			cooldownMs: 6e4
+		},
+		phases: ["light"],
+		cheapModel: null,
+		deepModel: null,
+		onExceed: "pause",
+		formEpisodes: false,
+		importanceScoring: false,
+		reflection: false,
+		importanceThreshold: 3,
+		reflectionMaxQuestions: 3,
+		contextualRetrieval: "late-chunk"
+	},
+	cheap: {
+		ceilings: {
+			maxTokensPerDay: 5e4,
+			maxCostPerDay: .2,
+			maxConcurrentRuns: 1,
+			maxRunDurationMs: 300 * 1e3,
+			cooldownMs: 6e4
+		},
+		phases: ["light", "standard"],
+		cheapModel: null,
+		deepModel: null,
+		onExceed: "pause",
+		formEpisodes: false,
+		importanceScoring: false,
+		reflection: false,
+		importanceThreshold: 3,
+		reflectionMaxQuestions: 3,
+		contextualRetrieval: "late-chunk"
+	},
+	standard: {
+		ceilings: {
+			maxTokensPerDay: 2e5,
+			maxCostPerDay: 1,
+			maxConcurrentRuns: 1,
+			maxRunDurationMs: 600 * 1e3,
+			cooldownMs: 3e4
+		},
+		phases: [
+			"light",
+			"standard",
+			"deep"
+		],
+		cheapModel: null,
+		deepModel: null,
+		onExceed: "log",
+		formEpisodes: true,
+		importanceScoring: true,
+		reflection: false,
+		importanceThreshold: 3,
+		reflectionMaxQuestions: 3,
+		contextualRetrieval: "late-chunk"
+	},
+	full: {
+		ceilings: {
+			maxTokensPerDay: 1e6,
+			maxCostPerDay: 5,
+			maxConcurrentRuns: 2,
+			maxRunDurationMs: 900 * 1e3,
+			cooldownMs: 1e4
+		},
+		phases: [
+			"light",
+			"standard",
+			"deep"
+		],
+		cheapModel: null,
+		deepModel: null,
+		onExceed: "log",
+		formEpisodes: true,
+		importanceScoring: true,
+		reflection: true,
+		importanceThreshold: 3,
+		reflectionMaxQuestions: 3,
+		contextualRetrieval: "late-chunk"
+	},
+	custom: {
+		ceilings: {
+			maxTokensPerDay: 0,
+			maxCostPerDay: 0,
+			maxConcurrentRuns: 1,
+			maxRunDurationMs: 300 * 1e3,
+			cooldownMs: 6e4
+		},
+		phases: ["light"],
+		cheapModel: null,
+		deepModel: null,
+		onExceed: "pause",
+		formEpisodes: false,
+		importanceScoring: false,
+		reflection: false,
+		importanceThreshold: 3,
+		reflectionMaxQuestions: 3,
+		contextualRetrieval: "late-chunk"
+	}
+});
+
+//#endregion
+export { CONSOLIDATOR_TIER_DEFAULTS };
+//# sourceMappingURL=types.js.map

package/dist/consolidator/types.js.map

@@ -0,0 +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"}