@atrib/recall 0.14.7 → 1.0.0

package/dist/index.js

@@ -33,13 +33,12 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { verifyRecord, EVENT_TYPE_SHORT_NAMES, isValidEventTypeUri, normalizeEventType, resolveEnvContextId, logReadPrimitiveCall, } from '@atrib/mcp';
-const EventTypeFilterSchema = z.union([
-    z.enum(EVENT_TYPE_SHORT_NAMES),
-    z.string().refine((value) => isValidEventTypeUri(value), {
-        message: 'event_type must be an atrib shorthand alias or a syntactically valid absolute URI',
-    }),
-]);
+import { verifyRecord, normalizeEventType, resolveEnvContextId, logReadPrimitiveCall, } from '@atrib/mcp';
+// EventTypeFilterSchema moved to ./event-type-filter.js (leaf module) so
+// recall-verb.ts can use it at module init despite the import cycle with
+// this file. Re-exported here for existing importers.
+import { EventTypeFilterSchema } from './event-type-filter.js';
+export { EventTypeFilterSchema };
 export const IMPORTANCE_NUMERIC = {
     critical: 5,
     high: 4,
@@ -128,6 +127,9 @@ import { z } from 'zod';
 import { aggregateAnnotationsByRecord, aggregateRevisionsByRecord, discoverLoaded, loadLoaded, loadLoadedAppend, loadNewestLoadedFromDir, } from './aggregations.js';
 import { recencyScore, importanceScore, parkScore, buildBM25Index, bm25Score, bm25ScoresForQuery, normalizedBm25Relevance, operationalToolCallScoreFactor, tokenize, indexableTokensForRecord, shouldSuppressLifecycleAnchorForQuery, queryMentionsLifecycle, } from './scoring.js';
 import { buildLocalGraph, shortestDistances, walkFrom } from './graph.js';
+import { registerRecallVerbTool } from './recall-verb.js';
+import { extractRecordHashFieldsFromMcpResult, registerTraceTools } from './trace-tools.js';
+import { registerVerifyTool } from './verification.js';
 import { synthesizeDisplaySummary, resolveDisplayProducer, formatAge } from './legibility.js';
 const ATRIB_RECORD_FILE = process.env.ATRIB_RECORD_FILE;
 const ATRIB_MIRROR_DIR = process.env.ATRIB_MIRROR_DIR ?? join(homedir(), '.atrib', 'records');
@@ -902,43 +904,6 @@ function fullify(bundles) {
         return out;
     });
 }
-function extractRecordHashFieldsFromMcpResult(result) {
-    const seen = new Set();
-    const pattern = /^sha256:[0-9a-f]{64}$/;
-    const content = result?.content;
-    const text = Array.isArray(content) &&
-        typeof content[0]?.text === 'string'
-        ? content[0].text
-        : undefined;
-    let root = result;
-    if (text) {
-        try {
-            root = JSON.parse(text);
-        }
-        catch {
-            root = result;
-        }
-    }
-    walk(root);
-    return Array.from(seen);
-    function walk(node) {
-        if (node === null || node === undefined)
-            return;
-        if (Array.isArray(node)) {
-            for (const item of node)
-                walk(item);
-            return;
-        }
-        if (typeof node !== 'object')
-            return;
-        const obj = node;
-        if (typeof obj.record_hash === 'string' && pattern.test(obj.record_hash)) {
-            seen.add(obj.record_hash);
-        }
-        for (const value of Object.values(obj))
-            walk(value);
-    }
-}
 /**
  * Discover and load records per the mirror-discovery contract:
  *   - If `recordFile` is provided, load just that file.
@@ -1133,13 +1098,340 @@ function readPackageVersion() {
         return '0.0.0';
     }
 }
+export async function runRecallWalk(args) {
+    const { loaded, annotationsByRecord } = getLoadedMirrorSnapshot();
+    const graph = buildLocalGraph(loaded);
+    const edgeTypes = args.edge_types ? new Set(args.edge_types) : undefined;
+    const depth = typeof args.depth === 'number' ? args.depth : 3;
+    const walk = walkFrom(graph, args.from_record_hash, edgeTypes, depth);
+    // Layer 1 v2 legibility: join walked hashes back to their loaded
+    // records so each step in the walk carries a readable label
+    // instead of just a hash + distance. Builds the index once for
+    // O(N) lookup across the walk; for typical walks (depth=3, k<50)
+    // this is fast.
+    const byHash = new Map(loaded.map((lr) => [lr.record_hash, lr]));
+    const now = Date.now();
+    const enriched = walk.map((step) => {
+        // walk derives from graph (built from `loaded`); byHash always has a hit.
+        const lr = byHash.get(step.record_hash);
+        const ann = annotationsByRecord.get(step.record_hash);
+        return {
+            record_hash: step.record_hash,
+            distance: step.distance,
+            event_type: lr.record.event_type,
+            timestamp: lr.record.timestamp,
+            display_summary: synthesizeDisplaySummary(lr.record, lr.content, ann),
+            display_producer: resolveDisplayProducer(lr.record, lr.producer),
+            age: formatAge(lr.record.timestamp, now),
+        };
+    });
+    return {
+        from_record_hash: args.from_record_hash,
+        edge_types: args.edge_types ?? ['CHAIN_PRECEDES', 'INFORMED_BY', 'ANNOTATES', 'REVISES'],
+        depth,
+        count: enriched.length,
+        walk: enriched,
+    };
+}
+export async function runRecallAnnotations(args) {
+    const { annotationsByRecord } = getLoadedMirrorSnapshot();
+    const summary = annotationsByRecord.get(args.record_hash) ?? null;
+    return { record_hash: args.record_hash, annotations: summary };
+}
+export async function runRecallRevisions(args) {
+    const { loaded, revisionsByRecord } = getLoadedMirrorSnapshot();
+    const byHash = new Map();
+    for (const lr of loaded)
+        byHash.set(lr.record_hash, lr);
+    const chain = [];
+    const seen = new Set();
+    let current = args.record_hash;
+    while (!seen.has(current)) {
+        seen.add(current);
+        const next = revisionsByRecord.get(current);
+        if (!next || next.length === 0)
+            break;
+        // Each entry in the map's value array is a revision pointing at
+        // `current`. The chain follows the first-by-timestamp revision;
+        // the remaining entries are surfaced as `sibling_hashes` so the
+        // agent learns that branches exist without the chain shape
+        // having to explode into a tree.
+        const revHash = next[0];
+        const siblings = next.slice(1);
+        const revLr = byHash.get(revHash);
+        const entry = { record_hash: revHash };
+        if (revLr) {
+            entry.timestamp = revLr.record.timestamp;
+            const c = revLr.content;
+            if (c && typeof c === 'object' && !Array.isArray(c)) {
+                const cObj = c;
+                if (typeof cObj.new_position === 'string')
+                    entry.new_position = cObj.new_position;
+                if (typeof cObj.reason === 'string')
+                    entry.reason = cObj.reason;
+                if (typeof cObj.importance === 'string')
+                    entry.importance = cObj.importance;
+            }
+        }
+        if (siblings.length > 0) {
+            entry.sibling_hashes = siblings;
+        }
+        chain.push(entry);
+        current = revHash;
+    }
+    return { record_hash: args.record_hash, revision_chain: chain };
+}
+export async function runRecallByContent(args) {
+    const evidenceMode = args.evidence_mode === 'require_complete' ? 'require_complete' : 'bounded';
+    const includeToolCallArgs = args.include_tool_call_args === true;
+    const boundedLimit = resolveBoundedContentSearchLimit(args.max_records, Number.MAX_SAFE_INTEGER);
+    const snapshot = getContentSearchSnapshotForRecall(evidenceMode, boundedLimit);
+    const { entryByHash } = snapshot;
+    const totalRecords = snapshot.totalRecords;
+    const loadedLength = snapshot.entries.length;
+    const searchLimit = evidenceMode === 'require_complete'
+        ? resolveCompleteContentSearchLimit(args.max_records, loadedLength)
+        : Math.min(boundedLimit, loadedLength);
+    const explicitLimit = hasExplicitRecordLimit(args.max_records);
+    if (evidenceMode === 'require_complete' && explicitLimit && searchLimit < loadedLength) {
+        const k = Math.max(1, Math.min(50, args.k ?? 10));
+        return {
+            query: args.query,
+            k,
+            runtime: recallRuntimeMetadata(),
+            ...(includeToolCallArgs ? { include_tool_call_args: true } : {}),
+            evidence_mode: evidenceMode,
+            evidence_status: 'incomplete',
+            fallback_required: true,
+            fallback_reason: `require_complete refused a partial corpus: search_cap=${searchLimit}, ` +
+                `total_records=${loadedLength}.`,
+            fallback: 'Rerun without max_records for full loaded-mirror coverage, or pass an explicit ' +
+                'partition filter through a caller-owned audit plan and treat each partition as its own coverage claim.',
+            total_records: loadedLength,
+            searched_records: 0,
+            search_cap: searchLimit,
+            coverage: recallCoverage(snapshot, 'incomplete_explicit_limit', 0, snapshot.index),
+            candidate_records: 0,
+            truncated_corpus: true,
+            count: 0,
+            results: [],
+        };
+    }
+    const bm25Index = getContentBm25IndexForNewestLimit(snapshot, searchLimit);
+    const queryTokens = tokenize(args.query);
+    const relevanceByHash = bm25ScoresForQuery(bm25Index, queryTokens);
+    const now = Date.now();
+    const searchPool = queryTokens.length > 0
+        ? Array.from(relevanceByHash.keys())
+            .map((hash) => entryByHash.get(hash))
+            .filter((entry) => entry !== undefined)
+        : snapshot.newestEntries.slice(0, searchLimit);
+    const filteredSearchPool = searchPool.filter((entry) => !(entry.lifecycle_anchor && !queryMentionsLifecycle(queryTokens)));
+    const scored = filteredSearchPool.map((entry) => {
+        const ann = entry.annotations;
+        const suppressLifecycleAnchor = entry.lifecycle_anchor && !queryMentionsLifecycle(queryTokens);
+        const toolCallScoreFactor = effectiveToolCallScoreFactor(entry, includeToolCallArgs);
+        const r = recencyScore(entry.timestamp, now, ATRIB_RECALL_TAU_DAYS) * toolCallScoreFactor;
+        const i = suppressLifecycleAnchor ? 0 : importanceScore(ann);
+        const rawRel = !suppressLifecycleAnchor && queryTokens.length > 0
+            ? (relevanceByHash.get(entry.record_hash) ?? 0)
+            : 0;
+        const rel = !suppressLifecycleAnchor && queryTokens.length > 0
+            ? normalizedBm25Relevance(bm25Index, entry.record_hash, queryTokens, rawRel) *
+                toolCallScoreFactor
+            : 0;
+        const score = parkScore(r, i, rel, ATRIB_RECALL_ALPHA, ATRIB_RECALL_BETA, ATRIB_RECALL_GAMMA);
+        return { entry, score, recency: r, importance: i, relevance: rel };
+    });
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return b.entry.timestamp - a.entry.timestamp;
+    });
+    const k = Math.max(1, Math.min(50, args.k ?? 10));
+    const top = scored.slice(0, k);
+    const completeCoverage = !snapshot.partial && searchLimit >= loadedLength;
+    return {
+        query: args.query,
+        k,
+        runtime: recallRuntimeMetadata(),
+        ...(includeToolCallArgs ? { include_tool_call_args: true } : {}),
+        evidence_mode: evidenceMode,
+        evidence_status: completeCoverage ? 'complete' : 'bounded',
+        fallback_required: false,
+        total_records: totalRecords,
+        searched_records: searchLimit,
+        coverage: recallCoverage(snapshot, completeCoverage ? 'complete_full_scan' : 'bounded_newest_first', searchLimit, snapshot.index),
+        candidate_records: filteredSearchPool.length,
+        truncated_corpus: !completeCoverage,
+        count: top.length,
+        results: top.map(({ entry, score, recency, importance, relevance }) => {
+            return {
+                record_hash: entry.record_hash,
+                event_type: entry.event_type,
+                context_id: entry.context_id,
+                timestamp: entry.timestamp,
+                tool_name: entry.tool_name,
+                annotations: entry.annotations,
+                // Layer 1 v2 legibility fields (parity with compactify).
+                display_summary: entry.display_summary,
+                display_producer: entry.display_producer,
+                age: formatAge(entry.timestamp, now),
+                score,
+                components: { recency, importance, relevance },
+            };
+        }),
+    };
+}
+export async function runRecallSessionChain(args) {
+    const ctx = args.context_id ?? resolveEnvContextId();
+    if (!ctx) {
+        return {
+            context_id: null,
+            count: 0,
+            records: [],
+            warning: 'no context_id supplied or resolvable via env',
+        };
+    }
+    const { loaded, annotationsByRecord } = getLoadedMirrorSnapshot();
+    const filtered = loaded
+        .filter((lr) => lr.record.context_id === ctx)
+        .sort((a, b) => a.record.timestamp - b.record.timestamp);
+    const limit = Math.max(1, Math.min(500, args.limit ?? 50));
+    const sliced = filtered.slice(0, limit);
+    const now = Date.now();
+    return {
+        context_id: ctx,
+        total: filtered.length,
+        returned: sliced.length,
+        truncated: filtered.length > sliced.length,
+        records: sliced.map((lr) => {
+            const ann = annotationsByRecord.get(lr.record_hash);
+            const entry = {
+                record_hash: lr.record_hash,
+                event_type: lr.record.event_type,
+                timestamp: lr.record.timestamp,
+                display_summary: synthesizeDisplaySummary(lr.record, lr.content, ann),
+                display_producer: resolveDisplayProducer(lr.record, lr.producer),
+                age: formatAge(lr.record.timestamp, now),
+            };
+            const informedBy = lr.record.informed_by;
+            const toolName = lr.record.tool_name;
+            const argsHash = lr.record.args_hash;
+            const resultHash = lr.record.result_hash;
+            if (Array.isArray(informedBy) && informedBy.length > 0) {
+                entry.informed_by = informedBy;
+            }
+            if (toolName)
+                entry.tool_name = toolName;
+            if (argsHash)
+                entry.args_hash = argsHash;
+            if (resultHash)
+                entry.result_hash = resultHash;
+            if (args.include_content === true && lr.content !== undefined) {
+                entry.local_content = lr.content;
+            }
+            if (args.include_content === true && lr.producer !== undefined) {
+                entry.local_producer = lr.producer;
+            }
+            return entry;
+        }),
+    };
+}
+export async function runRecallOrphans(args) {
+    const { loaded, annotationsByRecord } = getLoadedMirrorSnapshot();
+    // Build the set of all record_hashes that appear in any record's
+    // informed_by field. Anything in `loaded` whose record_hash is
+    // NOT in this set is an orphan.
+    const cited = new Set();
+    for (const lr of loaded) {
+        const ib = lr.record.informed_by;
+        if (Array.isArray(ib)) {
+            for (const h of ib)
+                if (typeof h === 'string')
+                    cited.add(h);
+        }
+    }
+    let orphans = loaded.filter((lr) => !cited.has(lr.record_hash));
+    if (args.context_id) {
+        orphans = orphans.filter((lr) => lr.record.context_id === args.context_id);
+    }
+    if (args.creator_key) {
+        orphans = orphans.filter((lr) => lr.record.creator_key === args.creator_key);
+    }
+    if (args.event_type) {
+        const targetUri = normalizeEventType(args.event_type);
+        orphans = orphans.filter((lr) => lr.record.event_type === targetUri);
+    }
+    orphans.sort((a, b) => b.record.timestamp - a.record.timestamp);
+    const limit = Math.max(1, Math.min(500, args.limit ?? 50));
+    const sliced = orphans.slice(0, limit);
+    const now = Date.now();
+    return {
+        total: orphans.length,
+        returned: sliced.length,
+        truncated: orphans.length > sliced.length,
+        records: sliced.map((lr) => {
+            const ann = annotationsByRecord.get(lr.record_hash);
+            return {
+                record_hash: lr.record_hash,
+                event_type: lr.record.event_type,
+                context_id: lr.record.context_id,
+                timestamp: lr.record.timestamp,
+                display_summary: synthesizeDisplaySummary(lr.record, lr.content, ann),
+                display_producer: resolveDisplayProducer(lr.record, lr.producer),
+                age: formatAge(lr.record.timestamp, now),
+            };
+        }),
+    };
+}
+export async function runRecallBySigner(args) {
+    const { loaded } = getLoadedMirrorSnapshot();
+    const byKey = new Map();
+    for (const lr of loaded) {
+        const key = lr.record.creator_key;
+        const existing = byKey.get(key);
+        if (existing) {
+            existing.count++;
+            if (lr.record.timestamp > existing.latest_timestamp)
+                existing.latest_timestamp = lr.record.timestamp;
+            if (lr.record.timestamp < existing.earliest_timestamp)
+                existing.earliest_timestamp = lr.record.timestamp;
+        }
+        else {
+            byKey.set(key, {
+                creator_key: key,
+                count: 1,
+                latest_timestamp: lr.record.timestamp,
+                earliest_timestamp: lr.record.timestamp,
+            });
+        }
+    }
+    const minRecords = Math.max(1, args.min_records ?? 1);
+    const stats = [...byKey.values()]
+        .filter((s) => s.count >= minRecords)
+        .sort((a, b) => b.count - a.count);
+    return {
+        total_signers: stats.length,
+        total_records: loaded.length,
+        signers: stats,
+    };
+}
+function jsonToolResult(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+}
 // The recall semantic surface (as defined in the public protocol specification).
-// Eight distinct MCP tools: recall_my_attribution_history is the base
-// filter-and-page tool; recall_annotations + recall_revisions return
-// aggregated annotation summaries / revision chains for a specific
-// record_hash; recall_walk traverses the local Layer 1 derived graph;
-// recall_by_content runs BM25 free-form retrieval; recall_session_chain,
-// recall_orphans, and recall_by_signer cover common agent lookup shapes.
+// Eight distinct legacy MCP tools kept as permanent aliases over the shape
+// runners above: recall_my_attribution_history is the base filter-and-page
+// tool; recall_annotations + recall_revisions return aggregated annotation
+// summaries / revision chains for a specific record_hash; recall_walk
+// traverses the local Layer 1 derived graph; recall_by_content runs BM25
+// free-form retrieval; recall_session_chain, recall_orphans, and
+// recall_by_signer cover common agent lookup shapes. New callers should
+// prefer the `recall` verb (one tool, `shape` argument); results are
+// JSON-identical by construction.
 export function registerAtribRecallTools(server) {
     server.registerTool('recall_my_attribution_history', {
         description: "Return signed atrib records from the local mirror. The agent's own past, with each record's " +
@@ -1154,7 +1446,8 @@ export function registerAtribRecallTools(server) {
             'omit all of them for cross-trace history. Results are sorted newest-first. Pagination uses ' +
             'offset; new records appended between calls invalidate offset stability. See the ' +
             'pagination_caveat in the response. The filtered_out_by_verification field reports how many ' +
-            'records were dropped due to signature failures (always 0 when include_unverified=true).',
+            'records were dropped due to signature failures (always 0 when include_unverified=true). ' +
+            "Legacy alias: new callers should prefer the `recall` tool with shape='history'.",
         inputSchema: {
             context_id: z
                 .string()
@@ -1269,20 +1562,13 @@ export function registerAtribRecallTools(server) {
         // min_importance, topic_tags, include_revised, min_signers,
         // rank_by, rank_anchor, and toc.
         const result = await recall(args);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify(result, null, 2),
-                },
-            ],
-        };
+        return jsonToolResult(result);
     }, extractRecordHashFieldsFromMcpResult));
     // ─── Layer 1 sibling tools ───
     // Sibling tools expose common agent lookup shapes beyond the base
     // filter-and-page tool.
     server.registerTool('recall_walk', {
-        description: 'Walk the local derived graph from a starting record_hash. Returns records reachable via the requested edge types up to the given hop depth, ordered by ascending weighted distance. Layer 1 covers four 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. Useful for tracing the local causal neighborhood of a record before re-attempting a similar action.',
+        description: 'Walk the local derived graph from a starting record_hash. Returns records reachable via the requested edge types up to the given hop depth, ordered by ascending weighted distance. Layer 1 covers four 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. Useful for tracing the local causal neighborhood of a record before re-attempting a similar action. Legacy alias: new callers should prefer the `recall` tool with shape=\'walk\' (no direction).',
         inputSchema: {
             from_record_hash: z
                 .string()
@@ -1296,131 +1582,29 @@ export function registerAtribRecallTools(server) {
                 .optional()
                 .describe('Maximum hop count (NOT cumulative weight). Default 3. Higher values may return many records; paginate downstream if needed.'),
         },
-    }, async (args) => logReadPrimitiveCall('recall_walk', args, async () => {
-        const { loaded, annotationsByRecord } = getLoadedMirrorSnapshot();
-        const graph = buildLocalGraph(loaded);
-        const edgeTypes = args.edge_types ? new Set(args.edge_types) : undefined;
-        const depth = typeof args.depth === 'number' ? args.depth : 3;
-        const walk = walkFrom(graph, args.from_record_hash, edgeTypes, depth);
-        // Layer 1 v2 legibility: join walked hashes back to their loaded
-        // records so each step in the walk carries a readable label
-        // instead of just a hash + distance. Builds the index once for
-        // O(N) lookup across the walk; for typical walks (depth=3, k<50)
-        // this is fast.
-        const byHash = new Map(loaded.map((lr) => [lr.record_hash, lr]));
-        const now = Date.now();
-        const enriched = walk.map((step) => {
-            // walk derives from graph (built from `loaded`); byHash always has a hit.
-            const lr = byHash.get(step.record_hash);
-            const ann = annotationsByRecord.get(step.record_hash);
-            return {
-                record_hash: step.record_hash,
-                distance: step.distance,
-                event_type: lr.record.event_type,
-                timestamp: lr.record.timestamp,
-                display_summary: synthesizeDisplaySummary(lr.record, lr.content, ann),
-                display_producer: resolveDisplayProducer(lr.record, lr.producer),
-                age: formatAge(lr.record.timestamp, now),
-            };
-        });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        from_record_hash: args.from_record_hash,
-                        edge_types: args.edge_types ?? [
-                            'CHAIN_PRECEDES',
-                            'INFORMED_BY',
-                            'ANNOTATES',
-                            'REVISES',
-                        ],
-                        depth,
-                        count: enriched.length,
-                        walk: enriched,
-                    }, null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
+    }, async (args) => logReadPrimitiveCall('recall_walk', args, async () => jsonToolResult(await runRecallWalk({
+        from_record_hash: args.from_record_hash,
+        edge_types: args.edge_types,
+        depth: typeof args.depth === 'number' ? args.depth : undefined,
+    })), extractRecordHashFieldsFromMcpResult));
     server.registerTool('recall_annotations', {
-        description: "Return the aggregated annotation summary for a record: maximum annotation importance across all D058 annotation records pointing at it, the union of their topic tags, and the most recent summary string. Useful for surfacing the agent's prior critique on a record before re-attempting a similar action. Returns null annotations field when no annotation points at the record.",
+        description: "Return the aggregated annotation summary for a record: maximum annotation importance across all D058 annotation records pointing at it, the union of their topic tags, and the most recent summary string. Useful for surfacing the agent's prior critique on a record before re-attempting a similar action. Returns null annotations field when no annotation points at the record. Legacy alias: new callers should prefer the `recall` tool with shape='annotations'.",
         inputSchema: {
             record_hash: z
                 .string()
                 .describe('Record hash (sha256:<64-hex>) of the record whose annotations should be retrieved. Annotations are D058 records whose signed annotates field equals this hash.'),
         },
-    }, async (args) => logReadPrimitiveCall('recall_annotations', args, async () => {
-        const { annotationsByRecord } = getLoadedMirrorSnapshot();
-        const summary = annotationsByRecord.get(args.record_hash) ?? null;
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({ record_hash: args.record_hash, annotations: summary }, null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
+    }, async (args) => logReadPrimitiveCall('recall_annotations', args, async () => jsonToolResult(await runRecallAnnotations(args)), extractRecordHashFieldsFromMcpResult));
     server.registerTool('recall_revisions', {
-        description: "Return the D059 revision chain for a record, with per-entry content + sibling-fan-out awareness. Walks revises edges forward from the given record_hash, surfacing each revision in turn. Each entry carries the revision's record_hash, timestamp, and content (`new_position`, `reason`, `importance`) so the agent can read the chain inline without follow-up recall calls per entry. When more than one revision targets the same record, the chain follows the first-by-timestamp branch and lists the other branch heads as `sibling_hashes` on that entry so the agent learns about parallel revision branches (common in multi-agent flows). Useful for checking whether a position the agent previously held has been revised before acting on it. Returns an empty chain when no revision points at the record.",
+        description: "Return the D059 revision chain for a record, with per-entry content + sibling-fan-out awareness. Walks revises edges forward from the given record_hash, surfacing each revision in turn. Each entry carries the revision's record_hash, timestamp, and content (`new_position`, `reason`, `importance`) so the agent can read the chain inline without follow-up recall calls per entry. When more than one revision targets the same record, the chain follows the first-by-timestamp branch and lists the other branch heads as `sibling_hashes` on that entry so the agent learns about parallel revision branches (common in multi-agent flows). Useful for checking whether a position the agent previously held has been revised before acting on it. Returns an empty chain when no revision points at the record. Legacy alias: new callers should prefer the `recall` tool with shape='revisions'.",
         inputSchema: {
             record_hash: z
                 .string()
                 .describe('Record hash (sha256:<64-hex>) of the record whose revision chain should be retrieved. Revisions are D059 records whose signed revises field equals this hash (or chain back to it).'),
         },
-    }, async (args) => logReadPrimitiveCall('recall_revisions', args, async () => {
-        const { loaded, revisionsByRecord } = getLoadedMirrorSnapshot();
-        const byHash = new Map();
-        for (const lr of loaded)
-            byHash.set(lr.record_hash, lr);
-        const chain = [];
-        const seen = new Set();
-        let current = args.record_hash;
-        while (!seen.has(current)) {
-            seen.add(current);
-            const next = revisionsByRecord.get(current);
-            if (!next || next.length === 0)
-                break;
-            // Each entry in the map's value array is a revision pointing at
-            // `current`. The chain follows the first-by-timestamp revision;
-            // the remaining entries are surfaced as `sibling_hashes` so the
-            // agent learns that branches exist without the chain shape
-            // having to explode into a tree.
-            const revHash = next[0];
-            const siblings = next.slice(1);
-            const revLr = byHash.get(revHash);
-            const entry = { record_hash: revHash };
-            if (revLr) {
-                entry.timestamp = revLr.record.timestamp;
-                const c = revLr.content;
-                if (c && typeof c === 'object' && !Array.isArray(c)) {
-                    const cObj = c;
-                    if (typeof cObj.new_position === 'string')
-                        entry.new_position = cObj.new_position;
-                    if (typeof cObj.reason === 'string')
-                        entry.reason = cObj.reason;
-                    if (typeof cObj.importance === 'string')
-                        entry.importance = cObj.importance;
-                }
-            }
-            if (siblings.length > 0) {
-                entry.sibling_hashes = siblings;
-            }
-            chain.push(entry);
-            current = revHash;
-        }
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({ record_hash: args.record_hash, revision_chain: chain }, null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
+    }, async (args) => logReadPrimitiveCall('recall_revisions', args, async () => jsonToolResult(await runRecallRevisions(args)), extractRecordHashFieldsFromMcpResult));
     server.registerTool('recall_by_content', {
-        description: "Free-form text search over the agent's signed past. Returns top-k records by hybrid retrieval: BM25 over each record's per-event_type indexable text (observation `what + why_noted + intent + rationale + topics`; tool_call `tool_name + args + result`; annotation `summary + topics`; revision `prior_position + new_position + reason + topics`; transaction counterparty + memo; directory_anchor tree_root; extension URIs via generic recursive string-walk per D086/D118) plus the annotation summary + topics when present as a curator-quality lift. Reranked by Park et al. weighted-sum scoring with annotation-derived importance and recency signals. Raw unannotated tool_call records are score-demoted so operation logs do not dominate substantive memory. BM25 contribution is clamped to [0, 1] before coverage scaling so the documented Park-component bound is honored. Responses include runtime metadata plus coverage.index, so callers can detect stale MCP processes and whether the durable content-token sidecar was hit, rebuilt, disabled, or bypassed. Useful when the agent has no specific filter and needs to ask 'what do I know about X?'.",
+        description: "Free-form text search over the agent's signed past. Returns top-k records by hybrid retrieval: BM25 over each record's per-event_type indexable text (observation `what + why_noted + intent + rationale + topics`; tool_call `tool_name + args + result`; annotation `summary + topics`; revision `prior_position + new_position + reason + topics`; transaction counterparty + memo; directory_anchor tree_root; extension URIs via generic recursive string-walk per D086/D118) plus the annotation summary + topics when present as a curator-quality lift. Reranked by Park et al. weighted-sum scoring with annotation-derived importance and recency signals. Raw unannotated tool_call records are score-demoted so operation logs do not dominate substantive memory. BM25 contribution is clamped to [0, 1] before coverage scaling so the documented Park-component bound is honored. Responses include runtime metadata plus coverage.index, so callers can detect stale MCP processes and whether the durable content-token sidecar was hit, rebuilt, disabled, or bypassed. Useful when the agent has no specific filter and needs to ask 'what do I know about X?'. Legacy alias: new callers should prefer the `recall` tool with shape='content'.",
         inputSchema: {
             query: z
                 .string()
@@ -1445,129 +1629,14 @@ export function registerAtribRecallTools(server) {
                 .optional()
                 .describe('Lift the operational tool_call score suppression for this query so unannotated tool_call records, including their indexed args and result excerpts, rank by ordinary recency and relevance. The default keeps them down-weighted so operational noise does not dominate conversational recall.'),
         },
-    }, async (args) => logReadPrimitiveCall('recall_by_content', args, async () => {
-        const evidenceMode = args.evidence_mode === 'require_complete' ? 'require_complete' : 'bounded';
-        const includeToolCallArgs = args.include_tool_call_args === true;
-        const boundedLimit = resolveBoundedContentSearchLimit(args.max_records, Number.MAX_SAFE_INTEGER);
-        const snapshot = getContentSearchSnapshotForRecall(evidenceMode, boundedLimit);
-        const { entryByHash } = snapshot;
-        const totalRecords = snapshot.totalRecords;
-        const loadedLength = snapshot.entries.length;
-        const searchLimit = evidenceMode === 'require_complete'
-            ? resolveCompleteContentSearchLimit(args.max_records, loadedLength)
-            : Math.min(boundedLimit, loadedLength);
-        const explicitLimit = hasExplicitRecordLimit(args.max_records);
-        if (evidenceMode === 'require_complete' && explicitLimit && searchLimit < loadedLength) {
-            const k = Math.max(1, Math.min(50, args.k ?? 10));
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            query: args.query,
-                            k,
-                            runtime: recallRuntimeMetadata(),
-                            ...(includeToolCallArgs ? { include_tool_call_args: true } : {}),
-                            evidence_mode: evidenceMode,
-                            evidence_status: 'incomplete',
-                            fallback_required: true,
-                            fallback_reason: `require_complete refused a partial corpus: search_cap=${searchLimit}, ` +
-                                `total_records=${loadedLength}.`,
-                            fallback: 'Rerun without max_records for full loaded-mirror coverage, or pass an explicit ' +
-                                'partition filter through a caller-owned audit plan and treat each partition as its own coverage claim.',
-                            total_records: loadedLength,
-                            searched_records: 0,
-                            search_cap: searchLimit,
-                            coverage: recallCoverage(snapshot, 'incomplete_explicit_limit', 0, snapshot.index),
-                            candidate_records: 0,
-                            truncated_corpus: true,
-                            count: 0,
-                            results: [],
-                        }, null, 2),
-                    },
-                ],
-            };
-        }
-        const bm25Index = getContentBm25IndexForNewestLimit(snapshot, searchLimit);
-        const queryTokens = tokenize(args.query);
-        const relevanceByHash = bm25ScoresForQuery(bm25Index, queryTokens);
-        const now = Date.now();
-        const searchPool = queryTokens.length > 0
-            ? Array.from(relevanceByHash.keys())
-                .map((hash) => entryByHash.get(hash))
-                .filter((entry) => entry !== undefined)
-            : snapshot.newestEntries.slice(0, searchLimit);
-        const filteredSearchPool = searchPool.filter((entry) => !(entry.lifecycle_anchor && !queryMentionsLifecycle(queryTokens)));
-        const scored = filteredSearchPool.map((entry) => {
-            const ann = entry.annotations;
-            const suppressLifecycleAnchor = entry.lifecycle_anchor && !queryMentionsLifecycle(queryTokens);
-            const toolCallScoreFactor = effectiveToolCallScoreFactor(entry, includeToolCallArgs);
-            const r = recencyScore(entry.timestamp, now, ATRIB_RECALL_TAU_DAYS) * toolCallScoreFactor;
-            const i = suppressLifecycleAnchor ? 0 : importanceScore(ann);
-            const rawRel = !suppressLifecycleAnchor && queryTokens.length > 0
-                ? (relevanceByHash.get(entry.record_hash) ?? 0)
-                : 0;
-            const rel = !suppressLifecycleAnchor && queryTokens.length > 0
-                ? normalizedBm25Relevance(bm25Index, entry.record_hash, queryTokens, rawRel) *
-                    toolCallScoreFactor
-                : 0;
-            const score = parkScore(r, i, rel, ATRIB_RECALL_ALPHA, ATRIB_RECALL_BETA, ATRIB_RECALL_GAMMA);
-            return { entry, score, recency: r, importance: i, relevance: rel };
-        });
-        scored.sort((a, b) => {
-            if (b.score !== a.score)
-                return b.score - a.score;
-            return b.entry.timestamp - a.entry.timestamp;
-        });
-        const k = Math.max(1, Math.min(50, args.k ?? 10));
-        const top = scored.slice(0, k);
-        const completeCoverage = !snapshot.partial && searchLimit >= loadedLength;
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        query: args.query,
-                        k,
-                        runtime: recallRuntimeMetadata(),
-                        ...(includeToolCallArgs ? { include_tool_call_args: true } : {}),
-                        evidence_mode: evidenceMode,
-                        evidence_status: completeCoverage ? 'complete' : 'bounded',
-                        fallback_required: false,
-                        total_records: totalRecords,
-                        searched_records: searchLimit,
-                        coverage: recallCoverage(snapshot, completeCoverage ? 'complete_full_scan' : 'bounded_newest_first', searchLimit, snapshot.index),
-                        candidate_records: filteredSearchPool.length,
-                        truncated_corpus: !completeCoverage,
-                        count: top.length,
-                        results: top.map(({ entry, score, recency, importance, relevance }) => {
-                            return {
-                                record_hash: entry.record_hash,
-                                event_type: entry.event_type,
-                                context_id: entry.context_id,
-                                timestamp: entry.timestamp,
-                                tool_name: entry.tool_name,
-                                annotations: entry.annotations,
-                                // Layer 1 v2 legibility fields (parity with compactify).
-                                display_summary: entry.display_summary,
-                                display_producer: entry.display_producer,
-                                age: formatAge(entry.timestamp, now),
-                                score,
-                                components: { recency, importance, relevance },
-                            };
-                        }),
-                    }, null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
+    }, async (args) => logReadPrimitiveCall('recall_by_content', args, async () => jsonToolResult(await runRecallByContent(args)), extractRecordHashFieldsFromMcpResult));
     // recall_session_chain: records in a context_id, ordered chronologically
     // (the natural traversal of the CHAIN_PRECEDES topology). Doable via
     // recall_my_attribution_history({context_id}) + a manual timestamp sort,
     // but agents naturally think "what happened in this session?" and this
     // gives them one call.
     server.registerTool('recall_session_chain', {
-        description: "Return all records in a context_id, ordered chronologically (oldest-first). The natural traversal of the CHAIN_PRECEDES topology for a single session/trace. Each entry carries record_hash, event_type, timestamp, display_summary (per-event_type human-readable text from D086), and producer label. Useful for 'what happened in this session?' without manually sorting filter results. Sibling tool to recall_my_attribution_history with built-in context_id scoping + chain-ascending order.",
+        description: "Return all records in a context_id, ordered chronologically (oldest-first). The natural traversal of the CHAIN_PRECEDES topology for a single session/trace. Each entry carries record_hash, event_type, timestamp, display_summary (per-event_type human-readable text from D086), and producer label. Useful for 'what happened in this session?' without manually sorting filter results. Sibling tool to recall_my_attribution_history with built-in context_id scoping + chain-ascending order. Legacy alias: new callers should prefer the `recall` tool with shape='chain'.",
         inputSchema: {
             context_id: z
                 .string()
@@ -1582,81 +1651,11 @@ export function registerAtribRecallTools(server) {
                 .optional()
                 .describe('When true, include D062 local mirror body as local_content on each returned record. Defaults false to keep the session chain cheap.'),
         },
-    }, async (args) => logReadPrimitiveCall('recall_session_chain', args, async () => {
-        const ctx = args.context_id ?? resolveEnvContextId();
-        if (!ctx) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            context_id: null,
-                            count: 0,
-                            records: [],
-                            warning: 'no context_id supplied or resolvable via env',
-                        }, null, 2),
-                    },
-                ],
-            };
-        }
-        const { loaded, annotationsByRecord } = getLoadedMirrorSnapshot();
-        const filtered = loaded
-            .filter((lr) => lr.record.context_id === ctx)
-            .sort((a, b) => a.record.timestamp - b.record.timestamp);
-        const limit = Math.max(1, Math.min(500, args.limit ?? 50));
-        const sliced = filtered.slice(0, limit);
-        const now = Date.now();
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        context_id: ctx,
-                        total: filtered.length,
-                        returned: sliced.length,
-                        truncated: filtered.length > sliced.length,
-                        records: sliced.map((lr) => {
-                            const ann = annotationsByRecord.get(lr.record_hash);
-                            const entry = {
-                                record_hash: lr.record_hash,
-                                event_type: lr.record.event_type,
-                                timestamp: lr.record.timestamp,
-                                display_summary: synthesizeDisplaySummary(lr.record, lr.content, ann),
-                                display_producer: resolveDisplayProducer(lr.record, lr.producer),
-                                age: formatAge(lr.record.timestamp, now),
-                            };
-                            const informedBy = lr.record
-                                .informed_by;
-                            const toolName = lr.record.tool_name;
-                            const argsHash = lr.record.args_hash;
-                            const resultHash = lr.record
-                                .result_hash;
-                            if (Array.isArray(informedBy) && informedBy.length > 0) {
-                                entry.informed_by = informedBy;
-                            }
-                            if (toolName)
-                                entry.tool_name = toolName;
-                            if (argsHash)
-                                entry.args_hash = argsHash;
-                            if (resultHash)
-                                entry.result_hash = resultHash;
-                            if (args.include_content === true && lr.content !== undefined) {
-                                entry.local_content = lr.content;
-                            }
-                            if (args.include_content === true && lr.producer !== undefined) {
-                                entry.local_producer = lr.producer;
-                            }
-                            return entry;
-                        }),
-                    }, null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
+    }, async (args) => logReadPrimitiveCall('recall_session_chain', args, async () => jsonToolResult(await runRecallSessionChain(args)), extractRecordHashFieldsFromMcpResult));
     // recall_orphans: records nothing else cites via informed_by. Useful for
     // "what decisions did I make and never act on?": loose-end discovery.
     server.registerTool('recall_orphans', {
-        description: "Return records that are NOT cited by any other record via informed_by (loose ends: decisions or observations the agent made but never followed up on). Surfaces records whose record_hash does NOT appear in any other record's informed_by[] array within the local mirror. Optionally scoped to one context_id, one event_type, or one creator_key. Useful for the agent to discover dropped balls (e.g. 'I noted X but never built on it').",
+        description: "Return records that are NOT cited by any other record via informed_by (loose ends: decisions or observations the agent made but never followed up on). Surfaces records whose record_hash does NOT appear in any other record's informed_by[] array within the local mirror. Optionally scoped to one context_id, one event_type, or one creator_key. Useful for the agent to discover dropped balls (e.g. 'I noted X but never built on it'). Legacy alias: new callers should prefer the `recall` tool with shape='orphans'.",
         inputSchema: {
             context_id: z
                 .string()
@@ -1672,119 +1671,47 @@ export function registerAtribRecallTools(server) {
                 .optional()
                 .describe('Maximum records to return (default 50, max 500), newest-first.'),
         },
-    }, async (args) => logReadPrimitiveCall('recall_orphans', args, async () => {
-        const { loaded, annotationsByRecord } = getLoadedMirrorSnapshot();
-        // Build the set of all record_hashes that appear in any record's
-        // informed_by field. Anything in `loaded` whose record_hash is
-        // NOT in this set is an orphan.
-        const cited = new Set();
-        for (const lr of loaded) {
-            const ib = lr.record.informed_by;
-            if (Array.isArray(ib)) {
-                for (const h of ib)
-                    if (typeof h === 'string')
-                        cited.add(h);
-            }
-        }
-        let orphans = loaded.filter((lr) => !cited.has(lr.record_hash));
-        if (args.context_id) {
-            orphans = orphans.filter((lr) => lr.record.context_id === args.context_id);
-        }
-        if (args.creator_key) {
-            orphans = orphans.filter((lr) => lr.record.creator_key === args.creator_key);
-        }
-        if (args.event_type) {
-            const targetUri = normalizeEventType(args.event_type);
-            orphans = orphans.filter((lr) => lr.record.event_type === targetUri);
-        }
-        orphans.sort((a, b) => b.record.timestamp - a.record.timestamp);
-        const limit = Math.max(1, Math.min(500, args.limit ?? 50));
-        const sliced = orphans.slice(0, limit);
-        const now = Date.now();
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        total: orphans.length,
-                        returned: sliced.length,
-                        truncated: orphans.length > sliced.length,
-                        records: sliced.map((lr) => {
-                            const ann = annotationsByRecord.get(lr.record_hash);
-                            return {
-                                record_hash: lr.record_hash,
-                                event_type: lr.record.event_type,
-                                context_id: lr.record.context_id,
-                                timestamp: lr.record.timestamp,
-                                display_summary: synthesizeDisplaySummary(lr.record, lr.content, ann),
-                                display_producer: resolveDisplayProducer(lr.record, lr.producer),
-                                age: formatAge(lr.record.timestamp, now),
-                            };
-                        }),
-                    }, null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
+    }, async (args) => logReadPrimitiveCall('recall_orphans', args, async () => jsonToolResult(await runRecallOrphans(args)), extractRecordHashFieldsFromMcpResult));
     // recall_by_signer: aggregate the mirror by creator_key. Lets the agent
     // ask "who else is in this mirror?" before deciding whether to scope
     // queries with creator_key filters. Useful when the mirror is shared
     // across multi-agent flows (transactions with counterparty signers,
     // peer-shared records, etc.).
     server.registerTool('recall_by_signer', {
-        description: "Aggregate the local mirror by creator_key. Returns the distinct creators present + per-creator record count + latest record timestamp. Useful when the mirror is multi-signer (multi-agent flows, transactions with counterparty signers) and the agent wants to discover who else's records are in scope before deciding whether to filter with creator_key. Pure aggregation; no records returned directly. Use recall_my_attribution_history with the creator_key filter to drill into one creator's records.",
+        description: "Aggregate the local mirror by creator_key. Returns the distinct creators present + per-creator record count + latest record timestamp. Useful when the mirror is multi-signer (multi-agent flows, transactions with counterparty signers) and the agent wants to discover who else's records are in scope before deciding whether to filter with creator_key. Pure aggregation; no records returned directly. Use recall_my_attribution_history with the creator_key filter to drill into one creator's records. Legacy alias: new callers should prefer the `recall` tool with shape='by_signer'.",
         inputSchema: {
             min_records: z
                 .number()
                 .optional()
                 .describe('Optional minimum record count to include a creator in the result. Default 1 (include all).'),
         },
-    }, async (args) => logReadPrimitiveCall('recall_by_signer', args, async () => {
-        const { loaded } = getLoadedMirrorSnapshot();
-        const byKey = new Map();
-        for (const lr of loaded) {
-            const key = lr.record.creator_key;
-            const existing = byKey.get(key);
-            if (existing) {
-                existing.count++;
-                if (lr.record.timestamp > existing.latest_timestamp)
-                    existing.latest_timestamp = lr.record.timestamp;
-                if (lr.record.timestamp < existing.earliest_timestamp)
-                    existing.earliest_timestamp = lr.record.timestamp;
-            }
-            else {
-                byKey.set(key, {
-                    creator_key: key,
-                    count: 1,
-                    latest_timestamp: lr.record.timestamp,
-                    earliest_timestamp: lr.record.timestamp,
-                });
-            }
-        }
-        const minRecords = Math.max(1, args.min_records ?? 1);
-        const stats = [...byKey.values()]
-            .filter((s) => s.count >= minRecords)
-            .sort((a, b) => b.count - a.count);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        total_signers: stats.length,
-                        total_records: loaded.length,
-                        signers: stats,
-                    }, null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
+    }, async (args) => logReadPrimitiveCall('recall_by_signer', args, async () => jsonToolResult(await runRecallBySigner(args)), extractRecordHashFieldsFromMcpResult));
+}
+// ─── Re-export surface for the @atrib/trace and @atrib/verify-mcp shims
+// and for embedders. The implementations live in this package per the
+// attest/recall rename; the legacy packages re-export them.
+export { compactVisited, createAtribTraceServer, registerTraceTools, runTraceWalk, summarizeSidecar, TraceInput, } from './trace-tools.js';
+export { extractRecordHashFieldsFromMcpResult };
+export { createAtribVerifyServer, handleAtribVerify, loadVerifyModule, registerVerifyTool, tryHandleAtribVerify, VerifyInput, } from './verification.js';
+export { registerRecallVerbTool, RecallVerbInput, RECALL_SHAPES, runRecallVerb } from './recall-verb.js';
+/**
+ * Register the full read union on one server: the `recall` verb plus every
+ * legacy read tool name it absorbs (8 recall_* tools, trace, trace_forward,
+ * atrib-verify). This is what the `atrib-recall` binary serves and what the
+ * primitive runtime / daemon mount for reads (alias-window rule W1).
+ */
+export function registerAtribReadTools(server) {
+    registerRecallVerbTool(server);
+    registerAtribRecallTools(server);
+    registerTraceTools(server);
+    registerVerifyTool(server);
 }
 export function createAtribRecallServer() {
     const mcp = new McpServer({
         name: 'atrib-recall',
         version: readPackageVersion(),
     });
-    registerAtribRecallTools(mcp);
+    registerAtribReadTools(mcp);
     return { mcp };
 }
 async function main() {