@atrib/trace 0.4.1 → 0.5.0

package/README.md

@@ -4,17 +4,24 @@ 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)
   max_nodes?: number,               // safety cap (default 200, max 500)
   compact?: boolean                 // omit signature/content_id bytes (default true)
 })
+
+mcp__atrib-trace__trace_forward({  // FORWARD — what was informed by this?
+  record_hash, depth?, max_nodes?, compact?    // same schema as `trace`
+})
+
 → {
-  start_hash, direction: "backward",
+  start_hash, direction: "backward" | "forward",
   depth_requested, depth_reached,
   visited: [
     {
@@ -30,6 +37,10 @@ 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:
@@ -45,8 +56,8 @@ 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.
+- **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. 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,50 @@
  * is also a v2 concern; v1 is backward-only.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.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;
+    };
+}
+/** 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 interface AtribTraceServer {
     mcp: McpServer;
 }
 export declare function createAtribTraceServer(): Promise<AtribTraceServer>;
+export {};

package/dist/index.js

@@ -17,7 +17,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { resolveEnvContextId, logReadPrimitiveCall, extractRecordHashesFromMcpResult, } 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({
@@ -38,8 +38,9 @@ const TraceInput = z.object({
         'spec_version/chain_root to keep the response small. Set false for full ' +
         'record bytes (useful for re-verification).'),
 });
-/** 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,13 +53,30 @@ 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'];
@@ -86,13 +104,32 @@ export async function createAtribTraceServer() {
         name: 'atrib-trace',
         version: '0.1.0',
     });
+    // Shared shape: build a compact payload from a TraceResult.
+    function buildPayload(result, byHash, compact) {
+        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)),
+                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;
@@ -108,25 +145,35 @@ 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), null, 2) }],
+        };
+    }, extractRecordHashesFromMcpResult));
+    // 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 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), null, 2) }],
         };
     }, extractRecordHashesFromMcpResult));
     return { mcp };

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.0",
   "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,7 +11,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.76",
-    "@atrib/mcp": "0.11.0"
+    "@atrib/mcp": "0.11.1"
   },
   "devDependencies": {
     "@types/node": "^25.8.0",