@atrib/trace 0.5.21 → 1.0.0

package/README.md

@@ -1,5 +1,15 @@
 # @atrib/trace
 
+**Legacy home.** The read-verb implementation moved to
+[`@atrib/recall`](../atrib-recall/README.md) per the attest/recall rename
+([D164](../../DECISIONS.md#d164-attestrecall-verb-rename-and-primitive-surface-collapse)).
+`trace` and `trace_forward` fold into `recall` with `shape: "walk"` and
+`direction: "backward"` or `"forward"`. This package re-exports the same
+surface and forwards the `atrib-trace` binary to `@atrib/recall`'s
+handlers. Results are JSON-identical. The `trace` and `trace_forward`
+tool names stay mounted as permanent aliases during the alias window,
+alongside the new `recall` tool.
+
 MCP server exposing the `trace` tool for atrib's verifiable action layer. It walks a record's `informed_by` chain backward to surface the signed relationship path that led to it.
 
 Closes the consumer-side cognitive-loop primitive: recall returns raw records; trace returns the declared-relationship trace, so an agent asking "why did I do X?" can see "X was claimed to be informed by Y, which was claimed to be informed by Z" without manually walking `informed_by` hash-by-hash.

package/dist/index.d.ts

@@ -1,79 +1,2 @@
-/**
- * atrib-trace MCP server: registers the `trace` tool that walks a record's
- * informed_by chain backward to surface the reasoning chain that led to it.
- *
- * Closes the consumer-side cognitive-loop primitive: recall returns raw
- * records; trace returns the declared-relationship path, so an agent asking
- * "why did I do X?" can see "X claimed Y as input, and Y claimed Z as input"
- * without manually walking informed_by hash-by-hash.
- *
- * Reads only the local mirror (~/.atrib/records/*.jsonl) for v1, same scope
- * as recall. v2 will fall back to log.atrib.dev/v1/lookup/<hash> for hashes
- * not in the local mirror. Forward-walk (records that reference THIS one)
- * is also a v2 concern; v1 is backward-only.
- */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type TraceVisited } from './trace.js';
-interface CompactVisited {
-    depth: number;
-    record_hash: string;
-    parent_hashes: string[];
-    source: string | null;
-    event_type: string | null;
-    context_id: string | null;
-    creator_key: string | null;
-    timestamp: number | null;
-    /** informed_by entries on this record. Empty if none or dangling. */
-    next_informed_by: string[];
-    /** Sub-set of next_informed_by that were resolved (present in mirror). */
-    next_resolved: string[];
-    /** Sub-set of next_informed_by that were dangling (not in mirror). */
-    next_dangling: string[];
-    /**
-     * Semantic context from the local sidecar when present. Carries
-     * tool name + brief content summary so the agent can reason about
-     * the record's meaning without separately fetching it. Absent on
-     * legacy bare-record entries that pre-date the sidecar.
-     */
-    sidecar_summary?: {
-        tool_name?: string;
-        span_kind?: string;
-        span_name?: string;
-        model_name?: string;
-        prompt_version?: string;
-        topics?: string[];
-        intent?: string;
-        rationale?: string;
-        /**
-         * First 200 chars of the record's human-readable content, derived
-         * per event_type from the @atrib/mcp normative shapes (D086):
-         * observation `what`, annotation `summary`, revision `new_position`.
-         * For legacy records using non-normative names (`summary` on
-         * observation), falls back to `summary`.
-         */
-        what?: string;
-        /** Annotation `importance` field when present. */
-        importance?: string;
-        producer?: string;
-    };
-    /** Signed structural disclosures, surfaced when present on the record. */
-    informed_by?: string[];
-    tool_name?: string;
-    args_hash?: string;
-    result_hash?: string;
-    /** D062 local mirror body, included only when include_content=true. */
-    local_content?: unknown;
-    local_producer?: string;
-}
-/** Pull a compact summary from the sidecar's content payload.
- * Exported for unit testing of the per-event_type content-shape handling. */
-export declare function summarizeSidecar(loadedRecord: {
-    local?: import('./storage.js').SidecarPayload;
-} | undefined): CompactVisited['sidecar_summary'];
-export declare function compactVisited(v: TraceVisited, danglingSet: Set<string>, byHash: Map<string, import('./storage.js').IndexedRecord>, includeContent: boolean): CompactVisited;
-export declare function extractRecordHashFieldsFromMcpResult(result: unknown): string[];
-export interface AtribTraceServer {
-    mcp: McpServer;
-}
-export declare function createAtribTraceServer(): Promise<AtribTraceServer>;
-export {};
+export { compactVisited, createAtribTraceServer, extractRecordHashFieldsFromMcpResult, registerTraceTools, runTraceWalk, summarizeSidecar, TraceInput, } from '@atrib/recall';
+export type { AtribTraceServer, TraceInputT } from '@atrib/recall';

package/dist/index.js

@@ -1,306 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
-/**
- * atrib-trace MCP server: registers the `trace` tool that walks a record's
- * informed_by chain backward to surface the reasoning chain that led to it.
- *
- * Closes the consumer-side cognitive-loop primitive: recall returns raw
- * records; trace returns the declared-relationship path, so an agent asking
- * "why did I do X?" can see "X claimed Y as input, and Y claimed Z as input"
- * without manually walking informed_by hash-by-hash.
- *
- * Reads only the local mirror (~/.atrib/records/*.jsonl) for v1, same scope
- * as recall. v2 will fall back to log.atrib.dev/v1/lookup/<hash> for hashes
- * not in the local mirror. Forward-walk (records that reference THIS one)
- * is also a v2 concern; v1 is backward-only.
- */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import { resolveEnvContextId, logReadPrimitiveCall } from '@atrib/mcp';
-import { loadAllRecords } from './storage.js';
-import { traceBackward, traceForward } from './trace.js';
-const SHA256_REF_PATTERN = /^sha256:[0-9a-f]{64}$/;
-const HEX_32_PATTERN = /^[0-9a-f]{32}$/;
-const TraceInput = z.object({
-    record_hash: z
-        .string()
-        .regex(SHA256_REF_PATTERN)
-        .describe("The 'sha256:<64-hex>' record_hash to start from. Walks backward via " +
-        'informed_by edges from this record.'),
-    context_id: z
-        .string()
-        .regex(HEX_32_PATTERN)
-        .optional()
-        .describe('Optional 32-hex context_id scope. When set, edges crossing into a ' +
-        'different context_id surface as dangling rather than expanding the ' +
-        'walk. Defaults to process.env.ATRIB_CONTEXT_ID when valid; omit at ' +
-        'the env-var level to walk cross-context. Used by Inspect-style ' +
-        "harnesses to keep each arm's trace inside its own context per D072."),
-    depth: z
-        .number()
-        .int()
-        .min(0)
-        .max(10)
-        .optional()
-        .describe('Maximum hop count from the starting record. Use 0 to return only ' +
-        'the start record. Defaults to 3. Bounded ' +
-        'at 10 to keep responses tractable; deeper chains should be walked ' +
-        'in pieces by re-rooting at a returned upstream hash.'),
-    max_nodes: z
-        .number()
-        .int()
-        .min(1)
-        .max(500)
-        .optional()
-        .describe('Hard cap on total visited records. Defaults to 200. Prevents pathological ' +
-        'fan-out (a record with hundreds of informed_by entries) from exploding ' +
-        'the response.'),
-    compact: z
-        .boolean()
-        .optional()
-        .describe('When true (the default), per-record output omits signature/content_id/' +
-        'spec_version/chain_root to keep the response small. Set false for full ' +
-        'record bytes (useful for re-verification).'),
-    include_content: z
-        .boolean()
-        .optional()
-        .describe('When true and compact=true, include the D062 local mirror body as ' +
-        'local_content and local_producer on each visited record. Defaults false ' +
-        'so trace stays cheap for ordinary causal walks.'),
-});
-/** Pull a compact summary from the sidecar's content payload.
- * Exported for unit testing of the per-event_type content-shape handling. */
-export function summarizeSidecar(loadedRecord) {
-    if (!loadedRecord?.local)
-        return undefined;
-    const sc = loadedRecord.local;
-    const out = {};
-    if (sc.toolName)
-        out.tool_name = sc.toolName;
-    if (sc.producer)
-        out.producer = sc.producer;
-    const c = sc.content;
-    if (!out.tool_name && c && typeof c['tool_name'] === 'string') {
-        out.tool_name = c['tool_name'];
-    }
-    if (c && typeof c['span_kind'] === 'string')
-        out.span_kind = c['span_kind'];
-    if (c && typeof c['span_name'] === 'string')
-        out.span_name = c['span_name'];
-    if (c && typeof c['model_name'] === 'string')
-        out.model_name = c['model_name'];
-    if (c && typeof c['prompt_version'] === 'string')
-        out.prompt_version = c['prompt_version'];
-    if (c && typeof c['intent'] === 'string') {
-        out.intent = c['intent'].length > 200 ? c['intent'].slice(0, 197) + '...' : c['intent'];
-    }
-    if (c && typeof c['rationale'] === 'string') {
-        out.rationale =
-            c['rationale'].length > 200 ? c['rationale'].slice(0, 197) + '...' : c['rationale'];
-    }
-    if (c && Array.isArray(c['topics'])) {
-        out.topics = c['topics']
-            .filter((t) => typeof t === 'string')
-            .slice(0, 6);
-    }
-    // Per-event_type human-readable text. The `what` slot here is generic
-    // (it's the human-scannable summary regardless of event_type); the
-    // priority order pulls the normative D086 field for each shape, with
-    // an explicit final fallback to `summary` for legacy records.
-    //   observation: content.what
-    //   annotation:  content.summary
-    //   revision:    content.new_position (D086-normative). Surface this
-    //                so trace consumers can read the agent's stance shift
-    //                without a separate recall call
-    //   legacy:      content.summary (catches pre-D086 extractor records)
-    if (c) {
-        let primary;
-        if (typeof c['what'] === 'string') {
-            primary = c['what'];
-        }
-        else if (typeof c['new_position'] === 'string') {
-            primary = c['new_position'];
-        }
-        else if (typeof c['summary'] === 'string') {
-            primary = c['summary'];
-        }
-        else if (typeof c['prompt'] === 'string') {
-            primary = c['prompt'];
-        }
-        else if (typeof c['output'] === 'string') {
-            primary = c['output'];
-        }
-        if (primary) {
-            out.what = primary.length > 200 ? primary.slice(0, 197) + '…' : primary;
-        }
-    }
-    if (c && typeof c['importance'] === 'string')
-        out.importance = c['importance'];
-    return Object.keys(out).length === 0 ? undefined : out;
-}
-export function compactVisited(v, danglingSet, byHash, includeContent) {
-    const indexed = byHash.get(v.record_hash);
-    const record = v.record;
-    const out = {
-        depth: v.depth,
-        record_hash: v.record_hash,
-        parent_hashes: v.parent_hashes,
-        source: v.source,
-        event_type: v.record?.event_type ?? null,
-        context_id: v.record?.context_id ?? null,
-        creator_key: v.record?.creator_key ?? null,
-        timestamp: v.record?.timestamp ?? null,
-        next_informed_by: v.next_informed_by,
-        next_resolved: v.next_informed_by.filter((h) => !danglingSet.has(h)),
-        next_dangling: v.next_informed_by.filter((h) => danglingSet.has(h)),
-        ...(summarizeSidecar(indexed) ? { sidecar_summary: summarizeSidecar(indexed) } : {}),
-    };
-    if (record) {
-        const informedBy = record.informed_by;
-        const toolName = record.tool_name;
-        const argsHash = record.args_hash;
-        const resultHash = record.result_hash;
-        if (Array.isArray(informedBy) && informedBy.length > 0)
-            out.informed_by = informedBy;
-        if (toolName)
-            out.tool_name = toolName;
-        if (argsHash)
-            out.args_hash = argsHash;
-        if (resultHash)
-            out.result_hash = resultHash;
-    }
-    if (includeContent && indexed?.local?.content !== undefined) {
-        out.local_content = indexed.local.content;
-    }
-    if (includeContent && indexed?.local?.producer !== undefined) {
-        out.local_producer = indexed.local.producer;
-    }
-    return out;
-}
-export 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);
-    }
-}
-export async function createAtribTraceServer() {
-    const mcp = new McpServer({
-        name: 'atrib-trace',
-        version: '0.1.0',
-    });
-    // Shared shape: build a compact payload from a TraceResult.
-    function buildPayload(result, byHash, compact, includeContent) {
-        const danglingSet = new Set(result.dangling);
-        return compact
-            ? {
-                start_hash: result.start_hash,
-                direction: result.direction,
-                depth_requested: result.depth_requested,
-                depth_reached: result.depth_reached,
-                visited: result.visited.map((v) => compactVisited(v, danglingSet, byHash, includeContent)),
-                dangling: result.dangling,
-                truncated_by_depth: result.truncated_by_depth,
-                truncated_by_cap: result.truncated_by_cap,
-                warnings: result.warnings,
-            }
-            : { ...result };
-    }
-    mcp.registerTool('trace', {
-        title: 'trace informed_by chain backward',
-        description: "Walk a record's informed_by chain backward to surface the reasoning " +
-            'chain that led to it. Reads from the local signed-record mirror ' +
-            '(~/.atrib/records/*.jsonl). Returns the records visited, parent links ' +
-            'so the caller can reconstruct the tree, and dangling hashes (records ' +
-            'referenced via informed_by but not present in the local mirror). ' +
-            'Sibling tool `trace_forward` walks the opposite direction (records ' +
-            'that cited THIS one via their informed_by).',
-        inputSchema: TraceInput.shape,
-    }, async (args) => logReadPrimitiveCall('trace', args, async () => {
-        const depth = args.depth ?? 3;
-        const maxNodes = args.max_nodes ?? 200;
-        const compact = args.compact ?? true;
-        const includeContent = args.include_content ?? false;
-        // Env-var context_id default: when the caller omitted context_id,
-        // fall back to @atrib/mcp's resolveEnvContextId (D078 + D083
-        // precedence: ATRIB_CONTEXT_ID, then a registered harness env var
-        // like CLAUDE_CODE_SESSION_ID). Explicit args.context_id always wins.
-        const contextId = args.context_id ?? resolveEnvContextId();
-        const { byHash } = loadAllRecords();
-        const result = traceBackward(args.record_hash, depth, byHash, {
-            maxNodes,
-            ...(contextId ? { contextId } : {}),
-        });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify(buildPayload(result, byHash, compact, includeContent), null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
-    // Sibling tool: forward walk (records that cited THIS one). Mirrors
-    // the trace input schema + response shape exactly so callers can use
-    // it interchangeably; only the direction of the walk differs.
-    mcp.registerTool('trace_forward', {
-        title: 'trace informed_by chain forward',
-        description: 'Walk forward from a record_hash, surfacing the records that cited ' +
-            'it via their informed_by chain. The dual of `trace` (backward). ' +
-            'Answers "I made decision X, what did I do because of it?" Reads from ' +
-            'the local signed-record mirror (~/.atrib/records/*.jsonl). Returns ' +
-            'the records visited, parent links (which upstream record at the ' +
-            'prior level cited this one), and dangling hashes (rare; only if the ' +
-            'reverse index references a record missing from the mirror).',
-        inputSchema: TraceInput.shape,
-    }, async (args) => logReadPrimitiveCall('trace_forward', args, async () => {
-        const depth = args.depth ?? 3;
-        const maxNodes = args.max_nodes ?? 200;
-        const compact = args.compact ?? true;
-        const includeContent = args.include_content ?? false;
-        const contextId = args.context_id ?? resolveEnvContextId();
-        const { byHash } = loadAllRecords();
-        const result = traceForward(args.record_hash, depth, byHash, {
-            maxNodes,
-            ...(contextId ? { contextId } : {}),
-        });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify(buildPayload(result, byHash, compact, includeContent), null, 2),
-                },
-            ],
-        };
-    }, extractRecordHashFieldsFromMcpResult));
-    return { mcp };
-}
+// @atrib/trace is the legacy home of the trace read primitive. The
+// implementation lives in @atrib/recall per the attest/recall rename:
+// trace and trace_forward fold into the `recall` verb as shape='walk'
+// with a direction, and both legacy tool names stay mounted as permanent
+// aliases over the same runner. This package re-exports the surface so
+// existing imports keep working.
+export { compactVisited, createAtribTraceServer, extractRecordHashFieldsFromMcpResult, registerTraceTools, runTraceWalk, summarizeSidecar, TraceInput, } from '@atrib/recall';

package/dist/main.js

@@ -1,15 +1,13 @@
 #!/usr/bin/env node
-// SPDX-License-Identifier: Apache-2.0
-// atrib-trace standalone binary. Wires the McpServer to a stdio transport
-// so it can be launched as a subprocess by an MCP host (Claude Code,
-// Claude Desktop, etc.).
+// atrib-trace standalone binary (forwarding shim). Serves the legacy
+// atrib-trace server, which mounts `trace` + `trace_forward` plus the
+// `recall` verb per the alias-window rule W1.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createAtribTraceServer } from './index.js';
+import { createAtribTraceServer } from '@atrib/recall';
 async function main() {
     const { mcp } = await createAtribTraceServer();
     const transport = new StdioServerTransport();
     await mcp.connect(transport);
-    // Stays alive on the stdio transport until the host closes it.
 }
 main().catch((e) => {
     console.error('atrib-trace: fatal', e instanceof Error ? e.stack ?? e.message : String(e));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@atrib/trace",
-  "version": "0.5.21",
-  "description": "MCP server for atrib's verifiable action layer. Walks informed_by chains to show the signed relationship path.",
+  "version": "1.0.0",
+  "description": "Legacy home of atrib's trace read primitive. Superseded by @atrib/recall (the read verb, shape=walk with a direction); this package re-exports the same surface and forwards the atrib-trace binary.",
   "author": "atrib <hello@atrib.dev>",
   "keywords": [
     "atrib",
@@ -24,8 +24,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.25.76",
-    "@atrib/mcp": "0.21.0"
+    "@atrib/recall": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/dist/storage.d.ts

@@ -1,36 +0,0 @@
-import { type AtribRecord, type OnRecordSidecar } from '@atrib/mcp';
-export interface IndexedRecord {
-    record: AtribRecord;
-    /** sha256:<64-hex> form, matching informed_by entries. */
-    record_hash: string;
-    /** Source file the record was read from (for debugging). */
-    source: string;
-    /**
-     * Pre-sign payload context, when the producer wrote it to the local
-     * mirror as a `_local` sidecar on the envelope. Carries semantic content
-     * (toolName, args, result, content) the signed AtribRecord COMMITS TO
-     * via content_id / args_hash / result_hash but does not itself contain.
-     * Absent on legacy bare-record entries from older mirror writes.
-     */
-    local?: SidecarPayload;
-}
-/**
- * Combined sidecar shape, superset of every producer's local payload
- * (mcp-wrap writes toolName/args/result; atrib-emit writes content).
- */
-export interface SidecarPayload extends OnRecordSidecar {
-    content?: unknown;
-    producer?: string;
-}
-/**
- * Read every *.jsonl mirror in ATRIB_RECORDS_DIR and return an index keyed
- * by sha256:<64-hex> record_hash. Both shapes (bare AtribRecord and emit's
- * { record, proof, written_at } envelope) are supported.
- *
- * Returns the indexed map AND a flat list (newest-first by timestamp) for
- * callers that want recall-style enumeration without by-hash lookup.
- */
-export declare function loadAllRecords(dir?: string): {
-    byHash: Map<string, IndexedRecord>;
-    newestFirst: IndexedRecord[];
-};

package/dist/storage.js

@@ -1,92 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Local mirror reader for atrib-trace.
- *
- * Reads either one ATRIB_RECORD_FILE mirror or every *.jsonl mirror under
- * ~/.atrib/records/ and normalizes to bare AtribRecord shape regardless of
- * producer (wrapper-signed or emit envelope).
- *
- * Builds an in-memory index by record_hash so trace can walk informed_by
- * chains in O(1) per hop. The hash key is sha256:<64-hex> (the same form
- * informed_by entries use), so no transformation needed at lookup time.
- */
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { basename, join } from 'node:path';
-import { canonicalRecord, hexEncode, sha256, withDerivedLocalContent, } from '@atrib/mcp';
-const RECORDS_FILE = process.env.ATRIB_RECORD_FILE;
-const RECORDS_DIR = process.env.ATRIB_RECORDS_DIR ?? join(homedir(), '.atrib', 'records');
-/**
- * Read every *.jsonl mirror in ATRIB_RECORDS_DIR and return an index keyed
- * by sha256:<64-hex> record_hash. Both shapes (bare AtribRecord and emit's
- * { record, proof, written_at } envelope) are supported.
- *
- * Returns the indexed map AND a flat list (newest-first by timestamp) for
- * callers that want recall-style enumeration without by-hash lookup.
- */
-export function loadAllRecords(dir = RECORDS_DIR) {
-    const byHash = new Map();
-    const all = [];
-    const paths = [];
-    if (RECORDS_FILE) {
-        paths.push({ path: RECORDS_FILE, source: basename(RECORDS_FILE) });
-    }
-    else {
-        if (!existsSync(dir))
-            return { byHash, newestFirst: [] };
-        try {
-            for (const fname of readdirSync(dir).filter((f) => f.endsWith('.jsonl'))) {
-                paths.push({ path: join(dir, fname), source: fname });
-            }
-        }
-        catch {
-            return { byHash, newestFirst: [] };
-        }
-    }
-    for (const { path, source } of paths) {
-        try {
-            const raw = readFileSync(path, 'utf8');
-            for (const line of raw.split('\n')) {
-                const trimmed = line.trim();
-                if (!trimmed)
-                    continue;
-                try {
-                    const parsed = JSON.parse(trimmed);
-                    // Normalize: envelope shape vs legacy bare record shape.
-                    const isEnvelope = 'record' in parsed &&
-                        parsed.record &&
-                        parsed.record.context_id !== undefined;
-                    const rec = isEnvelope
-                        ? parsed.record
-                        : parsed;
-                    if (!rec.context_id || !rec.signature || !rec.timestamp)
-                        continue;
-                    const hashHex = hexEncode(sha256(canonicalRecord(rec)));
-                    const indexed = {
-                        record: rec,
-                        record_hash: `sha256:${hashHex}`,
-                        source,
-                    };
-                    // Lift the `_local` sidecar onto the indexed record when present.
-                    // Legacy bare-record entries have no sidecar; that's OK, consumers
-                    // tolerate its absence.
-                    if (isEnvelope) {
-                        const sidecar = parsed._local;
-                        if (sidecar)
-                            indexed.local = withDerivedLocalContent(rec.event_type, sidecar);
-                    }
-                    byHash.set(indexed.record_hash, indexed);
-                    all.push(indexed);
-                }
-                catch {
-                    // Malformed line; skip.
-                }
-            }
-        }
-        catch {
-            // File read failure; skip this file.
-        }
-    }
-    all.sort((a, b) => b.record.timestamp - a.record.timestamp);
-    return { byHash, newestFirst: all };
-}

package/dist/trace.d.ts

@@ -1,106 +0,0 @@
-/**
- * Bounded directional walk through informed_by chains.
- *
- * Two directions:
- *   - backward (traceBackward): from a record, walk its informed_by chain
- *     toward causal ancestors. Answers "what informed this?"
- *   - forward (traceForward): from a record, walk the records that cite it
- *     via their informed_by. Answers "what was informed by this?" — i.e.
- *     what followed from this decision/observation.
- *
- * Each direction breadth-first walks edges until either (a) depth bound
- * reached, (b) no more unresolved hashes remain, or (c) safety cap on
- * total visited nodes hit.
- *
- * Each visited record is annotated with:
- *   - depth       , hop count from the starting record (0 = the start)
- *   - parent_hashes, which records in the previous level referenced this one
- *
- * Records referenced via informed_by but NOT present in the local mirror
- * are surfaced as `dangling` entries: the verifier hasn't seen the upstream
- * locally. This is informational, not a failure, the upstream may live on
- * the public log but not in the agent's local mirror.
- *
- * Forward walk requires a full-mirror reverse index (built on each call
- * from the same IndexedRecord map; O(N) once, then O(out-degree) per hop).
- * For typical mirror sizes (~14K records) this is negligible.
- */
-import type { IndexedRecord } from './storage.js';
-import type { AtribRecord } from '@atrib/mcp';
-export type TraceDirection = 'backward' | 'forward';
-export interface TraceVisited {
-    depth: number;
-    record_hash: string;
-    parent_hashes: string[];
-    /** Empty when source mirror lacks this record (dangling). */
-    record: AtribRecord | null;
-    /** Source file the record was read from, or null if dangling. */
-    source: string | null;
-    /** Sub-set of informed_by entries that are themselves walkable next-hop. */
-    next_informed_by: string[];
-}
-export interface TraceResult {
-    start_hash: string;
-    direction: TraceDirection;
-    depth_requested: number;
-    depth_reached: number;
-    visited: TraceVisited[];
-    dangling: string[];
-    truncated_by_depth: boolean;
-    truncated_by_cap: boolean;
-    warnings: string[];
-}
-export interface TraceOptions {
-    /** Hard cap on total visited nodes regardless of depth. Defaults to 200. */
-    maxNodes?: number;
-    /**
-     * When set, scope the walk to records that share this context_id. Edges
-     * crossing into a different context_id are treated as dangling: the
-     * upstream is real but lies outside the requested scope. Used by
-     * Inspect-style harnesses passing ATRIB_CONTEXT_ID to keep each arm's
-     * trace inside its own context.
-     */
-    contextId?: string;
-}
-/**
- * Walk informed_by edges backward from the starting record.
- *
- * Behaviors:
- *   - Cycle-safe: every record is visited at most once, even if multiple
- *     parents reference it.
- *   - Cap-safe: if maxNodes is hit mid-walk, returns partial result with
- *     truncated_by_cap=true. Callers can re-run with a smaller depth or
- *     start from a sub-tree if needed.
- *   - Dangling-aware: informed_by entries pointing at records not in the
- *     local mirror surface as `dangling`. Those entries do NOT advance the
- *     walk (we have nothing to walk from).
- */
-export declare function traceBackward(startHash: string, depth: number, index: Map<string, IndexedRecord>, options?: TraceOptions): TraceResult;
-/**
- * Build a reverse informed_by index: for each record_hash R, the list of
- * record_hashes that cite R in their informed_by field. O(total
- * informed_by entries) build; O(1) lookup per parent during walk.
- *
- * Exported so callers (or tests) can pre-build the index when running
- * multiple traceForward calls against the same mirror.
- */
-export declare function buildReverseInformedByIndex(index: Map<string, IndexedRecord>): Map<string, string[]>;
-/**
- * Walk informed_by edges FORWARD from the starting record.
- *
- * Answers: "what records cited THIS record via informed_by?" — i.e. what
- * decisions/observations followed from this one in the causal substrate.
- * The dual of traceBackward. Useful for "I made decision X, what did I do
- * because of it?" lookups.
- *
- * Same behaviors as traceBackward:
- *   - Cycle-safe via visited-set
- *   - Cap-safe via maxNodes
- *   - context_id-scoped (if specified): edges into a different context_id
- *     are treated as dangling
- *   - Dangling: walking forward to a record present in the reverse index
- *     but missing from the mirror surfaces it as dangling (defensive; in
- *     practice the same mirror that built the reverse index has the
- *     record itself)
- */
-export declare function traceForward(startHash: string, depth: number, index: Map<string, IndexedRecord>, options?: TraceOptions): TraceResult;

package/dist/trace.js

@@ -1,274 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Walk informed_by edges backward from the starting record.
- *
- * Behaviors:
- *   - Cycle-safe: every record is visited at most once, even if multiple
- *     parents reference it.
- *   - Cap-safe: if maxNodes is hit mid-walk, returns partial result with
- *     truncated_by_cap=true. Callers can re-run with a smaller depth or
- *     start from a sub-tree if needed.
- *   - Dangling-aware: informed_by entries pointing at records not in the
- *     local mirror surface as `dangling`. Those entries do NOT advance the
- *     walk (we have nothing to walk from).
- */
-export function traceBackward(startHash, depth, index, options = {}) {
-    const maxNodes = options.maxNodes ?? 200;
-    const contextId = options.contextId;
-    const warnings = [];
-    const visited = new Map();
-    const dangling = new Set();
-    let truncatedByCap = false;
-    let truncatedByDepth = false;
-    let depthReached = 0;
-    const startIdx = index.get(startHash);
-    if (!startIdx) {
-        return {
-            start_hash: startHash,
-            direction: 'backward',
-            depth_requested: depth,
-            depth_reached: 0,
-            visited: [],
-            dangling: [startHash],
-            truncated_by_depth: false,
-            truncated_by_cap: false,
-            warnings: [`start_hash ${startHash} not in local mirror`],
-        };
-    }
-    // context_id scope check: when the caller pinned a context_id, the start
-    // record itself must already live within it. Reject explicitly rather than
-    // silently returning an empty walk; the caller likely wants to know they
-    // pointed trace at the wrong record for the requested scope.
-    if (contextId && startIdx.record.context_id !== contextId) {
-        return {
-            start_hash: startHash,
-            direction: 'backward',
-            depth_requested: depth,
-            depth_reached: 0,
-            visited: [],
-            dangling: [],
-            truncated_by_depth: false,
-            truncated_by_cap: false,
-            warnings: [
-                `start_hash ${startHash} lives in context_id ${startIdx.record.context_id} but trace was scoped to ${contextId} (set ATRIB_CONTEXT_ID to override or omit context_id to walk cross-context)`,
-            ],
-        };
-    }
-    const frontier = [{ hash: startHash, depth: 0, parent: null }];
-    while (frontier.length > 0) {
-        if (visited.size >= maxNodes) {
-            truncatedByCap = true;
-            break;
-        }
-        const current = frontier.shift();
-        if (current.depth > depth) {
-            truncatedByDepth = true;
-            continue;
-        }
-        depthReached = Math.max(depthReached, current.depth);
-        const idx = index.get(current.hash);
-        if (!idx) {
-            dangling.add(current.hash);
-            // Tag the parent so caller can see which walkable record had a
-            // dangling reference, but we don't visit further.
-            continue;
-        }
-        // context_id scope filter: an upstream record that lives in a different
-        // context_id is treated as dangling from this walk's perspective. The
-        // record itself exists, but it sits outside the requested scope. This
-        // keeps per-arm trace results clean when ATRIB_CONTEXT_ID is set per
-        // D072 (cross-arm informed_by edges, if any leaked, do not pollute
-        // the walk).
-        if (contextId && idx.record.context_id !== contextId) {
-            dangling.add(current.hash);
-            continue;
-        }
-        let v = visited.get(current.hash);
-        if (!v) {
-            const informedByEntries = Array.isArray(idx.record.informed_by)
-                ? idx.record.informed_by
-                : [];
-            v = {
-                depth: current.depth,
-                record_hash: current.hash,
-                parent_hashes: [],
-                record: idx.record,
-                source: idx.source,
-                next_informed_by: informedByEntries,
-            };
-            visited.set(current.hash, v);
-            // Schedule informed_by entries for visit at depth+1.
-            if (current.depth < depth) {
-                for (const upstream of informedByEntries) {
-                    frontier.push({ hash: upstream, depth: current.depth + 1, parent: current.hash });
-                }
-            }
-            else if (informedByEntries.length > 0) {
-                truncatedByDepth = true;
-            }
-        }
-        if (current.parent && !v.parent_hashes.includes(current.parent)) {
-            v.parent_hashes.push(current.parent);
-        }
-    }
-    return {
-        start_hash: startHash,
-        direction: 'backward',
-        depth_requested: depth,
-        depth_reached: depthReached,
-        visited: Array.from(visited.values()),
-        dangling: Array.from(dangling),
-        truncated_by_depth: truncatedByDepth,
-        truncated_by_cap: truncatedByCap,
-        warnings,
-    };
-}
-/**
- * Build a reverse informed_by index: for each record_hash R, the list of
- * record_hashes that cite R in their informed_by field. O(total
- * informed_by entries) build; O(1) lookup per parent during walk.
- *
- * Exported so callers (or tests) can pre-build the index when running
- * multiple traceForward calls against the same mirror.
- */
-export function buildReverseInformedByIndex(index) {
-    const reverse = new Map();
-    for (const { record, record_hash } of index.values()) {
-        const ib = Array.isArray(record.informed_by) ? record.informed_by : [];
-        for (const upstream of ib) {
-            if (typeof upstream !== 'string')
-                continue;
-            const existing = reverse.get(upstream);
-            if (existing)
-                existing.push(record_hash);
-            else
-                reverse.set(upstream, [record_hash]);
-        }
-    }
-    return reverse;
-}
-/**
- * Walk informed_by edges FORWARD from the starting record.
- *
- * Answers: "what records cited THIS record via informed_by?" — i.e. what
- * decisions/observations followed from this one in the causal substrate.
- * The dual of traceBackward. Useful for "I made decision X, what did I do
- * because of it?" lookups.
- *
- * Same behaviors as traceBackward:
- *   - Cycle-safe via visited-set
- *   - Cap-safe via maxNodes
- *   - context_id-scoped (if specified): edges into a different context_id
- *     are treated as dangling
- *   - Dangling: walking forward to a record present in the reverse index
- *     but missing from the mirror surfaces it as dangling (defensive; in
- *     practice the same mirror that built the reverse index has the
- *     record itself)
- */
-export function traceForward(startHash, depth, index, options = {}) {
-    const maxNodes = options.maxNodes ?? 200;
-    const contextId = options.contextId;
-    const warnings = [];
-    const visited = new Map();
-    const dangling = new Set();
-    let truncatedByCap = false;
-    let truncatedByDepth = false;
-    let depthReached = 0;
-    const startIdx = index.get(startHash);
-    if (!startIdx) {
-        return {
-            start_hash: startHash,
-            direction: 'forward',
-            depth_requested: depth,
-            depth_reached: 0,
-            visited: [],
-            dangling: [startHash],
-            truncated_by_depth: false,
-            truncated_by_cap: false,
-            warnings: [`start_hash ${startHash} not in local mirror`],
-        };
-    }
-    if (contextId && startIdx.record.context_id !== contextId) {
-        return {
-            start_hash: startHash,
-            direction: 'forward',
-            depth_requested: depth,
-            depth_reached: 0,
-            visited: [],
-            dangling: [],
-            truncated_by_depth: false,
-            truncated_by_cap: false,
-            warnings: [
-                `start_hash ${startHash} lives in context_id ${startIdx.record.context_id} but trace was scoped to ${contextId} (set ATRIB_CONTEXT_ID to override or omit context_id to walk cross-context)`,
-            ],
-        };
-    }
-    // Build the reverse index once per call. For Layer 1 corpus sizes
-    // (~14K records) the O(N) build is negligible; the saved per-hop O(1)
-    // child lookup is worth the linear scan.
-    const reverse = buildReverseInformedByIndex(index);
-    const frontier = [{ hash: startHash, depth: 0, parent: null }];
-    while (frontier.length > 0) {
-        if (visited.size >= maxNodes) {
-            truncatedByCap = true;
-            break;
-        }
-        const current = frontier.shift();
-        if (current.depth > depth) {
-            truncatedByDepth = true;
-            continue;
-        }
-        depthReached = Math.max(depthReached, current.depth);
-        const idx = index.get(current.hash);
-        if (!idx) {
-            // The reverse index pointed at a record not present in the mirror.
-            // Defensive case (the reverse index was built FROM the same mirror,
-            // so this branch is unreachable in practice). Treat as dangling.
-            dangling.add(current.hash);
-            continue;
-        }
-        if (contextId && idx.record.context_id !== contextId) {
-            dangling.add(current.hash);
-            continue;
-        }
-        let v = visited.get(current.hash);
-        if (!v) {
-            const children = reverse.get(current.hash) ?? [];
-            v = {
-                depth: current.depth,
-                record_hash: current.hash,
-                parent_hashes: [],
-                record: idx.record,
-                source: idx.source,
-                // `next_informed_by` reused here as "edges out of this node in
-                // the walk direction" — for forward walk that's the children
-                // (records citing this one), not this record's own informed_by.
-                // Field name kept for shape-compat with traceBackward.
-                next_informed_by: children,
-            };
-            visited.set(current.hash, v);
-            if (current.depth < depth) {
-                for (const child of children) {
-                    frontier.push({ hash: child, depth: current.depth + 1, parent: current.hash });
-                }
-            }
-            else if (children.length > 0) {
-                truncatedByDepth = true;
-            }
-        }
-        if (current.parent && !v.parent_hashes.includes(current.parent)) {
-            v.parent_hashes.push(current.parent);
-        }
-    }
-    return {
-        start_hash: startHash,
-        direction: 'forward',
-        depth_requested: depth,
-        depth_reached: depthReached,
-        visited: Array.from(visited.values()),
-        dangling: Array.from(dangling),
-        truncated_by_depth: truncatedByDepth,
-        truncated_by_cap: truncatedByCap,
-        warnings,
-    };
-}