@atrib/trace 0.5.0 → 0.5.2

package/README.md

@@ -11,13 +11,14 @@ Two bidirectional walk tools share the same input + response shape; only the wal
 ```
 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?    // same schema as `trace`
+  record_hash, depth?, max_nodes?, compact?, include_content? // same schema
 })
 
 → {
@@ -28,7 +29,9 @@ mcp__atrib-trace__trace_forward({  // FORWARD — what was informed by this?
       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[],
@@ -43,12 +46,12 @@ mcp__atrib-trace__trace_forward({  // FORWARD — what was informed by this?
 
 ## 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
 
@@ -58,7 +61,7 @@ When the envelope carries an optional `_local` sidecar (per the local-mirror sid
 - **Dangling-aware**: `informed_by` entries pointing at records not in the local mirror surface in `dangling` and do NOT advance the walk.
 - **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.
+- **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,6 +13,7 @@
  * 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;
@@ -49,12 +50,22 @@ interface CompactVisited {
         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;
 }

package/dist/index.js

@@ -15,7 +15,7 @@
  */
 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, traceForward } from './trace.js';
 const SHA256_REF_PATTERN = /^sha256:[0-9a-f]{64}$/;
@@ -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,6 +38,9 @@ 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.
  * Exported for unit testing of the per-event_type content-shape handling. */
@@ -82,9 +86,10 @@ export function summarizeSidecar(loadedRecord) {
         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,
@@ -98,6 +103,63 @@ 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({
@@ -105,7 +167,7 @@ export async function createAtribTraceServer() {
         version: '0.1.0',
     });
     // Shared shape: build a compact payload from a TraceResult.
-    function buildPayload(result, byHash, compact) {
+    function buildPayload(result, byHash, compact, includeContent) {
         const danglingSet = new Set(result.dangling);
         return compact
             ? {
@@ -113,7 +175,7 @@ export async function createAtribTraceServer() {
                 direction: result.direction,
                 depth_requested: result.depth_requested,
                 depth_reached: result.depth_reached,
-                visited: result.visited.map((v) => compactVisited(v, danglingSet, byHash)),
+                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,
@@ -135,6 +197,7 @@ export async function createAtribTraceServer() {
         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
@@ -146,9 +209,9 @@ export async function createAtribTraceServer() {
             ...(contextId ? { contextId } : {}),
         });
         return {
-            content: [{ type: 'text', text: JSON.stringify(buildPayload(result, byHash, compact), null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(buildPayload(result, byHash, compact, includeContent), null, 2) }],
         };
-    }, extractRecordHashesFromMcpResult));
+    }, 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.
@@ -166,6 +229,7 @@ export async function createAtribTraceServer() {
         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, {
@@ -173,8 +237,8 @@ export async function createAtribTraceServer() {
             ...(contextId ? { contextId } : {}),
         });
         return {
-            content: [{ type: 'text', text: JSON.stringify(buildPayload(result, byHash, compact), null, 2) }],
+            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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atrib/trace",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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.1"
+    "@atrib/mcp": "0.13.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"