@hardkas/query 0.7.1-alpha → 0.7.4-alpha

package/dist/index.d.ts

@@ -170,6 +170,7 @@ interface LineageNode {
     readonly networkId: NetworkId;
     readonly mode: string;
     readonly createdAt: string | null;
+    readonly workflowId?: string | undefined;
 }
 interface LineageTransition {
     readonly from: LineageNode;

package/dist/index.js

@@ -127,7 +127,9 @@ var FilesystemQueryBackend = class {
     return { applied: 0 };
   }
   async executeRawSql(_sql) {
-    throw new Error("Raw SQL execution not supported by Filesystem backend. Use SQLite backend.");
+    throw new Error(
+      "Raw SQL execution not supported by Filesystem backend. Use SQLite backend."
+    );
   }
   async scanFiles(dir) {
     const results = [];
@@ -419,7 +421,9 @@ function formatWhyBlock(block) {
   }
   if (block.evidence.length > 0) {
     lines.push("");
-    lines.push(`  Evidence Refs: ${block.evidence.map((e) => `${e.type}:${e.value.slice(0, 12)}...`).join(", ")}`);
+    lines.push(
+      `  Evidence Refs: ${block.evidence.map((e) => `${e.type}:${e.value.slice(0, 12)}...`).join(", ")}`
+    );
   }
   return lines.join("\n");
 }
@@ -438,7 +442,18 @@ var ArtifactQueryAdapter = class {
     return ["list", "inspect", "diff", "verify"];
   }
   supportedFilters() {
-    return ["schema", "version", "networkId", "mode", "from.address", "to.address", "amountSompi", "status", "contentHash", "createdAt"];
+    return [
+      "schema",
+      "version",
+      "networkId",
+      "mode",
+      "from.address",
+      "to.address",
+      "amountSompi",
+      "status",
+      "contentHash",
+      "createdAt"
+    ];
   }
   async execute(request) {
     switch (request.op) {
@@ -487,12 +502,16 @@ var ArtifactQueryAdapter = class {
     const paged = sorted.slice(request.offset, request.offset + request.limit);
     let why;
     if (request.explain) {
-      why = paged.map((item) => explainIntegrity(item, {
-        ok: true,
-        hashMatch: true,
-        schemaValid: KNOWN_SCHEMAS.has(item.schema),
-        errors: []
-      }));
+      why = paged.map(
+        (item) => explainIntegrity(item, {
+          ok: true,
+          hashMatch: true,
+          schemaValid: KNOWN_SCHEMAS.has(
+            item.schema
+          ),
+          errors: []
+        })
+      );
     }
     return {
       domain: "artifacts",
@@ -516,7 +535,8 @@ var ArtifactQueryAdapter = class {
   async executeInspect(request) {
     const start = Date.now();
     const target = request.params["target"];
-    if (!target) throw new Error("inspect requires params.target (content hash or file path)");
+    if (!target)
+      throw new Error("inspect requires params.target (content hash or file path)");
     const filePath = await this.resolveTarget(target);
     const raw = await this.readJsonSafe(filePath);
     if (!raw) throw new Error(`Cannot read artifact at: ${filePath}`);
@@ -550,8 +570,13 @@ var ArtifactQueryAdapter = class {
       integrity: {
         ok: integrityResult.ok && hashMatch,
         hashMatch,
-        schemaValid: KNOWN_SCHEMAS.has(item.schema),
-        errors: [...integrityResult.issues.map((i) => i.message), ...semanticResult.issues.map((i) => i.message)]
+        schemaValid: KNOWN_SCHEMAS.has(
+          item.schema
+        ),
+        errors: [
+          ...integrityResult.issues.map((i) => i.message),
+          ...semanticResult.issues.map((i) => i.message)
+        ]
       },
       economics,
       staleness,
@@ -584,7 +609,8 @@ var ArtifactQueryAdapter = class {
     const start = Date.now();
     const leftPath = request.params["left"];
     const rightPath = request.params["right"];
-    if (!leftPath || !rightPath) throw new Error("diff requires params.left and params.right");
+    if (!leftPath || !rightPath)
+      throw new Error("diff requires params.left and params.right");
     const leftRaw = await this.readJsonSafe(leftPath);
     const rightRaw = await this.readJsonSafe(rightPath);
     if (!leftRaw) throw new Error(`Cannot read left artifact: ${leftPath}`);
@@ -653,7 +679,8 @@ var ArtifactQueryAdapter = class {
     for (const entry of entries) {
       const full = path2.join(dir, entry.name);
       if (entry.isDirectory()) {
-        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "keystores") continue;
+        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "keystores")
+          continue;
         await this.walkDir(full, out);
       } else if (entry.name.endsWith(".json") && !entry.name.endsWith(".enc.json")) {
         out.push(full);
@@ -738,7 +765,8 @@ import { deterministicCompare } from "@hardkas/core";
 var VALID_TRANSITIONS2 = {
   "hardkas.snapshot": ["hardkas.txPlan"],
   "hardkas.txPlan": ["hardkas.signedTx"],
-  "hardkas.signedTx": ["hardkas.txReceipt"]
+  "hardkas.signedTx": ["hardkas.signedTx", "hardkas.txReceipt"],
+  "hardkas.workflow.v1": ["hardkas.txPlan", "hardkas.signedTx", "hardkas.txReceipt"]
 };
 var LineageQueryAdapter = class {
   domain = "lineage";
@@ -771,8 +799,24 @@ var LineageQueryAdapter = class {
   // -------------------------------------------------------------------------
   async executeChain(request) {
     const start = Date.now();
-    const anchor = request.params["anchor"];
-    if (!anchor) throw new Error("chain requires params.anchor (contentHash or artifactId)");
+    let anchor = request.params["anchor"];
+    if (!anchor)
+      throw new Error("chain requires params.anchor (contentHash or artifactId)");
+    if (typeof anchor === "string") {
+      try {
+        const path7 = await import("path");
+        const fs7 = await import("fs");
+        const resolvedPath = path7.resolve(this.rootDir, anchor);
+        if (fs7.existsSync(resolvedPath) && fs7.statSync(resolvedPath).isFile()) {
+          const content = fs7.readFileSync(resolvedPath, "utf-8");
+          const json = JSON.parse(content);
+          if (json) {
+            anchor = json.lineage?.artifactId || json.artifactId || json.planId || json.signedId || json.txId || json.contentHash || anchor;
+          }
+        }
+      } catch (e) {
+      }
+    }
     const direction = request.params["direction"] ?? "ancestors";
     const graph = await this.buildGraph();
     const anchorNode = graph.byArtifactId.get(anchor) ?? graph.byContentHash.get(anchor);
@@ -910,30 +954,46 @@ var LineageQueryAdapter = class {
     const byContentHash = /* @__PURE__ */ new Map();
     const children = /* @__PURE__ */ new Map();
     const docs = await this.backend.findArtifacts();
+    const VALID_SCHEMAS = [
+      "hardkas.txPlan",
+      "hardkas.signedTx",
+      "hardkas.txReceipt",
+      "hardkas.workflow.v1",
+      "hardkas.snapshot"
+    ];
     for (const doc of docs) {
       const raw = doc.payload;
-      if (!raw?.schema || !raw.lineage) continue;
+      if (!raw?.schema || !VALID_SCHEMAS.includes(raw.schema)) continue;
       const node = {
         contentHash: doc.contentHash,
         schema: doc.schema,
-        artifactId: raw.lineage.artifactId || "",
-        parentArtifactId: raw.lineage.parentArtifactId,
-        rootArtifactId: raw.lineage.rootArtifactId || "",
-        lineageId: raw.lineage.lineageId || "",
-        sequence: raw.lineage.sequence,
+        artifactId: raw.lineage?.artifactId || raw.artifactId || raw.planId || raw.signedId || raw.txId || doc.contentHash || "",
+        parentArtifactId: raw.lineage?.parentArtifactId || raw.sourcePlanId || raw.sourceSignedId,
+        rootArtifactId: raw.lineage?.rootArtifactId || raw.rootArtifactId || raw.artifactId || raw.planId || raw.signedId || raw.txId || doc.contentHash || "",
+        lineageId: raw.lineage?.lineageId || "",
+        sequence: raw.lineage?.sequence,
         filePath: doc.path,
         networkId: doc.networkId,
         mode: doc.mode,
-        createdAt: doc.createdAt || ""
+        createdAt: doc.createdAt || "",
+        workflowId: raw.schema === "hardkas.workflow.v1" ? void 0 : raw.workflowId
       };
       nodes.push(node);
       if (node.artifactId) byArtifactId.set(node.artifactId, node);
+      if (raw.planId) byArtifactId.set(raw.planId, node);
+      if (raw.signedId) byArtifactId.set(raw.signedId, node);
+      if (raw.txId) byArtifactId.set(raw.txId, node);
       if (node.contentHash) byContentHash.set(node.contentHash, node);
       if (node.parentArtifactId) {
         const existing = children.get(node.parentArtifactId) ?? [];
         existing.push(node);
         children.set(node.parentArtifactId, existing);
       }
+      if (node.workflowId) {
+        const existing = children.get(node.workflowId) ?? [];
+        existing.push(node);
+        children.set(node.workflowId, existing);
+      }
     }
     return { nodes, byArtifactId, byContentHash, children, totalFiles: docs.length };
   }
@@ -941,44 +1001,59 @@ var LineageQueryAdapter = class {
   // Graph Traversal
   // -------------------------------------------------------------------------
   walkAncestors(node, graph, nodes, transitions) {
-    const chain = [node];
-    let current = node;
+    const queue = [node];
     const visited = /* @__PURE__ */ new Set();
-    while (current.parentArtifactId && !visited.has(current.parentArtifactId)) {
-      visited.add(current.parentArtifactId);
-      const parent = graph.byArtifactId.get(current.parentArtifactId);
-      if (!parent) break;
-      chain.unshift(parent);
-      const allowed = VALID_TRANSITIONS2[parent.schema] ?? [];
-      transitions.unshift({
-        from: parent,
-        to: current,
-        valid: allowed.includes(current.schema),
-        rule: allowed.includes(current.schema) ? `${parent.schema} \u2192 ${current.schema} (valid)` : `${parent.schema} \u2192 ${current.schema} (INVALID)`
-      });
-      current = parent;
+    const queued = /* @__PURE__ */ new Set([node.artifactId]);
+    nodes.push(node);
+    while (queue.length > 0) {
+      const current = queue.shift();
+      visited.add(current.artifactId);
+      const parentIds = [];
+      if (current.parentArtifactId) parentIds.push(current.parentArtifactId);
+      if (current.workflowId) parentIds.push(current.workflowId);
+      for (const parentId of parentIds) {
+        const parent = graph.byArtifactId.get(parentId) ?? graph.byContentHash.get(parentId);
+        if (!parent) continue;
+        if (!queued.has(parent.artifactId)) {
+          queued.add(parent.artifactId);
+          nodes.unshift(parent);
+          queue.push(parent);
+          const allowed = VALID_TRANSITIONS2[parent.schema] ?? [];
+          transitions.unshift({
+            from: parent,
+            to: current,
+            valid: allowed.includes(current.schema),
+            rule: allowed.includes(current.schema) ? `${parent.schema} \u2192 ${current.schema} (valid)` : `${parent.schema} \u2192 ${current.schema} (INVALID)`
+          });
+        }
+      }
     }
-    nodes.push(...chain);
   }
   walkDescendants(node, graph, nodes, transitions) {
     const queue = [node];
     const visited = /* @__PURE__ */ new Set();
+    const queued = /* @__PURE__ */ new Set([node.artifactId]);
     nodes.push(node);
     while (queue.length > 0) {
       const current = queue.shift();
-      if (visited.has(current.artifactId)) continue;
       visited.add(current.artifactId);
-      const kids = graph.children.get(current.artifactId) ?? [];
+      const kids = [
+        ...graph.children.get(current.artifactId) ?? [],
+        ...current.contentHash ? graph.children.get(current.contentHash) ?? [] : []
+      ];
       for (const child of kids) {
-        nodes.push(child);
-        queue.push(child);
-        const allowed = VALID_TRANSITIONS2[current.schema] ?? [];
-        transitions.push({
-          from: current,
-          to: child,
-          valid: allowed.includes(child.schema),
-          rule: allowed.includes(child.schema) ? `${current.schema} \u2192 ${child.schema} (valid)` : `${current.schema} \u2192 ${child.schema} (INVALID)`
-        });
+        if (!queued.has(child.artifactId)) {
+          queued.add(child.artifactId);
+          nodes.push(child);
+          queue.push(child);
+          const allowed = VALID_TRANSITIONS2[current.schema] ?? [];
+          transitions.push({
+            from: current,
+            to: child,
+            valid: allowed.includes(child.schema),
+            rule: allowed.includes(child.schema) ? `${current.schema} \u2192 ${child.schema} (valid)` : `${current.schema} \u2192 ${child.schema} (INVALID)`
+          });
+        }
       }
     }
   }
@@ -1000,7 +1075,8 @@ var LineageQueryAdapter = class {
     for (const entry of entries) {
       const full = path3.join(dir, entry.name);
       if (entry.isDirectory()) {
-        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "keystores") continue;
+        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "keystores")
+          continue;
         await this.walkDir(full, out);
       } else if (entry.name.endsWith(".json") && !entry.name.endsWith(".enc.json")) {
         out.push(full);
@@ -1033,7 +1109,15 @@ var ReplayQueryAdapter = class {
     return ["list", "summary", "divergences", "invariants"];
   }
   supportedFilters() {
-    return ["txId", "status", "networkId", "mode", "daaScore", "from.address", "to.address"];
+    return [
+      "txId",
+      "status",
+      "networkId",
+      "mode",
+      "daaScore",
+      "from.address",
+      "to.address"
+    ];
   }
   async execute(request) {
     switch (request.op) {
@@ -1096,7 +1180,8 @@ var ReplayQueryAdapter = class {
     const txId = request.params["txId"];
     if (!txId) throw new Error("summary requires params.txId");
     const receipt = await this.backend.getArtifact(txId);
-    if (!receipt || receipt.schema !== "hardkas.txReceipt") throw new Error(`Receipt not found for txId: ${txId}`);
+    if (!receipt || receipt.schema !== "hardkas.txReceipt")
+      throw new Error(`Receipt not found for txId: ${txId}`);
     const traces = await this.backend.findTraces({ txId });
     const trace = traces[0];
     const item = toSummary(receipt.payload, trace?.payload);
@@ -1209,7 +1294,8 @@ var ReplayQueryAdapter = class {
     const txId = request.params["txId"];
     if (!txId) throw new Error("invariants requires params.txId");
     const doc = await this.backend.getArtifact(txId);
-    if (!doc || doc.schema !== "hardkas.txReceipt") throw new Error(`Receipt not found for txId: ${txId}`);
+    if (!doc || doc.schema !== "hardkas.txReceipt")
+      throw new Error(`Receipt not found for txId: ${txId}`);
     const receipt = doc.payload;
     const issues = [];
     const planIntegrity = receipt.contentHash ? computeContentHashSafe(receipt) === receipt.contentHash : true;
@@ -1342,10 +1428,30 @@ function explainDivergence(d) {
 function explainInvariants(result) {
   const causalChain = [];
   let order = 1;
-  causalChain.push({ order: order++, assertion: result.planIntegrity ? "Plan integrity is OK" : "Plan integrity FAILED", evidence: `planIntegrity=${result.planIntegrity}`, rule: "SHA-256 canonical consistency" });
-  causalChain.push({ order: order++, assertion: result.receiptReproducible ? "Receipt is reproducible" : "Receipt is NOT reproducible", evidence: `receiptReproducible=${result.receiptReproducible}`, rule: "Replay evidence requirements" });
-  causalChain.push({ order: order++, assertion: result.stateTransitionValid ? "State transition is valid" : "State transition INVALID", evidence: `stateTransitionValid=${result.stateTransitionValid}`, rule: "Status/State alignment" });
-  causalChain.push({ order: order++, assertion: result.utxoConservation ? "UTXO conservation holds" : "UTXO conservation VIOLATED", evidence: `utxoConservation=${result.utxoConservation}`, rule: "Value conservation policy" });
+  causalChain.push({
+    order: order++,
+    assertion: result.planIntegrity ? "Plan integrity is OK" : "Plan integrity FAILED",
+    evidence: `planIntegrity=${result.planIntegrity}`,
+    rule: "SHA-256 canonical consistency"
+  });
+  causalChain.push({
+    order: order++,
+    assertion: result.receiptReproducible ? "Receipt is reproducible" : "Receipt is NOT reproducible",
+    evidence: `receiptReproducible=${result.receiptReproducible}`,
+    rule: "Replay evidence requirements"
+  });
+  causalChain.push({
+    order: order++,
+    assertion: result.stateTransitionValid ? "State transition is valid" : "State transition INVALID",
+    evidence: `stateTransitionValid=${result.stateTransitionValid}`,
+    rule: "Status/State alignment"
+  });
+  causalChain.push({
+    order: order++,
+    assertion: result.utxoConservation ? "UTXO conservation holds" : "UTXO conservation VIOLATED",
+    evidence: `utxoConservation=${result.utxoConservation}`,
+    rule: "Value conservation policy"
+  });
   const allOk = result.planIntegrity && result.receiptReproducible && result.stateTransitionValid && result.utxoConservation;
   return {
     question: `Are replay invariants satisfied for tx ${result.txId.slice(0, 16)}...?`,
@@ -1420,7 +1526,10 @@ var DagQueryAdapter = class {
       deterministic: true,
       queryHash: computeQueryHash(paged),
       why,
-      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start
+      }
     };
   }
   // -------------------------------------------------------------------------
@@ -1456,7 +1565,10 @@ var DagQueryAdapter = class {
       deterministic: true,
       queryHash: computeQueryHash(paged),
       why,
-      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start
+      }
     };
   }
   // -------------------------------------------------------------------------
@@ -1508,7 +1620,10 @@ var DagQueryAdapter = class {
       deterministic: true,
       queryHash: computeQueryHash(entries),
       why,
-      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start
+      }
     };
   }
   // -------------------------------------------------------------------------
@@ -1542,7 +1657,10 @@ var DagQueryAdapter = class {
       truncated: false,
       deterministic: true,
       queryHash: computeQueryHash([result]),
-      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start
+      }
     };
   }
   // -------------------------------------------------------------------------
@@ -1608,7 +1726,10 @@ var DagQueryAdapter = class {
       deterministic: true,
       queryHash: computeQueryHash(paged),
       why,
-      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start
+      }
     };
   }
   // -------------------------------------------------------------------------
@@ -1683,7 +1804,12 @@ function explainDisplacement(d, _dag) {
     answer: d.reason,
     evidence: [{ type: "txId", value: d.txId }],
     causalChain: [
-      { order: 1, assertion: "Tx in displaced set", evidence: "dag.displacedTxIds includes txId", rule: "DAG reorganization" },
+      {
+        order: 1,
+        assertion: "Tx in displaced set",
+        evidence: "dag.displacedTxIds includes txId",
+        rule: "DAG reorganization"
+      },
       { order: 2, assertion: "Status: displaced", evidence: d.reason }
     ],
     model: "deterministic-light-model",
@@ -1700,8 +1826,16 @@ function explainTxHistory(entry, _dag) {
       { type: "blockId", value: entry.blockId }
     ],
     causalChain: [
-      { order: 1, assertion: `In block ${entry.blockId}`, evidence: `daaScore=${entry.daaScore}` },
-      { order: 2, assertion: entry.inSinkPath ? "In selected sink path" : "Not in sink path", evidence: `selectedPathToSink.includes("${entry.blockId}")` }
+      {
+        order: 1,
+        assertion: `In block ${entry.blockId}`,
+        evidence: `daaScore=${entry.daaScore}`
+      },
+      {
+        order: 2,
+        assertion: entry.inSinkPath ? "In selected sink path" : "Not in sink path",
+        evidence: `selectedPathToSink.includes("${entry.blockId}")`
+      }
     ],
     model: "deterministic-light-model",
     confidence: "definitive"
@@ -1716,7 +1850,12 @@ function explainAnomaly(a, _dag) {
     answer: a.description,
     evidence,
     causalChain: [
-      { order: 1, assertion: a.description, evidence: `Anomaly: ${a.kind}`, rule: "DAG invariant check" }
+      {
+        order: 1,
+        assertion: a.description,
+        evidence: `Anomaly: ${a.kind}`,
+        rule: "DAG invariant check"
+      }
     ],
     model: "deterministic-light-model",
     confidence: "definitive"
@@ -1784,18 +1923,32 @@ var EventsQueryAdapter = class {
         executionMs: Date.now() - start,
         filesScanned: backendUsed === "sqlite" ? 0 : 1
       },
-      why: request.explain ? [{
-        question: "How were events loaded and linked?",
-        answer: `Loaded ${total} events matching filters. Causal links (correlation/causation) available in payload.`,
-        evidence: [],
-        causalChain: [
-          { order: 1, assertion: `Source: ${backendUsed}`, evidence: "Event stream processed" },
-          { order: 2, assertion: `Filters: ${effectiveFilters.length} applied`, evidence: effectiveFilters.map((f) => `${f.field} ${f.op} ${f.value}`).join(", ") || "none" },
-          { order: 3, assertion: "Ordering: timestamp ASC", evidence: "Deterministic stream sorting" }
-        ],
-        model: "events-causality",
-        confidence: "definitive"
-      }] : void 0
+      why: request.explain ? [
+        {
+          question: "How were events loaded and linked?",
+          answer: `Loaded ${total} events matching filters. Causal links (correlation/causation) available in payload.`,
+          evidence: [],
+          causalChain: [
+            {
+              order: 1,
+              assertion: `Source: ${backendUsed}`,
+              evidence: "Event stream processed"
+            },
+            {
+              order: 2,
+              assertion: `Filters: ${effectiveFilters.length} applied`,
+              evidence: effectiveFilters.map((f) => `${f.field} ${f.op} ${f.value}`).join(", ") || "none"
+            },
+            {
+              order: 3,
+              assertion: "Ordering: timestamp ASC",
+              evidence: "Deterministic stream sorting"
+            }
+          ],
+          model: "events-causality",
+          confidence: "definitive"
+        }
+      ] : void 0
     };
   }
   async loadEvents() {
@@ -1856,29 +2009,46 @@ var TxQueryAdapter = class {
     const roles = new Set(artifacts.map((a) => a.role));
     if (!roles.has("plan")) warnings.push("Missing tx plan artifact");
     if (!roles.has("signed")) warnings.push("Missing signed tx artifact");
-    if (!roles.has("receipt")) warnings.push("Missing tx receipt artifact (may not exist yet)");
+    if (!roles.has("receipt"))
+      warnings.push("Missing tx receipt artifact (may not exist yet)");
     const complete = roles.has("plan") && roles.has("signed");
     const result = {
       txId,
       artifacts,
-      events: events.sort((a, b) => deterministicCompare5(a.timestamp, b.timestamp) || deterministicCompare5(a.eventId, b.eventId)),
+      events: events.sort(
+        (a, b) => deterministicCompare5(a.timestamp, b.timestamp) || deterministicCompare5(a.eventId, b.eventId)
+      ),
       warnings,
       complete
     };
     let why;
     if (request.explain) {
-      why = [{
-        question: `Causal aggregation for transaction ${txId}?`,
-        answer: complete ? `Found ${artifacts.length} artifact(s) and ${events.length} event(s). Workflow is consistent.` : `Aggregation incomplete: ${warnings.join(". ")}.`,
-        evidence: [{ type: "txId", value: txId }],
-        causalChain: [
-          { order: 1, assertion: `Artifacts linked: ${artifacts.length}`, evidence: artifacts.map((a) => a.role).join(", ") },
-          { order: 2, assertion: `Events linked: ${events.length}`, evidence: "Events found in stream" },
-          { order: 3, assertion: `Completeness check: ${complete}`, evidence: warnings.join("; ") || "all required roles found" }
-        ],
-        model: "tx-causality",
-        confidence: "definitive"
-      }];
+      why = [
+        {
+          question: `Causal aggregation for transaction ${txId}?`,
+          answer: complete ? `Found ${artifacts.length} artifact(s) and ${events.length} event(s). Workflow is consistent.` : `Aggregation incomplete: ${warnings.join(". ")}.`,
+          evidence: [{ type: "txId", value: txId }],
+          causalChain: [
+            {
+              order: 1,
+              assertion: `Artifacts linked: ${artifacts.length}`,
+              evidence: artifacts.map((a) => a.role).join(", ")
+            },
+            {
+              order: 2,
+              assertion: `Events linked: ${events.length}`,
+              evidence: "Events found in stream"
+            },
+            {
+              order: 3,
+              assertion: `Completeness check: ${complete}`,
+              evidence: warnings.join("; ") || "all required roles found"
+            }
+          ],
+          model: "tx-causality",
+          confidence: "definitive"
+        }
+      ];
     }
     return {
       domain: "tx",
@@ -1949,18 +2119,21 @@ var QueryEngine = class _QueryEngine {
           const { HardkasStore, SqliteQueryBackend, HardkasIndexer } = await import("@hardkas/query-store");
           const store = new HardkasStore({ dbPath });
           if (options.autoSync) {
-            await withLock({
-              rootDir: options.artifactDir,
-              name: "query-store",
-              command: "query-engine-auto-sync",
-              wait: options.waitLock ?? false,
-              timeoutMs: 5e3
-              // Short timeout for auto-sync
-            }, async () => {
-              store.connect({ autoMigrate: true });
-              const indexer = new HardkasIndexer(store.getDatabase());
-              await indexer.sync();
-            });
+            await withLock(
+              {
+                rootDir: options.artifactDir,
+                name: "query-store",
+                command: "query-engine-auto-sync",
+                wait: options.waitLock ?? false,
+                timeoutMs: 5e3
+                // Short timeout for auto-sync
+              },
+              async () => {
+                store.connect({ autoMigrate: true });
+                const indexer = new HardkasIndexer(store.getDatabase());
+                await indexer.sync();
+              }
+            );
           } else {
             store.connect();
           }
@@ -1980,11 +2153,23 @@ var QueryEngine = class _QueryEngine {
   constructor(options) {
     this.backend = options.backend || new FilesystemQueryBackend(options.artifactDir);
     this.adapters = /* @__PURE__ */ new Map();
-    this.adapters.set("artifacts", new ArtifactQueryAdapter(options.artifactDir, this.backend));
-    this.adapters.set("lineage", new LineageQueryAdapter(options.artifactDir, this.backend));
-    this.adapters.set("replay", new ReplayQueryAdapter(options.artifactDir, this.backend));
+    this.adapters.set(
+      "artifacts",
+      new ArtifactQueryAdapter(options.artifactDir, this.backend)
+    );
+    this.adapters.set(
+      "lineage",
+      new LineageQueryAdapter(options.artifactDir, this.backend)
+    );
+    this.adapters.set(
+      "replay",
+      new ReplayQueryAdapter(options.artifactDir, this.backend)
+    );
     this.adapters.set("dag", new DagQueryAdapter(options.artifactDir, this.backend));
-    this.adapters.set("events", new EventsQueryAdapter(options.artifactDir, this.backend));
+    this.adapters.set(
+      "events",
+      new EventsQueryAdapter(options.artifactDir, this.backend)
+    );
     this.adapters.set("tx", new TxQueryAdapter(options.artifactDir, this.backend));
   }
   /**
@@ -2013,7 +2198,9 @@ var QueryEngine = class _QueryEngine {
         rowsRead: result.items.length,
         scannedFiles: result.annotations.filesScanned || 0,
         freshness,
-        warnings: freshness === "stale" ? ["Index is STALE. mtime mismatch detected. Run 'hardkas query store rebuild'."] : []
+        warnings: freshness === "stale" ? [
+          "Index is STALE. mtime mismatch detected. Run 'hardkas query store rebuild'."
+        ] : []
       };
     }
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/query",
-  "version": "0.7.1-alpha",
+  "version": "0.7.4-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,9 +14,9 @@
   ],
   "dependencies": {
     "picocolors": "^1.1.1",
-    "@hardkas/core": "0.7.1-alpha",
-    "@hardkas/artifacts": "0.7.1-alpha",
-    "@hardkas/query-store": "0.7.1-alpha"
+    "@hardkas/core": "0.7.4-alpha",
+    "@hardkas/query-store": "0.7.4-alpha",
+    "@hardkas/artifacts": "0.7.4-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",