@graphorin/memory 0.5.0

package/dist/consolidator/decay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decay.js","names":["DEFAULT_SALIENCE_WEIGHTS: SalienceWeights"],"sources":["../../src/consolidator/decay.ts"],"sourcesContent":["/**\n * Ebbinghaus retention curve for the light phase. Pure functions so\n * the formula is testable without touching storage.\n *\n * @packageDocumentation\n */\n\n/**\n * Default time constant for the retention curve. The plan calls for\n * `tau = 7` days; consumers may override per-consolidator via\n * `decayTauDays`.\n *\n * @stable\n */\nexport const DEFAULT_DECAY_TAU_DAYS = 7;\n\n/**\n * Default archive threshold — facts whose retention falls below this\n * value are soft-archived in the light phase. `0.05` matches the\n * documented forgetting policy for the memory system.\n *\n * @stable\n */\nexport const DEFAULT_DECAY_ARCHIVE_THRESHOLD = 0.05;\n\n/**\n * Compute the retention score for a fact given its age, last-access\n * recency, and accumulated `strength`. Larger `strength` means the\n * fact has been accessed more often, so the retention curve flattens\n * — `score = base * exp(-elapsedDays / (tau * strength))`.\n *\n * @stable\n */\nexport function retention(args: {\n  /** Reference time (ms epoch). */\n  readonly now: number;\n  /** Last access timestamp (ms epoch); falls back to `createdAt` when null. */\n  readonly lastAccessedAt: number | null;\n  /** Creation timestamp (ms epoch). */\n  readonly createdAt: number;\n  /** Strength multiplier (default 1.0). */\n  readonly strength: number;\n  /** Time constant in days. */\n  readonly tauDays: number;\n}): number {\n  const reference = args.lastAccessedAt ?? args.createdAt;\n  const elapsedMs = Math.max(0, args.now - reference);\n  const elapsedDays = elapsedMs / (1000 * 60 * 60 * 24);\n  const tau = Math.max(0.1, args.tauDays * Math.max(0.5, args.strength));\n  return Math.exp(-elapsedDays / tau);\n}\n\n/**\n * `true` when the fact's retention curve has fallen below the\n * archive threshold.\n *\n * @stable\n */\nexport function shouldArchive(args: {\n  readonly now: number;\n  readonly lastAccessedAt: number | null;\n  readonly createdAt: number;\n  readonly strength: number;\n  readonly tauDays: number;\n  readonly archiveThreshold: number;\n}): boolean {\n  const score = retention({\n    now: args.now,\n    lastAccessedAt: args.lastAccessedAt,\n    createdAt: args.createdAt,\n    strength: args.strength,\n    tauDays: args.tauDays,\n  });\n  return score < args.archiveThreshold;\n}\n\n/**\n * Neutral importance used when a fact carries no importance hint —\n * the midpoint of the `[0, 1]` range, so an unscored fact contributes\n * an importance factor of exactly `1.0` (`salience === retention`).\n *\n * @stable\n */\nexport const NEUTRAL_IMPORTANCE = 0.5;\n\n/**\n * Tunable weights for the multi-signal {@link salience} score (X-1).\n * Each weight is the *magnitude* of the corresponding signal's pull on\n * the retention curve; all default to values chosen so the ordering is\n * sensible without ever inverting it.\n *\n * @stable\n */\nexport interface SalienceWeights {\n  /**\n   * How strongly importance (P1-2) stretches retention. At the default\n   * `0.6`, importance `1.0` multiplies retention by `1.3` and importance\n   * `0.0` by `0.7`; neutral importance leaves it unchanged.\n   */\n  readonly importance: number;\n  /**\n   * Penalty applied to a **quarantined** fact (P1-4) — the explicit\n   * security-risk negative term. At the default `0.7`, a quarantined\n   * fact keeps only `0.3` of its retention, so it is evicted first under\n   * capacity pressure. Never a hard delete: the fact is archived,\n   * recoverable, and quarantine still gates it out of recall meanwhile.\n   */\n  readonly quarantine: number;\n  /**\n   * Mild penalty for a fact with non-first-party provenance (P1-4) —\n   * e.g. `'tool'` / `'imported'` content that did not originate with the\n   * user. At the default `0.2` such a fact keeps `0.8` of its retention.\n   */\n  readonly foreignProvenance: number;\n}\n\n/**\n * Default {@link SalienceWeights}. Chosen so that an active,\n * first-party, unscored fact has `salience === retention` (the X-1\n * change is invisible until a fact carries an importance hint, is\n * quarantined, or has foreign provenance).\n *\n * @stable\n */\nexport const DEFAULT_SALIENCE_WEIGHTS: SalienceWeights = Object.freeze({\n  importance: 0.6,\n  quarantine: 0.7,\n  foreignProvenance: 0.2,\n});\n\n/**\n * Multi-signal salience for capacity-bounded forgetting (X-1). Combines\n * the Ebbinghaus {@link retention} curve (temporal relevance + access\n * frequency via `strength`) with the P1-2 importance hint and a P1-4\n * security-risk negative term:\n *\n * ```\n * salience = retention × importanceFactor × securityFactor\n * ```\n *\n * Sold as **cost / staleness control, not accuracy**: it only orders\n * what gets archived first when storage is bounded — it never gates\n * recall. With neutral importance, an active fact, and first-party\n * provenance the factors are all `1`, so `salience === retention`.\n *\n * @stable\n */\nexport function salience(args: {\n  readonly now: number;\n  readonly lastAccessedAt: number | null;\n  readonly createdAt: number;\n  readonly strength: number;\n  readonly tauDays: number;\n  /** Importance hint in `[0, 1]`; `null` → {@link NEUTRAL_IMPORTANCE}. */\n  readonly importance: number | null;\n  /** P1-4: a quarantined fact gets the {@link SalienceWeights.quarantine} penalty. */\n  readonly quarantined: boolean;\n  /** P1-4: a non-first-party fact gets the {@link SalienceWeights.foreignProvenance} penalty. */\n  readonly foreignProvenance: boolean;\n  /** Defaults to {@link DEFAULT_SALIENCE_WEIGHTS}. */\n  readonly weights?: SalienceWeights;\n}): number {\n  const weights = args.weights ?? DEFAULT_SALIENCE_WEIGHTS;\n  const base = retention({\n    now: args.now,\n    lastAccessedAt: args.lastAccessedAt,\n    createdAt: args.createdAt,\n    strength: args.strength,\n    tauDays: args.tauDays,\n  });\n  const importance = clamp01(args.importance ?? NEUTRAL_IMPORTANCE);\n  const importanceFactor = Math.max(0, 1 + weights.importance * (importance - NEUTRAL_IMPORTANCE));\n  const securityFactor = args.quarantined\n    ? Math.max(0, 1 - weights.quarantine)\n    : args.foreignProvenance\n      ? Math.max(0, 1 - weights.foreignProvenance)\n      : 1;\n  return Math.max(0, base * importanceFactor * securityFactor);\n}\n\n/**\n * Capacity-bounded eviction selector (X-1). Given facts scored by\n * {@link salience}, return the ids of the lowest-salience ones to\n * archive so that at most `capacity` remain. Pure and deterministic:\n * ties break by id so a given batch always evicts the same set.\n *\n * Returns `[]` when the batch already fits (`length <= capacity`).\n * `capacity <= 0` evicts the whole batch.\n *\n * @stable\n */\nexport function selectForCapacityEviction(\n  scored: ReadonlyArray<{ readonly id: string; readonly salience: number }>,\n  capacity: number,\n): ReadonlyArray<string> {\n  const evictCount = scored.length - Math.max(0, capacity);\n  if (evictCount <= 0) return [];\n  return [...scored]\n    .sort((a, b) => a.salience - b.salience || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))\n    .slice(0, evictCount)\n    .map((row) => row.id);\n}\n\nfunction clamp01(value: number): number {\n  if (Number.isNaN(value)) return NEUTRAL_IMPORTANCE;\n  return Math.min(1, Math.max(0, value));\n}\n"],"mappings":";;;;;;;;;AAiCA,SAAgB,UAAU,MAWf;CACT,MAAM,YAAY,KAAK,kBAAkB,KAAK;CAE9C,MAAM,cADY,KAAK,IAAI,GAAG,KAAK,MAAM,UAAU,IAClB,MAAO,KAAK,KAAK;CAClD,MAAM,MAAM,KAAK,IAAI,IAAK,KAAK,UAAU,KAAK,IAAI,IAAK,KAAK,SAAS,CAAC;AACtE,QAAO,KAAK,IAAI,CAAC,cAAc,IAAI;;;;;;;;;AAkCrC,MAAa,qBAAqB;;;;;;;;;AAyClC,MAAaA,2BAA4C,OAAO,OAAO;CACrE,YAAY;CACZ,YAAY;CACZ,mBAAmB;CACpB,CAAC;;;;;;;;;;;;;;;;;;AAmBF,SAAgB,SAAS,MAcd;CACT,MAAM,UAAU,KAAK,WAAW;CAChC,MAAM,OAAO,UAAU;EACrB,KAAK,KAAK;EACV,gBAAgB,KAAK;EACrB,WAAW,KAAK;EAChB,UAAU,KAAK;EACf,SAAS,KAAK;EACf,CAAC;CACF,MAAM,aAAa,QAAQ,KAAK,cAAc,mBAAmB;CACjE,MAAM,mBAAmB,KAAK,IAAI,GAAG,IAAI,QAAQ,cAAc,aAAa,oBAAoB;CAChG,MAAM,iBAAiB,KAAK,cACxB,KAAK,IAAI,GAAG,IAAI,QAAQ,WAAW,GACnC,KAAK,oBACH,KAAK,IAAI,GAAG,IAAI,QAAQ,kBAAkB,GAC1C;AACN,QAAO,KAAK,IAAI,GAAG,OAAO,mBAAmB,eAAe;;;;;;;;;;;;;AAc9D,SAAgB,0BACd,QACA,UACuB;CACvB,MAAM,aAAa,OAAO,SAAS,KAAK,IAAI,GAAG,SAAS;AACxD,KAAI,cAAc,EAAG,QAAO,EAAE;AAC9B,QAAO,CAAC,GAAG,OAAO,CACf,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,CACnF,MAAM,GAAG,WAAW,CACpB,KAAK,QAAQ,IAAI,GAAG;;AAGzB,SAAS,QAAQ,OAAuB;AACtC,KAAI,OAAO,MAAM,MAAM,CAAE,QAAO;AAChC,QAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,MAAM,CAAC"}

package/dist/consolidator/dlq.js

@@ -0,0 +1,58 @@
+//#region src/consolidator/dlq.ts
+/**
+* Dead-letter queue helpers — pure functions used by the standard
+* + deep phases. The actual persistence lives in the storage
+* adapter's `enqueueFailedBatch / claimReadyBatches / ...` surface.
+*
+* @packageDocumentation
+*/
+/**
+* Compute the next retry delay given the failure count + retry
+* policy. Implements full-jitter exponential backoff capped by
+* `maxBackoffMs`.
+*
+* The formula is `delay = random(0, min(maxBackoffMs, baseMs * 2^retryCount))`
+* where `random` is the optional `jitter` callback (defaults to
+* `Math.random()`).
+*
+* @stable
+*/
+function nextBackoffMs(args) {
+	const cap = Math.min(args.maxMs, args.baseMs * 2 ** Math.max(0, args.retryCount));
+	const jitter = args.jitter ?? Math.random;
+	return Math.max(0, Math.floor(cap * jitter()));
+}
+/**
+* Classify a thrown error into the lowercase `error_kind` value
+* recorded against `consolidator_failed_batches`. Used by the phases
+* so the DLQ row carries a stable discriminator instead of free-form
+* prose.
+*
+* @stable
+*/
+function classifyError(err) {
+	if (err === null || err === void 0) return "unknown";
+	const message = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
+	if (message.includes("rate limit") || message.includes("429")) return "rate_limit";
+	if (message.includes("5xx") || message.includes("500") || message.includes("502")) return "5xx";
+	if (message.includes("timeout")) return "timeout";
+	if (message.includes("embedder") || message.includes("embedding")) return "embedder_failed";
+	if (message.includes("invalid") || message.includes("parse")) return "invalid_response";
+	if (message.includes("budget")) return "budget";
+	return "unknown";
+}
+/**
+* Best-effort error message extraction.
+*
+* @internal
+*/
+function describeError(err) {
+	if (err === null || err === void 0) return "unknown error";
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	return String(err);
+}
+
+//#endregion
+export { classifyError, describeError, nextBackoffMs };
+//# sourceMappingURL=dlq.js.map

package/dist/consolidator/dlq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq.js","names":[],"sources":["../../src/consolidator/dlq.ts"],"sourcesContent":["/**\n * Dead-letter queue helpers — pure functions used by the standard\n * + deep phases. The actual persistence lives in the storage\n * adapter's `enqueueFailedBatch / claimReadyBatches / ...` surface.\n *\n * @packageDocumentation\n */\n\n/**\n * Compute the next retry delay given the failure count + retry\n * policy. Implements full-jitter exponential backoff capped by\n * `maxBackoffMs`.\n *\n * The formula is `delay = random(0, min(maxBackoffMs, baseMs * 2^retryCount))`\n * where `random` is the optional `jitter` callback (defaults to\n * `Math.random()`).\n *\n * @stable\n */\nexport function nextBackoffMs(args: {\n  readonly retryCount: number;\n  readonly baseMs: number;\n  readonly maxMs: number;\n  readonly jitter?: () => number;\n}): number {\n  const cap = Math.min(args.maxMs, args.baseMs * 2 ** Math.max(0, args.retryCount));\n  const jitter = args.jitter ?? Math.random;\n  return Math.max(0, Math.floor(cap * jitter()));\n}\n\n/**\n * Classify a thrown error into the lowercase `error_kind` value\n * recorded against `consolidator_failed_batches`. Used by the phases\n * so the DLQ row carries a stable discriminator instead of free-form\n * prose.\n *\n * @stable\n */\nexport function classifyError(err: unknown): string {\n  if (err === null || err === undefined) return 'unknown';\n  const message = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();\n  if (message.includes('rate limit') || message.includes('429')) return 'rate_limit';\n  if (message.includes('5xx') || message.includes('500') || message.includes('502')) return '5xx';\n  if (message.includes('timeout')) return 'timeout';\n  if (message.includes('embedder') || message.includes('embedding')) return 'embedder_failed';\n  if (message.includes('invalid') || message.includes('parse')) return 'invalid_response';\n  if (message.includes('budget')) return 'budget';\n  return 'unknown';\n}\n\n/**\n * Best-effort error message extraction.\n *\n * @internal\n */\nexport function describeError(err: unknown): string {\n  if (err === null || err === undefined) return 'unknown error';\n  if (err instanceof Error) return err.message;\n  if (typeof err === 'string') return err;\n  return String(err);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,cAAc,MAKnB;CACT,MAAM,MAAM,KAAK,IAAI,KAAK,OAAO,KAAK,SAAS,KAAK,KAAK,IAAI,GAAG,KAAK,WAAW,CAAC;CACjF,MAAM,SAAS,KAAK,UAAU,KAAK;AACnC,QAAO,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,QAAQ,CAAC,CAAC;;;;;;;;;;AAWhD,SAAgB,cAAc,KAAsB;AAClD,KAAI,QAAQ,QAAQ,QAAQ,OAAW,QAAO;CAC9C,MAAM,UAAU,eAAe,QAAQ,IAAI,QAAQ,aAAa,GAAG,OAAO,IAAI,CAAC,aAAa;AAC5F,KAAI,QAAQ,SAAS,aAAa,IAAI,QAAQ,SAAS,MAAM,CAAE,QAAO;AACtE,KAAI,QAAQ,SAAS,MAAM,IAAI,QAAQ,SAAS,MAAM,IAAI,QAAQ,SAAS,MAAM,CAAE,QAAO;AAC1F,KAAI,QAAQ,SAAS,UAAU,CAAE,QAAO;AACxC,KAAI,QAAQ,SAAS,WAAW,IAAI,QAAQ,SAAS,YAAY,CAAE,QAAO;AAC1E,KAAI,QAAQ,SAAS,UAAU,IAAI,QAAQ,SAAS,QAAQ,CAAE,QAAO;AACrE,KAAI,QAAQ,SAAS,SAAS,CAAE,QAAO;AACvC,QAAO;;;;;;;AAQT,SAAgB,cAAc,KAAsB;AAClD,KAAI,QAAQ,QAAQ,QAAQ,OAAW,QAAO;AAC9C,KAAI,eAAe,MAAO,QAAO,IAAI;AACrC,KAAI,OAAO,QAAQ,SAAU,QAAO;AACpC,QAAO,OAAO,IAAI"}

package/dist/consolidator/errors.d.ts

@@ -0,0 +1,54 @@
+import { GraphorinMemoryError } from "../errors/index.js";
+import { ConsolidatorPhase } from "./types.js";
+
+//#region src/consolidator/errors.d.ts
+
+/**
+ * Raised when the consolidator's daily budget envelope is exhausted
+ * and `onExceed: 'throw'` is in effect.
+ *
+ * @stable
+ */
+declare class BudgetExceededError extends GraphorinMemoryError {
+  readonly name = "BudgetExceededError";
+  readonly kind: "budget-exceeded";
+  readonly phase: ConsolidatorPhase;
+  readonly budget: number;
+  readonly actual: number;
+  readonly resource: 'tokens' | 'cost';
+  constructor(args: {
+    phase: ConsolidatorPhase;
+    budget: number;
+    actual: number;
+    resource: 'tokens' | 'cost';
+  });
+}
+/**
+ * Raised when `tier: 'custom'` is selected without explicit
+ * `ceilings.maxTokensPerDay` / `ceilings.maxCostPerDay`. Custom is
+ * an explicit-only escape hatch.
+ *
+ * @stable
+ */
+declare class CustomTierMisconfiguredError extends GraphorinMemoryError {
+  readonly name = "CustomTierMisconfiguredError";
+  readonly kind: "custom-tier-misconfigured";
+  readonly missing: ReadonlyArray<string>;
+  constructor(missing: ReadonlyArray<string>);
+}
+/**
+ * Raised when the standard / deep phase attempts an LLM call without
+ * a configured provider. Surfaces as a typed failure that the DLQ
+ * pipeline can attribute correctly.
+ *
+ * @stable
+ */
+declare class ProviderNotConfiguredError extends GraphorinMemoryError {
+  readonly name = "ProviderNotConfiguredError";
+  readonly kind: "provider-not-configured";
+  readonly phase: ConsolidatorPhase;
+  constructor(phase: ConsolidatorPhase);
+}
+//#endregion
+export { BudgetExceededError, CustomTierMisconfiguredError, ProviderNotConfiguredError };
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../../src/consolidator/errors.ts"],"sourcesContent":[],"mappings":";;;;;AAiDA;;;;;AAuBA;AAGkB,cA1DL,mBAAA,SAA4B,oBAAA,CA0DvB;EAEG,SAAA,IAAA,GAAA,qBAAA;EAL2B,SAAA,IAAA,EAAA,iBAAA;EAAoB,SAAA,KAAA,EApDlD,iBAoDkD;;;;;WA9CzD;;;;;;;;;;;;;cAuBE,4BAAA,SAAqC,oBAAA;;;oBAG9B;uBAEG;;;;;;;;;cAkBV,0BAAA,SAAmC,oBAAA;;;kBAG9B;qBAEG"}

package/dist/consolidator/errors.js

@@ -0,0 +1,67 @@
+import { GraphorinMemoryError } from "../errors/index.js";
+
+//#region src/consolidator/errors.ts
+/**
+* Typed errors raised by the Phase 10c consolidator runtime. Every
+* error carries a stable lowercase `kind` discriminator so downstream
+* tooling can pattern-match without parsing the prose.
+*
+* @packageDocumentation
+*/
+/**
+* Raised when the consolidator's daily budget envelope is exhausted
+* and `onExceed: 'throw'` is in effect.
+*
+* @stable
+*/
+var BudgetExceededError = class extends GraphorinMemoryError {
+	name = "BudgetExceededError";
+	kind = "budget-exceeded";
+	phase;
+	budget;
+	actual;
+	resource;
+	constructor(args) {
+		super(`[graphorin/memory] consolidator budget exceeded — phase=${args.phase} resource=${args.resource} actual=${args.actual} budget=${args.budget}`, { hint: "Pass `onExceed: \"log\"` to keep running, or upgrade the tier ceilings." });
+		this.phase = args.phase;
+		this.budget = args.budget;
+		this.actual = args.actual;
+		this.resource = args.resource;
+	}
+};
+/**
+* Raised when `tier: 'custom'` is selected without explicit
+* `ceilings.maxTokensPerDay` / `ceilings.maxCostPerDay`. Custom is
+* an explicit-only escape hatch.
+*
+* @stable
+*/
+var CustomTierMisconfiguredError = class extends GraphorinMemoryError {
+	name = "CustomTierMisconfiguredError";
+	kind = "custom-tier-misconfigured";
+	missing;
+	constructor(missing) {
+		super(`[graphorin/memory] tier='custom' requires explicit ceilings — missing: ${missing.join(", ")}`, { hint: "Set `ceilings.maxTokensPerDay` + `ceilings.maxCostPerDay` (and `cheapModel` / `deepModel` if those phases are enabled)." });
+		this.missing = Object.freeze([...missing]);
+	}
+};
+/**
+* Raised when the standard / deep phase attempts an LLM call without
+* a configured provider. Surfaces as a typed failure that the DLQ
+* pipeline can attribute correctly.
+*
+* @stable
+*/
+var ProviderNotConfiguredError = class extends GraphorinMemoryError {
+	name = "ProviderNotConfiguredError";
+	kind = "provider-not-configured";
+	phase;
+	constructor(phase) {
+		super(`[graphorin/memory] consolidator phase '${phase}' requires a provider but none was supplied.`, { hint: "Pass `provider` to createConsolidator({...}) or pin tier=\"free\" to skip LLM phases." });
+		this.phase = phase;
+	}
+};
+
+//#endregion
+export { BudgetExceededError, CustomTierMisconfiguredError, ProviderNotConfiguredError };
+//# sourceMappingURL=errors.js.map

package/dist/consolidator/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../src/consolidator/errors.ts"],"sourcesContent":["/**\n * Typed errors raised by the Phase 10c consolidator runtime. Every\n * error carries a stable lowercase `kind` discriminator so downstream\n * tooling can pattern-match without parsing the prose.\n *\n * @packageDocumentation\n */\n\nimport { GraphorinMemoryError } from '../errors/index.js';\nimport type { ConsolidatorPhase } from './types.js';\n\n/**\n * Raised when the consolidator's daily budget envelope is exhausted\n * and `onExceed: 'throw'` is in effect.\n *\n * @stable\n */\nexport class BudgetExceededError extends GraphorinMemoryError {\n  override readonly name = 'BudgetExceededError';\n  readonly kind = 'budget-exceeded' as const;\n  readonly phase: ConsolidatorPhase;\n  readonly budget: number;\n  readonly actual: number;\n  readonly resource: 'tokens' | 'cost';\n\n  constructor(args: {\n    phase: ConsolidatorPhase;\n    budget: number;\n    actual: number;\n    resource: 'tokens' | 'cost';\n  }) {\n    super(\n      `[graphorin/memory] consolidator budget exceeded — phase=${args.phase} resource=${args.resource} actual=${args.actual} budget=${args.budget}`,\n      { hint: 'Pass `onExceed: \"log\"` to keep running, or upgrade the tier ceilings.' },\n    );\n    this.phase = args.phase;\n    this.budget = args.budget;\n    this.actual = args.actual;\n    this.resource = args.resource;\n  }\n}\n\n/**\n * Raised when `tier: 'custom'` is selected without explicit\n * `ceilings.maxTokensPerDay` / `ceilings.maxCostPerDay`. Custom is\n * an explicit-only escape hatch.\n *\n * @stable\n */\nexport class CustomTierMisconfiguredError extends GraphorinMemoryError {\n  override readonly name = 'CustomTierMisconfiguredError';\n  readonly kind = 'custom-tier-misconfigured' as const;\n  readonly missing: ReadonlyArray<string>;\n\n  constructor(missing: ReadonlyArray<string>) {\n    super(\n      `[graphorin/memory] tier='custom' requires explicit ceilings — missing: ${missing.join(', ')}`,\n      {\n        hint: 'Set `ceilings.maxTokensPerDay` + `ceilings.maxCostPerDay` (and `cheapModel` / `deepModel` if those phases are enabled).',\n      },\n    );\n    this.missing = Object.freeze([...missing]);\n  }\n}\n\n/**\n * Raised when the standard / deep phase attempts an LLM call without\n * a configured provider. Surfaces as a typed failure that the DLQ\n * pipeline can attribute correctly.\n *\n * @stable\n */\nexport class ProviderNotConfiguredError extends GraphorinMemoryError {\n  override readonly name = 'ProviderNotConfiguredError';\n  readonly kind = 'provider-not-configured' as const;\n  readonly phase: ConsolidatorPhase;\n\n  constructor(phase: ConsolidatorPhase) {\n    super(\n      `[graphorin/memory] consolidator phase '${phase}' requires a provider but none was supplied.`,\n      {\n        hint: 'Pass `provider` to createConsolidator({...}) or pin tier=\"free\" to skip LLM phases.',\n      },\n    );\n    this.phase = phase;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,IAAa,sBAAb,cAAyC,qBAAqB;CAC5D,AAAkB,OAAO;CACzB,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CAET,YAAY,MAKT;AACD,QACE,2DAA2D,KAAK,MAAM,YAAY,KAAK,SAAS,UAAU,KAAK,OAAO,UAAU,KAAK,UACrI,EAAE,MAAM,2EAAyE,CAClF;AACD,OAAK,QAAQ,KAAK;AAClB,OAAK,SAAS,KAAK;AACnB,OAAK,SAAS,KAAK;AACnB,OAAK,WAAW,KAAK;;;;;;;;;;AAWzB,IAAa,+BAAb,cAAkD,qBAAqB;CACrE,AAAkB,OAAO;CACzB,AAAS,OAAO;CAChB,AAAS;CAET,YAAY,SAAgC;AAC1C,QACE,0EAA0E,QAAQ,KAAK,KAAK,IAC5F,EACE,MAAM,2HACP,CACF;AACD,OAAK,UAAU,OAAO,OAAO,CAAC,GAAG,QAAQ,CAAC;;;;;;;;;;AAW9C,IAAa,6BAAb,cAAgD,qBAAqB;CACnE,AAAkB,OAAO;CACzB,AAAS,OAAO;CAChB,AAAS;CAET,YAAY,OAA0B;AACpC,QACE,0CAA0C,MAAM,+CAChD,EACE,MAAM,yFACP,CACF;AACD,OAAK,QAAQ"}

package/dist/consolidator/idempotency.d.ts

@@ -0,0 +1 @@
+import "../internal/storage-adapter.js";

package/dist/consolidator/idempotency.js

@@ -0,0 +1,22 @@
+//#region src/consolidator/idempotency.ts
+/**
+* Advance the cursor to the highest sequence number observed in the
+* batch. Returns `null` when the batch is empty.
+*
+* @stable
+*/
+function tipMessageId(batch) {
+	if (batch.length === 0) return null;
+	let bestIdx = 0;
+	for (let i = 1; i < batch.length; i++) {
+		const candidate = batch[i];
+		const champion = batch[bestIdx];
+		if (candidate === void 0 || champion === void 0) continue;
+		if (candidate.sequence > champion.sequence) bestIdx = i;
+	}
+	return batch[bestIdx]?.id ?? null;
+}
+
+//#endregion
+export { tipMessageId };
+//# sourceMappingURL=idempotency.js.map

package/dist/consolidator/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","names":[],"sources":["../../src/consolidator/idempotency.ts"],"sourcesContent":["/**\n * Idempotency cursor helpers. The runtime reads the persisted state\n * row directly via {@link ConsolidatorMemoryStoreExt.getState}; this\n * file centralises the pure helpers around the cursor advance.\n *\n * @packageDocumentation\n */\n\nimport type { SessionMessageRecord } from '../internal/storage-adapter.js';\n\n/**\n * Advance the cursor to the highest sequence number observed in the\n * batch. Returns `null` when the batch is empty.\n *\n * @stable\n */\nexport function tipMessageId(batch: ReadonlyArray<SessionMessageRecord>): string | null {\n  if (batch.length === 0) return null;\n  let bestIdx = 0;\n  for (let i = 1; i < batch.length; i++) {\n    const candidate = batch[i];\n    const champion = batch[bestIdx];\n    if (candidate === undefined || champion === undefined) continue;\n    if (candidate.sequence > champion.sequence) bestIdx = i;\n  }\n  return batch[bestIdx]?.id ?? null;\n}\n"],"mappings":";;;;;;;AAgBA,SAAgB,aAAa,OAA2D;AACtF,KAAI,MAAM,WAAW,EAAG,QAAO;CAC/B,IAAI,UAAU;AACd,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,YAAY,MAAM;EACxB,MAAM,WAAW,MAAM;AACvB,MAAI,cAAc,UAAa,aAAa,OAAW;AACvD,MAAI,UAAU,WAAW,SAAS,SAAU,WAAU;;AAExD,QAAO,MAAM,UAAU,MAAM"}

package/dist/consolidator/index.d.ts

@@ -0,0 +1,34 @@
+import { SalienceWeights } from "./decay.js";
+import { CONSOLIDATOR_TIER_DEFAULTS, ConsolidatorBudgetSnapshot, ConsolidatorCeilings, ConsolidatorConfig, ConsolidatorLastRuns, ConsolidatorPhase, ConsolidatorStatus, ConsolidatorTier, ConsolidatorTriggerReason, ConsolidatorTriggerSpec, CreateConsolidatorOptions, OnBudgetExceed, PhaseListener, PhaseOutcome } from "./types.js";
+import { ParsedTrigger, parseTriggerSpec, reasonFromTrigger } from "./triggers.js";
+import { ConsolidatorCatchupPolicy, RegisterTriggersOptions, RegisterTriggersResult, SchedulerLike, TriggerDeclarationLike, registerConsolidatorTriggers } from "./scheduler.js";
+import { Consolidator, createConsolidator } from "./runtime.js";
+import "./budget.js";
+import { BudgetExceededError, CustomTierMisconfiguredError, ProviderNotConfiguredError } from "./errors.js";
+import "./idempotency.js";
+import "./lock.js";
+import "./noise-filter.js";
+import "./phases/deep.js";
+import { DEFAULT_INDUCTION_MAX_TOKENS, INDUCTION_SYSTEM_PROMPT, InducedProcedure, MAX_PROCEDURE_STEPS, MAX_TRAJECTORY_STEPS_SHOWN, Trajectory, TrajectoryStep, VerificationResult, WorkflowInducer, WorkflowInductionOptions, buildInductionRequest, checkSuccessCriteria, createProviderWorkflowInducer, normalizeInducedProcedure, parseInducedProcedure, runWorkflowInduction, trajectoryFromRunState } from "./phases/induce.js";
+import "./phases/light.js";
+import "./phases/standard.js";
+
+//#region src/consolidator/index.d.ts
+
+/**
+ * Build a no-op consolidator that honours the full {@link Consolidator}
+ * interface but performs no background work. Useful for consumers
+ * that want the typed shape (e.g., unit tests of higher tiers) but
+ * do not pay the runtime cost of triggers / locking / DLQ.
+ *
+ * Phase 10c's {@link createConsolidator} is the production factory.
+ *
+ * @stable
+ */
+declare function createConsolidatorPlaceholder(options?: {
+  readonly triggers?: ReadonlyArray<ConsolidatorTriggerSpec>;
+  readonly tier?: ConsolidatorTier;
+}): Consolidator;
+//#endregion
+export { createConsolidatorPlaceholder };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/consolidator/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8IgB,6BAAA;sBAEQ,cAAc;kBAClB;IAEjB"}

package/dist/consolidator/index.js

@@ -0,0 +1,163 @@
+import { DEFAULT_SALIENCE_WEIGHTS, NEUTRAL_IMPORTANCE, retention, salience, selectForCapacityEviction } from "./decay.js";
+import { BudgetExceededError, CustomTierMisconfiguredError, ProviderNotConfiguredError } from "./errors.js";
+import { BudgetTracker, bucketStart, nextBucketStart } from "./budget.js";
+import { classifyError, describeError, nextBackoffMs } from "./dlq.js";
+import { tipMessageId } from "./idempotency.js";
+import { LockManager } from "./lock.js";
+import { applyNoiseFilters } from "./noise-filter.js";
+import { runDeepPhase } from "./phases/deep.js";
+import { DEFAULT_INDUCTION_MAX_TOKENS, INDUCTION_SYSTEM_PROMPT, MAX_PROCEDURE_STEPS, MAX_TRAJECTORY_STEPS_SHOWN, buildInductionRequest, checkSuccessCriteria, createProviderWorkflowInducer, normalizeInducedProcedure, parseInducedProcedure, runWorkflowInduction, trajectoryFromRunState } from "./phases/induce.js";
+import { runLightPhase } from "./phases/light.js";
+import { parseExtraction, runStandardPhase } from "./phases/standard.js";
+import { parseTriggerSpec, reasonFromTrigger } from "./triggers.js";
+import { registerConsolidatorTriggers } from "./scheduler.js";
+import { CONSOLIDATOR_TIER_DEFAULTS } from "./types.js";
+import { createConsolidator } from "./runtime.js";
+
+//#region src/consolidator/index.ts
+/**
+* `@graphorin/memory/consolidator` — Phase 10c runtime that turns
+* raw conversation turns into long-lived facts and episodes. The
+* module ships:
+*
+* - {@link createConsolidator} — the production factory that wires
+*   triggers, the budget envelope, the wait-then-defer lock, the
+*   idempotent cursor, the DLQ, and the three phases (light /
+*   standard / deep) into a single `Consolidator` handle.
+* - {@link createConsolidatorPlaceholder} — kept for back-compat
+*   with consumers that wired the no-op stub during Phase 10a; it
+*   honours the same shape but does no background work.
+* - Pure helpers (`noise-filter`, `decay`, `budget`, `lock`, `dlq`,
+*   `idempotency`, `triggers`) and the per-phase orchestrators —
+*   exported so tests + the standalone server (Phase 14) can compose
+*   them without re-implementing the algorithm.
+*
+* The `Consolidator` interface is **stable** — Phase 14 wires the
+* runtime into the lifecycle hooks, and Phase 15 surfaces every
+* method through `graphorin consolidator …` CLI commands.
+*
+* @packageDocumentation
+*/
+/**
+* Build a no-op consolidator that honours the full {@link Consolidator}
+* interface but performs no background work. Useful for consumers
+* that want the typed shape (e.g., unit tests of higher tiers) but
+* do not pay the runtime cost of triggers / locking / DLQ.
+*
+* Phase 10c's {@link createConsolidator} is the production factory.
+*
+* @stable
+*/
+function createConsolidatorPlaceholder(options = {}) {
+	let running = false;
+	let paused = false;
+	let tier = options.tier ?? "free";
+	const triggers = Object.freeze([...options.triggers ?? ["idle:5m", "cron:0 4 * * *"]]);
+	const listeners = /* @__PURE__ */ new Set();
+	const config = Object.freeze({
+		triggers,
+		tier,
+		phases: Object.freeze(["light"]),
+		ceilings: {
+			maxTokensPerDay: 0,
+			maxCostPerDay: 0,
+			maxConcurrentRuns: 1,
+			maxRunDurationMs: 300 * 1e3,
+			cooldownMs: 6e4
+		},
+		onExceed: "pause",
+		cheapModel: null,
+		deepModel: null,
+		budgetResetSemantics: "utc",
+		noiseFilters: Object.freeze(["default"]),
+		lockWaitMs: 3e4,
+		decayTauDays: 7,
+		decayArchiveThreshold: .05,
+		decayCapacity: null,
+		salienceWeights: DEFAULT_SALIENCE_WEIGHTS,
+		maxStandardBatchSize: 50,
+		maxDeepConflictsPerRun: 20,
+		dlqMaxRetries: 5,
+		dlqBaseBackoffMs: 6e4,
+		dlqMaxBackoffMs: 3600 * 1e3,
+		formEpisodes: false,
+		importanceScoring: false,
+		autoPromoteExtraction: false,
+		reflection: false,
+		importanceThreshold: 3,
+		reflectionMaxQuestions: 3,
+		contextualRetrieval: "late-chunk"
+	});
+	const status = async () => Object.freeze({
+		tier,
+		triggers,
+		phases: config.phases,
+		running,
+		paused,
+		pendingConflicts: 0,
+		queueDepth: 0,
+		dlqSize: 0,
+		deferredRuns: 0,
+		emptyExtractions: 0,
+		lastRuns: Object.freeze({}),
+		budget: {
+			tokensUsedToday: 0,
+			costUsedToday: 0,
+			tokensRemaining: 0,
+			costRemaining: 0,
+			resetAt: new Date(Date.now() + 864e5).toISOString()
+		},
+		budgetRemaining: {
+			tokens: 0,
+			costUsd: 0
+		}
+	});
+	return {
+		async start() {
+			running = true;
+		},
+		async stop() {
+			running = false;
+		},
+		async trigger() {
+			return null;
+		},
+		async fireNow() {
+			return null;
+		},
+		async setTier(next) {
+			tier = next;
+		},
+		async pause() {
+			paused = true;
+		},
+		async resume() {
+			paused = false;
+		},
+		recordExternalSpend() {},
+		onPhaseFinished(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		config() {
+			return config;
+		},
+		async registerWithScheduler() {
+			return Object.freeze({
+				registered: Object.freeze([]),
+				skipped: Object.freeze([])
+			});
+		},
+		isFree() {
+			return tier === "free";
+		},
+		async drainDlq() {
+			return 0;
+		},
+		status
+	};
+}
+
+//#endregion
+export { createConsolidatorPlaceholder };
+//# sourceMappingURL=index.js.map

package/dist/consolidator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["tier: ConsolidatorTier","config: ConsolidatorConfig"],"sources":["../../src/consolidator/index.ts"],"sourcesContent":["/**\n * `@graphorin/memory/consolidator` — Phase 10c runtime that turns\n * raw conversation turns into long-lived facts and episodes. The\n * module ships:\n *\n * - {@link createConsolidator} — the production factory that wires\n *   triggers, the budget envelope, the wait-then-defer lock, the\n *   idempotent cursor, the DLQ, and the three phases (light /\n *   standard / deep) into a single `Consolidator` handle.\n * - {@link createConsolidatorPlaceholder} — kept for back-compat\n *   with consumers that wired the no-op stub during Phase 10a; it\n *   honours the same shape but does no background work.\n * - Pure helpers (`noise-filter`, `decay`, `budget`, `lock`, `dlq`,\n *   `idempotency`, `triggers`) and the per-phase orchestrators —\n *   exported so tests + the standalone server (Phase 14) can compose\n *   them without re-implementing the algorithm.\n *\n * The `Consolidator` interface is **stable** — Phase 14 wires the\n * runtime into the lifecycle hooks, and Phase 15 surfaces every\n * method through `graphorin consolidator …` CLI commands.\n *\n * @packageDocumentation\n */\n\nimport { DEFAULT_SALIENCE_WEIGHTS } from './decay.js';\nimport type { Consolidator } from './runtime.js';\nimport type {\n  ConsolidatorConfig,\n  ConsolidatorPhase,\n  ConsolidatorStatus,\n  ConsolidatorTier,\n  ConsolidatorTriggerSpec,\n  PhaseListener,\n  PhaseOutcome,\n} from './types.js';\n\nexport {\n  type BudgetCheck,\n  type BudgetSnapshot,\n  BudgetTracker,\n  type BudgetTrackerOptions,\n  bucketStart,\n  nextBucketStart,\n} from './budget.js';\nexport {\n  DEFAULT_DECAY_ARCHIVE_THRESHOLD,\n  DEFAULT_DECAY_TAU_DAYS,\n  DEFAULT_SALIENCE_WEIGHTS,\n  NEUTRAL_IMPORTANCE,\n  retention,\n  type SalienceWeights,\n  salience,\n  selectForCapacityEviction,\n  shouldArchive,\n} from './decay.js';\nexport {\n  classifyError,\n  describeError,\n  nextBackoffMs,\n} from './dlq.js';\nexport {\n  BudgetExceededError,\n  CustomTierMisconfiguredError,\n  ProviderNotConfiguredError,\n} from './errors.js';\nexport { tipMessageId } from './idempotency.js';\nexport { LockManager, type LockManagerOptions, type LockOutcome } from './lock.js';\nexport {\n  applyNoiseFilters,\n  type NoiseFilterPreset,\n  type NoiseFilterResult,\n} from './noise-filter.js';\nexport { type DeepPhaseDeps, runDeepPhase } from './phases/deep.js';\nexport {\n  buildInductionRequest,\n  checkSuccessCriteria,\n  createProviderWorkflowInducer,\n  DEFAULT_INDUCTION_MAX_TOKENS,\n  INDUCTION_SYSTEM_PROMPT,\n  type InducedProcedure,\n  MAX_PROCEDURE_STEPS,\n  MAX_TRAJECTORY_STEPS_SHOWN,\n  normalizeInducedProcedure,\n  parseInducedProcedure,\n  runWorkflowInduction,\n  type Trajectory,\n  type TrajectoryStep,\n  trajectoryFromRunState,\n  type VerificationResult,\n  type WorkflowInducer,\n  type WorkflowInductionOptions,\n} from './phases/induce.js';\nexport {\n  type LightPhaseDeps,\n  runLightPhase,\n} from './phases/light.js';\nexport {\n  parseExtraction,\n  runStandardPhase,\n  type StandardPhaseDeps,\n} from './phases/standard.js';\nexport { type Consolidator, createConsolidator } from './runtime.js';\nexport {\n  type ConsolidatorCatchupPolicy,\n  type RegisterTriggersOptions,\n  type RegisterTriggersResult,\n  registerConsolidatorTriggers,\n  type SchedulerLike,\n  type TriggerDeclarationLike,\n} from './scheduler.js';\nexport {\n  type ParsedTrigger,\n  parseTriggerSpec,\n  reasonFromTrigger,\n} from './triggers.js';\nexport type {\n  ConsolidatorBudgetSnapshot,\n  ConsolidatorCeilings,\n  ConsolidatorConfig,\n  ConsolidatorLastRuns,\n  ConsolidatorPhase,\n  ConsolidatorStatus,\n  ConsolidatorTier,\n  ConsolidatorTriggerReason,\n  ConsolidatorTriggerSpec,\n  CreateConsolidatorOptions,\n  OnBudgetExceed,\n  PhaseListener,\n  PhaseOutcome,\n} from './types.js';\nexport { CONSOLIDATOR_TIER_DEFAULTS } from './types.js';\n\n/**\n * Build a no-op consolidator that honours the full {@link Consolidator}\n * interface but performs no background work. Useful for consumers\n * that want the typed shape (e.g., unit tests of higher tiers) but\n * do not pay the runtime cost of triggers / locking / DLQ.\n *\n * Phase 10c's {@link createConsolidator} is the production factory.\n *\n * @stable\n */\nexport function createConsolidatorPlaceholder(\n  options: {\n    readonly triggers?: ReadonlyArray<ConsolidatorTriggerSpec>;\n    readonly tier?: ConsolidatorTier;\n  } = {},\n): Consolidator {\n  let running = false;\n  let paused = false;\n  let tier: ConsolidatorTier = options.tier ?? 'free';\n  const triggers = Object.freeze([\n    // Matches the real runtime default (MCON-4): idle drives light/standard,\n    // the daily cron makes the deep phase reachable; turn:N is consumer-emitted\n    // so it is not a scheduler default.\n    ...(options.triggers ?? (['idle:5m', 'cron:0 4 * * *'] as ConsolidatorTriggerSpec[])),\n  ]) as ReadonlyArray<ConsolidatorTriggerSpec>;\n  const listeners = new Set<PhaseListener>();\n\n  const config: ConsolidatorConfig = Object.freeze({\n    triggers,\n    tier,\n    phases: Object.freeze(['light' as ConsolidatorPhase]),\n    ceilings: {\n      maxTokensPerDay: 0,\n      maxCostPerDay: 0,\n      maxConcurrentRuns: 1,\n      maxRunDurationMs: 5 * 60 * 1000,\n      cooldownMs: 60_000,\n    },\n    onExceed: 'pause',\n    cheapModel: null,\n    deepModel: null,\n    budgetResetSemantics: 'utc',\n    noiseFilters: Object.freeze(['default' as const]),\n    lockWaitMs: 30_000,\n    decayTauDays: 7,\n    decayArchiveThreshold: 0.05,\n    decayCapacity: null,\n    salienceWeights: DEFAULT_SALIENCE_WEIGHTS,\n    maxStandardBatchSize: 50,\n    maxDeepConflictsPerRun: 20,\n    dlqMaxRetries: 5,\n    dlqBaseBackoffMs: 60_000,\n    dlqMaxBackoffMs: 60 * 60 * 1000,\n    formEpisodes: false,\n    importanceScoring: false,\n    autoPromoteExtraction: false,\n    reflection: false,\n    importanceThreshold: 3,\n    reflectionMaxQuestions: 3,\n    contextualRetrieval: 'late-chunk',\n  });\n\n  const status = async (): Promise<ConsolidatorStatus> =>\n    Object.freeze({\n      tier,\n      triggers,\n      phases: config.phases,\n      running,\n      paused,\n      pendingConflicts: 0,\n      queueDepth: 0,\n      dlqSize: 0,\n      deferredRuns: 0,\n      emptyExtractions: 0,\n      lastRuns: Object.freeze({}),\n      budget: {\n        tokensUsedToday: 0,\n        costUsedToday: 0,\n        tokensRemaining: 0,\n        costRemaining: 0,\n        resetAt: new Date(Date.now() + 86_400_000).toISOString(),\n      },\n      budgetRemaining: {\n        tokens: 0,\n        costUsd: 0,\n      },\n    });\n\n  return {\n    async start() {\n      running = true;\n    },\n    async stop() {\n      running = false;\n    },\n    async trigger() {\n      return null;\n    },\n    async fireNow(): Promise<PhaseOutcome | null> {\n      return null;\n    },\n    async setTier(next: ConsolidatorTier) {\n      tier = next;\n    },\n    async pause() {\n      paused = true;\n    },\n    async resume() {\n      paused = false;\n    },\n    recordExternalSpend(): void {\n      // Placeholder — no budget to record against.\n    },\n    onPhaseFinished(listener) {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    config() {\n      return config;\n    },\n    async registerWithScheduler() {\n      // No-op consolidator: nothing to schedule.\n      return Object.freeze({ registered: Object.freeze([]), skipped: Object.freeze([]) });\n    },\n    isFree() {\n      return tier === 'free';\n    },\n    async drainDlq() {\n      return 0;\n    },\n    status,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8IA,SAAgB,8BACd,UAGI,EAAE,EACQ;CACd,IAAI,UAAU;CACd,IAAI,SAAS;CACb,IAAIA,OAAyB,QAAQ,QAAQ;CAC7C,MAAM,WAAW,OAAO,OAAO,CAI7B,GAAI,QAAQ,YAAa,CAAC,WAAW,iBAAiB,CACvD,CAAC;CACF,MAAM,4BAAY,IAAI,KAAoB;CAE1C,MAAMC,SAA6B,OAAO,OAAO;EAC/C;EACA;EACA,QAAQ,OAAO,OAAO,CAAC,QAA6B,CAAC;EACrD,UAAU;GACR,iBAAiB;GACjB,eAAe;GACf,mBAAmB;GACnB,kBAAkB,MAAS;GAC3B,YAAY;GACb;EACD,UAAU;EACV,YAAY;EACZ,WAAW;EACX,sBAAsB;EACtB,cAAc,OAAO,OAAO,CAAC,UAAmB,CAAC;EACjD,YAAY;EACZ,cAAc;EACd,uBAAuB;EACvB,eAAe;EACf,iBAAiB;EACjB,sBAAsB;EACtB,wBAAwB;EACxB,eAAe;EACf,kBAAkB;EAClB,iBAAiB,OAAU;EAC3B,cAAc;EACd,mBAAmB;EACnB,uBAAuB;EACvB,YAAY;EACZ,qBAAqB;EACrB,wBAAwB;EACxB,qBAAqB;EACtB,CAAC;CAEF,MAAM,SAAS,YACb,OAAO,OAAO;EACZ;EACA;EACA,QAAQ,OAAO;EACf;EACA;EACA,kBAAkB;EAClB,YAAY;EACZ,SAAS;EACT,cAAc;EACd,kBAAkB;EAClB,UAAU,OAAO,OAAO,EAAE,CAAC;EAC3B,QAAQ;GACN,iBAAiB;GACjB,eAAe;GACf,iBAAiB;GACjB,eAAe;GACf,SAAS,IAAI,KAAK,KAAK,KAAK,GAAG,MAAW,CAAC,aAAa;GACzD;EACD,iBAAiB;GACf,QAAQ;GACR,SAAS;GACV;EACF,CAAC;AAEJ,QAAO;EACL,MAAM,QAAQ;AACZ,aAAU;;EAEZ,MAAM,OAAO;AACX,aAAU;;EAEZ,MAAM,UAAU;AACd,UAAO;;EAET,MAAM,UAAwC;AAC5C,UAAO;;EAET,MAAM,QAAQ,MAAwB;AACpC,UAAO;;EAET,MAAM,QAAQ;AACZ,YAAS;;EAEX,MAAM,SAAS;AACb,YAAS;;EAEX,sBAA4B;EAG5B,gBAAgB,UAAU;AACxB,aAAU,IAAI,SAAS;AACvB,gBAAa,UAAU,OAAO,SAAS;;EAEzC,SAAS;AACP,UAAO;;EAET,MAAM,wBAAwB;AAE5B,UAAO,OAAO,OAAO;IAAE,YAAY,OAAO,OAAO,EAAE,CAAC;IAAE,SAAS,OAAO,OAAO,EAAE,CAAC;IAAE,CAAC;;EAErF,SAAS;AACP,UAAO,SAAS;;EAElB,MAAM,WAAW;AACf,UAAO;;EAET;EACD"}

package/dist/consolidator/lock.d.ts

@@ -0,0 +1,2 @@
+import "../internal/storage-adapter.js";
+import { SessionScope } from "@graphorin/core";

package/dist/consolidator/lock.js

@@ -0,0 +1,89 @@
+//#region src/consolidator/lock.ts
+const DEFAULT_POLL_MS = 100;
+/** @stable */
+var LockManager = class {
+	#store;
+	#waitMs;
+	#maxAge;
+	#now;
+	#sleep;
+	#randomId;
+	#localLocks = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.#store = opts.store;
+		this.#waitMs = Math.max(0, opts.waitMs);
+		this.#maxAge = Math.max(0, opts.maxRunDurationMs);
+		this.#now = opts.now ?? Date.now;
+		this.#sleep = opts.sleep ?? ((ms) => new Promise((resolve) => globalThis.setTimeout(resolve, ms)));
+		this.#randomId = opts.randomId ?? (() => {
+			return `run_${Math.floor(Math.random() * 1e9).toString(36)}${Math.floor(Math.random() * 1e9).toString(36)}`;
+		});
+	}
+	/**
+	* Try to acquire the per-scope lock. Returns the run id on success
+	* or `'deferred'` after the wait window elapses.
+	*
+	* @stable
+	*/
+	async acquire(scope) {
+		const runId = this.#randomId();
+		const start = this.#now();
+		const pollMs = Math.min(DEFAULT_POLL_MS, Math.max(10, this.#waitMs / 5 || DEFAULT_POLL_MS));
+		while (true) {
+			if (await this.#tryAcquire(scope, runId)) return {
+				kind: "acquired",
+				runId
+			};
+			if (this.#now() - start >= this.#waitMs) return {
+				kind: "deferred",
+				heldBy: await this.#heldBy(scope)
+			};
+			await this.#sleep(pollMs);
+		}
+	}
+	/**
+	* Release the lock. Idempotent — releasing an already-released
+	* lock is a no-op.
+	*
+	* @stable
+	*/
+	async release(scope, runId) {
+		if (this.#store !== null) await this.#store.releaseLock(scope, runId);
+		const key = scopeKey(scope);
+		const local = this.#localLocks.get(key);
+		if (local !== void 0 && local.runId === runId) this.#localLocks.delete(key);
+	}
+	async #tryAcquire(scope, runId) {
+		const now = this.#now();
+		if (this.#store !== null) return this.#store.acquireLock(scope, runId, now, this.#maxAge);
+		const key = scopeKey(scope);
+		const existing = this.#localLocks.get(key);
+		if (existing === void 0) {
+			this.#localLocks.set(key, {
+				runId,
+				acquiredAt: now
+			});
+			return true;
+		}
+		if (existing.runId === runId) return true;
+		if (this.#maxAge > 0 && now - existing.acquiredAt > this.#maxAge) {
+			this.#localLocks.set(key, {
+				runId,
+				acquiredAt: now
+			});
+			return true;
+		}
+		return false;
+	}
+	async #heldBy(scope) {
+		if (this.#store !== null) return (await this.#store.getState(scope))?.activeLockHeldBy ?? null;
+		return this.#localLocks.get(scopeKey(scope))?.runId ?? null;
+	}
+};
+function scopeKey(scope) {
+	return `${scope.userId}|${scope.sessionId ?? ""}|${scope.agentId ?? ""}`;
+}
+
+//#endregion
+export { LockManager };
+//# sourceMappingURL=lock.js.map

package/dist/consolidator/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","names":["#store","#waitMs","#maxAge","#now","#sleep","#randomId","#localLocks","#tryAcquire","#heldBy"],"sources":["../../src/consolidator/lock.ts"],"sourcesContent":["/**\n * Wait-then-defer lock manager. The lock state lives in the storage\n * layer's `consolidator_state` row so concurrent processes (lib +\n * server) coordinate through SQLite. The manager waits up to\n * `lockWaitMs` for the lock to clear; if the wait expires it returns\n * `'deferred'` so the trigger is recorded but no phase runs.\n *\n * The lock honours DEC-114 (\"memory does not block the agent loop\")\n * by capping the wait — the agent loop never observes a memory\n * blocker.\n *\n * @packageDocumentation\n */\n\nimport type { SessionScope } from '@graphorin/core';\nimport type { ConsolidatorMemoryStoreExt } from '../internal/storage-adapter.js';\n\n/** Outcome surfaced by {@link LockManager.acquire}. */\nexport type LockOutcome =\n  | { readonly kind: 'acquired'; readonly runId: string }\n  | { readonly kind: 'deferred'; readonly heldBy: string | null };\n\n/** Options accepted by {@link LockManager}. */\nexport interface LockManagerOptions {\n  readonly store: ConsolidatorMemoryStoreExt | null;\n  readonly waitMs: number;\n  readonly maxRunDurationMs: number;\n  readonly now?: () => number;\n  readonly sleep?: (ms: number) => Promise<void>;\n  readonly randomId?: () => string;\n}\n\nconst DEFAULT_POLL_MS = 100;\n\n/** @stable */\nexport class LockManager {\n  readonly #store: ConsolidatorMemoryStoreExt | null;\n  readonly #waitMs: number;\n  readonly #maxAge: number;\n  readonly #now: () => number;\n  readonly #sleep: (ms: number) => Promise<void>;\n  readonly #randomId: () => string;\n  // Per-process fallback when the storage adapter does not expose a\n  // consolidator surface (lib mode + in-memory test doubles).\n  readonly #localLocks = new Map<string, { runId: string; acquiredAt: number }>();\n\n  constructor(opts: LockManagerOptions) {\n    this.#store = opts.store;\n    this.#waitMs = Math.max(0, opts.waitMs);\n    this.#maxAge = Math.max(0, opts.maxRunDurationMs);\n    this.#now = opts.now ?? Date.now;\n    this.#sleep =\n      opts.sleep ??\n      ((ms): Promise<void> => new Promise((resolve) => globalThis.setTimeout(resolve, ms)));\n    this.#randomId =\n      opts.randomId ??\n      ((): string => {\n        const a = Math.floor(Math.random() * 1e9).toString(36);\n        const b = Math.floor(Math.random() * 1e9).toString(36);\n        return `run_${a}${b}`;\n      });\n  }\n\n  /**\n   * Try to acquire the per-scope lock. Returns the run id on success\n   * or `'deferred'` after the wait window elapses.\n   *\n   * @stable\n   */\n  async acquire(scope: SessionScope): Promise<LockOutcome> {\n    const runId = this.#randomId();\n    const start = this.#now();\n    const pollMs = Math.min(DEFAULT_POLL_MS, Math.max(10, this.#waitMs / 5 || DEFAULT_POLL_MS));\n    while (true) {\n      const ok = await this.#tryAcquire(scope, runId);\n      if (ok) return { kind: 'acquired', runId };\n      const elapsed = this.#now() - start;\n      if (elapsed >= this.#waitMs) {\n        const heldBy = await this.#heldBy(scope);\n        return { kind: 'deferred', heldBy };\n      }\n      await this.#sleep(pollMs);\n    }\n  }\n\n  /**\n   * Release the lock. Idempotent — releasing an already-released\n   * lock is a no-op.\n   *\n   * @stable\n   */\n  async release(scope: SessionScope, runId: string): Promise<void> {\n    if (this.#store !== null) {\n      await this.#store.releaseLock(scope, runId);\n    }\n    const key = scopeKey(scope);\n    const local = this.#localLocks.get(key);\n    if (local !== undefined && local.runId === runId) {\n      this.#localLocks.delete(key);\n    }\n  }\n\n  async #tryAcquire(scope: SessionScope, runId: string): Promise<boolean> {\n    const now = this.#now();\n    if (this.#store !== null) {\n      return this.#store.acquireLock(scope, runId, now, this.#maxAge);\n    }\n    // Fall back to per-process map.\n    const key = scopeKey(scope);\n    const existing = this.#localLocks.get(key);\n    if (existing === undefined) {\n      this.#localLocks.set(key, { runId, acquiredAt: now });\n      return true;\n    }\n    if (existing.runId === runId) return true;\n    if (this.#maxAge > 0 && now - existing.acquiredAt > this.#maxAge) {\n      this.#localLocks.set(key, { runId, acquiredAt: now });\n      return true;\n    }\n    return false;\n  }\n\n  async #heldBy(scope: SessionScope): Promise<string | null> {\n    if (this.#store !== null) {\n      const state = await this.#store.getState(scope);\n      return state?.activeLockHeldBy ?? null;\n    }\n    const local = this.#localLocks.get(scopeKey(scope));\n    return local?.runId ?? null;\n  }\n}\n\nfunction scopeKey(scope: SessionScope): string {\n  return `${scope.userId}|${scope.sessionId ?? ''}|${scope.agentId ?? ''}`;\n}\n"],"mappings":";AAgCA,MAAM,kBAAkB;;AAGxB,IAAa,cAAb,MAAyB;CACvB,CAASA;CACT,CAASC;CACT,CAASC;CACT,CAASC;CACT,CAASC;CACT,CAASC;CAGT,CAASC,6BAAc,IAAI,KAAoD;CAE/E,YAAY,MAA0B;AACpC,QAAKN,QAAS,KAAK;AACnB,QAAKC,SAAU,KAAK,IAAI,GAAG,KAAK,OAAO;AACvC,QAAKC,SAAU,KAAK,IAAI,GAAG,KAAK,iBAAiB;AACjD,QAAKC,MAAO,KAAK,OAAO,KAAK;AAC7B,QAAKC,QACH,KAAK,WACH,OAAsB,IAAI,SAAS,YAAY,WAAW,WAAW,SAAS,GAAG,CAAC;AACtF,QAAKC,WACH,KAAK,mBACU;AAGb,UAAO,OAFG,KAAK,MAAM,KAAK,QAAQ,GAAG,IAAI,CAAC,SAAS,GAAG,GAC5C,KAAK,MAAM,KAAK,QAAQ,GAAG,IAAI,CAAC,SAAS,GAAG;;;;;;;;;CAW5D,MAAM,QAAQ,OAA2C;EACvD,MAAM,QAAQ,MAAKA,UAAW;EAC9B,MAAM,QAAQ,MAAKF,KAAM;EACzB,MAAM,SAAS,KAAK,IAAI,iBAAiB,KAAK,IAAI,IAAI,MAAKF,SAAU,KAAK,gBAAgB,CAAC;AAC3F,SAAO,MAAM;AAEX,OADW,MAAM,MAAKM,WAAY,OAAO,MAAM,CACvC,QAAO;IAAE,MAAM;IAAY;IAAO;AAE1C,OADgB,MAAKJ,KAAM,GAAG,SACf,MAAKF,OAElB,QAAO;IAAE,MAAM;IAAY,QADZ,MAAM,MAAKO,OAAQ,MAAM;IACL;AAErC,SAAM,MAAKJ,MAAO,OAAO;;;;;;;;;CAU7B,MAAM,QAAQ,OAAqB,OAA8B;AAC/D,MAAI,MAAKJ,UAAW,KAClB,OAAM,MAAKA,MAAO,YAAY,OAAO,MAAM;EAE7C,MAAM,MAAM,SAAS,MAAM;EAC3B,MAAM,QAAQ,MAAKM,WAAY,IAAI,IAAI;AACvC,MAAI,UAAU,UAAa,MAAM,UAAU,MACzC,OAAKA,WAAY,OAAO,IAAI;;CAIhC,OAAMC,WAAY,OAAqB,OAAiC;EACtE,MAAM,MAAM,MAAKJ,KAAM;AACvB,MAAI,MAAKH,UAAW,KAClB,QAAO,MAAKA,MAAO,YAAY,OAAO,OAAO,KAAK,MAAKE,OAAQ;EAGjE,MAAM,MAAM,SAAS,MAAM;EAC3B,MAAM,WAAW,MAAKI,WAAY,IAAI,IAAI;AAC1C,MAAI,aAAa,QAAW;AAC1B,SAAKA,WAAY,IAAI,KAAK;IAAE;IAAO,YAAY;IAAK,CAAC;AACrD,UAAO;;AAET,MAAI,SAAS,UAAU,MAAO,QAAO;AACrC,MAAI,MAAKJ,SAAU,KAAK,MAAM,SAAS,aAAa,MAAKA,QAAS;AAChE,SAAKI,WAAY,IAAI,KAAK;IAAE;IAAO,YAAY;IAAK,CAAC;AACrD,UAAO;;AAET,SAAO;;CAGT,OAAME,OAAQ,OAA6C;AACzD,MAAI,MAAKR,UAAW,KAElB,SADc,MAAM,MAAKA,MAAO,SAAS,MAAM,GACjC,oBAAoB;AAGpC,SADc,MAAKM,WAAY,IAAI,SAAS,MAAM,CAAC,EACrC,SAAS;;;AAI3B,SAAS,SAAS,OAA6B;AAC7C,QAAO,GAAG,MAAM,OAAO,GAAG,MAAM,aAAa,GAAG,GAAG,MAAM,WAAW"}

package/dist/consolidator/noise-filter.d.ts

@@ -0,0 +1,2 @@
+import "../internal/storage-adapter.js";
+import { Message } from "@graphorin/core";