@atrib/trace 0.4.1 → 0.5.1

package/README.md

@@ -4,24 +4,34 @@ MCP server exposing the `trace` tool, walks a record's `informed_by` chain backw
 
 Closes the consumer-side cognitive-loop primitive: recall returns raw records; trace returns the causal chain, so an agent asking "why did I do X?" can see "X was informed by Y, which was informed by Z" without manually walking `informed_by` hash-by-hash.
 
-## Tool
+## Tools
+
+Two bidirectional walk tools share the same input + response shape; only the walk direction differs:
 
 ```
-mcp__atrib-trace__trace({
+mcp__atrib-trace__trace({          // BACKWARD — what informed this?
   record_hash: "sha256:<64-hex>",  // start
-  depth?: number,                   // hop cap (default 3, max 10)
+  depth?: number,                   // hop cap (0=start only, default 3, max 10)
   max_nodes?: number,               // safety cap (default 200, max 500)
-  compact?: boolean                 // omit signature/content_id bytes (default true)
+  compact?: boolean,                // omit signature/content_id bytes (default true)
+  include_content?: boolean         // include D062 local_content (default false)
+})
+
+mcp__atrib-trace__trace_forward({  // FORWARD — what was informed by this?
+  record_hash, depth?, max_nodes?, compact?, include_content? // same schema
 })
+
 → {
-  start_hash, direction: "backward",
+  start_hash, direction: "backward" | "forward",
   depth_requested, depth_reached,
   visited: [
     {
       depth, record_hash, parent_hashes, source,
       event_type, context_id, creator_key, timestamp,
       next_informed_by, next_resolved, next_dangling,
-      sidecar_summary?: { tool_name?, topics?, what?, importance?, producer? }
+      informed_by?, tool_name?, args_hash?, result_hash?,
+      sidecar_summary?: { tool_name?, topics?, what?, importance?, producer? },
+      local_content?, local_producer? // only when include_content=true
     }
   ],
   dangling: string[],
@@ -30,14 +40,18 @@ mcp__atrib-trace__trace({
 }
 ```
 
+- `trace` walks `informed_by` BACKWARD (toward causal ancestors). Answers "what informed this record?"
+- `trace_forward` walks `informed_by` FORWARD (records that cited this one). Answers "I made decision X, what did I do because of it?" The dual of `trace`. Same input schema, same response shape.
+- For forward walks, `next_informed_by` carries the CHILDREN visited at the next hop (records citing this one) rather than this record's own informed_by — field name kept for shape-compat with `trace`.
+
 ## Reads
 
-Every `*.jsonl` mirror under `~/.atrib/records/` (override via `ATRIB_RECORDS_DIR`). Tolerates both producer envelope shapes:
+Every `*.jsonl` mirror under `~/.atrib/records/` (override via `ATRIB_RECORDS_DIR`) or one explicit mirror file via `ATRIB_RECORD_FILE`. Tolerates both producer envelope shapes:
 
 - Bare `AtribRecord` per line (legacy / wrapper convention pre-sidecar)
 - `{ record, _local?, written_at }` envelope (current shape)
 
-When the envelope carries an optional `_local` sidecar (per the local-mirror sidecar pattern shipped in `@atrib/mcp` v0.2.x), trace surfaces a compact `sidecar_summary` per record: `tool_name`, `topics`, first ~200 chars of `what`/`summary`, and `importance` for annotations. Without the sidecar (legacy entries), the per-record output still includes the cryptographic evidence (event_type, hashes, creator_key, timestamp), just without the semantic context.
+When the envelope carries an optional `_local` sidecar (per the local-mirror sidecar pattern shipped in `@atrib/mcp` v0.2.x), trace surfaces a compact `sidecar_summary` per record: `tool_name`, `topics`, first ~200 chars of `what`/`summary`, and `importance` for annotations. When `include_content=true`, trace also returns the full [D062](../../DECISIONS.md#d062-local-mirror-sidecar--two-tier-private-local--public-canonical-persistence) local mirror body as `local_content` plus `local_producer`; this is intended for harness-mediated causal replay where the agent needs rich expected/actual outcome context. Without the sidecar (legacy entries), the per-record output still includes the cryptographic evidence (event_type, hashes, creator_key, timestamp), just without semantic context.
 
 ## Behaviors
 
@@ -45,9 +59,9 @@ When the envelope carries an optional `_local` sidecar (per the local-mirror sid
 - **Cap-safe**: hits `max_nodes` → returns partial result with `truncated_by_cap: true`.
 - **Depth-safe**: hits `depth` → returns partial result with `truncated_by_depth: true`.
 - **Dangling-aware**: `informed_by` entries pointing at records not in the local mirror surface in `dangling` and do NOT advance the walk.
-- **Local-only (v1)**: reads only the local mirror. v2 will fall back to `log.atrib.dev/v1/lookup/<hash>` for hashes not in the local mirror.
-- **Backward-only (v1)**: walks `informed_by` upstream. Forward-walk (records that reference THIS one) is a v2 concern via the graph service.
-- **Instrumented (per [D084](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d084-read-primitive-instrumentation-for-empirical-loop-closure-measurement) Surface 6)**: every call writes a per-invocation jsonl entry to `~/.atrib/state/read-primitives/calls.jsonl` for the unified loop-closure analyzer. Silent-failure per [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract); instrumentation never blocks the trace result. `ATRIB_READ_PRIMITIVES_LOG` overrides the default path for tests.
+- **Local-only**: reads only the local mirror. A future ship will fall back to `log.atrib.dev/v1/lookup/<hash>` for hashes not in the local mirror.
+- **Bidirectional**: `trace` walks `informed_by` backward; `trace_forward` walks forward via a reverse index built per call from the same mirror (O(N) build, O(out-degree) per hop).
+- **Instrumented (per [D084](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d084-read-primitive-instrumentation-for-empirical-loop-closure-measurement) Surface 6)**: every call writes a per-invocation jsonl entry to `~/.atrib/state/read-primitives/calls.jsonl` for the unified loop-closure analyzer. Instrumentation samples only `record_hash` fields, not `args_hash`, `result_hash`, or hashes embedded in `local_content`. Silent-failure per [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract); instrumentation never blocks the trace result. `ATRIB_READ_PRIMITIVES_LOG` overrides the default path for tests.
 
 ## Wire-up
 

package/dist/index.d.ts

@@ -13,7 +13,61 @@
  * 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;
+        topics?: 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 {};

package/dist/index.js

@@ -15,9 +15,9 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { resolveEnvContextId, logReadPrimitiveCall, extractRecordHashesFromMcpResult, } from '@atrib/mcp';
+import { resolveEnvContextId, logReadPrimitiveCall, } from '@atrib/mcp';
 import { loadAllRecords } from './storage.js';
-import { traceBackward } from './trace.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({
@@ -28,7 +28,8 @@ const TraceInput = z.object({
         '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(1).max(10).optional().describe('Maximum hop count from the starting record. Defaults to 3. Bounded ' +
+    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 ' +
@@ -37,9 +38,13 @@ const TraceInput = z.object({
     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. */
-function summarizeSidecar(loadedRecord) {
+/** 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;
@@ -52,21 +57,39 @@ function summarizeSidecar(loadedRecord) {
     if (c && Array.isArray(c['topics'])) {
         out.topics = c['topics'].filter((t) => typeof t === 'string').slice(0, 6);
     }
-    if (c && typeof c['what'] === 'string') {
-        const w = c['what'];
-        out.what = w.length > 200 ? w.slice(0, 197) + '…' : w;
-    }
-    else if (c && typeof c['summary'] === 'string') {
-        const s = c['summary'];
-        out.what = s.length > 200 ? s.slice(0, 197) + '…' : s;
+    // 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'];
+        }
+        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;
 }
-function compactVisited(v, danglingSet, byHash) {
+export function compactVisited(v, danglingSet, byHash, includeContent) {
     const indexed = byHash.get(v.record_hash);
-    return {
+    const record = v.record;
+    const out = {
         depth: v.depth,
         record_hash: v.record_hash,
         parent_hashes: v.parent_hashes,
@@ -80,24 +103,101 @@ function compactVisited(v, danglingSet, byHash) {
         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).',
+            '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
@@ -108,26 +208,37 @@ export async function createAtribTraceServer() {
             maxNodes,
             ...(contextId ? { contextId } : {}),
         });
-        const danglingSet = new Set(result.dangling);
-        const payload = 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)),
-                dangling: result.dangling,
-                truncated_by_depth: result.truncated_by_depth,
-                truncated_by_cap: result.truncated_by_cap,
-                warnings: result.warnings,
-            }
-            : {
-                ...result,
-                // Full records included
-            };
         return {
-            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            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) }],
         };
-    }, extractRecordHashesFromMcpResult));
+    }, extractRecordHashFieldsFromMcpResult));
     return { mcp };
 }

package/dist/storage.js

@@ -2,8 +2,9 @@
 /**
  * Local mirror reader for atrib-trace.
  *
- * Reads every *.jsonl mirror under ~/.atrib/records/ and normalizes to bare
- * AtribRecord shape regardless of producer (wrapper-signed or emit envelope).
+ * 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
@@ -11,8 +12,9 @@
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { canonicalRecord, hexEncode, sha256 } 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
@@ -25,17 +27,23 @@ const RECORDS_DIR = process.env.ATRIB_RECORDS_DIR ?? join(homedir(), '.atrib', '
 export function loadAllRecords(dir = RECORDS_DIR) {
     const byHash = new Map();
     const all = [];
-    if (!existsSync(dir))
-        return { byHash, newestFirst: [] };
-    let files = [];
-    try {
-        files = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+    const paths = [];
+    if (RECORDS_FILE) {
+        paths.push({ path: RECORDS_FILE, source: basename(RECORDS_FILE) });
     }
-    catch {
-        return { byHash, newestFirst: [] };
+    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 fname of files) {
-        const path = join(dir, fname);
+    for (const { path, source } of paths) {
         try {
             const raw = readFileSync(path, 'utf8');
             for (const line of raw.split('\n')) {
@@ -57,7 +65,7 @@ export function loadAllRecords(dir = RECORDS_DIR) {
                     const indexed = {
                         record: rec,
                         record_hash: `sha256:${hashHex}`,
-                        source: fname,
+                        source,
                     };
                     // Lift the `_local` sidecar onto the indexed record when present.
                     // Legacy bare-record entries have no sidecar; that's OK, consumers

package/dist/trace.d.ts

@@ -1,9 +1,16 @@
 /**
- * Bounded backward walk through informed_by chains.
+ * Bounded directional walk through informed_by chains.
  *
- * Given a starting record_hash and a depth bound, breadth-first walks every
- * informed_by edge until either (a) depth bound reached, (b) no more
- * unresolved hashes remain, or (c) safety cap on total visited nodes hit.
+ * 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)
@@ -14,14 +21,13 @@
  * 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 (records that reference THIS record via informed_by) is
- * out of scope for v1; it requires either a full-mirror scan per call
- * (acceptable but slower) or the graph service. v1 is backward-only;
- * forward-walk arrives in v2.
+ * 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';
+export type TraceDirection = 'backward' | 'forward';
 export interface TraceVisited {
     depth: number;
     record_hash: string;
@@ -70,3 +76,31 @@ export interface TraceOptions {
  *     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

@@ -123,3 +123,152 @@ export function traceBackward(startHash, depth, index, options = {}) {
         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,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atrib/trace",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "MCP server for atrib. Walks informed_by chains backward from a record_hash to surface the reasoning chain that produced it.",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,13 +11,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.76",
-    "@atrib/mcp": "0.11.0"
+    "@atrib/mcp": "0.12.0"
   },
   "devDependencies": {
-    "@types/node": "^25.8.0",
-    "tsx": "^4.22.1",
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.7"
   },
   "files": [
     "dist"