@remnic/core 1.0.3 → 1.1.1

package/dist/extraction-judge.d.ts

@@ -26,10 +26,87 @@ interface JudgeCandidate {
     /** Local importance level, set by caller before judging. */
     importanceLevel?: ImportanceLevel;
 }
+/**
+ * Verdict kinds (issue #562, PR 1).
+ *
+ * - `"accept"`: fact is durable, persist it.
+ * - `"reject"`: fact is not durable, drop it.
+ * - `"defer"`: fact is ambiguous; push it back into the buffer for another
+ *   pass with fresh context. Inspired by MemReader (arxiv 2604.07877).
+ *
+ * PR 1 only introduces the type. No emit path produces `"defer"` yet — the
+ * defer-capable prompt, buffer re-routing, telemetry, and GRPO data
+ * collection are landing in PRs 2, 3, and 4 respectively.
+ */
+type JudgeVerdictKind = "accept" | "reject" | "defer";
+/**
+ * Judge verdict shape.
+ *
+ * Back-compat note: `kind` is optional. Verdicts serialized before PR 1
+ * (both in-memory cache entries and any persisted caches) only carry
+ * `{ durable, reason }`. Downstream consumers must either read `durable`
+ * directly, or use {@link getVerdictKind} / {@link isDurableVerdict} which
+ * gracefully fall back to the boolean when `kind` is missing, and ignore
+ * unknown future `kind` values rather than crashing.
+ */
 interface JudgeVerdict {
+    /**
+     * True iff the fact should be persisted. For `"defer"` verdicts this is
+     * `false` — a deferred fact is not (yet) persisted, so callers that only
+     * look at `durable` will treat defer as "skip this turn", which matches
+     * the pre-PR-1 fail-closed behavior for non-accepted verdicts.
+     */
     durable: boolean;
     reason: string;
+    /**
+     * Optional explicit verdict kind. Added in PR 1 of issue #562. Legacy
+     * verdicts (including cache entries produced before this field existed)
+     * do not set `kind`; use {@link getVerdictKind} to read this safely.
+     */
+    kind?: JudgeVerdictKind;
 }
+/**
+ * Resolve a verdict's effective kind.
+ *
+ * - If `kind` is explicitly set to one of the known values, return it.
+ * - If `kind` is absent, infer from `durable` (back-compat with pre-PR-1
+ *   cache entries and emit paths that have not been updated yet).
+ * - If `kind` is set to an unrecognised value (forward-compat, e.g. a
+ *   future cache entry loaded by an older build), fall back to `durable`
+ *   so we never crash on unknown strings.
+ */
+declare function getVerdictKind(verdict: JudgeVerdict): JudgeVerdictKind;
+/**
+ * Type guard: returns `true` only for verdicts that should be persisted.
+ * Treats both `"reject"` and `"defer"` as "not durable" — defer means the
+ * caller should re-evaluate later, not write now.
+ */
+declare function isDurableVerdict(verdict: JudgeVerdict): boolean;
+/**
+ * Validate a cache entry loaded from persistence / another process.
+ *
+ * Strict: accepts legacy `{ durable, reason }` entries and new entries
+ * whose `kind` is one of the three known `JudgeVerdictKind` values.
+ * Rejects structurally wrong types and unknown `kind` strings so the
+ * type-guard narrowing is sound — callers that receive
+ * `value is JudgeVerdict` can safely treat `kind` as the declared
+ * union.
+ *
+ * Forward-compat is handled by {@link normalizeCachedVerdict}, which
+ * drops unknown `kind` strings before validation so a newer build's
+ * cache entry still loads instead of being rejected.
+ */
+declare function isValidCachedVerdict(value: unknown): value is JudgeVerdict;
+/**
+ * Forward-compatible cache-entry loader.
+ *
+ * Drops unknown `kind` strings to `undefined` (so `getVerdictKind` can
+ * fall back to `durable`), then validates structurally. Non-string
+ * `kind` values are still treated as structural violations and rejected.
+ * Returns the sanitised verdict, or `null` when the entry is structurally
+ * unusable.
+ */
+declare function normalizeCachedVerdict(value: unknown): JudgeVerdict | null;
 interface JudgeBatchResult {
     verdicts: Map<number, JudgeVerdict>;
     /** Number of verdicts served from cache. */
@@ -38,6 +115,45 @@ interface JudgeBatchResult {
     judged: number;
     /** Total wall-clock time in milliseconds. */
     elapsed: number;
+    /**
+     * Number of verdicts in this batch that resolved to `"defer"` (issue #562,
+     * PR 2). Callers can use this to decide whether to retain buffer turns for
+     * the next extraction pass.
+     */
+    deferred: number;
+    /**
+     * Number of defers that were forcibly converted to `"reject"` because the
+     * same candidate text had already been deferred at least
+     * `extractionJudgeMaxDeferrals` times. Rolled out of `deferred` — a
+     * candidate counted here is *not* also in `deferred`.
+     */
+    deferredCappedToReject: number;
+}
+/**
+ * Per-verdict observation emitted by `judgeFactDurability` when an
+ * `onVerdict` callback is supplied (issue #562, PR 3). Used to wire the
+ * observation ledger / telemetry stream without coupling the judge module
+ * directly to filesystem I/O. One event is emitted for every resolved
+ * verdict, including auto-approved and cache-hit paths.
+ */
+interface JudgeVerdictObservation {
+    verdict: JudgeVerdict;
+    /** The original `JudgeCandidate` passed in (same reference). */
+    candidate: JudgeCandidate;
+    /** SHA-256 of `text\0category`, same key the cache/deferCounter use. */
+    contentHash: string;
+    /** Verdict resolution path. Useful for debugging + dashboards. */
+    source: "auto-approve" | "cache" | "llm" | "llm-cap-rejected" | "fail-open";
+    /**
+     * How many times this candidate had already been deferred before this
+     * verdict resolved. 0 when the candidate had never been deferred.
+     */
+    priorDeferrals: number;
+    /**
+     * Milliseconds from batch start to now. Shared across verdicts emitted in
+     * the same batch.
+     */
+    elapsedMs: number;
 }
 /**
  * Deterministic gate for extracted `procedure` memories: ≥2 steps with non-empty
@@ -55,12 +171,18 @@ declare function validateProcedureExtraction(input: {
  * checked against an in-memory content-hash cache, and sent to the LLM
  * for verdict.
  */
-declare function judgeFactDurability(candidates: JudgeCandidate[], config: PluginConfig, localLlm: LocalLlmClient | null, fallbackLlm: FallbackLlmClient | null, cache?: Map<string, JudgeVerdict>): Promise<JudgeBatchResult>;
+declare function judgeFactDurability(candidates: JudgeCandidate[], config: PluginConfig, localLlm: LocalLlmClient | null, fallbackLlm: FallbackLlmClient | null, cache?: Map<string, JudgeVerdict>, deferCounts?: Map<string, number>, onVerdict?: (observation: JudgeVerdictObservation) => void): Promise<JudgeBatchResult>;
 /** Clear the in-memory default verdict cache. Primarily for tests. */
 declare function clearVerdictCache(): void;
 /** Return the current default verdict cache size. Primarily for tests. */
 declare function verdictCacheSize(): number;
 /** Create a new per-instance verdict cache. Orchestrators should hold one. */
 declare function createVerdictCache(): Map<string, JudgeVerdict>;
+/**
+ * Create a new per-instance defer-counter map. Orchestrators should hold one
+ * alongside their verdict cache so defer counts survive across extraction
+ * passes within a single orchestrator but do not leak across orchestrators.
+ */
+declare function createDeferCountMap(): Map<string, number>;
 
-export { type JudgeBatchResult, type JudgeCandidate, type JudgeVerdict, clearVerdictCache, createVerdictCache, judgeFactDurability, validateProcedureExtraction, verdictCacheSize };
+export { type JudgeBatchResult, type JudgeCandidate, type JudgeVerdict, type JudgeVerdictKind, type JudgeVerdictObservation, clearVerdictCache, createDeferCountMap, createVerdictCache, getVerdictKind, isDurableVerdict, isValidCachedVerdict, judgeFactDurability, normalizeCachedVerdict, validateProcedureExtraction, verdictCacheSize };

package/dist/extraction-judge.js

@@ -1,17 +1,27 @@
 import {
   clearVerdictCache,
+  createDeferCountMap,
   createVerdictCache,
+  getVerdictKind,
+  isDurableVerdict,
+  isValidCachedVerdict,
   judgeFactDurability,
+  normalizeCachedVerdict,
   validateProcedureExtraction,
   verdictCacheSize
-} from "./chunk-LAYN4LDC.js";
+} from "./chunk-C4SQJZAF.js";
 import "./chunk-UZB5KHKX.js";
 import "./chunk-QDW3E4RD.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   clearVerdictCache,
+  createDeferCountMap,
   createVerdictCache,
+  getVerdictKind,
+  isDurableVerdict,
+  isValidCachedVerdict,
   judgeFactDurability,
+  normalizeCachedVerdict,
   validateProcedureExtraction,
   verdictCacheSize
 };

package/dist/extraction.js

@@ -1,16 +1,17 @@
 import {
   ExtractionEngine
-} from "./chunk-2VFW5K5U.js";
-import "./chunk-UEYA6UC7.js";
+} from "./chunk-S3EEFKNY.js";
+import "./chunk-NZLQTHS5.js";
+import "./chunk-54V4BZWP.js";
 import "./chunk-NBNN5GOB.js";
-import "./chunk-UPMD5XND.js";
 import "./chunk-FEMOX5AD.js";
+import "./chunk-JL2PU6AI.js";
 import "./chunk-VEWZZM3H.js";
-import "./chunk-LK6SGL53.js";
 import "./chunk-GZCUW5IC.js";
+import "./chunk-LK6SGL53.js";
 import "./chunk-EJI5XIBB.js";
-import "./chunk-QKAH5B6E.js";
-import "./chunk-KEG4GNGI.js";
+import "./chunk-3GXCSUXR.js";
+import "./chunk-XZ2TIKGC.js";
 import "./chunk-ODWDQNRE.js";
 import "./chunk-Y27UJK6V.js";
 import "./chunk-UZB5KHKX.js";

package/dist/fallback-llm.d.ts

@@ -16,6 +16,10 @@ interface FallbackLlmResponse {
         totalTokens?: number;
     };
 }
+interface FallbackLlmRuntimeContext {
+    agentDir?: string;
+    workspaceDir?: string;
+}
 /**
  * Generic fallback LLM client that uses the gateway's default AI configuration
  * and walks through the full fallback chain (primary + fallbacks).
@@ -23,7 +27,8 @@ interface FallbackLlmResponse {
  */
 declare class FallbackLlmClient {
     private gatewayConfig;
-    constructor(gatewayConfig?: GatewayConfig);
+    private runtimeContext;
+    constructor(gatewayConfig?: GatewayConfig, runtimeContext?: FallbackLlmRuntimeContext);
     /**
      * Check if fallback is available (gateway config has at least one model).
      */
@@ -105,10 +110,14 @@ declare class FallbackLlmClient {
      * Call OpenAI-compatible API.
      */
     private callOpenAI;
+    /**
+     * Call an OpenAI-compatible Responses API.
+     */
+    private callOpenAIResponses;
     /**
      * Call Anthropic Messages API.
      */
     private callAnthropic;
 }
 
-export { FallbackLlmClient, type FallbackLlmOptions, type FallbackLlmResponse };
+export { FallbackLlmClient, type FallbackLlmOptions, type FallbackLlmResponse, type FallbackLlmRuntimeContext };

package/dist/fallback-llm.js

@@ -1,7 +1,7 @@
 import {
   FallbackLlmClient
-} from "./chunk-QKAH5B6E.js";
-import "./chunk-KEG4GNGI.js";
+} from "./chunk-3GXCSUXR.js";
+import "./chunk-XZ2TIKGC.js";
 import "./chunk-ODWDQNRE.js";
 import "./chunk-Y27UJK6V.js";
 import "./chunk-UZB5KHKX.js";

package/dist/graph-recall.d.ts

@@ -0,0 +1,100 @@
+import { MemoryEdgeSource, RemnicGraph } from './graph-retrieval.js';
+
+/**
+ * Graph-based retrieval integration (issue #559 PR 4 of 5).
+ *
+ * Pure helper that composes `extractGraphEdges` (PR 2) and `queryGraph`
+ * (PR 3) into a single retrieval surface. Operators opt in via the
+ * `recallGraphEnabled` config flag; until the `retrieval-graph` bench in
+ * PR 5 justifies flipping the default, this tier ships disabled.
+ *
+ * Kept as a pure function so the orchestrator can call it with whatever
+ * candidate pool it has (hot cache, recent window, QMD first-pass, etc.)
+ * without forcing a specific storage contract on this module.
+ */
+
+/**
+ * Subset of `PluginConfig` that governs the graph retrieval tier. Kept
+ * as a local interface so this module does not pull in the full
+ * `PluginConfig` import — `orchestrator.ts` can pass the fields directly.
+ */
+interface GraphRecallConfig {
+    /** Master enable flag. When false, `runGraphRecall` is a no-op. */
+    recallGraphEnabled: boolean;
+    /** PPR damping factor (default 0.85). */
+    recallGraphDamping: number;
+    /** PPR power-iteration cap (default 20). */
+    recallGraphIterations: number;
+    /**
+     * Max memories the graph tier returns. `0` disables the tier's
+     * contribution without touching `recallGraphEnabled`.
+     */
+    recallGraphTopK: number;
+}
+/** Per-invocation options for `runGraphRecall`. */
+interface GraphRecallOptions {
+    /**
+     * Candidate memories to build the graph from. Typically the caller's
+     * recall candidate pool (hot cache + QMD first-pass). The extractor
+     * reads only the fields declared on `MemoryEdgeSource` — callers can
+     * safely pass richer memory objects.
+     */
+    memories: readonly MemoryEdgeSource[];
+    /**
+     * Seed memory / entity ids produced by the query-to-graph matcher.
+     * Typically the ids of the top QMD hits plus any entity-exact matches.
+     * If empty, PPR falls back to a uniform distribution over graph nodes.
+     */
+    seedIds: readonly string[];
+    /**
+     * Optional per-seed weights. When provided, PPR starts from the
+     * weighted distribution instead of uniform-over-seeds.
+     */
+    seedWeights?: ReadonlyMap<string, number> | Readonly<Record<string, number>>;
+}
+/** A single result from the graph tier. */
+interface GraphRecallResult {
+    /** Memory id (the `to` of the highest-scoring `memory`-typed node). */
+    id: string;
+    /** PPR score in [0, 1]. Higher is better. */
+    score: number;
+}
+/** The full shape returned by `runGraphRecall`. */
+interface GraphRecallRun {
+    /**
+     * Whether the graph tier actually ran. `false` when `recallGraphEnabled`
+     * is `false` or `recallGraphTopK <= 0` — in both cases `results` is `[]`
+     * and `reason` indicates which gate short-circuited.
+     */
+    ran: boolean;
+    /**
+     * Memory-typed ranked results. Entity / agent nodes are filtered out
+     * because the orchestrator merges this list with memory-typed QMD
+     * results via MMR.
+     */
+    results: GraphRecallResult[];
+    /** The graph that was built (or `null` if the tier did not run). */
+    graph: RemnicGraph | null;
+    /** Debugging tag for tier-explain surfaces. */
+    reason: "ran" | "disabled" | "topk-zero" | "empty-input";
+    /** Number of power-iteration rounds that executed. */
+    iterations: number;
+    /** Whether PPR's L1 delta fell below tolerance before the iter cap. */
+    converged: boolean;
+}
+/**
+ * Pure graph retrieval run.
+ *
+ * 1. Short-circuits to `{ ran: false }` when the feature flag is off,
+ *    `topK <= 0`, or the memory pool is empty. No graph is built, no
+ *    PPR runs — this preserves the zero-cost guarantee for
+ *    `recallGraphEnabled: false` (the default).
+ * 2. Otherwise builds the retrieval graph from the candidate pool via
+ *    `buildGraphFromMemories` (PR 2 extractor).
+ * 3. Runs Personalized PageRank via `queryGraph` (PR 3).
+ * 4. Projects ranked nodes to memory-typed ids only — entity and agent
+ *    nodes never appear in the recall result set.
+ */
+declare function runGraphRecall(config: GraphRecallConfig, options: GraphRecallOptions): GraphRecallRun;
+
+export { type GraphRecallConfig, type GraphRecallOptions, type GraphRecallResult, type GraphRecallRun, runGraphRecall };

package/dist/graph-recall.js

@@ -0,0 +1,8 @@
+import {
+  runGraphRecall
+} from "./chunk-DGVM5SFL.js";
+import "./chunk-64NJRYU2.js";
+export {
+  runGraphRecall
+};
+//# sourceMappingURL=graph-recall.js.map

package/dist/graph-recall.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/graph-retrieval.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Graph-based retrieval types (issue #559, PR 1 of 5).
+ *
+ * This module defines the forward-looking type contract for Remnic's
+ * first-class retrieval graph (GAAMA / GAM inspired). It ships types
+ * and a no-op `queryGraph()` stub only — no behavior, no I/O, and
+ * no importers inside the codebase yet.
+ *
+ * Subsequent slices will land:
+ *   - PR 2: Edge extraction from existing relationship facts + cross-memory
+ *           entity references during indexing (writes `~/.remnic/graph.json`).
+ *   - PR 3: Pure `personalizedPageRank()` implementation.
+ *   - PR 4: Feature-flagged wiring into `retrieval.ts` behind
+ *           `graphRetrievalEnabled` (default `false`).
+ *   - PR 5: LoCoMo A/B bench harness + default flip decision.
+ *
+ * Keeping the node/edge type enums complete from PR 1 avoids type churn
+ * when later slices add reflection/concept node synthesis or additional
+ * edge semantics.
+ */
+/**
+ * Kinds of nodes the retrieval graph can hold.
+ *
+ * - `memory`:     a stored memory file (the primary retrieval target).
+ * - `entity`:     a named entity referenced by one or more memories.
+ * - `episode`:    a temporally-bounded interaction or session grouping.
+ * - `concept`:    an abstract topic / idea (forward-looking; synthesis
+ *                 is out of scope for this issue, but the type is
+ *                 defined here to keep later slices additive).
+ * - `reflection`: an LLM-generated summary / meta-memory about other
+ *                 nodes (also forward-looking, same rationale).
+ */
+type NodeType = "memory" | "entity" | "episode" | "concept" | "reflection";
+/**
+ * Kinds of edges the retrieval graph can hold.
+ *
+ * Edges are directed. `from` → `to` semantics:
+ *
+ * - `references`:    `from` contains an explicit reference to `to`
+ *                    (e.g., a memory referencing another memory).
+ * - `supersedes`:    `from` supersedes `to` (newer memory replaces older).
+ * - `authored-by`:   `from` was authored by the entity in `to`.
+ * - `mentions`:      `from` mentions the entity/concept in `to` without
+ *                    a stronger relationship claim.
+ * - `derived-from`:  `from` was derived from `to` (reflections,
+ *                    consolidations, summaries).
+ * - `temporal-next`: `from` immediately follows `to` in time (episodes).
+ * - `related-to`:    generic weak relationship fallback for edges that
+ *                    do not fit a stronger type.
+ */
+type EdgeType = "references" | "supersedes" | "authored-by" | "mentions" | "derived-from" | "temporal-next" | "related-to";
+/**
+ * A single node in the retrieval graph.
+ *
+ * `id` is the caller-controlled stable identifier (typically a memory
+ * file path, entity slug, or episode id). `weight` is an optional prior
+ * importance score used as a starting bias during Personalized PageRank;
+ * it is intentionally optional because most nodes default to uniform
+ * priors.
+ *
+ * Named `RemnicGraphNode` (not `GraphNode`) to avoid colliding with the
+ * unrelated `GraphEdge` in `graph.ts`, which models Multi-Graph Memory
+ * (MAGMA/SYNAPSE) edges and is an incompatible shape.
+ */
+interface RemnicGraphNode {
+    id: string;
+    type: NodeType;
+    weight?: number;
+}
+/**
+ * A directed edge between two nodes.
+ *
+ * `weight` is optional; when absent PPR implementations should treat
+ * the edge as weight `1`. We keep weight optional rather than defaulting
+ * at construction so producers can serialize a minimal edge shape.
+ *
+ * Named `RemnicGraphEdge` (not `GraphEdge`) to avoid colliding with the
+ * unrelated `GraphEdge` in `graph.ts` (Multi-Graph Memory).
+ */
+interface RemnicGraphEdge {
+    from: string;
+    to: string;
+    type: EdgeType;
+    weight?: number;
+}
+/**
+ * The retrieval graph itself.
+ *
+ * Nodes are held in a `Map<string, RemnicGraphNode>` keyed by `id` so
+ * PPR lookups are O(1). Edges are kept as a flat array; adjacency
+ * indexing is a PR-3 concern (PPR will likely build a transient
+ * outgoing-adjacency map on demand).
+ */
+interface RemnicGraph {
+    nodes: Map<string, RemnicGraphNode>;
+    edges: RemnicGraphEdge[];
+}
+/**
+ * Options for `queryGraph()`.
+ *
+ * Defaults (applied when undefined):
+ *   - `damping`:    0.85 (standard PageRank value — higher values make the
+ *                   random walk follow edges longer before teleporting back
+ *                   to the seed distribution).
+ *   - `iterations`: 20 (power-iteration cap).
+ *   - `tolerance`:  1e-6 (L1 convergence threshold; iteration stops early
+ *                   when the L1 norm of the delta between successive
+ *                   rank vectors falls below this).
+ *   - `topK`:       unbounded — all nodes with positive score are returned,
+ *                   ordered by descending score.
+ */
+interface QueryGraphOptions {
+    /** Number of top-ranked nodes to return. Defaults to unbounded. */
+    topK?: number;
+    /**
+     * PPR damping factor in (0, 1). The probability of following an outgoing
+     * edge at each step (vs. teleporting back to the seed distribution).
+     * Defaults to 0.85.
+     */
+    damping?: number;
+    /** Maximum PPR iterations before falling back to current rank vector. */
+    iterations?: number;
+    /** L1 convergence threshold. Defaults to 1e-6. */
+    tolerance?: number;
+    /**
+     * Optional per-seed weights. Keys must appear in `seedIds` or (if empty)
+     * in the graph. Values must be non-negative. Weights are normalized so
+     * they sum to 1 before seeding. If omitted, seed mass is distributed
+     * uniformly across `seedIds`.
+     */
+    seedWeights?: ReadonlyMap<string, number> | Readonly<Record<string, number>>;
+}
+/**
+ * A scored node returned by `queryGraph()`.
+ */
+interface RankedGraphNode {
+    id: string;
+    score: number;
+}
+/**
+ * The shape returned by `queryGraph()`.
+ */
+interface QueryGraphResult {
+    rankedNodes: RankedGraphNode[];
+    /** Number of power-iteration rounds actually executed. */
+    iterations: number;
+    /** L1 delta at the last iteration. */
+    converged: boolean;
+}
+/** PPR damping factor default. */
+declare const DEFAULT_PPR_DAMPING = 0.85;
+/** Power-iteration cap default. */
+declare const DEFAULT_PPR_ITERATIONS = 20;
+/** L1 convergence threshold default. */
+declare const DEFAULT_PPR_TOLERANCE = 0.000001;
+/**
+ * Personalized PageRank via power iteration.
+ *
+ * Pure function — no I/O. Deterministic given the same graph and options.
+ *
+ * Algorithm:
+ *
+ *   r_{t+1}(v) = (1 - d) * s(v)
+ *              + d * Σ_{u → v} r_t(u) * w(u,v) / Σ_w w(u,·)
+ *              + d * (dangling mass) * s(v)
+ *
+ * where:
+ *   - `d` is the damping factor (default 0.85).
+ *   - `s` is the seed vector (normalized personalization distribution).
+ *   - dangling mass is the total rank on nodes with no outgoing edges,
+ *     redistributed over the seed vector so probability mass is conserved.
+ *
+ * The loop stops early when `|r_{t+1} - r_t|_1 < tolerance` or after
+ * `iterations` rounds, whichever comes first.
+ *
+ * Edge cases:
+ *   - Empty graph → `{ rankedNodes: [], iterations: 0, converged: true }`.
+ *   - Seed ids that are not in the graph are silently dropped.
+ *   - If no in-graph seed mass remains (empty seed or all seeds missing),
+ *     the uniform distribution over graph nodes is used — matching
+ *     standard PageRank semantics.
+ *   - `damping` is clamped to `[0, 1)` (a damping of exactly 1 would make
+ *     the chain non-ergodic; damping of exactly 0 reduces to the seed
+ *     distribution).
+ *   - `topK <= 0` returns an empty ranked list (but the `iterations` and
+ *     `converged` fields still reflect the actual computation).
+ */
+declare function queryGraph(graph: RemnicGraph, seedIds: readonly string[], options?: QueryGraphOptions): QueryGraphResult;
+/** Returns true iff `value` is a valid `NodeType`. */
+declare function isNodeType(value: unknown): value is NodeType;
+/** Returns true iff `value` is a valid `EdgeType`. */
+declare function isEdgeType(value: unknown): value is EdgeType;
+/**
+ * Minimum fields the edge extractor reads from a memory record. Structural
+ * typing is used so callers can pass any subset of `MemoryFrontmatter`
+ * (including richer loaded memories) without a cast.
+ *
+ * All reference fields are optional — memories written before earlier slices
+ * landed will simply contribute no edges for those dimensions.
+ */
+interface MemoryEdgeSource {
+    /** Stable identifier for the memory (typically the file path). */
+    id: string;
+    /** Older memory id this memory supersedes (1:1). */
+    supersedes?: string;
+    /** Parent memory ids this memory was derived from (lineage). */
+    lineage?: string[];
+    /**
+     * Consolidation provenance — `"<memory-id>:<version-number>"` strings.
+     * The memory-id portion before the last `:` is used as the edge target.
+     */
+    derived_from?: string[];
+    /** Primary entity reference on the memory (e.g. `person:Jane Doe`). */
+    entityRef?: string;
+    /** Additional entity references (used by episodes and ledger records). */
+    entityRefs?: string[];
+    /** Raw memory body — scanned for inline `[Source: ...]` citation blocks. */
+    content?: string;
+}
+/** Options controlling edge extraction. */
+interface ExtractGraphEdgesOptions {
+    /**
+     * When true, include edges whose `to` endpoint is not present in the
+     * provided node index. Defaults to `false` — dangling edges are silently
+     * skipped because PPR cannot propagate mass through a missing node.
+     */
+    includeDanglingEdges?: boolean;
+}
+/**
+ * Extract retrieval-graph edges from a collection of memories.
+ *
+ * Pure function — no I/O, no config access, no time-based side effects.
+ * Given the same inputs, always produces the same edges in the same order
+ * so dedup downstream is deterministic.
+ *
+ * Source → target semantics by edge type:
+ *
+ *   - `supersedes`:    memory → older memory (from `supersedes` field).
+ *   - `derived-from`:  memory → each parent in `lineage` OR `derived_from`.
+ *   - `mentions`:      memory → each entity in `entityRef` / `entityRefs`.
+ *   - `authored-by`:   memory → agent id parsed from inline `[Source: ...]`.
+ *
+ * `temporal-next`, `references`, `related-to`, and `concept` / `reflection`
+ * node synthesis are deferred to later slices — they require either episode
+ * sequencing or an abstraction synthesis pass that is out of scope for PR 2.
+ *
+ * @param memories     Memories to scan. Order is preserved; duplicates are
+ *                     not deduped (the caller controls the input set).
+ * @param options      Extraction knobs. See `ExtractGraphEdgesOptions`.
+ * @returns            A `{ nodes, edges }` pair. `nodes` contains one
+ *                     `memory` node per input memory plus one `entity` node
+ *                     per distinct entity discovered across all mentions.
+ *                     Edges reference ids in the returned node map unless
+ *                     `includeDanglingEdges` is set.
+ */
+declare function extractGraphEdges(memories: readonly MemoryEdgeSource[], options?: ExtractGraphEdgesOptions): {
+    nodes: Map<string, RemnicGraphNode>;
+    edges: RemnicGraphEdge[];
+};
+/**
+ * Build a `RemnicGraph` from a collection of memories by delegating to
+ * `extractGraphEdges()`. Convenience wrapper so callers do not have to
+ * re-wrap the `{ nodes, edges }` pair into the `RemnicGraph` interface.
+ *
+ * Pure function — no I/O. Persisting the graph (e.g. writing
+ * `~/.remnic/graph.json`) is left to the caller; that decision belongs with
+ * the maintenance / consolidation pass in PR 4, not the extractor.
+ */
+declare function buildGraphFromMemories(memories: readonly MemoryEdgeSource[], options?: ExtractGraphEdgesOptions): RemnicGraph;
+
+export { DEFAULT_PPR_DAMPING, DEFAULT_PPR_ITERATIONS, DEFAULT_PPR_TOLERANCE, type EdgeType, type ExtractGraphEdgesOptions, type MemoryEdgeSource, type NodeType, type QueryGraphOptions, type QueryGraphResult, type RankedGraphNode, type RemnicGraph, type RemnicGraphEdge, type RemnicGraphNode, buildGraphFromMemories, extractGraphEdges, isEdgeType, isNodeType, queryGraph };

package/dist/graph-retrieval.js

@@ -0,0 +1,21 @@
+import {
+  DEFAULT_PPR_DAMPING,
+  DEFAULT_PPR_ITERATIONS,
+  DEFAULT_PPR_TOLERANCE,
+  buildGraphFromMemories,
+  extractGraphEdges,
+  isEdgeType,
+  isNodeType,
+  queryGraph
+} from "./chunk-64NJRYU2.js";
+export {
+  DEFAULT_PPR_DAMPING,
+  DEFAULT_PPR_ITERATIONS,
+  DEFAULT_PPR_TOLERANCE,
+  buildGraphFromMemories,
+  extractGraphEdges,
+  isEdgeType,
+  isNodeType,
+  queryGraph
+};
+//# sourceMappingURL=graph-retrieval.js.map

package/dist/graph-retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/harmonic-retrieval.js

@@ -1,7 +1,8 @@
 import {
   searchHarmonicRetrieval
-} from "./chunk-AAI7JARD.js";
+} from "./chunk-HMDCOMYU.js";
 import "./chunk-C6QPK5GG.js";
+import "./chunk-PVGDJXVK.js";
 import "./chunk-NGAVDO7E.js";
 import "./chunk-DT5TVLJE.js";
 import "./chunk-DGXUHMOV.js";