/**
 * 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 };
