@graphorin/memory 0.5.0

package/dist/conflict/types.d.ts

@@ -0,0 +1,222 @@
+import { LocalePack } from "./locale-packs/types.js";
+import { ConflictMemoryStoreExt, MemoryStoreAdapter } from "../internal/storage-adapter.js";
+import { EmbedderProvider, Fact, MemoryHit, Tracer } from "@graphorin/core";
+
+//#region src/conflict/types.d.ts
+
+/**
+ * Stable lowercase identifier of the pipeline stage. Mirrored
+ * byte-for-byte by `@graphorin/store-sqlite`'s `ConflictPipelineStage`
+ * so `fact_conflicts` / `conflict_check_pending` rows can be grouped
+ * deterministically.
+ *
+ * @stable
+ */
+type ConflictStage = 'exact-dedup' | 'embedding-three-zone' | 'heuristic-regex' | 'subject-predicate' | 'defer-to-deep';
+/**
+ * Configurable similarity thresholds for Stage 2 (embedding three-
+ * zone). Defaults pinned at `0.95 / 0.85 / 0.4` per RB-02 §8 — the
+ * production values for the default `Xenova/multilingual-e5-base`
+ * embedder (DEC-130).
+ *
+ * @stable
+ */
+interface ConflictThresholds {
+  readonly hot: number;
+  readonly nearDup: number;
+  readonly cold: number;
+}
+/**
+ * Hard-coded defaults for the three-zone thresholds. Imported by the
+ * pipeline + the test suite so call sites stay aligned.
+ *
+ * @stable
+ */
+declare const DEFAULT_CONFLICT_THRESHOLDS: ConflictThresholds;
+/**
+ * Final pipeline outcome — discriminated union returned by
+ * {@link runConflictPipeline}. Mirrors RB-02 §8.1 / DEC-117 — every
+ * variant carries the originating `stage` so audit + replay tooling
+ * can pattern-match without inspecting the message.
+ *
+ * @stable
+ */
+type ConflictDecision = {
+  readonly kind: 'admit';
+  readonly stage: ConflictStage;
+  readonly reason?: string;
+} | {
+  readonly kind: 'dedup';
+  readonly stage: ConflictStage;
+  readonly existingId: string;
+  readonly similarity?: number;
+  readonly reason?: string;
+} | {
+  readonly kind: 'supersede';
+  readonly stage: ConflictStage;
+  readonly existingId: string;
+  readonly reason: string;
+} | {
+  readonly kind: 'pending';
+  readonly stage: ConflictStage;
+  /** The candidate id that was admitted as `pending`. */
+  readonly candidateId: string;
+  /** Top-K conflicting existing fact ids from Stage 2's vector search. */
+  readonly conflictingIds: ReadonlyArray<string>;
+  readonly similarity?: number;
+  readonly reason?: string;
+};
+/**
+ * Pipeline configuration accepted by `createMemory({ conflictPipeline:
+ * ... })` and surfaced through {@link createConflictPipeline}.
+ *
+ * The `mode` field is the master switch:
+ *
+ *  - `'on'` (default) — the multi-stage pipeline runs on every
+ *    `SemanticMemory.remember(...)` call.
+ *  - `'off'` — bypass the pipeline and fall back to 10a's straight-
+ *    through write. Emits a one-shot WARN (per process) so operators
+ *    notice the regression risk.
+ *
+ * @stable
+ */
+interface ConflictPipelineOptions {
+  readonly mode?: 'on' | 'off';
+  readonly thresholds?: Partial<ConflictThresholds>;
+  readonly localePack?: LocalePack;
+  /** Per-list candidate count fed into Stage 2. Default `5` (RB-02 §8.1). */
+  readonly stage2TopK?: number;
+  /** Override the audit / pending sink. Defaults to `store.conflicts` when present. */
+  readonly conflictStore?: ConflictMemoryStoreExt;
+  /** Inject a deterministic clock. Defaults to `() => new Date().toISOString()`. */
+  readonly now?: () => string;
+}
+/**
+ * Inputs the orchestrator hands every stage. The `existing` array is
+ * populated during Stage 2 (vector search top-K); Stage 1 receives an
+ * empty array because the dedup hash is computed off the candidate
+ * alone.
+ *
+ * @stable
+ */
+interface StageContext {
+  readonly candidate: Fact;
+  readonly existing: ReadonlyArray<MemoryHit<Fact>>;
+  readonly localePack: LocalePack;
+  readonly thresholds: ConflictThresholds;
+}
+/**
+ * Per-stage outcome surfaced to the orchestrator. `'admit'` means the
+ * stage decided not to short-circuit — the pipeline continues to the
+ * next stage. Every other variant terminates the pipeline.
+ *
+ * @stable
+ */
+type StageOutcome = {
+  readonly kind: 'continue';
+} | {
+  readonly kind: 'admit';
+  readonly reason?: string;
+} | {
+  readonly kind: 'dedup';
+  readonly existingId: string;
+  readonly similarity?: number;
+  readonly reason?: string;
+} | {
+  readonly kind: 'supersede';
+  readonly existingId: string;
+  readonly reason: string;
+} | {
+  readonly kind: 'pending';
+  readonly conflictingIds: ReadonlyArray<string>;
+  readonly similarity?: number;
+  readonly reason?: string;
+};
+/**
+ * Stage interface every step implements. The orchestrator visits
+ * stages in declaration order and stops at the first non-`'continue'`
+ * outcome.
+ *
+ * @stable
+ */
+interface PipelineStage {
+  readonly id: ConflictStage;
+  evaluate(ctx: StageContext): Promise<StageOutcome>;
+}
+/**
+ * Pre-built pipeline returned by {@link createConflictPipeline}. The
+ * `run` method is what `SemanticMemory.remember(...)` calls to make
+ * the conflict decision.
+ *
+ * @stable
+ */
+interface ConflictPipeline {
+  readonly mode: 'on' | 'off';
+  readonly localePack: LocalePack;
+  readonly thresholds: ConflictThresholds;
+  run(deps: ConflictPipelineDeps, candidate: Fact): Promise<ConflictDecision>;
+}
+/**
+ * Per-call dependency bag handed to the pipeline by `SemanticMemory`.
+ *
+ * @stable
+ */
+interface ConflictPipelineDeps {
+  readonly store: MemoryStoreAdapter;
+  readonly tracer: Tracer;
+  readonly embedder: EmbedderProvider | null;
+  readonly embedderId: string | null;
+  /** Optional cancellation signal forwarded to embedder + searchVector. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * The four actions the neighbour-aware reconcile loop (P0-3) may choose
+ * for a candidate fact once the LLM has the most-similar existing
+ * memories in view. The de-facto-standard memory write loop
+ * (Mem0 / LangMem / Letta), with Graphorin's twist: `update` and
+ * `conflict` route through a **bi-temporal supersede** (close the old
+ * interval, insert the new) rather than a destructive delete.
+ *
+ * @stable
+ */
+type ReconcileAction = 'add' | 'update' | 'noop' | 'conflict';
+/**
+ * Outcome of {@link reconcileCandidate}. `add` is independent / unsure
+ * (a fresh fact); `noop` is a duplicate that adds nothing; `update` is
+ * a newer version of `targetId`; `conflict` contradicts `targetId` and
+ * closes it. The three neighbour-referencing variants carry the
+ * `targetId` of the existing fact they resolve against.
+ *
+ * @stable
+ */
+type ReconcileDecision = {
+  readonly action: 'add';
+  readonly reason?: string;
+} | {
+  readonly action: 'update';
+  readonly targetId: string;
+  readonly reason: string;
+} | {
+  readonly action: 'noop';
+  readonly targetId: string;
+  readonly reason?: string;
+} | {
+  readonly action: 'conflict';
+  readonly targetId: string;
+  readonly reason: string;
+};
+/**
+ * Map a {@link ReconcileDecision} onto the existing {@link ConflictDecision}
+ * so reconcile outcomes land in `fact_conflicts` through the same audit
+ * path as the inline pipeline (no new stage / schema): `add` → `admit`,
+ * `noop` → `dedup`, `update` / `conflict` → `supersede`. All reconcile
+ * decisions are stamped with the `defer-to-deep` stage — the reconcile
+ * loop is the consolidator's replacement for the deferred deep-judge
+ * step it supersedes.
+ *
+ * @stable
+ */
+declare function reconcileToConflictDecision(decision: ReconcileDecision): ConflictDecision;
+//#endregion
+export { ConflictDecision, ConflictPipeline, ConflictPipelineDeps, ConflictPipelineOptions, ConflictStage, ConflictThresholds, DEFAULT_CONFLICT_THRESHOLDS, PipelineStage, ReconcileAction, ReconcileDecision, StageContext, StageOutcome, reconcileToConflictDecision };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/conflict/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAwGA;;AAEwB,KAvFZ,aAAA,GAuFY,aAAA,GAAA,sBAAA,GAAA,iBAAA,GAAA,mBAAA,GAAA,eAAA;;;;AAkBxB;;;;;AAGuB,UA7FN,kBAAA,CA6FM;EACA,SAAA,GAAA,EAAA,MAAA;EAAkB,SAAA,OAAA,EAAA,MAAA;EAU7B,SAAA,IAAA,EAAY,MAAA;AA4BxB;;;;;;AAYA;AAEuB,cAtIV,2BAsIU,EAtImB,kBAsInB;;;;;;;AAUvB;;AAEmB,KApIP,gBAAA,GAoIO;EACE,SAAA,IAAA,EAAA,OAAA;EAGD,SAAA,KAAA,EArIE,aAqIF;EAAW,SAAA,MAAA,CAAA,EAAA,MAAA;AAa/B,CAAA,GAAY;EAWA,SAAA,IAAA,EAAA,OAAiB;EAiBb,SAAA,KAAA,EAzKM,aAyKN;;;;;;kBAlKM;;;;;kBAMA;;;;2BAIS;;;;;;;;;;;;;;;;;;UAmBd,uBAAA;;wBAEO,QAAQ;wBACR;;;;2BAIG;;;;;;;;;;;;UAaV,YAAA;sBACK;qBACD,cAAc,UAAU;uBACtB;uBACA;;;;;;;;;KAUX,YAAA;;;;;;;;;;;;;;;;2BAgBmB;;;;;;;;;;;UAYd,aAAA;eACF;gBACC,eAAe,QAAQ;;;;;;;;;UAUtB,gBAAA;;uBAEM;uBACA;YACX,iCAAiC,OAAO,QAAQ;;;;;;;UAQ3C,oBAAA;kBACC;mBACC;qBACE;;;oBAGD;;;;;;;;;;;;KAaR,eAAA;;;;;;;;;;KAWA,iBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiBI,2BAAA,WAAsC,oBAAoB"}

package/dist/conflict/types.js

@@ -0,0 +1,50 @@
+//#region src/conflict/types.ts
+/**
+* Hard-coded defaults for the three-zone thresholds. Imported by the
+* pipeline + the test suite so call sites stay aligned.
+*
+* @stable
+*/
+const DEFAULT_CONFLICT_THRESHOLDS = Object.freeze({
+	hot: .95,
+	nearDup: .85,
+	cold: .4
+});
+/**
+* Map a {@link ReconcileDecision} onto the existing {@link ConflictDecision}
+* so reconcile outcomes land in `fact_conflicts` through the same audit
+* path as the inline pipeline (no new stage / schema): `add` → `admit`,
+* `noop` → `dedup`, `update` / `conflict` → `supersede`. All reconcile
+* decisions are stamped with the `defer-to-deep` stage — the reconcile
+* loop is the consolidator's replacement for the deferred deep-judge
+* step it supersedes.
+*
+* @stable
+*/
+function reconcileToConflictDecision(decision) {
+	const stage = "defer-to-deep";
+	switch (decision.action) {
+		case "add": return {
+			kind: "admit",
+			stage,
+			...decision.reason !== void 0 ? { reason: decision.reason } : {}
+		};
+		case "noop": return {
+			kind: "dedup",
+			stage,
+			existingId: decision.targetId,
+			...decision.reason !== void 0 ? { reason: decision.reason } : {}
+		};
+		case "update":
+		case "conflict": return {
+			kind: "supersede",
+			stage,
+			existingId: decision.targetId,
+			reason: decision.reason
+		};
+	}
+}
+
+//#endregion
+export { DEFAULT_CONFLICT_THRESHOLDS, reconcileToConflictDecision };
+//# sourceMappingURL=types.js.map

package/dist/conflict/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":["DEFAULT_CONFLICT_THRESHOLDS: ConflictThresholds","stage: ConflictStage"],"sources":["../../src/conflict/types.ts"],"sourcesContent":["/**\n * Public types for the multi-stage conflict resolution pipeline shipped\n * in `@graphorin/memory` Phase 10b (DEC-117 / ADR-018 ext / RB-02).\n *\n * @packageDocumentation\n */\n\nimport type { EmbedderProvider, Fact, MemoryHit, Tracer } from '@graphorin/core';\nimport type { ConflictMemoryStoreExt, MemoryStoreAdapter } from '../internal/storage-adapter.js';\nimport type { LocalePack } from './locale-packs/index.js';\n\n/**\n * Stable lowercase identifier of the pipeline stage. Mirrored\n * byte-for-byte by `@graphorin/store-sqlite`'s `ConflictPipelineStage`\n * so `fact_conflicts` / `conflict_check_pending` rows can be grouped\n * deterministically.\n *\n * @stable\n */\nexport type ConflictStage =\n  | 'exact-dedup'\n  | 'embedding-three-zone'\n  | 'heuristic-regex'\n  | 'subject-predicate'\n  | 'defer-to-deep';\n\n/**\n * Configurable similarity thresholds for Stage 2 (embedding three-\n * zone). Defaults pinned at `0.95 / 0.85 / 0.4` per RB-02 §8 — the\n * production values for the default `Xenova/multilingual-e5-base`\n * embedder (DEC-130).\n *\n * @stable\n */\nexport interface ConflictThresholds {\n  readonly hot: number;\n  readonly nearDup: number;\n  readonly cold: number;\n}\n\n/**\n * Hard-coded defaults for the three-zone thresholds. Imported by the\n * pipeline + the test suite so call sites stay aligned.\n *\n * @stable\n */\nexport const DEFAULT_CONFLICT_THRESHOLDS: ConflictThresholds = Object.freeze({\n  hot: 0.95,\n  nearDup: 0.85,\n  cold: 0.4,\n});\n\n/**\n * Final pipeline outcome — discriminated union returned by\n * {@link runConflictPipeline}. Mirrors RB-02 §8.1 / DEC-117 — every\n * variant carries the originating `stage` so audit + replay tooling\n * can pattern-match without inspecting the message.\n *\n * @stable\n */\nexport type ConflictDecision =\n  | {\n      readonly kind: 'admit';\n      readonly stage: ConflictStage;\n      readonly reason?: string;\n    }\n  | {\n      readonly kind: 'dedup';\n      readonly stage: ConflictStage;\n      readonly existingId: string;\n      readonly similarity?: number;\n      readonly reason?: string;\n    }\n  | {\n      readonly kind: 'supersede';\n      readonly stage: ConflictStage;\n      readonly existingId: string;\n      readonly reason: string;\n    }\n  | {\n      readonly kind: 'pending';\n      readonly stage: ConflictStage;\n      /** The candidate id that was admitted as `pending`. */\n      readonly candidateId: string;\n      /** Top-K conflicting existing fact ids from Stage 2's vector search. */\n      readonly conflictingIds: ReadonlyArray<string>;\n      readonly similarity?: number;\n      readonly reason?: string;\n    };\n\n/**\n * Pipeline configuration accepted by `createMemory({ conflictPipeline:\n * ... })` and surfaced through {@link createConflictPipeline}.\n *\n * The `mode` field is the master switch:\n *\n *  - `'on'` (default) — the multi-stage pipeline runs on every\n *    `SemanticMemory.remember(...)` call.\n *  - `'off'` — bypass the pipeline and fall back to 10a's straight-\n *    through write. Emits a one-shot WARN (per process) so operators\n *    notice the regression risk.\n *\n * @stable\n */\nexport interface ConflictPipelineOptions {\n  readonly mode?: 'on' | 'off';\n  readonly thresholds?: Partial<ConflictThresholds>;\n  readonly localePack?: LocalePack;\n  /** Per-list candidate count fed into Stage 2. Default `5` (RB-02 §8.1). */\n  readonly stage2TopK?: number;\n  /** Override the audit / pending sink. Defaults to `store.conflicts` when present. */\n  readonly conflictStore?: ConflictMemoryStoreExt;\n  /** Inject a deterministic clock. Defaults to `() => new Date().toISOString()`. */\n  readonly now?: () => string;\n}\n\n/**\n * Inputs the orchestrator hands every stage. The `existing` array is\n * populated during Stage 2 (vector search top-K); Stage 1 receives an\n * empty array because the dedup hash is computed off the candidate\n * alone.\n *\n * @stable\n */\nexport interface StageContext {\n  readonly candidate: Fact;\n  readonly existing: ReadonlyArray<MemoryHit<Fact>>;\n  readonly localePack: LocalePack;\n  readonly thresholds: ConflictThresholds;\n}\n\n/**\n * Per-stage outcome surfaced to the orchestrator. `'admit'` means the\n * stage decided not to short-circuit — the pipeline continues to the\n * next stage. Every other variant terminates the pipeline.\n *\n * @stable\n */\nexport type StageOutcome =\n  | { readonly kind: 'continue' }\n  | { readonly kind: 'admit'; readonly reason?: string }\n  | {\n      readonly kind: 'dedup';\n      readonly existingId: string;\n      readonly similarity?: number;\n      readonly reason?: string;\n    }\n  | {\n      readonly kind: 'supersede';\n      readonly existingId: string;\n      readonly reason: string;\n    }\n  | {\n      readonly kind: 'pending';\n      readonly conflictingIds: ReadonlyArray<string>;\n      readonly similarity?: number;\n      readonly reason?: string;\n    };\n\n/**\n * Stage interface every step implements. The orchestrator visits\n * stages in declaration order and stops at the first non-`'continue'`\n * outcome.\n *\n * @stable\n */\nexport interface PipelineStage {\n  readonly id: ConflictStage;\n  evaluate(ctx: StageContext): Promise<StageOutcome>;\n}\n\n/**\n * Pre-built pipeline returned by {@link createConflictPipeline}. The\n * `run` method is what `SemanticMemory.remember(...)` calls to make\n * the conflict decision.\n *\n * @stable\n */\nexport interface ConflictPipeline {\n  readonly mode: 'on' | 'off';\n  readonly localePack: LocalePack;\n  readonly thresholds: ConflictThresholds;\n  run(deps: ConflictPipelineDeps, candidate: Fact): Promise<ConflictDecision>;\n}\n\n/**\n * Per-call dependency bag handed to the pipeline by `SemanticMemory`.\n *\n * @stable\n */\nexport interface ConflictPipelineDeps {\n  readonly store: MemoryStoreAdapter;\n  readonly tracer: Tracer;\n  readonly embedder: EmbedderProvider | null;\n  readonly embedderId: string | null;\n  /** Optional cancellation signal forwarded to embedder + searchVector. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * The four actions the neighbour-aware reconcile loop (P0-3) may choose\n * for a candidate fact once the LLM has the most-similar existing\n * memories in view. The de-facto-standard memory write loop\n * (Mem0 / LangMem / Letta), with Graphorin's twist: `update` and\n * `conflict` route through a **bi-temporal supersede** (close the old\n * interval, insert the new) rather than a destructive delete.\n *\n * @stable\n */\nexport type ReconcileAction = 'add' | 'update' | 'noop' | 'conflict';\n\n/**\n * Outcome of {@link reconcileCandidate}. `add` is independent / unsure\n * (a fresh fact); `noop` is a duplicate that adds nothing; `update` is\n * a newer version of `targetId`; `conflict` contradicts `targetId` and\n * closes it. The three neighbour-referencing variants carry the\n * `targetId` of the existing fact they resolve against.\n *\n * @stable\n */\nexport type ReconcileDecision =\n  | { readonly action: 'add'; readonly reason?: string }\n  | { readonly action: 'update'; readonly targetId: string; readonly reason: string }\n  | { readonly action: 'noop'; readonly targetId: string; readonly reason?: string }\n  | { readonly action: 'conflict'; readonly targetId: string; readonly reason: string };\n\n/**\n * Map a {@link ReconcileDecision} onto the existing {@link ConflictDecision}\n * so reconcile outcomes land in `fact_conflicts` through the same audit\n * path as the inline pipeline (no new stage / schema): `add` → `admit`,\n * `noop` → `dedup`, `update` / `conflict` → `supersede`. All reconcile\n * decisions are stamped with the `defer-to-deep` stage — the reconcile\n * loop is the consolidator's replacement for the deferred deep-judge\n * step it supersedes.\n *\n * @stable\n */\nexport function reconcileToConflictDecision(decision: ReconcileDecision): ConflictDecision {\n  const stage: ConflictStage = 'defer-to-deep';\n  switch (decision.action) {\n    case 'add':\n      return {\n        kind: 'admit',\n        stage,\n        ...(decision.reason !== undefined ? { reason: decision.reason } : {}),\n      };\n    case 'noop':\n      return {\n        kind: 'dedup',\n        stage,\n        existingId: decision.targetId,\n        ...(decision.reason !== undefined ? { reason: decision.reason } : {}),\n      };\n    case 'update':\n    case 'conflict':\n      return {\n        kind: 'supersede',\n        stage,\n        existingId: decision.targetId,\n        reason: decision.reason,\n      };\n  }\n}\n"],"mappings":";;;;;;;AA8CA,MAAaA,8BAAkD,OAAO,OAAO;CAC3E,KAAK;CACL,SAAS;CACT,MAAM;CACP,CAAC;;;;;;;;;;;;AA2LF,SAAgB,4BAA4B,UAA+C;CACzF,MAAMC,QAAuB;AAC7B,SAAQ,SAAS,QAAjB;EACE,KAAK,MACH,QAAO;GACL,MAAM;GACN;GACA,GAAI,SAAS,WAAW,SAAY,EAAE,QAAQ,SAAS,QAAQ,GAAG,EAAE;GACrE;EACH,KAAK,OACH,QAAO;GACL,MAAM;GACN;GACA,YAAY,SAAS;GACrB,GAAI,SAAS,WAAW,SAAY,EAAE,QAAQ,SAAS,QAAQ,GAAG,EAAE;GACrE;EACH,KAAK;EACL,KAAK,WACH,QAAO;GACL,MAAM;GACN;GACA,YAAY,SAAS;GACrB,QAAQ,SAAS;GAClB"}

package/dist/consolidator/budget.d.ts

@@ -0,0 +1 @@
+import "./types.js";

package/dist/consolidator/budget.js

@@ -0,0 +1,214 @@
+import { BudgetExceededError } from "./errors.js";
+
+//#region src/consolidator/budget.ts
+/**
+* Cost-budget enforcement for the consolidator. The tracker is a
+* pure in-memory state machine: it owns the day-bucketed counters
+* (token + cost), the UTC reset semantics, and the `onExceed`
+* dispatch.
+*
+* The tracker does not perform any I/O — operators surface the live
+* counters via `Consolidator.status()` and the persisted snapshot is
+* derived from `consolidator_runs` rows.
+*
+* @packageDocumentation
+*/
+/**
+* Per-instance budget tracker. The runtime creates one tracker per
+* consolidator and resets the day counters lazily on the next phase
+* invocation.
+*
+* @stable
+*/
+var BudgetTracker = class {
+	#now;
+	#resetSemantics;
+	#onExceed;
+	#maxTokensPerDay;
+	#maxCostPerDay;
+	#bucketStart;
+	#tokens = 0;
+	#cost = 0;
+	#paused = false;
+	#pausedReason = null;
+	/**
+	* Timestamped spend ledger for `sliding-24h` only. `#maybeReset` trims it to
+	* the trailing 24h window and recomputes `#tokens` / `#cost` from it, so the
+	* counters reflect a true rolling window instead of being zeroed on every
+	* check (MCON-3). Unused — and never appended to — under `utc` / `local`.
+	*/
+	#ledger = [];
+	constructor(opts) {
+		this.#now = opts.now ?? Date.now;
+		this.#resetSemantics = opts.resetSemantics;
+		this.#onExceed = opts.onExceed;
+		this.#maxTokensPerDay = opts.maxTokensPerDay;
+		this.#maxCostPerDay = opts.maxCostPerDay;
+		this.#bucketStart = bucketStart(this.#now(), this.#resetSemantics);
+	}
+	/**
+	* Replace the active ceilings. Used by `Consolidator.setTier(...)`.
+	*
+	* @stable
+	*/
+	reconfigure(opts) {
+		this.#maxTokensPerDay = opts.maxTokensPerDay;
+		this.#maxCostPerDay = opts.maxCostPerDay;
+		if (this.#paused) {
+			const tokensOk = this.#tokens <= this.#maxTokensPerDay;
+			const costOk = this.#cost <= this.#maxCostPerDay;
+			if (tokensOk && costOk) {
+				this.#paused = false;
+				this.#pausedReason = null;
+			}
+		}
+	}
+	/**
+	* Return whether the supplied phase may run right now.
+	*
+	* @stable
+	*/
+	precheck(phase) {
+		this.#maybeReset();
+		if (phase === "light") return { allowed: true };
+		if (this.#paused) return {
+			allowed: false,
+			reason: this.#pausedReason ?? "cost-exceeded"
+		};
+		if (this.#maxTokensPerDay <= 0) return {
+			allowed: false,
+			reason: "tokens-exceeded"
+		};
+		if (this.#maxCostPerDay <= 0) return {
+			allowed: false,
+			reason: "cost-exceeded"
+		};
+		return { allowed: true };
+	}
+	/**
+	* Record consumption. Returns the post-record state — `paused` is
+	* `true` when the spend pushed past a ceiling under
+	* `onExceed: 'pause'`.
+	*
+	* Throws {@link BudgetExceededError} when the configured behaviour
+	* is `'throw'`.
+	*
+	* @stable
+	*/
+	record(args) {
+		this.#maybeReset();
+		const tokens = Math.max(0, args.tokens);
+		const cost = Math.max(0, args.costUsd);
+		if (this.#resetSemantics === "sliding-24h") this.#ledger.push({
+			at: this.#now(),
+			tokens,
+			cost
+		});
+		this.#tokens += tokens;
+		this.#cost += cost;
+		if (this.#tokens > this.#maxTokensPerDay) this.#handleBreach(args.phase, "tokens", this.#tokens, this.#maxTokensPerDay);
+		if (this.#cost > this.#maxCostPerDay) this.#handleBreach(args.phase, "cost", this.#cost, this.#maxCostPerDay);
+		return this.snapshot();
+	}
+	/**
+	* Read-only snapshot. Surfaced through `Consolidator.status()`.
+	*
+	* @stable
+	*/
+	snapshot() {
+		this.#maybeReset();
+		const resetAt = this.#resetSemantics === "sliding-24h" ? (this.#ledger[0]?.at ?? this.#now()) + DAY_MS : nextBucketStart(this.#bucketStart, this.#resetSemantics);
+		return Object.freeze({
+			tokensUsedToday: this.#tokens,
+			costUsedToday: this.#cost,
+			tokensRemaining: Math.max(0, this.#maxTokensPerDay - this.#tokens),
+			costRemaining: Math.max(0, this.#maxCostPerDay - this.#cost),
+			resetAt: new Date(resetAt).toISOString(),
+			paused: this.#paused
+		});
+	}
+	/**
+	* Force a reset. Used by tests + manual operator action.
+	*
+	* @stable
+	*/
+	reset() {
+		this.#tokens = 0;
+		this.#cost = 0;
+		this.#paused = false;
+		this.#pausedReason = null;
+		this.#ledger = [];
+		this.#bucketStart = bucketStart(this.#now(), this.#resetSemantics);
+	}
+	#handleBreach(phase, resource, actual, budget) {
+		if (this.#onExceed === "throw") throw new BudgetExceededError({
+			phase,
+			resource,
+			actual,
+			budget
+		});
+		if (this.#onExceed === "pause") {
+			this.#paused = true;
+			this.#pausedReason = resource === "tokens" ? "tokens-exceeded" : "cost-exceeded";
+		}
+	}
+	#maybeReset() {
+		const now = this.#now();
+		if (this.#resetSemantics === "sliding-24h") {
+			const cutoff = now - DAY_MS;
+			if (this.#ledger.length > 0 && this.#ledger[0] !== void 0 && this.#ledger[0].at <= cutoff) this.#ledger = this.#ledger.filter((entry) => entry.at > cutoff);
+			this.#tokens = this.#ledger.reduce((sum, entry) => sum + entry.tokens, 0);
+			this.#cost = this.#ledger.reduce((sum, entry) => sum + entry.cost, 0);
+			if (this.#paused && this.#tokens <= this.#maxTokensPerDay && this.#cost <= this.#maxCostPerDay) {
+				this.#paused = false;
+				this.#pausedReason = null;
+			}
+			return;
+		}
+		const currentBucket = bucketStart(now, this.#resetSemantics);
+		if (currentBucket !== this.#bucketStart) {
+			this.#bucketStart = currentBucket;
+			this.#tokens = 0;
+			this.#cost = 0;
+			this.#paused = false;
+			this.#pausedReason = null;
+		}
+	}
+};
+const DAY_MS = 1440 * 60 * 1e3;
+/**
+* Compute the start of the current bucket (ms epoch) for the
+* supplied reset semantics. UTC midnight is the production default
+* per ADR-038.
+*
+* @internal
+*/
+function bucketStart(now, semantics) {
+	switch (semantics) {
+		case "utc": {
+			const d = new Date(now);
+			return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+		}
+		case "local": {
+			const d = new Date(now);
+			return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+		}
+		case "sliding-24h": return now;
+	}
+}
+/**
+* Compute the next reset boundary (ms epoch).
+*
+* @internal
+*/
+function nextBucketStart(bucket, semantics) {
+	switch (semantics) {
+		case "utc":
+		case "local": return bucket + DAY_MS;
+		case "sliding-24h": return bucket + DAY_MS;
+	}
+}
+
+//#endregion
+export { BudgetTracker, bucketStart, nextBucketStart };
+//# sourceMappingURL=budget.js.map

package/dist/consolidator/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","names":["#now","#resetSemantics","#onExceed","#maxTokensPerDay","#maxCostPerDay","#bucketStart","#paused","#tokens","#cost","#pausedReason","#maybeReset","#ledger","#handleBreach"],"sources":["../../src/consolidator/budget.ts"],"sourcesContent":["/**\n * Cost-budget enforcement for the consolidator. The tracker is a\n * pure in-memory state machine: it owns the day-bucketed counters\n * (token + cost), the UTC reset semantics, and the `onExceed`\n * dispatch.\n *\n * The tracker does not perform any I/O — operators surface the live\n * counters via `Consolidator.status()` and the persisted snapshot is\n * derived from `consolidator_runs` rows.\n *\n * @packageDocumentation\n */\n\nimport { BudgetExceededError } from './errors.js';\nimport type { ConsolidatorPhase, OnBudgetExceed } from './types.js';\n\n/**\n * @stable\n */\nexport interface BudgetSnapshot {\n  readonly tokensUsedToday: number;\n  readonly costUsedToday: number;\n  readonly tokensRemaining: number;\n  readonly costRemaining: number;\n  readonly resetAt: string;\n  readonly paused: boolean;\n}\n\n/**\n * @stable\n */\nexport interface BudgetCheck {\n  readonly allowed: boolean;\n  readonly reason?: 'paused' | 'tokens-exceeded' | 'cost-exceeded';\n}\n\n/**\n * @stable\n */\nexport interface BudgetTrackerOptions {\n  readonly maxTokensPerDay: number;\n  readonly maxCostPerDay: number;\n  readonly onExceed: OnBudgetExceed;\n  readonly resetSemantics: 'utc' | 'local' | 'sliding-24h';\n  readonly now?: () => number;\n}\n\n/**\n * Per-instance budget tracker. The runtime creates one tracker per\n * consolidator and resets the day counters lazily on the next phase\n * invocation.\n *\n * @stable\n */\nexport class BudgetTracker {\n  readonly #now: () => number;\n  readonly #resetSemantics: 'utc' | 'local' | 'sliding-24h';\n  readonly #onExceed: OnBudgetExceed;\n  #maxTokensPerDay: number;\n  #maxCostPerDay: number;\n  #bucketStart: number;\n  #tokens = 0;\n  #cost = 0;\n  #paused = false;\n  #pausedReason: 'tokens-exceeded' | 'cost-exceeded' | null = null;\n  /**\n   * Timestamped spend ledger for `sliding-24h` only. `#maybeReset` trims it to\n   * the trailing 24h window and recomputes `#tokens` / `#cost` from it, so the\n   * counters reflect a true rolling window instead of being zeroed on every\n   * check (MCON-3). Unused — and never appended to — under `utc` / `local`.\n   */\n  #ledger: Array<{ at: number; tokens: number; cost: number }> = [];\n\n  constructor(opts: BudgetTrackerOptions) {\n    this.#now = opts.now ?? Date.now;\n    this.#resetSemantics = opts.resetSemantics;\n    this.#onExceed = opts.onExceed;\n    this.#maxTokensPerDay = opts.maxTokensPerDay;\n    this.#maxCostPerDay = opts.maxCostPerDay;\n    this.#bucketStart = bucketStart(this.#now(), this.#resetSemantics);\n  }\n\n  /**\n   * Replace the active ceilings. Used by `Consolidator.setTier(...)`.\n   *\n   * @stable\n   */\n  reconfigure(opts: { maxTokensPerDay: number; maxCostPerDay: number }): void {\n    this.#maxTokensPerDay = opts.maxTokensPerDay;\n    this.#maxCostPerDay = opts.maxCostPerDay;\n    if (this.#paused) {\n      const tokensOk = this.#tokens <= this.#maxTokensPerDay;\n      const costOk = this.#cost <= this.#maxCostPerDay;\n      if (tokensOk && costOk) {\n        this.#paused = false;\n        this.#pausedReason = null;\n      }\n    }\n  }\n\n  /**\n   * Return whether the supplied phase may run right now.\n   *\n   * @stable\n   */\n  precheck(phase: ConsolidatorPhase): BudgetCheck {\n    this.#maybeReset();\n    if (phase === 'light') return { allowed: true };\n    if (this.#paused) {\n      const reason = this.#pausedReason ?? 'cost-exceeded';\n      return { allowed: false, reason };\n    }\n    if (this.#maxTokensPerDay <= 0) {\n      return { allowed: false, reason: 'tokens-exceeded' };\n    }\n    if (this.#maxCostPerDay <= 0) {\n      return { allowed: false, reason: 'cost-exceeded' };\n    }\n    return { allowed: true };\n  }\n\n  /**\n   * Record consumption. Returns the post-record state — `paused` is\n   * `true` when the spend pushed past a ceiling under\n   * `onExceed: 'pause'`.\n   *\n   * Throws {@link BudgetExceededError} when the configured behaviour\n   * is `'throw'`.\n   *\n   * @stable\n   */\n  record(args: { phase: ConsolidatorPhase; tokens: number; costUsd: number }): BudgetSnapshot {\n    this.#maybeReset();\n    const tokens = Math.max(0, args.tokens);\n    const cost = Math.max(0, args.costUsd);\n    if (this.#resetSemantics === 'sliding-24h') {\n      this.#ledger.push({ at: this.#now(), tokens, cost });\n    }\n    this.#tokens += tokens;\n    this.#cost += cost;\n    if (this.#tokens > this.#maxTokensPerDay) {\n      this.#handleBreach(args.phase, 'tokens', this.#tokens, this.#maxTokensPerDay);\n    }\n    if (this.#cost > this.#maxCostPerDay) {\n      this.#handleBreach(args.phase, 'cost', this.#cost, this.#maxCostPerDay);\n    }\n    return this.snapshot();\n  }\n\n  /**\n   * Read-only snapshot. Surfaced through `Consolidator.status()`.\n   *\n   * @stable\n   */\n  snapshot(): BudgetSnapshot {\n    this.#maybeReset();\n    // For the rolling window the \"reset\" is continuous — the boundary is when\n    // the oldest in-window spend ages out (24h after it landed).\n    const resetAt =\n      this.#resetSemantics === 'sliding-24h'\n        ? (this.#ledger[0]?.at ?? this.#now()) + DAY_MS\n        : nextBucketStart(this.#bucketStart, this.#resetSemantics);\n    return Object.freeze({\n      tokensUsedToday: this.#tokens,\n      costUsedToday: this.#cost,\n      tokensRemaining: Math.max(0, this.#maxTokensPerDay - this.#tokens),\n      costRemaining: Math.max(0, this.#maxCostPerDay - this.#cost),\n      resetAt: new Date(resetAt).toISOString(),\n      paused: this.#paused,\n    });\n  }\n\n  /**\n   * Force a reset. Used by tests + manual operator action.\n   *\n   * @stable\n   */\n  reset(): void {\n    this.#tokens = 0;\n    this.#cost = 0;\n    this.#paused = false;\n    this.#pausedReason = null;\n    this.#ledger = [];\n    this.#bucketStart = bucketStart(this.#now(), this.#resetSemantics);\n  }\n\n  #handleBreach(\n    phase: ConsolidatorPhase,\n    resource: 'tokens' | 'cost',\n    actual: number,\n    budget: number,\n  ): void {\n    if (this.#onExceed === 'throw') {\n      throw new BudgetExceededError({ phase, resource, actual, budget });\n    }\n    if (this.#onExceed === 'pause') {\n      this.#paused = true;\n      this.#pausedReason = resource === 'tokens' ? 'tokens-exceeded' : 'cost-exceeded';\n    }\n  }\n\n  #maybeReset(): void {\n    const now = this.#now();\n    if (this.#resetSemantics === 'sliding-24h') {\n      // Rolling window: drop spends older than the trailing 24h and recompute\n      // the totals from what remains, rather than zeroing on every check.\n      const cutoff = now - DAY_MS;\n      if (\n        this.#ledger.length > 0 &&\n        this.#ledger[0] !== undefined &&\n        this.#ledger[0].at <= cutoff\n      ) {\n        this.#ledger = this.#ledger.filter((entry) => entry.at > cutoff);\n      }\n      this.#tokens = this.#ledger.reduce((sum, entry) => sum + entry.tokens, 0);\n      this.#cost = this.#ledger.reduce((sum, entry) => sum + entry.cost, 0);\n      // Auto-unpause once the window has dropped back under both ceilings.\n      if (\n        this.#paused &&\n        this.#tokens <= this.#maxTokensPerDay &&\n        this.#cost <= this.#maxCostPerDay\n      ) {\n        this.#paused = false;\n        this.#pausedReason = null;\n      }\n      return;\n    }\n    // utc / local: zero the counters when the calendar bucket rolls over.\n    const currentBucket = bucketStart(now, this.#resetSemantics);\n    if (currentBucket !== this.#bucketStart) {\n      this.#bucketStart = currentBucket;\n      this.#tokens = 0;\n      this.#cost = 0;\n      this.#paused = false;\n      this.#pausedReason = null;\n    }\n  }\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\n\n/**\n * Compute the start of the current bucket (ms epoch) for the\n * supplied reset semantics. UTC midnight is the production default\n * per ADR-038.\n *\n * @internal\n */\nexport function bucketStart(now: number, semantics: 'utc' | 'local' | 'sliding-24h'): number {\n  switch (semantics) {\n    case 'utc': {\n      const d = new Date(now);\n      return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());\n    }\n    case 'local': {\n      const d = new Date(now);\n      return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();\n    }\n    case 'sliding-24h':\n      return now;\n  }\n}\n\n/**\n * Compute the next reset boundary (ms epoch).\n *\n * @internal\n */\nexport function nextBucketStart(\n  bucket: number,\n  semantics: 'utc' | 'local' | 'sliding-24h',\n): number {\n  switch (semantics) {\n    case 'utc':\n    case 'local':\n      return bucket + DAY_MS;\n    case 'sliding-24h':\n      return bucket + DAY_MS;\n  }\n}\n"],"mappings":"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"}

package/dist/consolidator/decay.d.ts

@@ -0,0 +1,35 @@
+//#region src/consolidator/decay.d.ts
+
+/**
+ * Tunable weights for the multi-signal {@link salience} score (X-1).
+ * Each weight is the *magnitude* of the corresponding signal's pull on
+ * the retention curve; all default to values chosen so the ordering is
+ * sensible without ever inverting it.
+ *
+ * @stable
+ */
+interface SalienceWeights {
+  /**
+   * How strongly importance (P1-2) stretches retention. At the default
+   * `0.6`, importance `1.0` multiplies retention by `1.3` and importance
+   * `0.0` by `0.7`; neutral importance leaves it unchanged.
+   */
+  readonly importance: number;
+  /**
+   * Penalty applied to a **quarantined** fact (P1-4) — the explicit
+   * security-risk negative term. At the default `0.7`, a quarantined
+   * fact keeps only `0.3` of its retention, so it is evicted first under
+   * capacity pressure. Never a hard delete: the fact is archived,
+   * recoverable, and quarantine still gates it out of recall meanwhile.
+   */
+  readonly quarantine: number;
+  /**
+   * Mild penalty for a fact with non-first-party provenance (P1-4) —
+   * e.g. `'tool'` / `'imported'` content that did not originate with the
+   * user. At the default `0.2` such a fact keeps `0.8` of its retention.
+   */
+  readonly foreignProvenance: number;
+}
+//#endregion
+export { SalienceWeights };
+//# sourceMappingURL=decay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decay.d.ts","names":[],"sources":["../../src/consolidator/decay.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;UA6FiB,eAAA"}

package/dist/consolidator/decay.js

@@ -0,0 +1,91 @@
+//#region src/consolidator/decay.ts
+/**
+* Compute the retention score for a fact given its age, last-access
+* recency, and accumulated `strength`. Larger `strength` means the
+* fact has been accessed more often, so the retention curve flattens
+* — `score = base * exp(-elapsedDays / (tau * strength))`.
+*
+* @stable
+*/
+function retention(args) {
+	const reference = args.lastAccessedAt ?? args.createdAt;
+	const elapsedDays = Math.max(0, args.now - reference) / (1e3 * 60 * 60 * 24);
+	const tau = Math.max(.1, args.tauDays * Math.max(.5, args.strength));
+	return Math.exp(-elapsedDays / tau);
+}
+/**
+* Neutral importance used when a fact carries no importance hint —
+* the midpoint of the `[0, 1]` range, so an unscored fact contributes
+* an importance factor of exactly `1.0` (`salience === retention`).
+*
+* @stable
+*/
+const NEUTRAL_IMPORTANCE = .5;
+/**
+* Default {@link SalienceWeights}. Chosen so that an active,
+* first-party, unscored fact has `salience === retention` (the X-1
+* change is invisible until a fact carries an importance hint, is
+* quarantined, or has foreign provenance).
+*
+* @stable
+*/
+const DEFAULT_SALIENCE_WEIGHTS = Object.freeze({
+	importance: .6,
+	quarantine: .7,
+	foreignProvenance: .2
+});
+/**
+* Multi-signal salience for capacity-bounded forgetting (X-1). Combines
+* the Ebbinghaus {@link retention} curve (temporal relevance + access
+* frequency via `strength`) with the P1-2 importance hint and a P1-4
+* security-risk negative term:
+*
+* ```
+* salience = retention × importanceFactor × securityFactor
+* ```
+*
+* Sold as **cost / staleness control, not accuracy**: it only orders
+* what gets archived first when storage is bounded — it never gates
+* recall. With neutral importance, an active fact, and first-party
+* provenance the factors are all `1`, so `salience === retention`.
+*
+* @stable
+*/
+function salience(args) {
+	const weights = args.weights ?? DEFAULT_SALIENCE_WEIGHTS;
+	const base = retention({
+		now: args.now,
+		lastAccessedAt: args.lastAccessedAt,
+		createdAt: args.createdAt,
+		strength: args.strength,
+		tauDays: args.tauDays
+	});
+	const importance = clamp01(args.importance ?? NEUTRAL_IMPORTANCE);
+	const importanceFactor = Math.max(0, 1 + weights.importance * (importance - NEUTRAL_IMPORTANCE));
+	const securityFactor = args.quarantined ? Math.max(0, 1 - weights.quarantine) : args.foreignProvenance ? Math.max(0, 1 - weights.foreignProvenance) : 1;
+	return Math.max(0, base * importanceFactor * securityFactor);
+}
+/**
+* Capacity-bounded eviction selector (X-1). Given facts scored by
+* {@link salience}, return the ids of the lowest-salience ones to
+* archive so that at most `capacity` remain. Pure and deterministic:
+* ties break by id so a given batch always evicts the same set.
+*
+* Returns `[]` when the batch already fits (`length <= capacity`).
+* `capacity <= 0` evicts the whole batch.
+*
+* @stable
+*/
+function selectForCapacityEviction(scored, capacity) {
+	const evictCount = scored.length - Math.max(0, capacity);
+	if (evictCount <= 0) return [];
+	return [...scored].sort((a, b) => a.salience - b.salience || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).slice(0, evictCount).map((row) => row.id);
+}
+function clamp01(value) {
+	if (Number.isNaN(value)) return NEUTRAL_IMPORTANCE;
+	return Math.min(1, Math.max(0, value));
+}
+
+//#endregion
+export { DEFAULT_SALIENCE_WEIGHTS, NEUTRAL_IMPORTANCE, retention, salience, selectForCapacityEviction };
+//# sourceMappingURL=decay.js.map