@graphorin/memory 0.6.1 → 0.7.0

package/src/memory-interface.ts

@@ -0,0 +1,158 @@
+/**
+ * The mutually-recursive `Memory` + `ContextEngine` interface pair
+ * (issue #22). `ContextEngine.assemble` / `compactNow` consume the
+ * full `Memory` facade, and `Memory` exposes its `contextEngine` -
+ * splitting the two across `facade.ts` and `context-engine/engine.ts`
+ * put a type-only cycle into the module graph (facade -> engine ->
+ * facade, plus every compaction hook that names `Memory`). Co-locating
+ * the pair in this leaf module (importing only IO types, tier
+ * surfaces, and other leaves) makes the graph acyclic.
+ *
+ * Both interfaces are re-exported from their original homes
+ * (`facade.ts` and the context-engine barrel) - no public import path
+ * changed.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  EmbedderProvider,
+  MemoryMetadata,
+  Message,
+  MessageContent,
+  SessionScope,
+  Tool,
+} from '@graphorin/core';
+import type { ConflictPipeline } from './conflict/index.js';
+import type { Consolidator } from './consolidator/runtime.js';
+import type {
+  CompactionResult,
+  CompactionSource,
+  CompactionSummarizer,
+} from './context-engine/compaction/types.js';
+import type {
+  AssembledPrompt,
+  AssembleInput,
+  CompileOptions,
+  CompileScope,
+  MemoryContextBlocks,
+  ResolvedContextEngineConfig,
+} from './context-engine/io-types.js';
+import type { EpisodicMemory } from './tiers/episodic-memory.js';
+import type { InsightMemory } from './tiers/insight-memory.js';
+import type { ProceduralMemory } from './tiers/procedural-memory.js';
+import type { SemanticMemory } from './tiers/semantic-memory.js';
+import type { SessionMemory } from './tiers/session-memory.js';
+import type { SharedMemory } from './tiers/shared-memory.js';
+import type { WorkingMemory } from './tiers/working-memory.js';
+
+/**
+ * Public surface of the {@link ContextEngine} instance returned by
+ * {@link createContextEngine}.
+ *
+ * @stable
+ */
+export interface ContextEngine {
+  /** Assemble the layered system prompt for a single step. */
+  assemble(memory: Memory, input: AssembleInput): Promise<AssembledPrompt>;
+  /**
+   * Trigger evaluation primitive used by Phase 12 (agent runtime)
+   * at the top of every step. Returns `true` when the in-flight
+   * buffer's token count crosses the per-provider trigger
+   * threshold. Pass `precomputedTokens` to amortize the count
+   * via the per-message cache surfaced by
+   * `SessionMemoryStoreExt.totalCachedTokens(scope)` (DEC-131) -
+   * the production hot path is an O(1) comparison when the cache
+   * is warm.
+   */
+  shouldCompact(
+    messages: ReadonlyArray<Message>,
+    options?: {
+      readonly precomputedTokens?: number;
+      /**
+       * Index of the first COMPACTABLE message (context-engine-04): the
+       * caller's pinned, never-compacted system prefix ends here. The
+       * SOTA-4 reclaim floor counts only `messages.slice(from)` older
+       * turns as reclaimable - without it a large system prompt is
+       * counted as reclaimable and the floor fires the summarizer for
+       * near-zero real reclaim. Default `0` (everything compactable).
+       */
+      readonly compactableFromIndex?: number;
+    },
+  ): Promise<boolean>;
+  /**
+   * Run a compaction call. Phase 12 calls this when the trigger
+   * fires (`source: 'auto-trigger'`) or the operator invokes
+   * `agent.compact(...)` (`source: 'manual'`).
+   */
+  compactNow(input: {
+    readonly scope: SessionScope;
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly agentId: string;
+    readonly source: CompactionSource;
+    readonly messages: ReadonlyArray<Message>;
+    readonly memory: Memory;
+    readonly summarizer?: CompactionSummarizer;
+    /** Per-call override of the strategy's preserve-recent count (CE-3). */
+    readonly preserveRecentTurns?: number;
+    /** Topic/tags narrowing for the procedural-rules re-anchor hook (CE-6). */
+    readonly procedural?: { readonly topic?: string; readonly tags?: ReadonlyArray<string> };
+    /**
+     * The caller's pinned system prefix - the messages EXCLUDED from
+     * `messages` before this call (context-engine-04). Used only for
+     * accounting: the anti-thrash guard and the "still above threshold"
+     * warning must compare against the FULL post-splice context
+     * (prefix + summary + preserved + essentials), or a real system
+     * prompt defeats the guard and a summarizer call fires every step
+     * at the context edge. Never compacted, never returned.
+     */
+    readonly prefixMessages?: ReadonlyArray<Message>;
+    readonly signal?: AbortSignal;
+  }): Promise<{
+    readonly result: CompactionResult;
+    readonly extraContent: ReadonlyArray<MessageContent>;
+    readonly hookFailures: ReadonlyArray<{ readonly hookName: string; readonly reason: string }>;
+  }>;
+  /** Resolved configuration snapshot. */
+  config(): ResolvedContextEngineConfig;
+}
+
+/**
+ * The facade returned by {@link createMemory}.
+ *
+ * @stable
+ */
+export interface Memory {
+  readonly working: WorkingMemory;
+  readonly session: SessionMemory;
+  readonly episodic: EpisodicMemory;
+  readonly semantic: SemanticMemory;
+  readonly procedural: ProceduralMemory;
+  readonly shared: SharedMemory;
+  /**
+   * Read surface over reflection insights (P1-1). A no-op (returns
+   * empty) when the storage adapter does not expose the optional
+   * insight surface.
+   */
+  readonly insights: InsightMemory;
+  readonly tools: ReadonlyArray<Tool>;
+  readonly consolidator: Consolidator;
+  /** The configured conflict pipeline. Surfaced for tests + CLI tooling. */
+  readonly conflictPipeline: ConflictPipeline;
+  /** The configured context engine (Phase 10d). */
+  readonly contextEngine: ContextEngine;
+  /** The active embedder, when configured. `null` otherwise. */
+  readonly embedder: EmbedderProvider | null;
+  /** The canonical id of the active embedder, when configured. */
+  embedderId(): string | null;
+  /**
+   * Compile a system-prompt block bundle. The bundle carries the
+   * static fragments per memory tier; the agent runtime consumes
+   * the {@link ContextEngine} surface (`memory.contextEngine`)
+   * directly for the full six-layer assembly.
+   */
+  compile(scope: CompileScope, options?: CompileOptions): Promise<MemoryContextBlocks>;
+  /** Counter snapshot consumed by Phase 10d's metadata layer. */
+  metadata(scope: SessionScope): Promise<MemoryMetadata>;
+}

package/src/migration/embedder-migration.ts

@@ -0,0 +1,237 @@
+import type { EmbedderProvider } from '@graphorin/core';
+import {
+  EmbedderMigrationAbortedError,
+  EmbedderMigrationLockedError,
+  EmbedderMigrationStateError,
+} from '../errors/index.js';
+import { bindEmbedder } from '../internal/embedder-binding.js';
+import type { EmbeddingMetaRegistryLike } from '../internal/storage-adapter.js';
+
+/**
+ * Coexistence policy for embedder swaps.
+ *
+ *  - `'lock-on-first'` (default) - refuses to register a second active
+ *    embedder; surfaces an actionable error pointing at the planned
+ *    migration runner.
+ *  - `'multi-active'` - keeps both embedders alive (read union, write
+ *    to active); used while a long migration is in flight.
+ *  - `'auto-migrate'` - re-embeds existing rows in resumable batches
+ *    until the source embedder has zero rows, then retires it.
+ *
+ * @stable
+ */
+export type EmbedderMigrationStrategy = 'lock-on-first' | 'multi-active' | 'auto-migrate';
+
+/**
+ * Per-iteration progress snapshot yielded by {@link migrateEmbedder}.
+ *
+ * @stable
+ */
+export interface MigrationProgress {
+  /** `'fact'`, `'episode'`, or `'message'` - which entity is being migrated. */
+  readonly kind: 'fact' | 'episode' | 'message';
+  /** Number of records processed so far. */
+  readonly processed: number;
+  /** Total records expected for this entity (when known). */
+  readonly total: number;
+  /** Identifier of the source embedder (`'<adapter>:<model>@<dim>'`). */
+  readonly source: string;
+  /** Identifier of the target embedder. */
+  readonly target: string;
+  /**
+   * Identifier for this migration run. MST-12: this is an in-memory id for
+   * the current run - there is no persisted `migration_state` cursor today, so
+   * a migration does not resume across processes.
+   */
+  readonly migrationId: string;
+  /** Phase discriminator. */
+  readonly phase: 'planning' | 'running' | 'paused' | 'committed' | 'aborted';
+}
+
+/**
+ * Options accepted by {@link migrateEmbedder}.
+ *
+ * @stable
+ */
+export interface MigrateEmbedderOptions {
+  /** Source embedder (currently active). */
+  readonly source: EmbedderProvider;
+  /** Target embedder (becomes active when migration commits). */
+  readonly target: EmbedderProvider;
+  /** Storage layer's embedder registry. */
+  readonly embeddings: EmbeddingMetaRegistryLike;
+  /** Strategy applied per `embedding_meta` row. Default `'lock-on-first'`. */
+  readonly strategy?: EmbedderMigrationStrategy;
+  /**
+   * Threshold for `auto-migrate`. The runner streams source rows in
+   * batches of `batchSize` (default `512`) and yields progress after
+   * each batch.
+   */
+  readonly batchSize?: number;
+  /** Optional cap on the number of rows to migrate per kind. */
+  readonly maxRecordsPerKind?: number;
+  /**
+   * Hook that returns the next batch of rows to re-embed for a given kind.
+   * MST-12: this is **caller-supplied** - there is no store-side helper that
+   * auto-wires it today, and `auto-migrate` throws without it. Pass a paging
+   * function over your source rows to drive the migration.
+   */
+  readonly nextBatch?: NextBatchHook;
+  /** Optional abort signal - aborting yields one final progress event. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Per-batch loader. Returns up to `batchSize` rows for the supplied
+ * `kind` whose `embedder_id` is the source embedder. Returning an
+ * empty array signals end-of-stream.
+ *
+ * @stable
+ */
+export type NextBatchHook = (args: {
+  readonly kind: 'fact' | 'episode' | 'message';
+  readonly source: string;
+  readonly target: string;
+  readonly batchSize: number;
+  readonly cursor: string | null;
+}) => Promise<{ readonly rows: ReadonlyArray<MigrationRow>; readonly nextCursor: string | null }>;
+
+/**
+ * Single row exposed to the migration runner. The runner re-embeds
+ * `text` with the target embedder; the storage adapter is responsible
+ * for committing the new vector + updating `embedder_id`.
+ *
+ * @stable
+ */
+export interface MigrationRow {
+  readonly id: string;
+  readonly text: string;
+  readonly write: (vector: Float32Array) => Promise<void>;
+}
+
+/**
+ * Stream embedder migrations as `AsyncIterable<MigrationProgress>`.
+ *
+ * The function is the universal entry point for every migration
+ * strategy:
+ *
+ *  - `'lock-on-first'`: surfaces the locked error eagerly so the
+ *    operator can act before any work happens.
+ *  - `'multi-active'`: registers the target alongside the source and
+ *    yields a single `'committed'` progress event.
+ *  - `'auto-migrate'`: streams batches until the source is fully
+ *    drained, then retires the source row.
+ *
+ * @stable
+ */
+export async function* migrateEmbedder(
+  options: MigrateEmbedderOptions,
+): AsyncGenerator<MigrationProgress, void, unknown> {
+  const { source, target, embeddings } = options;
+  const strategy = options.strategy ?? 'lock-on-first';
+  const sourceId = source.id();
+  const targetId = target.id();
+  const migrationId = `migration_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+
+  if (sourceId === targetId) {
+    throw new EmbedderMigrationStateError(
+      `source and target embedders must differ; both resolved to '${sourceId}'.`,
+    );
+  }
+
+  const sourceMeta = embeddings.get(sourceId);
+  if (sourceMeta === null) {
+    throw new EmbedderMigrationStateError(
+      `source embedder '${sourceId}' is not registered. Run createMemory({ embedder: source }) first.`,
+    );
+  }
+
+  if (strategy === 'lock-on-first') {
+    throw new EmbedderMigrationLockedError(sourceId, targetId);
+  }
+
+  bindEmbedder(target, embeddings);
+
+  if (strategy === 'multi-active') {
+    yield {
+      kind: 'fact',
+      processed: 0,
+      total: 0,
+      source: sourceId,
+      target: targetId,
+      migrationId,
+      phase: 'committed',
+    };
+    return;
+  }
+
+  // strategy === 'auto-migrate'
+  if (options.nextBatch === undefined) {
+    throw new EmbedderMigrationStateError(
+      "'auto-migrate' requires a `nextBatch` hook supplied by the storage adapter.",
+    );
+  }
+
+  const batchSize = options.batchSize ?? 512;
+  const cap = options.maxRecordsPerKind ?? Number.POSITIVE_INFINITY;
+
+  for (const kind of ['fact', 'episode', 'message'] as const) {
+    let cursor: string | null = null;
+    let processed = 0;
+    while (processed < cap) {
+      if (options.signal?.aborted === true) {
+        yield {
+          kind,
+          processed,
+          total: processed,
+          source: sourceId,
+          target: targetId,
+          migrationId,
+          phase: 'aborted',
+        };
+        throw new EmbedderMigrationAbortedError(migrationId);
+      }
+      const batch = await options.nextBatch({
+        kind,
+        source: sourceId,
+        target: targetId,
+        batchSize,
+        cursor,
+      });
+      if (batch.rows.length === 0) break;
+      const texts = batch.rows.map((r) => r.text);
+      const vectors = await target.embed(texts, {
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+      });
+      for (let i = 0; i < batch.rows.length; i++) {
+        const row = batch.rows[i];
+        const vector = vectors[i];
+        if (row === undefined || vector === undefined) continue;
+        await row.write(vector);
+      }
+      processed += batch.rows.length;
+      cursor = batch.nextCursor;
+      yield {
+        kind,
+        processed,
+        total: processed,
+        source: sourceId,
+        target: targetId,
+        migrationId,
+        phase: 'running',
+      };
+      if (cursor === null) break;
+    }
+  }
+
+  embeddings.retire(sourceId);
+  yield {
+    kind: 'fact',
+    processed: 0,
+    total: 0,
+    source: sourceId,
+    target: targetId,
+    migrationId,
+    phase: 'committed',
+  };
+}

package/src/migration/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Embedder migration runner - one of the three deliverables that turns
+ * `@graphorin/memory` into a long-running, embedder-aware system.
+ *
+ * @packageDocumentation
+ */
+
+export type {
+  EmbedderMigrationStrategy,
+  MigrateEmbedderOptions,
+  MigrationProgress,
+} from './embedder-migration.js';
+export { migrateEmbedder } from './embedder-migration.js';

package/src/search/explain.ts

@@ -0,0 +1,123 @@
+/**
+ * Recall explainability for `@graphorin/memory` - "why was this
+ * recalled?" (X-3). Turns the per-signal scores the hybrid pipeline
+ * already records on each {@link MemoryHit} (FTS `bm25`, vector
+ * similarity, the fused reciprocal-rank term, the decay multiplier,
+ * future graph-hop terms) into a structured, renderable explanation.
+ *
+ * Pure data: the builder re-uses whatever {@link MemoryHit.signals} the
+ * pipeline left behind rather than re-deriving them, so the explanation
+ * always matches the ranking that actually happened. The renderer
+ * returns a string and performs no I/O, so the explanation can be
+ * attached to a span, logged, or surfaced by operator tooling.
+ *
+ * @packageDocumentation
+ */
+
+import type { MemoryHit, MemoryKind, MemoryRecord } from '@graphorin/core';
+
+/**
+ * Per-memory contribution breakdown for one recalled record: the
+ * decomposed signals the hybrid pipeline summed into the final score,
+ * plus the record's final rank. Surfaces *why* a single memory was
+ * recalled and how it ranked relative to its siblings.
+ *
+ * @stable
+ */
+export interface RecalledMemoryExplanation {
+  /** Record id (fact / episode / insight / …). */
+  readonly id: string;
+  /** Memory kind of the recalled record. */
+  readonly kind: MemoryKind;
+  /** 1-based position in the final fused + decayed ranking. */
+  readonly rank: number;
+  /** Final score after fusion and (optional) decay. */
+  readonly score: number;
+  /**
+   * Raw per-signal scores contributing to `score`, exactly as the
+   * pipeline recorded them on the hit: FTS (`bm25`), vector similarity
+   * (`vector`), the fused reciprocal-rank terms (`rrf` plus one
+   * `rrf.<label>` entry per fused list keyed by the retriever kind,
+   * e.g. `rrf.fts` / `rrf.vector`, with `rrf.list_N` as the fallback
+   * when a list carries no label), and the decay multiplier (`decay`)
+   * when decay ran.
+   */
+  readonly signals: Readonly<Record<string, number>>;
+}
+
+/**
+ * Structured "why was this recalled?" explanation for one
+ * {@link SemanticMemory.search} call: the query, the reranker that
+ * fused the candidate lists, and the per-memory signal breakdown in
+ * final-rank order. Pure data - safe to attach to a span, log, or
+ * render. X-3.
+ *
+ * @stable
+ */
+export interface RecallExplanation {
+  /** The query the recall ran for. */
+  readonly query: string;
+  /** Stable id of the reranker that fused the candidate lists. */
+  readonly rerankerId: string;
+  /** Number of recalled memories explained. */
+  readonly count: number;
+  /** Per-memory breakdown, in final-rank order (rank 1 first). */
+  readonly results: ReadonlyArray<RecalledMemoryExplanation>;
+}
+
+/**
+ * Build a {@link RecallExplanation} from a ranked hit list. Pure and
+ * deterministic: it surfaces whatever per-signal scores the hybrid
+ * pipeline left on each {@link MemoryHit.signals} (FTS, vector, RRF,
+ * decay, future graph-hop terms) without re-deriving them, so the
+ * explanation always matches what actually drove the ranking. Hits are
+ * assumed to be in final-rank order (as returned by `search`).
+ *
+ * @stable
+ */
+export function explainRecall<TRecord extends MemoryRecord>(
+  hits: ReadonlyArray<MemoryHit<TRecord>>,
+  opts: { readonly query: string; readonly rerankerId: string },
+): RecallExplanation {
+  const results = hits.map(
+    (hit, idx): RecalledMemoryExplanation =>
+      Object.freeze({
+        id: hit.record.id,
+        kind: hit.record.kind,
+        rank: idx + 1,
+        score: hit.score,
+        signals: Object.freeze({ ...(hit.signals ?? {}) }),
+      }),
+  );
+  return Object.freeze({
+    query: opts.query,
+    rerankerId: opts.rerankerId,
+    count: results.length,
+    results: Object.freeze(results),
+  });
+}
+
+/**
+ * Render a {@link RecallExplanation} as a compact ASCII block - a
+ * header line plus one line per recalled memory with its signal
+ * breakdown. Pure (returns a string, no I/O); used by operator tooling
+ * and trace inspectors.
+ *
+ * @stable
+ */
+export function formatRecallExplanation(explanation: RecallExplanation): string {
+  const header = `recall ${JSON.stringify(explanation.query)} via ${explanation.rerankerId} -> ${explanation.count} result(s)`;
+  if (explanation.results.length === 0) return header;
+  const lines = explanation.results.map((r) => {
+    const signals = Object.entries(r.signals)
+      .map(([key, value]) => `${key}=${formatScore(value)}`)
+      .join(' ');
+    const suffix = signals === '' ? '' : ` (${signals})`;
+    return `  #${r.rank} ${r.id} [${r.kind}] score=${formatScore(r.score)}${suffix}`;
+  });
+  return [header, ...lines].join('\n');
+}
+
+function formatScore(value: number): string {
+  return Number.isFinite(value) ? value.toFixed(4) : String(value);
+}

package/src/search/fit-weights.ts

@@ -0,0 +1,109 @@
+/**
+ * C5: offline fusion-weight fitting. Tuned convex/weighted fusion beats
+ * RRF with a handful of labelled queries (Bruch et al., TOIS 2023) - this
+ * module turns that into a small, pure routine: grid-search
+ * {@link FusionWeights} over labelled cases and return the setting that
+ * maximizes mean nDCG@k, together with the plain-RRF baseline so the
+ * caller can see whether tuning actually paid.
+ *
+ * Pure and I/O-free: the caller supplies per-kind candidate lists (run
+ * your FTS and vector retrievers once per query, offline) plus the ids
+ * judged relevant. Feed the winning weights to
+ * `search(..., { fusion: { strategy: 'weighted', weights } })` or a
+ * process-default `WeightedRRFReranker`.
+ *
+ * @packageDocumentation
+ */
+
+import type { MemoryHit, MemoryRecord } from '@graphorin/core';
+import { fuseWeighted } from './rrf.js';
+
+/** One labelled query: per-kind candidate lists + the relevant ids. */
+export interface FitFusionCase<TRecord extends MemoryRecord = MemoryRecord> {
+  /** FTS candidate list, best-first (as the store returns it). */
+  readonly fts: ReadonlyArray<MemoryHit<TRecord>>;
+  /** Vector candidate list, best-first. */
+  readonly vector: ReadonlyArray<MemoryHit<TRecord>>;
+  /** Ids judged relevant for this query (binary gain). */
+  readonly relevantIds: ReadonlyArray<string>;
+}
+
+/** Options for {@link fitFusionWeights}. */
+export interface FitFusionOptions {
+  /** Candidate weight values per axis. Default `[0.25, 0.5, 1, 2, 4]`. */
+  readonly grid?: ReadonlyArray<number>;
+  /** nDCG cutoff. Default `10`. */
+  readonly k?: number;
+  /** RRF constant forwarded to the fuse. Default `60`. */
+  readonly rrfK?: number;
+}
+
+/** Result of a fit: the winning weights + its score and the RRF baseline. */
+export interface FitFusionResult {
+  readonly weights: { readonly fts: number; readonly vector: number };
+  /** Mean nDCG@k of the winning weights across the cases. */
+  readonly score: number;
+  /** Mean nDCG@k of unit weights (plain RRF) - compare before adopting. */
+  readonly baseline: number;
+}
+
+/**
+ * Binary-gain nDCG@k over a ranked id list.
+ *
+ * @stable
+ */
+export function ndcgAtK(
+  rankedIds: ReadonlyArray<string>,
+  relevant: ReadonlySet<string>,
+  k: number,
+): number {
+  const cutoff = Math.min(k, rankedIds.length);
+  let dcg = 0;
+  for (let i = 0; i < cutoff; i++) {
+    const id = rankedIds[i];
+    if (id !== undefined && relevant.has(id)) dcg += 1 / Math.log2(i + 2);
+  }
+  const idealHits = Math.min(relevant.size, k);
+  let idcg = 0;
+  for (let i = 0; i < idealHits; i++) idcg += 1 / Math.log2(i + 2);
+  return idcg === 0 ? 0 : dcg / idcg;
+}
+
+/**
+ * Grid-search fusion weights against labelled cases (C5).
+ *
+ * @stable
+ */
+export function fitFusionWeights<TRecord extends MemoryRecord = MemoryRecord>(
+  cases: ReadonlyArray<FitFusionCase<TRecord>>,
+  options: FitFusionOptions = {},
+): FitFusionResult {
+  if (cases.length === 0) {
+    throw new TypeError('[graphorin/memory] fitFusionWeights: at least one labelled case required');
+  }
+  const grid = options.grid ?? [0.25, 0.5, 1, 2, 4];
+  const k = options.k ?? 10;
+  const rrfK = options.rrfK ?? 60;
+
+  const meanNdcg = (wFts: number, wVector: number): number => {
+    let total = 0;
+    for (const c of cases) {
+      const fused = fuseWeighted([c.fts, c.vector], [wFts, wVector], rrfK);
+      const rankedIds = fused.map((h) => h.record.id);
+      total += ndcgAtK(rankedIds, new Set(c.relevantIds), k);
+    }
+    return total / cases.length;
+  };
+
+  const baseline = meanNdcg(1, 1);
+  let best: FitFusionResult = { weights: { fts: 1, vector: 1 }, score: baseline, baseline };
+  for (const wFts of grid) {
+    for (const wVector of grid) {
+      const score = meanNdcg(wFts, wVector);
+      if (score > best.score + 1e-12) {
+        best = { weights: { fts: wFts, vector: wVector }, score, baseline };
+      }
+    }
+  }
+  return best;
+}

package/src/search/graph-ppr.ts

@@ -0,0 +1,38 @@
+/**
+ * PPR-lite graph scoring (D5) - damped spreading activation over the
+ * entity-graph neighbourhood, generalizing the flat one-hop expansion.
+ * Pure: given the seed facts (the lexical/vector candidates retrieved so
+ * far) and the graded neighbours (`{ fact, depth }` from
+ * `expandActivation`), it assigns each neighbour an activation score
+ * that decays with hop distance, so a fact two hops from a strong seed
+ * ranks below a direct neighbour instead of tying at a flat `1`.
+ *
+ * This is HippoRAG-style personalized-PageRank, "lite": a single damped
+ * BFS pass seeded from retrieval rather than an iterative power method.
+ * Seeding from query-matched entities (rather than retrieved candidates)
+ * is the eval-gated extension the roadmap defers until numbers justify.
+ *
+ * @packageDocumentation
+ */
+
+/** Default damping applied per hop (activation × damping^depth). */
+export const DEFAULT_PPR_DAMPING = 0.5;
+
+/**
+ * Compute PPR-lite activation for graded neighbours. `damping` in
+ * `(0, 1]`; a neighbour at `depth` d contributes `damping^d` per seed
+ * that reaches it. Since `expandActivation` already returns the MINIMUM
+ * depth per neighbour (dedup across seeds), the score here is a pure
+ * function of that min-depth - `damping^depth`, clamped to `[0, 1]`.
+ * A neighbour list produced with `maxHops: 1` reproduces a flat-ish
+ * score of `damping` at every node; `maxHops: 2` separates the tiers.
+ *
+ * @stable
+ */
+export function pprActivation(
+  neighbours: ReadonlyArray<{ readonly depth: number }>,
+  damping = DEFAULT_PPR_DAMPING,
+): number[] {
+  const d = damping <= 0 || damping > 1 ? DEFAULT_PPR_DAMPING : damping;
+  return neighbours.map((n) => d ** Math.max(1, n.depth));
+}