@atrib/recall 0.3.2 → 0.5.0

package/dist/graph.js

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Local graph derivation + BFS for the recall semantic surface.
+ *
+ * Wires the §3.2.4 derived-graph shape that the recall_walk handler and
+ * the rank_by='causal_distance' path need, but scoped to the four
+ * load-bearing edge types for "what records causally inform this one":
+ *
+ *   CHAIN_PRECEDES (weight 1): direct chain link.
+ *     chain_root != genesisChainRoot(context_id) implies a prior record
+ *     whose canonical hash equals chain_root sans "sha256:" prefix.
+ *
+ *   INFORMED_BY (weight 1): explicit record-to-record reference (D041).
+ *     Records carry an `informed_by` field whose entries are record_hashes
+ *     of records consulted during construction.
+ *
+ *   ANNOTATES (weight 2): an annotation record points at a target record
+ *     (D058). Edge runs annotation -> target.
+ *
+ *   REVISES (weight 2): a revision record supersedes a target record
+ *     (D059). Edge runs revision -> target.
+ *
+ * Weights come from the Layer 1 design: direct causality (chain +
+ * informed_by) is weight 1; annotation/revision relationships are
+ * weight 2 (less direct: the agent's later judgment on a record vs the
+ * record's own causal inputs).
+ *
+ * SESSION_PRECEDES + SESSION_PARALLEL + CONVERGES_ON + CROSS_SESSION
+ * are deliberately omitted at Layer 1. They encode temporal/sibling
+ * structure, not causal-ancestor structure — useful for the public
+ * graph-node /v1/graph view but not for "what should the agent re-read
+ * before re-attempting a similar action". The graph-node service
+ * (services/graph-node/src/graph-builder.ts) is the spec-faithful
+ * full §3.2.4 derivation; this module is its Layer 1 subset.
+ *
+ * PROVENANCE_OF (D044) is also omitted at Layer 1 — it operates on the
+ * cross-session genesis anchor via a 16-byte-truncated token, which
+ * doesn't compose naturally with the within-mirror BFS path. A future
+ * release that wires cross-session PROVENANCE_OF onto provenance_token
+ * inputs would extend this graph.
+ *
+ * The graph is built once per recall() call from the LoadedRecord array
+ * and discarded; no caching. Layer 2 (sqlite-vec sidecar) materializes
+ * the graph alongside the embedding store.
+ */
+import { genesisChainRoot } from '@atrib/mcp';
+/**
+ * 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 const EDGE_WEIGHTS = {
+    CHAIN_PRECEDES: 1,
+    INFORMED_BY: 1,
+    ANNOTATES: 2,
+    REVISES: 2,
+};
+/**
+ * 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 function buildLocalGraph(loaded) {
+    const graph = new Map();
+    for (const lr of loaded) {
+        if (!graph.has(lr.record_hash))
+            graph.set(lr.record_hash, []);
+    }
+    const addEdge = (from, edge) => {
+        const list = graph.get(from);
+        if (list)
+            list.push(edge);
+        else
+            graph.set(from, [edge]);
+    };
+    const addUndirected = (a, b, type) => {
+        const weight = EDGE_WEIGHTS[type];
+        addEdge(a, { type, target: b, weight });
+        addEdge(b, { type, target: a, weight });
+    };
+    // Index by canonical-hash-hex so CHAIN_PRECEDES lookups (chain_root
+    // sans "sha256:") can resolve to the prior record's record_hash.
+    const byHashHex = new Map(); // hex -> record_hash form
+    for (const lr of loaded) {
+        const hex = lr.record_hash.startsWith('sha256:')
+            ? lr.record_hash.slice('sha256:'.length)
+            : lr.record_hash;
+        byHashHex.set(hex, lr.record_hash);
+    }
+    for (const lr of loaded) {
+        // CHAIN_PRECEDES: skip genesis records (chain_root == genesisChainRoot(context_id)).
+        const genesis = genesisChainRoot(lr.record.context_id);
+        if (lr.record.chain_root !== genesis) {
+            const expected = lr.record.chain_root.startsWith('sha256:')
+                ? lr.record.chain_root.slice('sha256:'.length)
+                : lr.record.chain_root;
+            const prior = byHashHex.get(expected);
+            if (prior) {
+                addUndirected(lr.record_hash, prior, 'CHAIN_PRECEDES');
+            }
+        }
+        // INFORMED_BY: explicit references.
+        const informedBy = lr.record.informed_by;
+        if (Array.isArray(informedBy)) {
+            for (const ref of informedBy) {
+                if (typeof ref !== 'string')
+                    continue;
+                // Only emit when the referenced record is present in the mirror.
+                // Cross-mirror references will be resolved by Layer 2 (cache or
+                // log-side lookup) once that ships.
+                if (graph.has(ref) || byHashHex.has(stripPrefix(ref))) {
+                    addUndirected(lr.record_hash, ref, 'INFORMED_BY');
+                }
+            }
+        }
+        // ANNOTATES: annotation record -> target. content.annotates lives in
+        // _local.content on a D062 envelope; bare-record annotations have no
+        // body to read (the §8.1 posture); skip those.
+        if (lr.content && typeof lr.content === 'object') {
+            const c = lr.content;
+            if (typeof c.annotates === 'string' &&
+                lr.record.event_type === 'https://atrib.dev/v1/types/annotation') {
+                addUndirected(lr.record_hash, c.annotates, 'ANNOTATES');
+            }
+            if (typeof c.revises === 'string' &&
+                lr.record.event_type === 'https://atrib.dev/v1/types/revision') {
+                addUndirected(lr.record_hash, c.revises, 'REVISES');
+            }
+        }
+    }
+    return graph;
+}
+function stripPrefix(hash) {
+    return hash.startsWith('sha256:') ? hash.slice('sha256:'.length) : hash;
+}
+/**
+ * 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 function shortestDistances(graph, start, edgeTypes, maxHops = Number.POSITIVE_INFINITY) {
+    if (!graph.has(start))
+        return new Map();
+    const dist = new Map();
+    const hops = new Map();
+    dist.set(start, 0);
+    hops.set(start, 0);
+    const visited = new Set();
+    while (true) {
+        // O(V) min extraction. Layer 1 graphs are small (hundreds of
+        // records); a heap is overkill.
+        let node;
+        let minDist = Number.POSITIVE_INFINITY;
+        for (const [k, d] of dist) {
+            if (visited.has(k))
+                continue;
+            if (d < minDist) {
+                minDist = d;
+                node = k;
+            }
+        }
+        if (node === undefined)
+            break;
+        visited.add(node);
+        const nodeHops = hops.get(node) ?? 0;
+        if (nodeHops >= maxHops)
+            continue;
+        for (const edge of graph.get(node) ?? []) {
+            if (edgeTypes && edgeTypes.size > 0 && !edgeTypes.has(edge.type))
+                continue;
+            const candidate = minDist + edge.weight;
+            const existing = dist.get(edge.target);
+            if (existing === undefined || candidate < existing) {
+                dist.set(edge.target, candidate);
+                hops.set(edge.target, nodeHops + 1);
+            }
+        }
+    }
+    return dist;
+}
+/**
+ * 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 function walkFrom(graph, start, edgeTypes, maxHops = 3) {
+    const dist = shortestDistances(graph, start, edgeTypes, maxHops);
+    // Drop the start node itself (distance 0) — the agent asked for
+    // adjacent records, not a re-echo of the anchor.
+    return [...dist.entries()]
+        .filter(([h]) => h !== start)
+        .map(([record_hash, distance]) => ({ record_hash, distance }))
+        .sort((a, b) => a.distance - b.distance);
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAQ7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAA6B;IACpD,cAAc,EAAE,CAAC;IACjB,WAAW,EAAE,CAAC;IACd,SAAS,EAAE,CAAC;IACZ,OAAO,EAAE,CAAC;CACX,CAAA;AAgBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,MAAsB;IACpD,MAAM,KAAK,GAAe,IAAI,GAAG,EAAE,CAAA;IACnC,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,WAAW,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;IAC/D,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,IAAe,EAAE,EAAE;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC5B,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;;YACpB,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;IAC9B,CAAC,CAAA;IACD,MAAM,aAAa,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,IAAc,EAAE,EAAE;QAC7D,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;QACjC,OAAO,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACvC,OAAO,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;IACzC,CAAC,CAAA;IAED,oEAAoE;IACpE,iEAAiE;IACjE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAA,CAAC,0BAA0B;IACtE,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC;YAC9C,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;YACxC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAA;QAClB,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,qFAAqF;QACrF,MAAM,OAAO,GAAG,gBAAgB,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QACtD,IAAI,EAAE,CAAC,MAAM,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;YACrC,MAAM,QAAQ,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC;gBACzD,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;gBAC9C,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAA;YACxB,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACrC,IAAI,KAAK,EAAE,CAAC;gBACV,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAA;YACxD,CAAC;QACH,CAAC;QAED,oCAAoC;QACpC,MAAM,UAAU,GAAI,EAAE,CAAC,MAAkD,CAAC,WAAW,CAAA;QACrF,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;gBAC7B,IAAI,OAAO,GAAG,KAAK,QAAQ;oBAAE,SAAQ;gBACrC,iEAAiE;gBACjE,gEAAgE;gBAChE,oCAAoC;gBACpC,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;oBACtD,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE,aAAa,CAAC,CAAA;gBACnD,CAAC;YACH,CAAC;QACH,CAAC;QAED,qEAAqE;QACrE,qEAAqE;QACrE,+CAA+C;QAC/C,IAAI,EAAE,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACjD,MAAM,CAAC,GAAG,EAAE,CAAC,OAAqD,CAAA;YAClE,IACE,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;gBAC/B,EAAE,CAAC,MAAM,CAAC,UAAU,KAAK,uCAAuC,EAChE,CAAC;gBACD,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS,EAAE,WAAW,CAAC,CAAA;YACzD,CAAC;YACD,IACE,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;gBAC7B,EAAE,CAAC,MAAM,CAAC,UAAU,KAAK,qCAAqC,EAC9D,CAAC;gBACD,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;YACrD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACzE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAiB,EACjB,KAAa,EACb,SAAyB,EACzB,UAAkB,MAAM,CAAC,iBAAiB;IAE1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAA;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAA;IACtC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAA;IACtC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAClB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IAClB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IACjC,OAAO,IAAI,EAAE,CAAC;QACZ,6DAA6D;QAC7D,gCAAgC;QAChC,IAAI,IAAwB,CAAA;QAC5B,IAAI,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAA;QACtC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;YAC1B,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAQ;YAC5B,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC;gBAChB,OAAO,GAAG,CAAC,CAAA;gBACX,IAAI,GAAG,CAAC,CAAA;YACV,CAAC;QACH,CAAC;QACD,IAAI,IAAI,KAAK,SAAS;YAAE,MAAK;QAC7B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACjB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpC,IAAI,QAAQ,IAAI,OAAO;YAAE,SAAQ;QACjC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACzC,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,SAAQ;YAC1E,MAAM,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC,MAAM,CAAA;YACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YACtC,IAAI,QAAQ,KAAK,SAAS,IAAI,SAAS,GAAG,QAAQ,EAAE,CAAC;gBACnD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;gBAChC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAiB,EACjB,KAAa,EACb,SAAyB,EACzB,UAAkB,CAAC;IAEnB,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;IAChE,gEAAgE;IAChE,iDAAiD;IACjD,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;SACvB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC;SAC5B,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC;SAC7D,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;AAC5C,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 import type { AtribRecord } from '@atrib/mcp';
+export type ImportanceLabel = 'critical' | 'high' | 'medium' | 'low' | 'noise';
+export declare const IMPORTANCE_NUMERIC: Record<ImportanceLabel, number>;
+export declare const ATRIB_RECALL_ALPHA: number;
+export declare const ATRIB_RECALL_BETA: number;
+export declare const ATRIB_RECALL_GAMMA: number;
+export declare const ATRIB_RECALL_TAU_DAYS: number;
+import type { AnnotationSummary as AggAnnotationSummary } from './aggregations.js';
 export declare function loadRecords(path: string): AtribRecord[];
 /**
  * Load every `*.jsonl` file in `dir` and merge their records. Files that
@@ -11,7 +18,7 @@ export declare function loadRecords(path: string): AtribRecord[];
  * mirror namespace; every producer running under one identity writes a
  * file there with the convention `<producer>-<agent>.jsonl`. Scanning the
  * directory unifies recall across producers without recall having to know
- * the naming scheme — any producer that follows §5.9 just shows up.
+ * the naming scheme - any producer that follows §5.9 just shows up.
  */
 export declare function loadRecordsFromDir(dir: string): {
     records: AtribRecord[];
@@ -19,7 +26,92 @@ export declare function loadRecordsFromDir(dir: string): {
 };
 interface RecallArgs {
     context_id?: string;
-    event_type?: 'tool_call' | 'transaction';
+    event_type?: 'tool_call' | 'transaction' | 'annotation' | 'revision';
+    /**
+     * Optional exact match on `record.content_id` (`sha256:<64-hex>`). Per spec
+     * §1.2.2, content_id is `sha256(serverUrl + ":" + toolName)`. Filtering by
+     * content_id groups all records emitted by the same tool on the same MCP
+     * server. Useful for "all calls to this tool, ever." Coarser than tool_name
+     * because two tools on different servers share no content_id even if their
+     * names match.
+     */
+    content_id?: string;
+    /**
+     * Optional exact match on the §8.2 disclosed `tool_name`. Records that did
+     * NOT opt in to tool-name disclosure (the §8.1 default posture) carry no
+     * tool_name field and are excluded from results when this filter is set.
+     * Use this to query by human-readable name (e.g. tool_name="Edit") across
+     * MCP servers, when the producer disclosed it.
+     */
+    tool_name?: string;
+    /**
+     * Optional exact match on `record.args_hash` (`sha256:<64-hex>`). Per spec
+     * §8.3, args_hash commits to canonical args bytes. Salted (D045) and plain
+     * forms hash identically on the wire; this filter does not distinguish
+     * them. Most useful for replay detection (same args, same hash) and for
+     * agent-side keyed lookup when the agent computes a probe hash over a
+     * normalized {tool, target} dict.
+     */
+    args_hash?: string;
+    /**
+     * Layer 1 filter (NEW in 0.5.0): minimum annotation importance. Records
+     * are ranked by max(annotation.importance) where annotations are D058
+     * records pointing at this record. Records with no annotations at all
+     * have importance=0 and are EXCLUDED from results when min_importance is
+     * set. Use this to surface only records the agent or its critique loop
+     * has marked as worth attention.
+     */
+    min_importance?: ImportanceLabel;
+    /**
+     * Layer 1 filter (NEW in 0.5.0): OR-match against annotation topic tags.
+     * Records are kept if AT LEAST ONE annotation pointing at them carries
+     * AT LEAST ONE of the listed topics. Records with no annotations or no
+     * topic-overlap are excluded. Topics come from D058 annotation content.
+     */
+    topic_tags?: string[];
+    /**
+     * Layer 1 filter (NEW in 0.5.0): hide records superseded by D059 revision
+     * records. Default false (records remain visible even if a later revision
+     * supersedes them; the response carries `superseded_by` so the agent can
+     * see). Set true to filter superseded records out of the response entirely.
+     */
+    include_revised?: boolean;
+    /**
+     * Layer 1 filter (NEW in 0.5.0): minimum count of distinct cross-attesting
+     * signers per D052. Useful for transaction records that must carry >= 2
+     * signers; also useful as a credibility filter when querying multi-agent
+     * substrate. Records below the threshold are excluded.
+     */
+    min_signers?: number;
+    /**
+     * Layer 1 ranking (NEW in 0.5.0): how to order results before paging.
+     * 'timestamp' (default, backward-compatible): newest first.
+     * 'relevance': Park et al. 2023 weighted-sum scoring with annotation-derived
+     * importance (NO embedding component until Layer 2 ships; falls back to BM25
+     * over summary+topics if rank_anchor query is provided).
+     * 'causal_distance': BFS shortest path in the §3.2.4 derived graph from
+     * `rank_anchor` (which must be a record_hash). Edge weights per design.
+     */
+    rank_by?: 'timestamp' | 'relevance' | 'causal_distance';
+    /**
+     * Layer 1 ranking (NEW in 0.5.0): the anchor for non-timestamp rank_by
+     * modes. For rank_by='causal_distance', this MUST be a record_hash
+     * (`sha256:<64-hex>`); records are ranked by BFS shortest path from
+     * the anchor. For rank_by='relevance' with an optional query string,
+     * pass the query here as a free-form text string (Layer 2 will use it
+     * for embedding similarity; Layer 1 falls back to BM25-style scoring
+     * over summary+topics).
+     */
+    rank_anchor?: string;
+    /**
+     * New in 0.5.0: table-of-contents response shape. When true,
+     * each record returned is a one-line entry shape (record_hash, tool_name,
+     * summary, importance, topic_tags, timestamp, superseded_by). Cheap to
+     * scan, ~40-80 tokens per entry; agent expands on demand via
+     * `recall(content_id=..., compact=false)` or `recall_walk(...)`. Used at
+     * SessionStart for the auto-injected scaffold.
+     */
+    toc?: boolean;
     limit?: number;
     offset?: number;
     /**
@@ -35,11 +127,23 @@ interface RecallArgs {
      */
     include_unverified?: boolean;
 }
+/**
+ * Aggregated annotation summary attached to a record per Layer 1. Same
+ * shape as the canonical AnnotationSummary exported from aggregations.ts;
+ * aliased here so the response types in this file don't have to drag the
+ * aggregations module into their import surface.
+ */
+type AnnotationSummary = AggAnnotationSummary;
 /**
  * The shape returned to the agent. Each record is annotated with
- * signature_verified — true if the local Ed25519 signature check passed.
+ * signature_verified - true if the local Ed25519 signature check passed.
  * In compact mode the heavy fields (signature, content_id, chain_root,
  * spec_version) are dropped; the verified status is preserved.
+ *
+ * Layer 1 (0.5.0) adds optional `annotations` (max_importance + topics from
+ * any D058 annotations pointing at this record) and `superseded_by` (record
+ * hashes of any D059 revision records whose `revises` field equals this
+ * record's hash).
  */
 type RecallRecordCompact = {
     event_type: AtribRecord['event_type'];
@@ -48,9 +152,37 @@ type RecallRecordCompact = {
     timestamp: number;
     signature_verified: boolean;
     session_token?: string;
+    /**
+     * §8.2 disclosed tool name. Included in compact mode when present so a
+     * caller filtering by tool_name sees the value back in the response (the
+     * common pattern: filter by tool_name -> render results, want the name
+     * visible). Records without tool_name disclosure (the §8.1 default
+     * posture) omit this field as they always do.
+     */
+    tool_name?: string;
+    /** New in 0.5.0: aggregated annotation summary. */
+    annotations?: AnnotationSummary;
+    /** New in 0.5.0: record hashes of D059 revisions superseding this record. */
+    superseded_by?: string[];
+};
+/**
+ * TOC entry: the smallest cheap-to-scan shape (~40-80 tokens). Used at
+ * SessionStart auto-inject to surface a candidate set the agent can
+ * expand on demand via recall(content_id=...) or recall_walk.
+ */
+export type RecallRecordToc = {
+    record_hash?: string;
+    tool_name?: string;
+    summary?: string;
+    importance?: ImportanceLabel;
+    topic_tags?: string[];
+    timestamp: number;
+    superseded_by?: string[];
 };
 type RecallRecordFull = AtribRecord & {
     signature_verified: boolean;
+    annotations?: AnnotationSummary;
+    superseded_by?: string[];
 };
 export interface RecallResult {
     total: number;
@@ -73,7 +205,7 @@ export interface RecallResult {
     record_file: string;
     log_origin: string;
     pagination_caveat: string;
-    records: RecallRecordFull[] | RecallRecordCompact[];
+    records: RecallRecordFull[] | RecallRecordCompact[] | RecallRecordToc[];
 }
 /**
  * Discover and load records per the mirror-discovery contract: