@atrib/recall 0.3.2 → 0.6.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: Apache-2.0
 /**
- * @atrib/recall — recall_my_attribution_history MCP server.
+ * @atrib/recall - recall_my_attribution_history MCP server.
  *
  * Exposes a single tool to the host agent: recall_my_attribution_history.
  * Reads signed-record jsonl mirrors (per spec §5.9), VERIFIES the Ed25519
@@ -10,9 +10,9 @@
  * or partial mirror state.
  *
  * Mirror discovery (in priority order):
- *   1. ATRIB_RECORD_FILE — single explicit jsonl file. Back-compat with
+ *   1. ATRIB_RECORD_FILE - single explicit jsonl file. Back-compat with
  *      pre-0.4.0 callers that pinned a specific producer's mirror.
- *   2. ATRIB_MIRROR_DIR — directory; recall reads every `*.jsonl` inside.
+ *   2. ATRIB_MIRROR_DIR - directory; recall reads every `*.jsonl` inside.
  *      Default: ~/.atrib/records (the spec §5.9 well-known mirror namespace).
  *
  * Two on-disk shapes are accepted, matching D062 / spec §5.9:
@@ -26,14 +26,14 @@
  * should fetch the inclusion proof from the log API.
  *
  * Configuration via environment variables:
- *   ATRIB_RECORD_FILE — single explicit file (overrides directory scan).
- *   ATRIB_MIRROR_DIR — directory to scan. Default: ~/.atrib/records.
- *   ATRIB_LOG_ORIGIN — origin used in human-readable messages.
+ *   ATRIB_RECORD_FILE - single explicit file (overrides directory scan).
+ *   ATRIB_MIRROR_DIR - directory to scan. Default: ~/.atrib/records.
+ *   ATRIB_LOG_ORIGIN - origin used in human-readable messages.
  *                        Default: log.atrib.dev
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { verifyRecord, EVENT_TYPE_TOOL_CALL_URI, EVENT_TYPE_TRANSACTION_URI, } from '@atrib/mcp';
+import { verifyRecord, EVENT_TYPE_TOOL_CALL_URI, EVENT_TYPE_TRANSACTION_URI, EVENT_TYPE_ANNOTATION_URI, EVENT_TYPE_REVISION_URI, } from '@atrib/mcp';
 // Short-form event_type names accepted by the recall MCP schema map onto
 // their atrib-normative URI form (spec §1.2.4). Records sign the URI form
 // per §1.4.5 + isValidEventTypeUri; without this mapping, a recall caller
@@ -42,14 +42,45 @@ import { verifyRecord, EVENT_TYPE_TOOL_CALL_URI, EVENT_TYPE_TRANSACTION_URI, } f
 const EVENT_TYPE_SHORT_TO_URI = {
     tool_call: EVENT_TYPE_TOOL_CALL_URI,
     transaction: EVENT_TYPE_TRANSACTION_URI,
+    annotation: EVENT_TYPE_ANNOTATION_URI,
+    revision: EVENT_TYPE_REVISION_URI,
 };
+export const IMPORTANCE_NUMERIC = {
+    critical: 5,
+    high: 4,
+    medium: 3,
+    low: 2,
+    noise: 1,
+};
+// Layer 1 ranking weights per the recall semantic surface design. Park et al. 2023
+// "Generative Agents" defaults; tunable via env for experiment-time
+// per-axis sensitivity studies. Values must sum to 1.0; the implementation
+// does not enforce this but the operator-facing default does. Exported so
+// future releases implementing the parkScore function can import them.
+export const ATRIB_RECALL_ALPHA = parseFloat(process.env.ATRIB_RECALL_ALPHA ?? '0.3');
+export const ATRIB_RECALL_BETA = parseFloat(process.env.ATRIB_RECALL_BETA ?? '0.3');
+export const ATRIB_RECALL_GAMMA = parseFloat(process.env.ATRIB_RECALL_GAMMA ?? '0.4');
+// Recency time constant (in days) for the exponential-decay scoring
+// component. 7-day default per design; longer windows favor older records,
+// shorter windows favor very-recent records. Tunable per experiment.
+export const ATRIB_RECALL_TAU_DAYS = parseFloat(process.env.ATRIB_RECALL_TAU_DAYS ?? '7');
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { z } from 'zod';
+import { aggregateAnnotationsByRecord, aggregateRevisionsByRecord, discoverLoaded, } from './aggregations.js';
+import { recencyScore, importanceScore, parkScore, buildBM25Index, bm25Score, tokenize, indexableTextFromAnnotation, } from './scoring.js';
+import { buildLocalGraph, shortestDistances, walkFrom, } from './graph.js';
 const ATRIB_RECORD_FILE = process.env.ATRIB_RECORD_FILE;
 const ATRIB_MIRROR_DIR = process.env.ATRIB_MIRROR_DIR ?? join(homedir(), '.atrib', 'records');
 const ATRIB_LOG_ORIGIN = process.env.ATRIB_LOG_ORIGIN ?? 'log.atrib.dev';
+// 32-hex context_id pattern per spec §1.2.3. Read once at module-init so
+// every recall invocation honors the same value (the env var is a per-run
+// declaration; changing it mid-process is not supported).
+const HEX_32_CONTEXT_ID = /^[0-9a-f]{32}$/;
+const ATRIB_CONTEXT_ID_DEFAULT = process.env.ATRIB_CONTEXT_ID && HEX_32_CONTEXT_ID.test(process.env.ATRIB_CONTEXT_ID)
+    ? process.env.ATRIB_CONTEXT_ID
+    : undefined;
 /**
  * Pull the inner AtribRecord out of either on-disk shape (D062 envelope or
  * legacy bare record). Returns null when the line is neither shape or is
@@ -105,7 +136,7 @@ export function loadRecords(path) {
  * 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 function loadRecordsFromDir(dir) {
     if (!existsSync(dir))
@@ -137,35 +168,145 @@ export function loadRecordsFromDir(dir) {
         else {
             // Surface empty/unreadable files too so the operator can see them in
             // the response if they care, but only if the file existed (which it
-            // does — readdirSync returned it).
+            // does - readdirSync returned it).
             files.push(full);
         }
     }
     return { records, files };
 }
-async function annotateVerification(records) {
-    return Promise.all(records.map(async (r) => {
+/**
+ * Sort `filtered` in-place by Park et al. parkScore descending. Builds
+ * the BM25 index over each loaded record's annotation summary + topics
+ * (the indexable Layer 1 text per the design); when rank_anchor is a
+ * non-empty string, treats it as the query and adds the relevance
+ * component. When rank_anchor is empty or a record_hash (the
+ * causal_distance shape), relevance is 0 for every record and the score
+ * collapses to alpha*recency + beta*importance.
+ *
+ * Uses now=Date.now() inside the function so the recall response reflects
+ * the moment of evaluation. Determinism is preserved at the per-call
+ * level (two recall() calls in the same millisecond produce identical
+ * scores given identical input).
+ */
+function rankByRelevance(filtered, annotationsByRecord, rankAnchor) {
+    const now = Date.now();
+    // Treat rank_anchor as a free-form query unless it parses as a record_hash
+    // (sha256:<64-hex>). Future: when rank_by='causal_distance' wires up,
+    // record_hash anchors go to the BFS path; here, record_hash anchors
+    // contribute 0 relevance (recency + importance only).
+    const looksLikeRecordHash = typeof rankAnchor === 'string' && /^sha256:[0-9a-f]{64}$/.test(rankAnchor);
+    const queryTokens = rankAnchor && !looksLikeRecordHash ? tokenize(rankAnchor) : [];
+    // Build the BM25 index over the filtered set's indexable text. Index
+    // construction is O(total token count); for Layer 1 corpus sizes this
+    // is negligible (a few hundred records × tens of tokens each).
+    const corpus = filtered.map((lr) => ({
+        id: lr.record_hash,
+        tokens: indexableTextFromAnnotation(annotationsByRecord.get(lr.record_hash)),
+    }));
+    const idx = buildBM25Index(corpus);
+    const scores = new Map();
+    for (const lr of filtered) {
+        const r = recencyScore(lr.record.timestamp, now, ATRIB_RECALL_TAU_DAYS);
+        const i = importanceScore(annotationsByRecord.get(lr.record_hash));
+        const rel = queryTokens.length > 0
+            ? bm25Score(idx, lr.record_hash, queryTokens)
+            : 0;
+        scores.set(lr.record_hash, parkScore(r, i, rel, ATRIB_RECALL_ALPHA, ATRIB_RECALL_BETA, ATRIB_RECALL_GAMMA));
+    }
+    filtered.sort((a, b) => {
+        const sa = scores.get(a.record_hash) ?? 0;
+        const sb = scores.get(b.record_hash) ?? 0;
+        if (sb !== sa)
+            return sb - sa;
+        // Stable tie-break on timestamp newest-first.
+        return b.record.timestamp - a.record.timestamp;
+    });
+}
+/**
+ * Sort `filtered` in-place by BFS shortest-path distance from rank_anchor.
+ * The graph is built from the FULL `all` set (not just filtered) so the
+ * BFS can traverse through records that the post-filter pipeline would
+ * later drop — the agent's question is "what's causally near this
+ * anchor", not "what's causally near and also matches my filters".
+ *
+ * Records unreachable from rank_anchor are sorted to the end (Infinity
+ * distance) with a stable timestamp tie-break newest-first.
+ *
+ * If rank_anchor is missing or doesn't parse as a record_hash, the
+ * function leaves `filtered` in input order. (Callers passing a free-form
+ * query meant rank_by='relevance' instead; we don't second-guess.)
+ */
+function rankByCausalDistance(filtered, all, rankAnchor) {
+    if (!rankAnchor || !/^sha256:[0-9a-f]{64}$/.test(rankAnchor)) {
+        // Fall back to timestamp newest-first when the anchor is unusable;
+        // matches the existing pre-Layer-1 default rather than leaving an
+        // arbitrary order.
+        filtered.sort((a, b) => b.record.timestamp - a.record.timestamp);
+        return;
+    }
+    const graph = buildLocalGraph(all);
+    const dist = shortestDistances(graph, rankAnchor);
+    filtered.sort((a, b) => {
+        const da = dist.get(a.record_hash) ?? Number.POSITIVE_INFINITY;
+        const db = dist.get(b.record_hash) ?? Number.POSITIVE_INFINITY;
+        if (da !== db)
+            return da - db;
+        return b.record.timestamp - a.record.timestamp;
+    });
+}
+async function annotateVerification(loaded, annotationsByRecord, revisionsByRecord) {
+    return Promise.all(loaded.map(async (lr) => {
         let ok = false;
         try {
-            ok = await verifyRecord(r);
+            ok = await verifyRecord(lr.record);
         }
         catch {
             ok = false;
         }
-        return { ...r, signature_verified: ok };
+        const out = {
+            record: lr.record,
+            record_hash: lr.record_hash,
+            signature_verified: ok,
+        };
+        const ann = annotationsByRecord.get(lr.record_hash);
+        if (ann)
+            out.annotations = ann;
+        const supers = revisionsByRecord.get(lr.record_hash);
+        if (supers && supers.length > 0)
+            out.superseded_by = supers;
+        return out;
     }));
 }
-function compactify(records) {
-    return records.map((r) => {
+function compactify(bundles) {
+    return bundles.map((b) => {
+        const r = b.record;
         const out = {
             event_type: r.event_type,
             context_id: r.context_id,
             creator_key: r.creator_key,
             timestamp: r.timestamp,
-            signature_verified: r.signature_verified,
+            signature_verified: b.signature_verified,
         };
-        if (r.session_token)
-            out.session_token = r.session_token;
+        const sessionToken = r.session_token;
+        const toolName = r.tool_name;
+        if (sessionToken)
+            out.session_token = sessionToken;
+        if (toolName)
+            out.tool_name = toolName;
+        if (b.annotations)
+            out.annotations = b.annotations;
+        if (b.superseded_by)
+            out.superseded_by = b.superseded_by;
+        return out;
+    });
+}
+function fullify(bundles) {
+    return bundles.map((b) => {
+        const out = { ...b.record, signature_verified: b.signature_verified };
+        if (b.annotations)
+            out.annotations = b.annotations;
+        if (b.superseded_by)
+            out.superseded_by = b.superseded_by;
         return out;
     });
 }
@@ -194,24 +335,81 @@ export async function recall(args, recordFile) {
     // would otherwise treat tampered records as provable. Default to safe.
     const compact = args.compact !== false;
     const includeUnverified = args.include_unverified === true;
-    const { records: all, files } = discoverRecords(recordFile);
+    const { loaded: all, files } = discoverLoaded(recordFile);
+    const annotationsByRecord = aggregateAnnotationsByRecord(all);
+    const revisionsByRecord = aggregateRevisionsByRecord(all);
+    // Apply ATRIB_CONTEXT_ID env-var default when the caller omits the
+    // context_id filter. Lets Inspect-style harnesses scope recall to a
+    // per-arm context_id without threading it through every tool call;
+    // an explicit args.context_id always wins (explicit beats implicit).
+    const effectiveContextId = args.context_id ?? ATRIB_CONTEXT_ID_DEFAULT;
     let filtered = all;
-    if (args.context_id)
-        filtered = filtered.filter((r) => r.context_id === args.context_id);
+    if (effectiveContextId)
+        filtered = filtered.filter((lr) => lr.record.context_id === effectiveContextId);
     if (args.event_type) {
         // Schema accepts short form ('tool_call'|'transaction'); records carry
         // the URI form. Normalize before comparison; pass URIs through as-is so
         // a forward-compatible caller passing the URI directly still matches.
         const targetUri = EVENT_TYPE_SHORT_TO_URI[args.event_type] ?? args.event_type;
-        filtered = filtered.filter((r) => r.event_type === targetUri);
+        filtered = filtered.filter((lr) => lr.record.event_type === targetUri);
+    }
+    if (args.content_id)
+        filtered = filtered.filter((lr) => lr.record.content_id === args.content_id);
+    if (args.tool_name)
+        filtered = filtered.filter((lr) => lr.record.tool_name === args.tool_name);
+    if (args.args_hash)
+        filtered = filtered.filter((lr) => lr.record.args_hash === args.args_hash);
+    // Layer 1 filters (consume the annotation + revision aggregations).
+    if (args.min_importance) {
+        const minScore = IMPORTANCE_NUMERIC[args.min_importance];
+        filtered = filtered.filter((lr) => {
+            const ann = annotationsByRecord.get(lr.record_hash);
+            if (!ann || !ann.max_importance)
+                return false;
+            return IMPORTANCE_NUMERIC[ann.max_importance] >= minScore;
+        });
+    }
+    if (args.topic_tags && args.topic_tags.length > 0) {
+        const wanted = new Set(args.topic_tags);
+        filtered = filtered.filter((lr) => {
+            const ann = annotationsByRecord.get(lr.record_hash);
+            return !!ann?.topics?.some((t) => wanted.has(t));
+        });
+    }
+    // include_revised is misnamed: `true` HIDES records that have revisions
+    // pointing at them. `false` / undefined keeps them visible (the default;
+    // they appear with superseded_by populated). See the schema description.
+    if (args.include_revised === true) {
+        filtered = filtered.filter((lr) => !revisionsByRecord.has(lr.record_hash));
+    }
+    // min_signers: distinct-signer count is signers?.length (transaction records
+    // per D052) or 1 (the implicit creator's single signature on every other
+    // event_type). Records below the threshold are excluded.
+    if (typeof args.min_signers === 'number') {
+        const min = args.min_signers;
+        filtered = filtered.filter((lr) => {
+            const signersField = lr.record.signers;
+            const count = Array.isArray(signersField) ? signersField.length : 1;
+            return count >= min;
+        });
+    }
+    // Sort: timestamp (default, newest first), Park et al. relevance, or
+    // BFS shortest-path causal distance from rank_anchor.
+    if (args.rank_by === 'relevance') {
+        rankByRelevance(filtered, annotationsByRecord, args.rank_anchor);
+    }
+    else if (args.rank_by === 'causal_distance') {
+        rankByCausalDistance(filtered, all, args.rank_anchor);
+    }
+    else {
+        // Newest first - the agent typically wants its most-recent provable
+        // actions, not the genesis of the log.
+        filtered.sort((a, b) => b.record.timestamp - a.record.timestamp);
     }
-    // Newest first — the agent typically wants its most-recent provable
-    // actions, not the genesis of the log.
-    filtered.sort((a, b) => b.timestamp - a.timestamp);
     const offset = Math.max(0, args.offset ?? 0);
     const limit = Math.max(1, Math.min(200, args.limit ?? 25));
     const page = filtered.slice(offset, offset + limit);
-    let verified = await annotateVerification(page);
+    let verified = await annotateVerification(page, annotationsByRecord, revisionsByRecord);
     // Apply verification filter post-paging so `total` reflects the unfiltered
     // count (matches user expectation of "how many records exist that match
     // your context_id+event_type filters?"). filtered_out distinguishes the
@@ -222,7 +420,37 @@ export async function recall(args, recordFile) {
         verified = verified.filter((r) => r.signature_verified === true);
         filteredOutByVerification = before - verified.length;
     }
-    const records = compact ? compactify(verified) : verified;
+    // toc=true: ~40-80-token-per-entry shape suitable for SessionStart
+    // auto-injection. Pulls the cheap-to-scan fields and drops everything
+    // else. Implicit signature_verified is preserved-by-omission (only
+    // records that passed the verification filter make it here, unless
+    // the caller also set include_unverified=true).
+    const toc = args.toc === true;
+    let records;
+    if (toc) {
+        records = verified.map((b) => {
+            const out = { timestamp: b.record.timestamp };
+            out.record_hash = b.record_hash;
+            const toolName = b.record.tool_name;
+            if (toolName)
+                out.tool_name = toolName;
+            if (b.annotations?.summary)
+                out.summary = b.annotations.summary;
+            if (b.annotations?.max_importance)
+                out.importance = b.annotations.max_importance;
+            if (b.annotations?.topics)
+                out.topic_tags = b.annotations.topics;
+            if (b.superseded_by)
+                out.superseded_by = b.superseded_by;
+            return out;
+        });
+    }
+    else if (compact) {
+        records = compactify(verified);
+    }
+    else {
+        records = fullify(verified);
+    }
     return {
         total: filtered.length,
         returned: verified.length,
@@ -237,18 +465,31 @@ export async function recall(args, recordFile) {
 }
 const server = new McpServer({
     name: 'atrib-recall',
-    version: '0.3.0',
+    // Keep in sync with package.json. The Layer 1 stub scaffolding ships
+    // under the 0.4.0 surface (additive optional schema params + 4 stub
+    // tools that return "Layer 1 in progress" notice); the version bump
+    // happens via the queued changeset on next publication run.
+    version: '0.4.0',
 });
+// The recall semantic surface (as defined in the public protocol specification).
+// Five 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 over annotation
+// summaries + topic tags.
 server.registerTool('recall_my_attribution_history', {
-    description: "Return signed atrib records from the local mirror — the agent's own past, with each record's " +
+    description: "Return signed atrib records from the local mirror. The agent's own past, with each record's " +
         'Ed25519 signature verified locally. By default the response is compact (no signature bytes) and ' +
-        'includes only records that passed signature verification — both can be opted out of with ' +
+        'includes only records that passed signature verification; both can be opted out of with ' +
         'compact=false and include_unverified=true respectively. Local signature verification proves ' +
         '"this record was signed by that creator_key"; it does NOT prove log inclusion (fetch a log ' +
-        'inclusion proof to confirm). Filter by context_id (specific trace) or event_type ' +
-        '(tool_call|transaction); omit filters 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 ' +
+        'inclusion proof to confirm). Filter by context_id (specific trace), event_type ' +
+        '(tool_call|transaction), content_id (specific tool on specific server), tool_name (disclosed ' +
+        'name per §8.2), or args_hash (canonical-args commitment per §8.3). Filters are AND-combined; ' +
+        '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).',
     inputSchema: {
         context_id: z
@@ -260,11 +501,30 @@ server.registerTool('recall_my_attribution_history', {
             .enum(['tool_call', 'transaction'])
             .optional()
             .describe('Optional filter to a single event kind. Most calls leave this unset.'),
+        content_id: z
+            .string()
+            .optional()
+            .describe('Optional exact match on record.content_id (sha256:<64-hex>). Per spec §1.2.2, content_id ' +
+            'is sha256(serverUrl + ":" + toolName), so filtering groups all records emitted by the same ' +
+            'tool on the same MCP server. Coarser than tool_name (different servers, same name -> ' +
+            'different content_id).'),
+        tool_name: z
+            .string()
+            .optional()
+            .describe('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.'),
+        args_hash: z
+            .string()
+            .optional()
+            .describe('Optional exact match on record.args_hash (sha256:<64-hex>). Per spec §8.3, args_hash commits ' +
+            'to canonical args bytes (salted or plain; both forms hash identically on the wire). Most ' +
+            'useful for replay detection or agent-side keyed lookup over a normalized probe hash.'),
         limit: z.number().optional().describe('Page size, default 25, max 200.'),
         offset: z
             .number()
             .optional()
-            .describe('Pagination offset, default 0. Note: not stable when new records land between calls — see ' +
+            .describe('Pagination offset, default 0. Note: not stable when new records land between calls - see ' +
             'pagination_caveat in the response.'),
         compact: z
             .boolean()
@@ -277,15 +537,257 @@ server.registerTool('recall_my_attribution_history', {
             .optional()
             .describe('Default false. When false, records with signature_verified=false are dropped from the ' +
             'response (their count is reported in filtered_out_by_verification). Set to true to ' +
-            'include them — useful when investigating tampered or partial mirror state.'),
+            'include them - useful when investigating tampered or partial mirror state.'),
+        // ─── New schema params: accepted now; enforcement in flight. Each ───
+        //    of the seven params below is currently STUB-ACCEPTED: the schema
+        //    validates the value and the handler ignores it (returns the same
+        //    results it would return without the param). The response payload
+        //    includes a layer_1_warnings array listing which stub-accepted
+        //    params were silently ignored, so callers can detect the pre-impl
+        //    state without having to read source. Full enforcement implementation
+        //    lands in upcoming releases.
+        min_importance: z
+            .enum(['critical', 'high', 'medium', 'low', 'noise'])
+            .optional()
+            .describe('Filter to records whose maximum annotation importance is at least this level. Annotation ' +
+            'importance comes from annotation records pointing at the record. Records with no ' +
+            'annotations at all are excluded when this filter is set.'),
+        topic_tags: z
+            .array(z.string())
+            .optional()
+            .describe('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.'),
+        include_revised: z
+            .boolean()
+            .optional()
+            .describe('Default false: revised records remain visible with superseded_by populated. Set true to hide ' +
+            'records that have been superseded by a revision record (revises field equals this record).'),
+        min_signers: z
+            .number()
+            .optional()
+            .describe('Minimum count of distinct signers. Transaction records carry a signers[] array (cross- ' +
+            'attestation); the count is its length. Non-transaction records have a single signature; ' +
+            'their count is 1. Records below the threshold are excluded.'),
+        rank_by: z
+            .enum(['timestamp', 'relevance', 'causal_distance'])
+            .optional()
+            .describe('Result ordering. timestamp (default): newest first. relevance: Park et al. weighted-sum ' +
+            'scoring over recency + annotation-derived importance + BM25 relevance against rank_anchor ' +
+            '(treated as a free-form query when not a record_hash; otherwise relevance component is 0). ' +
+            'causal_distance: BFS shortest path in the local derived graph from rank_anchor (a record_hash). ' +
+            'Records unreachable from the anchor sort to the end.'),
+        rank_anchor: z
+            .string()
+            .optional()
+            .describe('Anchor for non-timestamp rank_by modes. For rank_by=relevance: free-form text query for the ' +
+            'BM25 component (matched against annotation summary + topics of each candidate). For ' +
+            'rank_by=causal_distance: record_hash to BFS from (sha256:<64-hex>); falls back to timestamp ' +
+            'newest-first when not a valid record_hash.'),
+        toc: z
+            .boolean()
+            .optional()
+            .describe('Default false. When true, each returned record is the table-of-contents entry shape ' +
+            '(record_hash, tool_name, summary, importance, topic_tags, timestamp, superseded_by) at ' +
+            '~40-80 tokens per entry. Designed for SessionStart auto-injected scaffold and any other ' +
+            'cheap-to-scan candidate set the agent expands on demand via recall(content_id=...) or ' +
+            'recall_walk.'),
     },
 }, async (args) => {
+    // Layer 1 stub-acceptance: detect newly-accepted Layer 1 params, run the
+    // existing 0.4.0 recall path (which ignores them), and return the
+    // result with a layer_1_warnings array listing exactly which stub-
+    // accepted params were silently ignored. Callers can detect the
+    // pre-implementation state without having to read source.
+    // All seven Layer 1 surface parameters are now enforced
+    // (min_importance, topic_tags, include_revised, min_signers,
+    // rank_by, rank_anchor, toc). The layer_1_warnings array stays in
+    // the response shape (per the original wire contract) but is now
+    // always empty unless a future Layer extension lands more
+    // stub-accepted params.
+    const ignored = [];
     const result = await recall(args);
+    const augmented = ignored.length > 0
+        ? {
+            ...result,
+            layer_1_warnings: ignored.map((k) => ({
+                param: k,
+                status: 'stub-accepted',
+                note: `Layer 1 param '${k}' was supplied; handler ignored it (full enforcement lands in upcoming release). Result reflects 0.4.0 behavior as if the param was not set.`,
+            })),
+        }
+        : result;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(augmented, null, 2),
+            },
+        ],
+    };
+});
+// ─── Layer 1 sibling tools ───
+// recall_walk, recall_annotations, recall_revisions, recall_by_content
+// expose the cognitive surface 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.",
+    inputSchema: {
+        from_record_hash: z
+            .string()
+            .describe("Starting record hash (sha256:<64-hex>). The walk begins here and expands through the local derived graph."),
+        edge_types: z
+            .array(z.enum(['CHAIN_PRECEDES', 'INFORMED_BY', 'ANNOTATES', 'REVISES']))
+            .optional()
+            .describe("Optional list of Layer 1 edge types to follow. Default: all four. Unknown values are rejected by the schema."),
+        depth: z
+            .number()
+            .optional()
+            .describe("Maximum hop count (NOT cumulative weight). Default 3. Higher values may return many records; paginate downstream if needed."),
+    },
+}, async (args) => {
+    const { loaded } = discoverLoaded();
+    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);
+    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: walk.length,
+                    walk,
+                }, null, 2),
+            },
+        ],
+    };
+});
+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.",
+    inputSchema: {
+        record_hash: z
+            .string()
+            .describe("Record hash (sha256:<64-hex>) of the record whose annotations should be retrieved. Annotations are D058 records whose content.annotates field equals this hash."),
+    },
+}, async (args) => {
+    const { loaded } = discoverLoaded();
+    const annotationsByRecord = aggregateAnnotationsByRecord(loaded);
+    const summary = annotationsByRecord.get(args.record_hash) ?? null;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ record_hash: args.record_hash, annotations: summary }, null, 2),
+            },
+        ],
+    };
+});
+server.registerTool('recall_revisions', {
+    description: "Return the D059 revision chain for a record. Walks revises edges forward from the given record_hash, surfacing each revision in turn. The chain is the linked list of revisions where each revision's revises field points at the prior entry. 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.",
+    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 content.revises field equals this hash (or chain back to it)."),
+    },
+}, async (args) => {
+    const { loaded } = discoverLoaded();
+    const revisionsByRecord = aggregateRevisionsByRecord(loaded);
+    // Walk the chain forward: the input record may be revised by R1;
+    // R1 may be revised by R2; collect them in order. Bounded by the
+    // mirror size (no cycles since timestamps are monotonic per
+    // signer; defensive seen-set anyway).
+    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`. Convention: the chain follows the first-by-timestamp
+        // revision; agents wanting the full sibling fan-out (parallel
+        // revisions at the same target) should call recall_my_attribution_history
+        // with event_type=revision and inspect their revises field manually.
+        const revHash = next[0];
+        chain.push(revHash);
+        current = revHash;
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ record_hash: args.record_hash, revision_chain: chain }, null, 2),
+            },
+        ],
+    };
+});
+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 annotation summary + topics, then reranked by Park et al. weighted-sum scoring with annotation-derived importance and recency signals. Layer 2 (sqlite-vec sidecar, separate ship) extends with embedding similarity. Useful when the agent has no specific filter and needs to ask 'what do I know about X?'.",
+    inputSchema: {
+        query: z
+            .string()
+            .describe("Free-form text query. Matches against each record's annotation summary + topic_tags via BM25. Records with no annotation contribute no relevance signal (will only surface via the recency + importance fallback)."),
+        k: z
+            .number()
+            .optional()
+            .describe("Top-k results to return (default 10, max 50). Final ordering uses Park et al. weighted-sum scoring: alpha*recency + beta*importance + gamma*BM25_relevance. Weights are tunable via ATRIB_RECALL_ALPHA/BETA/GAMMA env vars."),
+    },
+}, async (args) => {
+    const { loaded } = discoverLoaded();
+    const annotationsByRecord = aggregateAnnotationsByRecord(loaded);
+    const queryTokens = tokenize(args.query);
+    const corpus = loaded.map((lr) => ({
+        id: lr.record_hash,
+        tokens: indexableTextFromAnnotation(annotationsByRecord.get(lr.record_hash)),
+    }));
+    const idx = buildBM25Index(corpus);
+    const now = Date.now();
+    const scored = loaded.map((lr) => {
+        const r = recencyScore(lr.record.timestamp, now, ATRIB_RECALL_TAU_DAYS);
+        const i = importanceScore(annotationsByRecord.get(lr.record_hash));
+        const rel = queryTokens.length > 0
+            ? bm25Score(idx, lr.record_hash, queryTokens)
+            : 0;
+        const score = parkScore(r, i, rel, ATRIB_RECALL_ALPHA, ATRIB_RECALL_BETA, ATRIB_RECALL_GAMMA);
+        return { lr, score, recency: r, importance: i, relevance: rel };
+    });
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return b.lr.record.timestamp - a.lr.record.timestamp;
+    });
+    const k = Math.max(1, Math.min(50, args.k ?? 10));
+    const top = scored.slice(0, k);
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify(result, null, 2),
+                text: JSON.stringify({
+                    query: args.query,
+                    k,
+                    count: top.length,
+                    results: top.map(({ lr, score, recency, importance, relevance }) => ({
+                        record_hash: lr.record_hash,
+                        event_type: lr.record.event_type,
+                        context_id: lr.record.context_id,
+                        timestamp: lr.record.timestamp,
+                        tool_name: lr.record.tool_name,
+                        annotations: annotationsByRecord.get(lr.record_hash),
+                        score,
+                        components: { recency, importance, relevance },
+                    })),
+                }, null, 2),
             },
         ],
     };