@atrib/recall 0.3.1 → 0.5.0

package/README.md

@@ -2,27 +2,85 @@
 
 MCP server for atrib. Lets agents query their own provable past from the local signed-record mirror with per-record signature verification.
 
-The consumer-side counterpart to `@atrib/emit`: emit produces signed records, recall reads them back and exposes them to the agent through one tool, `recall_my_attribution_history`. Each returned record carries a `signature_verified` boolean so a poorly-written agent treats tampered records as such.
+The consumer-side counterpart to `@atrib/emit`: emit produces signed records, recall reads them back and exposes them to the agent through five MCP tools. Each returned record carries a `signature_verified` boolean so a poorly-written agent treats tampered records as such.
 
 ## Tool surface
 
+Five MCP tools cover the cognitive surface of the local mirror.
+
+### `recall_my_attribution_history`
+
+The base filter-rank-page tool over the local mirror.
+
 ```typescript
 mcp__atrib-recall__recall_my_attribution_history({
   // All optional
   context_id?: string,           // 32-hex. Filter to records signed under this trace.
-  event_type?: 'tool_call' | 'transaction',  // Filter to a single event kind.
-                                              // Short-form names are normalized to the URI form.
+  event_type?: 'tool_call' | 'transaction' | 'annotation' | 'revision',
+                                 // Filter to a single event kind. Short-form names are normalized
+                                 // to the URI form.
+  content_id?: string,           // sha256:... exact match on §1.2.2 content_id.
+  tool_name?: string,            // §8.2 disclosed tool name; records without disclosure excluded.
+  args_hash?: string,            // sha256:... §8.3 args_hash exact match.
   limit?: number,                // Default 25, max 200.
   offset?: number,               // For pagination. Note pagination_caveat in the response.
-  compact?: boolean,             // Default true — omits signature/content_id/chain_root/spec_version
+  compact?: boolean,             // Default true - omits signature/content_id/chain_root/spec_version
                                  // fields. Set false for full record bytes (re-verification).
-  include_unverified?: boolean,  // Default false — drops records whose signature didn't verify.
+  include_unverified?: boolean,  // Default false - drops records whose signature didn't verify.
                                  // Set true ONLY when consuming the verbose mode AND explicitly
                                  // checking signature_verified per record.
+
+  // Annotation- and revision-driven filters. Records with no incident
+  // annotation are excluded when min_importance or topic_tags is set;
+  // records that have a revision pointing at them surface superseded_by
+  // by default and are hidden when include_revised=true.
+  min_importance?: 'critical' | 'high' | 'medium' | 'low' | 'noise',
+  topic_tags?: string[],         // OR-match against annotation topic_tags.
+  include_revised?: boolean,     // True hides records superseded by a D059 revision.
+  min_signers?: number,          // Distinct-signer threshold; 1 for non-transaction records.
+
+  // Ranking.
+  rank_by?: 'timestamp' | 'relevance' | 'causal_distance',
+                                 // 'timestamp' (default): newest first.
+                                 // 'relevance': Park et al. weighted-sum scoring (recency +
+                                 //   annotation-derived importance + BM25 against rank_anchor).
+                                 // 'causal_distance': BFS shortest-path from rank_anchor over
+                                 //   the local derived graph (CHAIN_PRECEDES, INFORMED_BY,
+                                 //   ANNOTATES, REVISES).
+  rank_anchor?: string,          // record_hash for causal_distance, free-form query for relevance.
+
+  // Response shape.
+  toc?: boolean,                 // Default false. True returns the ~40-80-token-per-entry
+                                 // table-of-contents shape (record_hash, tool_name, summary,
+                                 // importance, topic_tags, timestamp, superseded_by) suitable
+                                 // for SessionStart auto-injected scaffolds.
 })
 ```
 
-Returns a `RecallResult` with `total`, `returned`, `filtered_out_by_verification`, `record_file`, `log_origin`, `pagination_caveat`, and `records` (compact or full per the flag).
+Returns `{ total, returned, filtered_out_by_verification, record_files, record_file, log_origin, pagination_caveat, records }`. Each record carries `annotations` (when annotation records point at it) and `superseded_by` (when revision records point at it).
+
+### Sibling tools
+
+- `mcp__atrib-recall__recall_walk({ from_record_hash, edge_types?, depth? })` - walks the local derived graph from `from_record_hash` up to `depth` hops (default 3), returning each reachable record_hash + weighted distance. Edge types: CHAIN_PRECEDES (weight 1), INFORMED_BY (weight 1), ANNOTATES (weight 2), REVISES (weight 2). SESSION_PRECEDES, SESSION_PARALLEL, CONVERGES_ON, CROSS_SESSION, and PROVENANCE_OF are deferred to subsequent releases.
+
+- `mcp__atrib-recall__recall_annotations({ record_hash })` - returns the aggregated annotation summary (max_importance, union of topics, latest summary) for the target record. Returns `annotations: null` when no annotation points at the record.
+
+- `mcp__atrib-recall__recall_revisions({ record_hash })` - returns the forward revision chain for the target record. Each entry's revises field points at the prior entry; the chain follows the first-by-timestamp revision at each step. Sibling fan-out (parallel revisions of the same target) requires calling `recall_my_attribution_history` with event_type=revision and inspecting `content.revises` manually.
+
+- `mcp__atrib-recall__recall_by_content({ query, k? })` - BM25 free-form retrieval over each record's annotation summary + topic_tags, then reranked by Park et al. weighted-sum scoring (recency + importance + relevance). Default k=10, max 50. Records with no annotation contribute no relevance signal (will only surface via the recency + importance fallback). Layer 2 (sqlite-vec sidecar, separate ship) extends with embedding similarity over the same indexed text.
+
+### Tunable weights
+
+The Park et al. ranking weights and recency time constant are environment-tunable for per-axis sensitivity studies:
+
+| Env var | Default | Role |
+|---|---|---|
+| `ATRIB_RECALL_ALPHA` | 0.3 | Recency component weight |
+| `ATRIB_RECALL_BETA` | 0.3 | Importance component weight |
+| `ATRIB_RECALL_GAMMA` | 0.4 | Relevance (BM25) component weight |
+| `ATRIB_RECALL_TAU_DAYS` | 7 | Exponential-decay time constant for recency |
+
+The implementation does not enforce that alpha + beta + gamma sum to 1.0; the operator-facing defaults do.
 
 ## Trust scope
 
@@ -32,9 +90,12 @@ Signature verification is local-only. A passing `signature_verified` proves the
 
 | Env var | Required | Purpose |
 |---|---|---|
-| `ATRIB_RECORD_FILE` | optional | Path to the signed-record jsonl mirror to read. Default: `~/.atrib/records/mcp-wrap-claude-code.jsonl` |
+| `ATRIB_RECORD_FILE` | optional | Path to a single signed-record jsonl mirror to read. When set, overrides directory scanning. Back-compat with pre-0.4.0 callers that pinned a specific producer's mirror. No default. |
+| `ATRIB_MIRROR_DIR` | optional | Directory to scan; recall reads every `*.jsonl` inside. Default: `~/.atrib/records/` (the spec [§5.9](../../atrib-spec.md#59-local-mirror-conventions) well-known per-agent mirror namespace). When unset, this is the path used. |
 | `ATRIB_LOG_ORIGIN` | optional | Origin used in human-readable response messages. Default: `log.atrib.dev` |
 
+**Mirror discovery priority** (per spec [§5.9](../../atrib-spec.md#59-local-mirror-conventions)): if `ATRIB_RECORD_FILE` is set, recall reads that single file. Otherwise recall scans `ATRIB_MIRROR_DIR` and merges every `*.jsonl` inside. The directory-scan default unifies recall across producers without recall having to know per-producer naming conventions; any producer that follows the spec convention just shows up.
+
 ## Installation in an MCP host
 
 ```jsonc

package/dist/aggregations.d.ts

@@ -0,0 +1,114 @@
+import type { AtribRecord } from '@atrib/mcp';
+import type { ImportanceLabel } from './index.js';
+/**
+ * A mirror record paired with its D062 sidecar content (when present) and
+ * its content-addressable record_hash (computed at load time). The
+ * record_hash form is `sha256:<64-hex>` per spec §2.3 — matches what the
+ * log entries commit to and what `informed_by` / `content.annotates` /
+ * `content.revises` reference.
+ *
+ * `content` is the deserialized `_local.content` from a D062 envelope mirror
+ * line. Producers writing bare AtribRecord lines (legacy / non-envelope)
+ * yield `content: undefined` here; annotation aggregation simply skips
+ * those records (the §8.1 posture: no body disclosed). Code that wants to
+ * read annotation importance / topics / summary MUST handle the undefined
+ * case.
+ */
+export type LoadedRecord = {
+    record: AtribRecord;
+    record_hash: string;
+    content?: unknown;
+};
+/**
+ * Compute the spec §2.3 record_hash for an AtribRecord: sha256 over the
+ * JCS-canonical serialization including the signature field. Matches the
+ * pattern in `packages/openinference/test/informed-by.test.ts`
+ * and the in-tree atrib-span-processor build output. Kept local to
+ * atrib-recall for now — when a third caller appears, lift to `@atrib/mcp`.
+ */
+export declare function computeRecordHash(record: AtribRecord): string;
+/**
+ * Load a single jsonl mirror file as LoadedRecord[]. Each line's
+ * record_hash is computed once at load; subsequent lookups are O(1).
+ * Malformed lines are silently skipped (same contract as `loadRecords`).
+ */
+export declare function loadLoaded(path: string): LoadedRecord[];
+/**
+ * Mirror-discovery variant of `loadLoaded` that scans a directory of
+ * `*.jsonl` files. See loadRecordsFromDir in index.ts for the bare
+ * AtribRecord equivalent. Files that don't exist or aren't readable are silently
+ * skipped (a file rotated mid-scan shouldn't error the whole call).
+ * Returns the union of loaded entries plus the list of files scanned.
+ */
+export declare function loadLoadedFromDir(dir: string): {
+    loaded: LoadedRecord[];
+    files: string[];
+};
+/**
+ * LoadedRecord variant of `discoverRecords` in index.ts. Same priority
+ * order: explicit `recordFile` arg > ATRIB_RECORD_FILE env > ATRIB_MIRROR_DIR
+ * scan. Re-evaluates env vars on each call so test harnesses that mutate
+ * process.env per-test get the value they set.
+ */
+export declare function discoverLoaded(recordFile?: string): {
+    loaded: LoadedRecord[];
+    files: string[];
+};
+/**
+ * Per-record annotation summary: max importance across all annotations
+ * pointing at the record (or undefined if none), the union of all
+ * topic_tags arrays carried by those annotations, and the most-recent
+ * summary string. "Most recent" here means the last annotation by
+ * timestamp; ties (rare in practice) resolve to the last array index
+ * (mirror order).
+ *
+ * Matches the AnnotationSummary type declared in `index.ts`. Kept as a
+ * separate exported type so future callers (e.g. the public
+ * recall_annotations handler) can return this shape without depending
+ * on the recall server's internal types.
+ */
+export type AnnotationSummary = {
+    max_importance?: ImportanceLabel;
+    topics?: string[];
+    summary?: string;
+};
+/**
+ * Walk loaded records, identify D058 annotation records, and bin them by
+ * `content.annotates` target. Returns Map<target_record_hash,
+ * AnnotationSummary>. Records with no annotations pointing at them
+ * receive no entry (callers should default to undefined).
+ *
+ * Annotation records WITHOUT a `_local.content` sidecar (legacy bare
+ * mirrors that didn't preserve content) are skipped entirely; the §8.1
+ * privacy posture means the annotation's importance / topics / summary
+ * are not knowable from the public AtribRecord alone.
+ *
+ * Spec references:
+ *   - D058: annotation event_type byte 0x05, URI form annotation
+ *   - §8.3: salted-commitment posture (body lives in _local; log has only content_id)
+ *   - §1.2.4: event_type URI form (required for annotation records)
+ */
+export declare function aggregateAnnotationsByRecord(loaded: LoadedRecord[]): Map<string, AnnotationSummary>;
+/**
+ * Walk loaded records, identify D059 revision records, and bin them by
+ * `content.revises` target. Returns Map<target_record_hash,
+ * revision_record_hashes[]>. The value array contains the record_hashes
+ * of every revision pointing at the target (immediate revisions only;
+ * chain traversal is the caller's responsibility — the recall_revisions
+ * handler walks the chain by recursing on each revision's own hash).
+ *
+ * The returned value array is ordered by revision timestamp ascending so
+ * the caller sees revisions in the order they were issued. Ties resolve
+ * to mirror-iteration order.
+ *
+ * Revision records WITHOUT a `_local.content` sidecar are skipped per the
+ * §8.1 bare-record posture — without content, the `revises` target is
+ * unknowable. Revision records WITH content but no `revises` field are
+ * also skipped (the revision is malformed).
+ *
+ * Spec references:
+ *   - D059: revision event_type byte 0x06, URI form revision
+ *   - §8.3: salted-commitment posture (body lives in _local; log has only content_id)
+ *   - §1.2.4: event_type URI form (required for revision records)
+ */
+export declare function aggregateRevisionsByRecord(loaded: LoadedRecord[]): Map<string, string[]>;

package/dist/aggregations.js

@@ -0,0 +1,267 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Layer 1 aggregation helpers for the recall semantic surface.
+ *
+ * Annotation records (D058, event_type = EVENT_TYPE_ANNOTATION_URI) carry
+ * their importance + topic_tags + summary in `content.*`, with the target
+ * record_hash in `content.annotates`. Per the §8.3 privacy posture the
+ * public log carries only content_id (kind hash); the actual content body
+ * lives in the local mirror's D062 envelope at `_local.content`. To compute
+ * "what annotations does record X have?" the recall server must walk the
+ * mirror, recover `_local.content` per envelope, and bin annotations by
+ * their `content.annotates` target.
+ *
+ * This module isolates that walk + bin step plus the record_hash helper
+ * needed to key the result map. The existing `loadRecords` / `recall` paths
+ * in `index.ts` deal in bare AtribRecord[] and stay unchanged; the Layer 1
+ * filter / ranking wire-up will compose `loadLoaded` ->
+ * `aggregateAnnotationsByRecord` -> filter alongside the existing recall
+ * flow.
+ *
+ * Revision aggregation (D059) is a near-identical shape that will land
+ * alongside; the structure here is designed to extend.
+ */
+import { canonicalRecord, sha256, hexEncode, EVENT_TYPE_ANNOTATION_URI, EVENT_TYPE_REVISION_URI, } from '@atrib/mcp';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { IMPORTANCE_NUMERIC } from './index.js';
+/**
+ * Compute the spec §2.3 record_hash for an AtribRecord: sha256 over the
+ * JCS-canonical serialization including the signature field. Matches the
+ * pattern in `packages/openinference/test/informed-by.test.ts`
+ * and the in-tree atrib-span-processor build output. Kept local to
+ * atrib-recall for now — when a third caller appears, lift to `@atrib/mcp`.
+ */
+export function computeRecordHash(record) {
+    return `sha256:${hexEncode(sha256(canonicalRecord(record)))}`;
+}
+/**
+ * Pull the inner AtribRecord and the D062 `_local.content` out of one
+ * parsed mirror line. Returns null when the line is neither shape or is
+ * missing the required AtribRecord fields. The shape contract mirrors
+ * `extractRecord` in `index.ts` exactly; the only addition is the optional
+ * `content` field carried back. Kept as a separate function (rather than
+ * augmenting `extractRecord`) so the existing recall flow's signature
+ * stays AtribRecord[].
+ */
+function extractLoaded(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    const envelopeRecord = (typeof obj.record === 'object' && obj.record !== null)
+        ? obj.record
+        : null;
+    const candidate = envelopeRecord ?? obj;
+    if (typeof candidate.spec_version !== 'string' ||
+        typeof candidate.event_type !== 'string' ||
+        typeof candidate.context_id !== 'string' ||
+        typeof candidate.creator_key !== 'string' ||
+        typeof candidate.chain_root !== 'string' ||
+        typeof candidate.signature !== 'string') {
+        return null;
+    }
+    const record = candidate;
+    if (envelopeRecord !== null) {
+        const local = obj._local ?? undefined;
+        if (local && 'content' in local) {
+            return { record, content: local.content };
+        }
+    }
+    return { record };
+}
+/**
+ * Load a single jsonl mirror file as LoadedRecord[]. Each line's
+ * record_hash is computed once at load; subsequent lookups are O(1).
+ * Malformed lines are silently skipped (same contract as `loadRecords`).
+ */
+export function loadLoaded(path) {
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    const raw = readFileSync(path, 'utf8');
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const extracted = extractLoaded(parsed);
+        if (!extracted)
+            continue;
+        out.push({
+            record: extracted.record,
+            record_hash: computeRecordHash(extracted.record),
+            content: extracted.content,
+        });
+    }
+    return out;
+}
+/**
+ * Mirror-discovery variant of `loadLoaded` that scans a directory of
+ * `*.jsonl` files. See loadRecordsFromDir in index.ts for the bare
+ * AtribRecord equivalent. Files that don't exist or aren't readable are silently
+ * skipped (a file rotated mid-scan shouldn't error the whole call).
+ * Returns the union of loaded entries plus the list of files scanned.
+ */
+export function loadLoadedFromDir(dir) {
+    if (!existsSync(dir))
+        return { loaded: [], files: [] };
+    let entries = [];
+    try {
+        entries = readdirSync(dir).filter((name) => name.endsWith('.jsonl'));
+    }
+    catch {
+        return { loaded: [], files: [] };
+    }
+    const loaded = [];
+    const files = [];
+    for (const name of entries) {
+        const full = join(dir, name);
+        try {
+            const stat = statSync(full);
+            if (!stat.isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const partial = loadLoaded(full);
+        files.push(full);
+        if (partial.length > 0)
+            loaded.push(...partial);
+    }
+    return { loaded, files };
+}
+/**
+ * LoadedRecord variant of `discoverRecords` in index.ts. Same priority
+ * order: explicit `recordFile` arg > ATRIB_RECORD_FILE env > ATRIB_MIRROR_DIR
+ * scan. Re-evaluates env vars on each call so test harnesses that mutate
+ * process.env per-test get the value they set.
+ */
+export function discoverLoaded(recordFile) {
+    const envFile = process.env.ATRIB_RECORD_FILE;
+    const envDir = process.env.ATRIB_MIRROR_DIR ??
+        join(process.env.HOME ?? '', '.atrib', 'records');
+    const explicit = recordFile ?? envFile;
+    if (explicit) {
+        return { loaded: loadLoaded(explicit), files: [explicit] };
+    }
+    return loadLoadedFromDir(envDir);
+}
+/**
+ * Walk loaded records, identify D058 annotation records, and bin them by
+ * `content.annotates` target. Returns Map<target_record_hash,
+ * AnnotationSummary>. Records with no annotations pointing at them
+ * receive no entry (callers should default to undefined).
+ *
+ * Annotation records WITHOUT a `_local.content` sidecar (legacy bare
+ * mirrors that didn't preserve content) are skipped entirely; the §8.1
+ * privacy posture means the annotation's importance / topics / summary
+ * are not knowable from the public AtribRecord alone.
+ *
+ * Spec references:
+ *   - D058: annotation event_type byte 0x05, URI form annotation
+ *   - §8.3: salted-commitment posture (body lives in _local; log has only content_id)
+ *   - §1.2.4: event_type URI form (required for annotation records)
+ */
+export function aggregateAnnotationsByRecord(loaded) {
+    const bins = new Map();
+    for (const lr of loaded) {
+        if (lr.record.event_type !== EVENT_TYPE_ANNOTATION_URI)
+            continue;
+        if (lr.content === undefined || lr.content === null)
+            continue;
+        if (typeof lr.content !== 'object')
+            continue;
+        const c = lr.content;
+        if (typeof c.annotates !== 'string' || c.annotates.length === 0)
+            continue;
+        const target = c.annotates;
+        const bin = bins.get(target) ?? {
+            importances: [],
+            topics: new Set(),
+            summary_ts: -Infinity,
+        };
+        if (typeof c.importance === 'string' && c.importance in IMPORTANCE_NUMERIC) {
+            bin.importances.push(c.importance);
+        }
+        if (Array.isArray(c.topic_tags)) {
+            for (const t of c.topic_tags) {
+                if (typeof t === 'string' && t.length > 0)
+                    bin.topics.add(t);
+            }
+        }
+        if (typeof c.summary === 'string' && lr.record.timestamp >= bin.summary_ts) {
+            bin.summary = c.summary;
+            bin.summary_ts = lr.record.timestamp;
+        }
+        bins.set(target, bin);
+    }
+    const out = new Map();
+    for (const [target, bin] of bins) {
+        const max_importance = bin.importances.length === 0
+            ? undefined
+            : bin.importances.reduce((a, b) => IMPORTANCE_NUMERIC[a] >= IMPORTANCE_NUMERIC[b] ? a : b);
+        const summary = {};
+        if (max_importance !== undefined)
+            summary.max_importance = max_importance;
+        if (bin.topics.size > 0)
+            summary.topics = [...bin.topics].sort();
+        if (bin.summary !== undefined)
+            summary.summary = bin.summary;
+        out.set(target, summary);
+    }
+    return out;
+}
+/**
+ * Walk loaded records, identify D059 revision records, and bin them by
+ * `content.revises` target. Returns Map<target_record_hash,
+ * revision_record_hashes[]>. The value array contains the record_hashes
+ * of every revision pointing at the target (immediate revisions only;
+ * chain traversal is the caller's responsibility — the recall_revisions
+ * handler walks the chain by recursing on each revision's own hash).
+ *
+ * The returned value array is ordered by revision timestamp ascending so
+ * the caller sees revisions in the order they were issued. Ties resolve
+ * to mirror-iteration order.
+ *
+ * Revision records WITHOUT a `_local.content` sidecar are skipped per the
+ * §8.1 bare-record posture — without content, the `revises` target is
+ * unknowable. Revision records WITH content but no `revises` field are
+ * also skipped (the revision is malformed).
+ *
+ * Spec references:
+ *   - D059: revision event_type byte 0x06, URI form revision
+ *   - §8.3: salted-commitment posture (body lives in _local; log has only content_id)
+ *   - §1.2.4: event_type URI form (required for revision records)
+ */
+export function aggregateRevisionsByRecord(loaded) {
+    const bins = new Map();
+    for (const lr of loaded) {
+        if (lr.record.event_type !== EVENT_TYPE_REVISION_URI)
+            continue;
+        if (lr.content === undefined || lr.content === null)
+            continue;
+        if (typeof lr.content !== 'object')
+            continue;
+        const c = lr.content;
+        if (typeof c.revises !== 'string' || c.revises.length === 0)
+            continue;
+        const target = c.revises;
+        const list = bins.get(target) ?? [];
+        list.push({ hash: lr.record_hash, ts: lr.record.timestamp });
+        bins.set(target, list);
+    }
+    const out = new Map();
+    for (const [target, entries] of bins) {
+        entries.sort((a, b) => a.ts - b.ts);
+        out.set(target, entries.map((e) => e.hash));
+    }
+    return out;
+}
+//# sourceMappingURL=aggregations.js.map

package/dist/aggregations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregations.js","sourceRoot":"","sources":["../src/aggregations.ts"],"names":[],"mappings":"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"}

package/dist/graph.d.ts

@@ -0,0 +1,63 @@
+import type { LoadedRecord } from './aggregations.js';
+export type EdgeType = 'CHAIN_PRECEDES' | 'INFORMED_BY' | 'ANNOTATES' | 'REVISES';
+/**
+ * Layer 1 BFS edge weights. Direct causal links (CHAIN_PRECEDES,
+ * INFORMED_BY) are weight 1; annotation/revision relationships are
+ * weight 2. The recall_walk handler accepts an edge_types filter that
+ * intersects with these four; weights apply only when an edge type
+ * passes the filter.
+ */
+export declare const EDGE_WEIGHTS: Record<EdgeType, number>;
+export type GraphEdge = {
+    type: EdgeType;
+    target: string;
+    weight: number;
+};
+/**
+ * Undirected adjacency. For each record_hash, the value is the list of
+ * edges out of that record_hash. CHAIN_PRECEDES and INFORMED_BY edges
+ * are emitted in both directions (the BFS is for "how close is X to
+ * anchor", which is symmetric); ANNOTATES and REVISES likewise.
+ */
+export type LocalGraph = Map<string, GraphEdge[]>;
+/**
+ * Build the local Layer 1 graph from loaded records. Returns adjacency
+ * map keyed by record_hash. Records present in the loaded set but with
+ * no incident edges still appear as map keys with empty arrays — this
+ * keeps the BFS path consistent (graph.has(anchor) is still true even
+ * when the anchor has no neighbors).
+ *
+ * Time complexity: O(N) for the chain index pass + O(E) for edge
+ * emission. N = loaded.length, E = sum of informed_by entries + chain
+ * links + annotation+revision edges.
+ */
+export declare function buildLocalGraph(loaded: LoadedRecord[]): LocalGraph;
+/**
+ * BFS-shortest-path distances from `start` over the local graph.
+ * Returns a map record_hash -> distance (weighted). Records with no path
+ * to `start` are omitted (rather than mapped to Infinity) so callers
+ * iterate only reachable nodes.
+ *
+ * The traversal honors `edgeTypes` when provided: only edges whose type
+ * is in the set are followed. When edgeTypes is undefined or empty,
+ * ALL edge types are followed.
+ *
+ * `maxDepth` caps the traversal at that hop-count (NOT cumulative
+ * weight). Set to Infinity (the default) to traverse the full reachable
+ * subgraph. Useful for recall_walk's depth parameter.
+ *
+ * Since edge weights differ (1 or 2), the traversal uses Dijkstra (with
+ * a simple O(V^2) min-extraction since the candidate sets are small at
+ * Layer 1). This produces correct shortest paths in weighted graphs.
+ */
+export declare function shortestDistances(graph: LocalGraph, start: string, edgeTypes?: Set<EdgeType>, maxHops?: number): Map<string, number>;
+/**
+ * Walk the graph from `start`, returning every reachable record_hash
+ * within `maxHops` hops, filtered to the requested edge_types. Result
+ * is sorted by ascending distance from start. Used by the recall_walk
+ * MCP tool to surface the local causal neighborhood of an anchor.
+ */
+export declare function walkFrom(graph: LocalGraph, start: string, edgeTypes?: Set<EdgeType>, maxHops?: number): Array<{
+    record_hash: string;
+    distance: number;
+}>;