@graphorin/memory 0.6.1 → 0.7.0

package/src/consolidator/budget.ts

@@ -0,0 +1,312 @@
+/**
+ * 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
+ */
+
+import { BudgetExceededError } from './errors.js';
+import type { ConsolidatorPhase, OnBudgetExceed } from './types.js';
+
+/**
+ * @stable
+ */
+export interface BudgetSnapshot {
+  readonly tokensUsedToday: number;
+  readonly costUsedToday: number;
+  readonly tokensRemaining: number;
+  readonly costRemaining: number;
+  readonly resetAt: string;
+  readonly paused: boolean;
+}
+
+/**
+ * @stable
+ */
+export interface BudgetCheck {
+  readonly allowed: boolean;
+  readonly reason?: 'paused' | 'tokens-exceeded' | 'cost-exceeded';
+}
+
+/**
+ * @stable
+ */
+export interface BudgetTrackerOptions {
+  readonly maxTokensPerDay: number;
+  readonly maxCostPerDay: number;
+  readonly onExceed: OnBudgetExceed;
+  readonly resetSemantics: 'utc' | 'local' | 'sliding-24h';
+  readonly now?: () => number;
+  /**
+   * Sink for the `onExceed: 'log'` WARN (memory-consolidation-02).
+   * Defaults to `process.stderr`. One WARN per resource per budget
+   * window - the shipped standard/full presets use `'log'`, so without
+   * it a breached ceiling was completely silent.
+   */
+  readonly logger?: (message: string) => void;
+}
+
+/**
+ * Per-instance budget tracker. The runtime creates one tracker per
+ * consolidator and resets the day counters lazily on the next phase
+ * invocation.
+ *
+ * @stable
+ */
+export class BudgetTracker {
+  readonly #now: () => number;
+  readonly #resetSemantics: 'utc' | 'local' | 'sliding-24h';
+  readonly #onExceed: OnBudgetExceed;
+  readonly #logger: (message: string) => void;
+  #maxTokensPerDay: number;
+  #maxCostPerDay: number;
+  #bucketStart: number;
+  #tokens = 0;
+  #cost = 0;
+  #paused = false;
+  #pausedReason: 'tokens-exceeded' | 'cost-exceeded' | null = null;
+  /** Resources already WARNed this window under `onExceed: 'log'` (memory-consolidation-02). */
+  #warnedThisWindow = new Set<'tokens' | 'cost'>();
+  /**
+   * 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: Array<{ at: number; tokens: number; cost: number }> = [];
+
+  constructor(opts: BudgetTrackerOptions) {
+    this.#now = opts.now ?? Date.now;
+    this.#resetSemantics = opts.resetSemantics;
+    this.#onExceed = opts.onExceed;
+    this.#logger =
+      opts.logger ??
+      ((message: string): void => {
+        process.stderr.write(`${message}\n`);
+      });
+    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: { maxTokensPerDay: number; maxCostPerDay: number }): void {
+    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: ConsolidatorPhase): BudgetCheck {
+    this.#maybeReset();
+    if (phase === 'light') return { allowed: true };
+    if (this.#paused) {
+      const reason = this.#pausedReason ?? 'cost-exceeded';
+      return { allowed: false, reason };
+    }
+    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: { phase: ConsolidatorPhase; tokens: number; costUsd: number }): BudgetSnapshot {
+    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(): BudgetSnapshot {
+    this.#maybeReset();
+    // For the rolling window the "reset" is continuous - the boundary is when
+    // the oldest in-window spend ages out (24h after it landed).
+    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(): void {
+    this.#tokens = 0;
+    this.#cost = 0;
+    this.#paused = false;
+    this.#pausedReason = null;
+    this.#ledger = [];
+    this.#warnedThisWindow.clear();
+    this.#bucketStart = bucketStart(this.#now(), this.#resetSemantics);
+  }
+
+  #handleBreach(
+    phase: ConsolidatorPhase,
+    resource: 'tokens' | 'cost',
+    actual: number,
+    budget: number,
+  ): void {
+    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';
+    }
+    if (this.#onExceed === 'log' && !this.#warnedThisWindow.has(resource)) {
+      // memory-consolidation-02: the type doc always promised "'log'
+      // keeps running with a WARN" - the WARN finally exists. Once per
+      // resource per budget window, so a breached daily ceiling is
+      // visible without flooding.
+      this.#warnedThisWindow.add(resource);
+      this.#logger(
+        `[graphorin/memory] consolidator ${resource} budget exceeded in phase '${phase}': ` +
+          `${resource === 'cost' ? `$${actual.toFixed(4)} > $${budget.toFixed(4)}` : `${actual} > ${budget}`} ` +
+          `(onExceed: 'log' - continuing; switch to 'pause'/'throw' to enforce).`,
+      );
+    }
+  }
+
+  #maybeReset(): void {
+    const now = this.#now();
+    if (this.#resetSemantics === 'sliding-24h') {
+      // Rolling window: drop spends older than the trailing 24h and recompute
+      // the totals from what remains, rather than zeroing on every check.
+      const cutoff = now - DAY_MS;
+      if (
+        this.#ledger.length > 0 &&
+        this.#ledger[0] !== undefined &&
+        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);
+      // Auto-unpause once the window has dropped back under both ceilings.
+      if (
+        this.#paused &&
+        this.#tokens <= this.#maxTokensPerDay &&
+        this.#cost <= this.#maxCostPerDay
+      ) {
+        this.#paused = false;
+        this.#pausedReason = null;
+      }
+      if (this.#tokens <= this.#maxTokensPerDay && this.#cost <= this.#maxCostPerDay) {
+        this.#warnedThisWindow.clear();
+      }
+      return;
+    }
+    // utc / local: zero the counters when the calendar bucket rolls over.
+    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;
+      this.#warnedThisWindow.clear();
+    }
+  }
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Compute the start of the current bucket (ms epoch) for the
+ * supplied reset semantics. UTC midnight is the production default
+ * per ADR-038.
+ *
+ * @internal
+ */
+export function bucketStart(now: number, semantics: 'utc' | 'local' | 'sliding-24h'): number {
+  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
+ */
+export function nextBucketStart(
+  bucket: number,
+  semantics: 'utc' | 'local' | 'sliding-24h',
+): number {
+  switch (semantics) {
+    case 'utc':
+    case 'local':
+      return bucket + DAY_MS;
+    case 'sliding-24h':
+      return bucket + DAY_MS;
+  }
+}

package/src/consolidator/decay.ts

@@ -0,0 +1,246 @@
+/**
+ * Ebbinghaus retention curve for the light phase. Pure functions so
+ * the formula is testable without touching storage.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Default time constant for the retention curve. The plan calls for
+ * `tau = 7` days; consumers may override per-consolidator via
+ * `decayTauDays`.
+ *
+ * @stable
+ */
+export const DEFAULT_DECAY_TAU_DAYS = 7;
+
+/**
+ * Default archive threshold - facts whose retention falls below this
+ * value are soft-archived in the light phase. `0.05` matches the
+ * documented forgetting policy for the memory system.
+ *
+ * @stable
+ */
+export const DEFAULT_DECAY_ARCHIVE_THRESHOLD = 0.05;
+
+/**
+ * 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
+ */
+export function retention(args: {
+  /** Reference time (ms epoch). */
+  readonly now: number;
+  /** Last access timestamp (ms epoch); falls back to `createdAt` when null. */
+  readonly lastAccessedAt: number | null;
+  /** Creation timestamp (ms epoch). */
+  readonly createdAt: number;
+  /** Strength multiplier (default 1.0). */
+  readonly strength: number;
+  /** Time constant in days. */
+  readonly tauDays: number;
+}): number {
+  const reference = args.lastAccessedAt ?? args.createdAt;
+  const elapsedMs = Math.max(0, args.now - reference);
+  const elapsedDays = elapsedMs / (1000 * 60 * 60 * 24);
+  const tau = Math.max(0.1, args.tauDays * Math.max(0.5, args.strength));
+  return Math.exp(-elapsedDays / tau);
+}
+
+/**
+ * `true` when the fact's retention curve has fallen below the
+ * archive threshold.
+ *
+ * @stable
+ */
+export function shouldArchive(args: {
+  readonly now: number;
+  readonly lastAccessedAt: number | null;
+  readonly createdAt: number;
+  readonly strength: number;
+  readonly tauDays: number;
+  readonly archiveThreshold: number;
+}): boolean {
+  const score = retention({
+    now: args.now,
+    lastAccessedAt: args.lastAccessedAt,
+    createdAt: args.createdAt,
+    strength: args.strength,
+    tauDays: args.tauDays,
+  });
+  return score < args.archiveThreshold;
+}
+
+/**
+ * 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
+ */
+export const NEUTRAL_IMPORTANCE = 0.5;
+
+/**
+ * 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
+ */
+export 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;
+  /**
+   * Retrieval-frequency reinforcement (D3) - the use-it-or-lose-it
+   * signal. How strongly the monotonic access counter stretches
+   * retention: the factor is
+   * `1 + weight * min(1, log1p(count) / log1p(saturation))`, saturating
+   * at {@link ACCESS_REINFORCEMENT_SATURATION} accesses. At the default
+   * `0` the factor is exactly `1` - behaviour is byte-identical until an
+   * operator opts in (e.g. `0.3` ⇒ a heavily-used fact keeps up to 1.3x
+   * its retention). Optional so existing weight literals stay valid.
+   */
+  readonly accessReinforcement?: number;
+}
+
+/**
+ * Access count at which retrieval-frequency reinforcement saturates
+ * (D3). `log1p`-scaled, so the first few accesses matter most and
+ * anything past this count contributes the full weight.
+ *
+ * @stable
+ */
+export const ACCESS_REINFORCEMENT_SATURATION = 32;
+
+/**
+ * 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
+ */
+export const DEFAULT_SALIENCE_WEIGHTS: SalienceWeights = Object.freeze({
+  importance: 0.6,
+  quarantine: 0.7,
+  foreignProvenance: 0.2,
+  // D3: reinforcement is opt-in - the default weight 0 keeps salience
+  // byte-identical for every fact regardless of its access count.
+  accessReinforcement: 0,
+});
+
+/**
+ * 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
+ */
+export function salience(args: {
+  readonly now: number;
+  readonly lastAccessedAt: number | null;
+  readonly createdAt: number;
+  readonly strength: number;
+  readonly tauDays: number;
+  /** Importance hint in `[0, 1]`; `null` → {@link NEUTRAL_IMPORTANCE}. */
+  readonly importance: number | null;
+  /** P1-4: a quarantined fact gets the {@link SalienceWeights.quarantine} penalty. */
+  readonly quarantined: boolean;
+  /** P1-4: a non-first-party fact gets the {@link SalienceWeights.foreignProvenance} penalty. */
+  readonly foreignProvenance: boolean;
+  /**
+   * Monotonic retrieval-access count (D3); `null` / absent ⇒ `0`.
+   * Contributes only when {@link SalienceWeights.accessReinforcement}
+   * is non-zero (the default `0` keeps salience unchanged).
+   */
+  readonly accessCount?: number | null;
+  /** Defaults to {@link DEFAULT_SALIENCE_WEIGHTS}. */
+  readonly weights?: SalienceWeights;
+}): number {
+  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;
+  // D3: use-it-or-lose-it reinforcement. log1p-saturating in the access
+  // count so early accesses matter most; identity at the default weight 0.
+  const reinforcementWeight = weights.accessReinforcement ?? 0;
+  const count = Math.max(0, args.accessCount ?? 0);
+  const reinforcementFactor =
+    reinforcementWeight === 0
+      ? 1
+      : 1 +
+        reinforcementWeight *
+          Math.min(1, Math.log1p(count) / Math.log1p(ACCESS_REINFORCEMENT_SATURATION));
+  return Math.max(0, base * importanceFactor * securityFactor * reinforcementFactor);
+}
+
+/**
+ * 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
+ */
+export function selectForCapacityEviction(
+  scored: ReadonlyArray<{ readonly id: string; readonly salience: number }>,
+  capacity: number,
+): ReadonlyArray<string> {
+  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: number): number {
+  if (Number.isNaN(value)) return NEUTRAL_IMPORTANCE;
+  return Math.min(1, Math.max(0, value));
+}

package/src/consolidator/dlq.ts

@@ -0,0 +1,61 @@
+/**
+ * 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
+ */
+export function nextBackoffMs(args: {
+  readonly retryCount: number;
+  readonly baseMs: number;
+  readonly maxMs: number;
+  readonly jitter?: () => number;
+}): number {
+  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
+ */
+export function classifyError(err: unknown): string {
+  if (err === null || err === undefined) 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
+ */
+export function describeError(err: unknown): string {
+  if (err === null || err === undefined) return 'unknown error';
+  if (err instanceof Error) return err.message;
+  if (typeof err === 'string') return err;
+  return String(err);
+}

package/src/consolidator/errors.ts

@@ -0,0 +1,87 @@
+/**
+ * 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
+ */
+
+import { GraphorinMemoryError } from '../errors/index.js';
+import type { ConsolidatorPhase } from './types.js';
+
+/**
+ * Raised when the consolidator's daily budget envelope is exhausted
+ * and `onExceed: 'throw'` is in effect.
+ *
+ * @stable
+ */
+export class BudgetExceededError extends GraphorinMemoryError {
+  override readonly name = 'BudgetExceededError';
+  readonly kind = 'budget-exceeded' as const;
+  readonly phase: ConsolidatorPhase;
+  readonly budget: number;
+  readonly actual: number;
+  readonly resource: 'tokens' | 'cost';
+
+  constructor(args: {
+    phase: ConsolidatorPhase;
+    budget: number;
+    actual: number;
+    resource: 'tokens' | 'cost';
+  }) {
+    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
+ */
+export class CustomTierMisconfiguredError extends GraphorinMemoryError {
+  override readonly name = 'CustomTierMisconfiguredError';
+  readonly kind = 'custom-tier-misconfigured' as const;
+  readonly missing: ReadonlyArray<string>;
+
+  constructor(missing: ReadonlyArray<string>) {
+    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
+ */
+export class ProviderNotConfiguredError extends GraphorinMemoryError {
+  override readonly name = 'ProviderNotConfiguredError';
+  readonly kind = 'provider-not-configured' as const;
+  readonly phase: ConsolidatorPhase;
+
+  constructor(phase: ConsolidatorPhase) {
+    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;
+  }
+}