@atrib/recall 0.14.6 → 1.0.0

package/dist/trace-tools.js

@@ -0,0 +1,314 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The legacy `trace` / `trace_forward` tools, kept as permanent aliases over
+ * @atrib/recall's read surface (the walk shapes of the `recall` verb). Walks
+ * a record's informed_by chain backward (the reasoning chain that led to it)
+ * or forward (the records that cited it). Reads only the local mirror
+ * (~/.atrib/records/*.jsonl), same scope as recall.
+ *
+ * Moved here from @atrib/trace per the attest/recall rename; @atrib/trace
+ * re-exports this module so existing imports keep working, and the
+ * `recall` verb reaches the same implementation via shape='walk' with a
+ * direction argument.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { resolveEnvContextId, logReadPrimitiveCall } from '@atrib/mcp';
+import { loadAllRecords } from './trace-storage.js';
+import { traceBackward, traceForward } from './trace-walk.js';
+const SHA256_REF_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const HEX_32_PATTERN = /^[0-9a-f]{32}$/;
+export 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);
+    }
+}
+/** 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 };
+}
+/**
+ * Run one informed_by walk and return the JSON payload. This is the single
+ * implementation behind the legacy `trace` / `trace_forward` tools AND the
+ * `recall` verb's shape='walk' with a direction, so their results are
+ * JSON-identical by construction (read-equivalence conformance family).
+ */
+export function runTraceWalk(direction, args) {
+    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 walkFn = direction === 'backward' ? traceBackward : traceForward;
+    const result = walkFn(args.record_hash, depth, byHash, {
+        maxNodes,
+        ...(contextId ? { contextId } : {}),
+    });
+    return buildPayload(result, byHash, compact, includeContent);
+}
+/** Register the legacy `trace` + `trace_forward` tools on a server. */
+export function registerTraceTools(mcp) {
+    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). Legacy alias: new callers ' +
+            "should prefer the `recall` tool with shape='walk', direction='backward'.",
+        inputSchema: TraceInput.shape,
+    }, async (args) => logReadPrimitiveCall('trace', args, async () => ({
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(runTraceWalk('backward', args), 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). Legacy ' +
+            "alias: new callers should prefer `recall` with shape='walk', direction='forward'.",
+        inputSchema: TraceInput.shape,
+    }, async (args) => logReadPrimitiveCall('trace_forward', args, async () => ({
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(runTraceWalk('forward', args), null, 2),
+            },
+        ],
+    }), extractRecordHashFieldsFromMcpResult));
+}
+/**
+ * Wire up the legacy atrib-trace MCP server. Mounts `trace` and
+ * `trace_forward` plus the `recall` verb (alias-window rule W1). The
+ * @atrib/trace package re-exports this factory.
+ */
+export async function createAtribTraceServer() {
+    const mcp = new McpServer({
+        name: 'atrib-trace',
+        version: '0.1.0',
+    });
+    registerTraceTools(mcp);
+    const { registerRecallVerbTool } = await import('./recall-verb.js');
+    registerRecallVerbTool(mcp);
+    return { mcp };
+}
+//# sourceMappingURL=trace-tools.js.map

package/dist/trace-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-tools.js","sourceRoot":"","sources":["../src/trace-tools.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACtE,OAAO,EAAE,cAAc,EAA2C,MAAM,oBAAoB,CAAA;AAC5F,OAAO,EAAE,aAAa,EAAE,YAAY,EAAqB,MAAM,iBAAiB,CAAA;AAEhF,MAAM,kBAAkB,GAAG,uBAAuB,CAAA;AAClD,MAAM,cAAc,GAAG,gBAAgB,CAAA;AAEvC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,KAAK,CAAC,kBAAkB,CAAC;SACzB,QAAQ,CACP,sEAAsE;QACpE,qCAAqC,CACxC;IACH,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,KAAK,CAAC,cAAc,CAAC;SACrB,QAAQ,EAAE;SACV,QAAQ,CACP,oEAAoE;QAClE,qEAAqE;QACrE,qEAAqE;QACrE,iEAAiE;QACjE,qEAAqE,CACxE;IACH,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,EAAE;SACV,QAAQ,CACP,mEAAmE;QACjE,2CAA2C;QAC3C,oEAAoE;QACpE,sDAAsD,CACzD;IACH,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,4EAA4E;QAC1E,yEAAyE;QACzE,eAAe,CAClB;IACH,OAAO,EAAE,CAAC;SACP,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,wEAAwE;QACtE,yEAAyE;QACzE,4CAA4C,CAC/C;IACH,eAAe,EAAE,CAAC;SACf,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,oEAAoE;QAClE,0EAA0E;QAC1E,iDAAiD,CACpD;CACJ,CAAC,CAAA;AAwDF;6EAC6E;AAC7E,MAAM,UAAU,gBAAgB,CAC9B,YAAoD;IAEpD,IAAI,CAAC,YAAY,EAAE,KAAK;QAAE,OAAO,SAAS,CAAA;IAC1C,MAAM,EAAE,GAAG,YAAY,CAAC,KAAK,CAAA;IAC7B,MAAM,GAAG,GAAmD,EAAE,CAAA;IAC9D,IAAI,EAAE,CAAC,QAAQ;QAAE,GAAG,CAAC,SAAS,GAAG,EAAE,CAAC,QAAQ,CAAA;IAC5C,IAAI,EAAE,CAAC,QAAQ;QAAE,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAA;IAC3C,MAAM,CAAC,GAAG,EAAE,CAAC,OAA8C,CAAA;IAC3D,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC9D,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,WAAW,CAAC,CAAA;IAChC,CAAC;IACD,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,QAAQ;QAAE,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,WAAW,CAAC,CAAA;IAC3E,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,QAAQ;QAAE,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,WAAW,CAAC,CAAA;IAC3E,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,YAAY,CAAC,KAAK,QAAQ;QAAE,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,CAAA;IAC9E,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,gBAAgB,CAAC,KAAK,QAAQ;QAAE,GAAG,CAAC,cAAc,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAA;IAC1F,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ,EAAE,CAAC;QACzC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IACzF,CAAC;IACD,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC5C,GAAG,CAAC,SAAS;YACX,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACvF,CAAC;IACD,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QACpC,GAAG,CAAC,MAAM,GAAI,CAAC,CAAC,QAAQ,CAAe;aACpC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;aACjD,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAChB,CAAC;IACD,sEAAsE;IACtE,mEAAmE;IACnE,qEAAqE;IACrE,8DAA8D;IAC9D,8BAA8B;IAC9B,iCAAiC;IACjC,qEAAqE;IACrE,sEAAsE;IACtE,gDAAgD;IAChD,sEAAsE;IACtE,IAAI,CAAC,EAAE,CAAC;QACN,IAAI,OAA2B,CAAA;QAC/B,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;YAClC,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA;QACrB,CAAC;aAAM,IAAI,OAAO,CAAC,CAAC,cAAc,CAAC,KAAK,QAAQ,EAAE,CAAC;YACjD,OAAO,GAAG,CAAC,CAAC,cAAc,CAAC,CAAA;QAC7B,CAAC;aAAM,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC5C,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAA;QACxB,CAAC;aAAM,IAAI,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC3C,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;QACvB,CAAC;aAAM,IAAI,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC3C,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAA;QACvB,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAA;QACzE,CAAC;IACH,CAAC;IACD,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,YAAY,CAAC,KAAK,QAAQ;QAAE,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,CAAA;IAC9E,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAA;AACxD,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,CAAe,EACf,WAAwB,EACxB,MAAkC,EAClC,cAAuB;IAEvB,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACzC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAA;IACvB,MAAM,GAAG,GAAmB;QAC1B,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,aAAa,EAAE,CAAC,CAAC,aAAa;QAC9B,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,UAAU,IAAI,IAAI;QACxC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,UAAU,IAAI,IAAI;QACxC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,WAAW,IAAI,IAAI;QAC1C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,SAAS,IAAI,IAAI;QACtC,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;QACpC,aAAa,EAAE,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpE,aAAa,EAAE,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnE,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACrF,CAAA;IACD,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,UAAU,GAAI,MAAqD,CAAC,WAAW,CAAA;QACrF,MAAM,QAAQ,GAAI,MAAiD,CAAC,SAAS,CAAA;QAC7E,MAAM,QAAQ,GAAI,MAAiD,CAAC,SAAS,CAAA;QAC7E,MAAM,UAAU,GAAI,MAAmD,CAAC,WAAW,CAAA;QACnF,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,WAAW,GAAG,UAAU,CAAA;QACpF,IAAI,QAAQ;YAAE,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAA;QACtC,IAAI,QAAQ;YAAE,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAA;QACtC,IAAI,UAAU;YAAE,GAAG,CAAC,WAAW,GAAG,UAAU,CAAA;IAC9C,CAAC;IACD,IAAI,cAAc,IAAI,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;QAC5D,GAAG,CAAC,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAA;IAC3C,CAAC;IACD,IAAI,cAAc,IAAI,OAAO,EAAE,KAAK,EAAE,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC7D,GAAG,CAAC,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAA;IAC7C,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,oCAAoC,CAAC,MAAe;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,OAAO,GAAG,uBAAuB,CAAA;IACvC,MAAM,OAAO,GAAI,MAAgC,EAAE,OAAO,CAAA;IAC1D,MAAM,IAAI,GACR,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QACtB,OAAQ,OAAO,CAAC,CAAC,CAAoC,EAAE,IAAI,KAAK,QAAQ;QACtE,CAAC,CAAE,OAAO,CAAC,CAAC,CAAsB,CAAC,IAAI;QACvC,CAAC,CAAC,SAAS,CAAA;IACf,IAAI,IAAI,GAAY,MAAM,CAAA;IAC1B,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,MAAM,CAAA;QACf,CAAC;IACH,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,CAAA;IACV,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAEvB,SAAS,IAAI,CAAC,IAAa;QACzB,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS;YAAE,OAAM;QAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,KAAK,MAAM,IAAI,IAAI,IAAI;gBAAE,IAAI,CAAC,IAAI,CAAC,CAAA;YACnC,OAAM;QACR,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAM;QACpC,MAAM,GAAG,GAAG,IAA+B,CAAA;QAC3C,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QAC3B,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,CAAA;IACrD,CAAC;AACH,CAAC;AAED,gEAAgE;AAChE,SAAS,YAAY,CACnB,MAAwC,EACxC,MAAkC,EAClC,OAAgB,EAChB,cAAuB;IAEvB,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC5C,OAAO,OAAO;QACZ,CAAC,CAAC;YACE,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;YAC1F,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;YAC7C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B;QACH,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAA;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAiC,EACjC,IAAiB;IAEjB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAA;IAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAA;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAA;IACpC,MAAM,cAAc,GAAG,IAAI,CAAC,eAAe,IAAI,KAAK,CAAA;IAEpD,kEAAkE;IAClE,6DAA6D;IAC7D,kEAAkE;IAClE,sEAAsE;IACtE,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,IAAI,mBAAmB,EAAE,CAAA;IAE1D,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAAA;IACnC,MAAM,MAAM,GAAG,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAA;IACtE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE;QACrD,QAAQ;QACR,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAC,CAAA;IACF,OAAO,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAA4B,CAAA;AACzF,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,GAAc;IAC/C,GAAG,CAAC,YAAY,CACd,OAAO,EACP;QACE,KAAK,EAAE,kCAAkC;QACzC,WAAW,EACT,sEAAsE;YACtE,kEAAkE;YAClE,wEAAwE;YACxE,uEAAuE;YACvE,mEAAmE;YACnE,qEAAqE;YACrE,wEAAwE;YACxE,0EAA0E;QAC5E,WAAW,EAAE,UAAU,CAAC,KAAK;KAC9B,EACD,KAAK,EAAE,IAAiB,EAAE,EAAE,CAC1B,oBAAoB,CAClB,OAAO,EACP,IAAI,EACJ,KAAK,IAAI,EAAE,CAAC,CAAC;QACX,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;aAC9D;SACF;KACF,CAAC,EACF,oCAAoC,CACrC,CACJ,CAAA;IAED,oEAAoE;IACpE,qEAAqE;IACrE,8DAA8D;IAC9D,GAAG,CAAC,YAAY,CACd,eAAe,EACf;QACE,KAAK,EAAE,iCAAiC;QACxC,WAAW,EACT,oEAAoE;YACpE,kEAAkE;YAClE,uEAAuE;YACvE,qEAAqE;YACrE,kEAAkE;YAClE,sEAAsE;YACtE,qEAAqE;YACrE,mFAAmF;QACrF,WAAW,EAAE,UAAU,CAAC,KAAK;KAC9B,EACD,KAAK,EAAE,IAAiB,EAAE,EAAE,CAC1B,oBAAoB,CAClB,eAAe,EACf,IAAI,EACJ,KAAK,IAAI,EAAE,CAAC,CAAC;QACX,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;aAC7D;SACF;KACF,CAAC,EACF,oCAAoC,CACrC,CACJ,CAAA;AACH,CAAC;AAMD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,MAAM,GAAG,GAAG,IAAI,SAAS,CAAC;QACxB,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAA;IACF,kBAAkB,CAAC,GAAG,CAAC,CAAA;IACvB,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAA;IACnE,sBAAsB,CAAC,GAAG,CAAC,CAAA;IAC3B,OAAO,EAAE,GAAG,EAAE,CAAA;AAChB,CAAC"}

package/dist/trace-walk.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 './trace-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;