@atrib/trace 0.2.4 → 0.3.0

package/dist/index.js

@@ -18,9 +18,15 @@ import { z } from 'zod';
 import { loadAllRecords } from './storage.js';
 import { traceBackward } 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(1).max(10).optional().describe('Maximum hop count from the starting 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.'),
@@ -91,8 +97,19 @@ export async function createAtribTraceServer() {
         const depth = args.depth ?? 3;
         const maxNodes = args.max_nodes ?? 200;
         const compact = args.compact ?? true;
+        // ATRIB_CONTEXT_ID env-var default: when the caller omitted
+        // context_id, fall back to the env var if it carries a valid
+        // 32-hex value. Lets Inspect-style harnesses scope the trace walk
+        // to a per-arm context_id via the MCP env block (per D072's
+        // per-arm isolation contract). Explicit args.context_id always wins.
+        const envContextId = process.env['ATRIB_CONTEXT_ID'];
+        const contextId = args.context_id ??
+            (envContextId && HEX_32_PATTERN.test(envContextId) ? envContextId : undefined);
         const { byHash } = loadAllRecords();
-        const result = traceBackward(args.record_hash, depth, byHash, { maxNodes });
+        const result = traceBackward(args.record_hash, depth, byHash, {
+            maxNodes,
+            ...(contextId ? { contextId } : {}),
+        });
         const danglingSet = new Set(result.dangling);
         const payload = compact
             ? {

package/dist/trace.d.ts

@@ -47,6 +47,14 @@ export interface TraceResult {
 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.

package/dist/trace.js

@@ -14,6 +14,7 @@
  */
 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();
@@ -34,6 +35,25 @@ export function traceBackward(startHash, depth, index, options = {}) {
             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) {
@@ -53,6 +73,16 @@ export function traceBackward(startHash, depth, index, options = {}) {
             // 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atrib/trace",
-  "version": "0.2.4",
+  "version": "0.3.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.6.1"
+    "@atrib/mcp": "0.6.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",