@hardkas/query 0.2.2-alpha → 0.3.0-alpha

package/dist/index.js

@@ -1,6 +1,164 @@
-// src/adapters/artifact-adapter.ts
+// src/backend-fs.ts
 import fs from "fs/promises";
 import path from "path";
+var FilesystemQueryBackend = class {
+  rootDir;
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  isReady() {
+    return true;
+  }
+  kind() {
+    return "filesystem";
+  }
+  async findArtifacts(filters) {
+    const files = await this.scanFiles(this.rootDir);
+    const docs = [];
+    for (const f of files) {
+      const raw = await this.readJson(f);
+      if (!raw || !raw.schema) continue;
+      if (filters?.schema && raw.schema !== filters.schema) continue;
+      if (filters?.mode && raw.mode !== filters.mode) continue;
+      if (filters?.networkId && raw.networkId !== filters.networkId) continue;
+      docs.push({
+        contentHash: raw.contentHash || "",
+        schema: raw.schema,
+        version: raw.version || "unknown",
+        kind: raw.kind || raw.schema,
+        mode: raw.mode,
+        networkId: raw.networkId,
+        createdAt: raw.createdAt || null,
+        txId: raw.txId || null,
+        artifactId: raw.artifactId || raw.contentHash || "",
+        path: f,
+        payload: raw
+      });
+    }
+    return docs;
+  }
+  async getArtifact(idOrHash) {
+    const artifacts = await this.findArtifacts();
+    return artifacts.find(
+      (a) => a.contentHash === idOrHash || a.payload.lineage?.artifactId === idOrHash || a.payload.artifactId === idOrHash || a.payload.txId === idOrHash
+    ) || null;
+  }
+  async getEvents(filters) {
+    const eventsPath = path.join(this.rootDir, ".hardkas", "events.jsonl");
+    const docs = [];
+    try {
+      const content = await fs.readFile(eventsPath, "utf-8");
+      const lines = content.split("\n").filter((l) => l.trim() !== "");
+      for (const line of lines) {
+        try {
+          const parsed = JSON.parse(line);
+          if (filters?.kind && parsed.kind !== filters.kind) continue;
+          if (filters?.txId && parsed.txId !== filters.txId) continue;
+          docs.push({
+            eventId: parsed.eventId,
+            kind: parsed.kind,
+            domain: parsed.domain,
+            timestamp: parsed.timestamp || null,
+            workflowId: parsed.workflowId,
+            correlationId: parsed.correlationId,
+            causationId: parsed.causationId || null,
+            txId: parsed.txId || null,
+            artifactId: parsed.artifactId || null,
+            networkId: parsed.networkId,
+            payload: parsed.payload
+          });
+        } catch {
+        }
+      }
+    } catch {
+    }
+    return docs;
+  }
+  async getLineageEdges(filters) {
+    const artifacts = await this.findArtifacts();
+    const edges = [];
+    for (const a of artifacts) {
+      if (a.payload.lineage?.parentArtifactId) {
+        edges.push({
+          parentArtifactId: a.payload.lineage.parentArtifactId,
+          childArtifactId: a.artifactId,
+          lineageId: a.payload.lineage.lineageId || "unknown",
+          rule: "parent",
+          createdAt: a.createdAt
+        });
+      }
+    }
+    return edges.filter((e) => {
+      if (filters?.parentHash && e.parentArtifactId !== filters.parentHash) return false;
+      if (filters?.childHash && e.childArtifactId !== filters.childHash) return false;
+      return true;
+    });
+  }
+  async getStoreStatus() {
+    return "fresh";
+  }
+  async doctor() {
+    return { ok: true, backend: "filesystem" };
+  }
+  async rebuild(options) {
+    return {
+      schema: "hardkas.queryRebuild.v1",
+      ok: true,
+      artifacts: { scanned: 0, indexed: 0, duplicates: 0, corrupted: 0 },
+      events: { scanned: 0, indexed: 0, duplicates: 0, corrupted: 0 },
+      warnings: ["Filesystem backend does not support indexing"],
+      errors: []
+    };
+  }
+  async findReceipts(filters) {
+    return this.findArtifacts({ schema: "hardkas.txReceipt", ...filters });
+  }
+  async findTraces(filters) {
+    const artifacts = await this.findArtifacts({ schema: "hardkas.txTrace" });
+    if (filters?.txId) {
+      return artifacts.filter((a) => a.payload.txId === filters.txId);
+    }
+    return artifacts;
+  }
+  async sync(options) {
+    return this.rebuild(options);
+  }
+  async migrate() {
+    return { applied: 0 };
+  }
+  async executeRawSql(_sql) {
+    throw new Error("Raw SQL execution not supported by Filesystem backend. Use SQLite backend.");
+  }
+  async scanFiles(dir) {
+    const results = [];
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name === "node_modules" || entry.name === ".git") continue;
+          results.push(...await this.scanFiles(fullPath));
+        } else if (entry.name.endsWith(".json") && !entry.name.endsWith(".enc.json") && entry.name !== "events.jsonl") {
+          results.push(fullPath);
+        }
+      }
+    } catch {
+    }
+    return results;
+  }
+  async readJson(file) {
+    try {
+      const content = await fs.readFile(file, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/adapters/artifact-adapter.ts
+import fs2 from "fs/promises";
+import path2 from "path";
 import {
   calculateContentHash,
   verifyArtifactIntegrity,
@@ -123,144 +281,145 @@ var VALID_TRANSITIONS = {
   "hardkas.txPlan": ["hardkas.signedTx"],
   "hardkas.signedTx": ["hardkas.txReceipt"]
 };
+function createExplainBlock(options) {
+  return {
+    backend: options.backend,
+    executionPlan: options.executionPlan,
+    indexesUsed: options.indexesUsed || [],
+    filtersApplied: options.filtersApplied || [],
+    rowsRead: options.rowsRead,
+    scannedFiles: options.scannedFiles,
+    freshness: options.freshness,
+    warnings: options.warnings || []
+  };
+}
 function explainIntegrity(artifact, integrity) {
-  const steps = [];
+  const causalChain = [];
+  const evidence = [];
   let order = 1;
-  steps.push({
+  if (artifact.contentHash) {
+    evidence.push({ type: "contentHash", value: artifact.contentHash });
+  }
+  evidence.push({ type: "filePath", value: artifact.filePath });
+  causalChain.push({
     order: order++,
     assertion: integrity.schemaValid ? `Schema "${artifact.schema}" is a recognized HardKAS artifact schema` : `Schema "${artifact.schema}" is not recognized`,
     evidence: `artifact.schema = "${artifact.schema}"`,
     rule: "ARTIFACT_SCHEMAS constant (artifacts/constants.ts)"
   });
   if (artifact.contentHash) {
-    steps.push({
+    causalChain.push({
       order: order++,
-      assertion: integrity.hashMatch ? "Content hash matches recomputed hash" : "Content hash does NOT match recomputed hash \u2014 possible corruption",
-      evidence: `artifact.contentHash = "${artifact.contentHash}"`,
+      assertion: integrity.hashMatch ? "Content hash matches recomputed hash" : "Content hash does NOT match recomputed hash",
+      evidence: `hash(payload) === "${artifact.contentHash}"`,
       rule: "canonicalStringify + SHA-256 (artifacts/canonical.ts)"
     });
-  } else {
-    steps.push({
-      order: order++,
-      assertion: "Artifact has no contentHash field (pre-verification artifact)",
-      evidence: "artifact.contentHash is undefined",
-      rule: "contentHash is optional but recommended"
-    });
   }
   if (integrity.errors.length > 0) {
     for (const err of integrity.errors) {
-      steps.push({
+      causalChain.push({
         order: order++,
-        assertion: `Integrity issue: ${err}`,
-        evidence: err,
-        rule: "verifyArtifactIntegrity (artifacts/verify.ts)"
+        assertion: `Semantic violation detected: ${err}`,
+        evidence: "Verification engine failure",
+        rule: "verifyArtifactSemantics (artifacts/verify.ts)"
       });
     }
   }
   return {
-    question: `Why is artifact "${artifact.schema}" at ${artifact.filePath} ${integrity.ok ? "valid" : "invalid"}?`,
-    conclusion: integrity.ok ? "All integrity checks passed. Schema is valid and content hash matches." : `Integrity check failed: ${integrity.errors.join("; ")}`,
-    steps,
-    model: "artifact-verification",
-    confidence: "definitive",
-    references: artifact.contentHash ? [artifact.contentHash] : []
+    question: `Why is artifact "${artifact.schema}" ${integrity.ok ? "valid" : "invalid"}?`,
+    answer: integrity.ok ? "All deterministic checks (schema, hash, semantics) passed successfully." : `Verification failed: ${integrity.errors.join("; ")}`,
+    evidence,
+    causalChain,
+    model: "integrity-verifier",
+    confidence: "definitive"
   };
 }
 function explainTransition(transition) {
-  const steps = [];
+  const causalChain = [];
+  const evidence = [
+    { type: "contentHash", value: transition.from.contentHash },
+    { type: "contentHash", value: transition.to.contentHash }
+  ];
   let order = 1;
   const allowed = VALID_TRANSITIONS[transition.from.schema] ?? [];
-  steps.push({
-    order: order++,
-    assertion: allowed.length > 0 ? `Schema "${transition.from.schema}" allows transitions to: ${allowed.join(", ")}` : `Schema "${transition.from.schema}" has no defined transitions`,
-    evidence: `VALID_TRANSITIONS["${transition.from.schema}"] = [${allowed.map((s) => `"${s}"`).join(", ")}]`,
-    rule: "Lineage transition table (artifacts/lineage.ts)"
-  });
-  steps.push({
+  causalChain.push({
     order: order++,
-    assertion: transition.valid ? `Transition "${transition.from.schema}" \u2192 "${transition.to.schema}" is VALID` : `Transition "${transition.from.schema}" \u2192 "${transition.to.schema}" is NOT in the allowed set`,
-    evidence: `target schema = "${transition.to.schema}", allowed = [${allowed.map((s) => `"${s}"`).join(", ")}]`,
-    rule: "Lineage transition table (artifacts/lineage.ts)"
+    assertion: transition.valid ? `Transition "${transition.from.schema}" \u2192 "${transition.to.schema}" is allowed` : `Transition "${transition.from.schema}" \u2192 "${transition.to.schema}" is NOT allowed`,
+    evidence: `allowed_from_${transition.from.schema} = [${allowed.join(", ")}]`,
+    rule: "Lineage transition table"
   });
-  const networkMatch = transition.from.networkId === transition.to.networkId;
-  steps.push({
+  const contextMatch = transition.from.networkId === transition.to.networkId && transition.from.mode === transition.to.mode;
+  causalChain.push({
     order: order++,
-    assertion: networkMatch ? `Network is consistent: both "${transition.from.networkId}"` : `NETWORK CONTAMINATION: "${transition.from.networkId}" \u2192 "${transition.to.networkId}"`,
-    evidence: `parent.networkId = "${transition.from.networkId}", child.networkId = "${transition.to.networkId}"`,
-    rule: "NETWORK_CONTAMINATION check (artifacts/lineage.ts)"
+    assertion: contextMatch ? "Execution context (network, mode) is consistent" : "EXECUTION CONTEXT MISMATCH detected",
+    evidence: `from: ${transition.from.networkId}/${transition.from.mode}, to: ${transition.to.networkId}/${transition.to.mode}`,
+    rule: "Context isolation policy"
   });
-  const modeMatch = transition.from.mode === transition.to.mode;
-  steps.push({
-    order: order++,
-    assertion: modeMatch ? `Mode is consistent: both "${transition.from.mode}"` : `MODE CONTAMINATION: "${transition.from.mode}" \u2192 "${transition.to.mode}"`,
-    evidence: `parent.mode = "${transition.from.mode}", child.mode = "${transition.to.mode}"`,
-    rule: "MODE_CONTAMINATION check (artifacts/lineage.ts)"
-  });
-  const lineageMatch = transition.from.lineageId === transition.to.lineageId;
-  steps.push({
-    order: order++,
-    assertion: lineageMatch ? "Lineage ID is continuous" : "LINEAGE ID MISMATCH \u2014 artifacts belong to different lineage chains",
-    evidence: `parent.lineageId = "${transition.from.lineageId}", child.lineageId = "${transition.to.lineageId}"`,
-    rule: "LINEAGE_ID_MISMATCH check (artifacts/lineage.ts)"
-  });
-  const allValid = transition.valid && networkMatch && modeMatch && lineageMatch;
   return {
-    question: `Why is the transition "${transition.from.schema}" \u2192 "${transition.to.schema}" ${allValid ? "valid" : "invalid"}?`,
-    conclusion: allValid ? `Valid transition. Rule: ${transition.from.schema} \u2192 ${transition.to.schema}. Network, mode, and lineage ID are all consistent.` : `Invalid transition. ${!transition.valid ? "Schema transition not allowed. " : ""}${!networkMatch ? "Network mismatch. " : ""}${!modeMatch ? "Mode mismatch. " : ""}${!lineageMatch ? "Lineage ID mismatch." : ""}`,
-    steps,
-    model: "lineage-rules",
-    confidence: "definitive",
-    references: [transition.from.contentHash, transition.to.contentHash]
+    question: `Why transition ${transition.from.schema} \u2192 ${transition.to.schema}?`,
+    answer: transition.valid && contextMatch ? "Causal chain is consistent with HardKAS state transition rules." : "Workflow violation: invalid schema transition or context contamination.",
+    evidence,
+    causalChain,
+    model: "causal-lineage",
+    confidence: "definitive"
   };
 }
 function explainOrphan(node, missingParentId) {
   return {
-    question: `Why is artifact "${node.schema}" (${node.contentHash.slice(0, 12)}...) an orphan?`,
-    conclusion: `Parent artifact with ID "${missingParentId.slice(0, 12)}..." is not found in the artifact store. This artifact is disconnected from its workflow context.`,
-    steps: [
+    question: `Why is artifact "${node.artifactId.slice(0, 8)}" an orphan?`,
+    answer: "The parent artifact referenced in the lineage metadata is missing from the indexed store.",
+    evidence: [
+      { type: "artifactId", value: node.artifactId },
+      { type: "artifactId", value: missingParentId }
+    ],
+    causalChain: [
       {
         order: 1,
-        assertion: `Artifact declares parentArtifactId = "${missingParentId}"`,
-        evidence: `artifact.lineage.parentArtifactId = "${missingParentId}"`,
-        rule: "Lineage parent resolution"
+        assertion: "Artifact defines a parent dependency",
+        evidence: `parentArtifactId = "${missingParentId}"`,
+        rule: "Lineage metadata requirement"
       },
       {
         order: 2,
-        assertion: "No artifact in the store has a matching lineage.artifactId",
-        evidence: "Full store scan found 0 artifacts with this artifactId",
-        rule: "Lineage graph construction (query/lineage-adapter.ts)"
-      },
-      {
-        order: 3,
-        assertion: "Artifact is classified as an orphan",
-        evidence: "Missing parent means the lineage chain is broken",
-        rule: "Orphan detection: parentArtifactId exists but not resolvable"
+        assertion: "Parent artifact lookup failed",
+        evidence: "Index scan for artifactId returned 0 results",
+        rule: "Store integrity policy"
       }
     ],
-    model: "lineage-rules",
-    confidence: "definitive",
-    references: [node.contentHash, missingParentId]
+    model: "orphan-analysis",
+    confidence: "definitive"
   };
 }
-function formatExplainBrief(chain) {
-  return `${chain.conclusion} [model: ${chain.model}, confidence: ${chain.confidence}]`;
+function formatExplainBlock(block) {
+  const lines = [];
+  lines.push(`  [Explain: Technical Diagnostics]`);
+  lines.push(`  Backend:      ${block.backend}`);
+  lines.push(`  Freshness:    ${block.freshness}`);
+  lines.push(`  Rows Read:    ${block.rowsRead}`);
+  lines.push(`  Files Scan:   ${block.scannedFiles}`);
+  if (block.executionPlan.length > 0) {
+    lines.push(`  Plan:         ${block.executionPlan.join(" \u2192 ")}`);
+  }
+  if (block.warnings.length > 0) {
+    lines.push(`  Warnings:`);
+    for (const w of block.warnings) lines.push(`    \u26A0 ${w}`);
+  }
+  return lines.join("\n");
 }
-function formatExplainFull(chain) {
+function formatWhyBlock(block) {
   const lines = [];
-  lines.push(`Q: ${chain.question}`);
+  lines.push(`  [Why: Causal Analysis]`);
+  lines.push(`  Q: ${block.question}`);
+  lines.push(`  A: ${block.answer}`);
   lines.push("");
-  for (const step of chain.steps) {
-    lines.push(`  ${step.order}. ${step.assertion}`);
-    lines.push(`     Evidence: ${step.evidence}`);
-    if (step.rule) {
-      lines.push(`     Rule: ${step.rule}`);
-    }
+  for (const step of block.causalChain) {
+    lines.push(`    ${step.order}. ${step.assertion}`);
+    lines.push(`       Evidence: ${step.evidence}`);
+    if (step.rule) lines.push(`       Rule:     ${step.rule}`);
   }
-  lines.push("");
-  lines.push(`Conclusion: ${chain.conclusion}`);
-  lines.push(`Model: ${chain.model} | Confidence: ${chain.confidence}`);
-  if (chain.references.length > 0) {
-    lines.push(`References: ${chain.references.map((r) => r.slice(0, 16) + "...").join(", ")}`);
+  if (block.evidence.length > 0) {
+    lines.push("");
+    lines.push(`  Evidence Refs: ${block.evidence.map((e) => `${e.type}:${e.value.slice(0, 12)}...`).join(", ")}`);
   }
   return lines.join("\n");
 }
@@ -270,8 +429,10 @@ var KNOWN_SCHEMAS = new Set(Object.values(ARTIFACT_SCHEMAS));
 var ArtifactQueryAdapter = class {
   domain = "artifacts";
   rootDir;
-  constructor(rootDir) {
+  backend;
+  constructor(rootDir, backend) {
     this.rootDir = rootDir;
+    this.backend = backend;
   }
   supportedOps() {
     return ["list", "inspect", "diff", "verify"];
@@ -298,12 +459,25 @@ var ArtifactQueryAdapter = class {
   // -------------------------------------------------------------------------
   async executeList(request) {
     const start = Date.now();
-    const files = await this.scanArtifactFiles();
+    const docs = await this.backend.findArtifacts();
     const items = [];
-    for (const filePath of files) {
-      const raw = await this.readJsonSafe(filePath);
-      if (!raw || !raw.schema) continue;
-      const item = toArtifactQueryItem(raw, filePath);
+    for (const doc of docs) {
+      const item = {
+        filePath: doc.path,
+        schema: doc.schema,
+        version: doc.version,
+        networkId: doc.networkId,
+        mode: doc.mode,
+        createdAt: doc.createdAt,
+        contentHash: doc.contentHash,
+        payload: doc.payload,
+        // Optional mapping for common fields
+        status: doc.payload.status,
+        from: doc.payload.from,
+        to: doc.payload.to,
+        amountSompi: doc.payload.amountSompi,
+        lineage: doc.payload.lineage
+      };
       if (evaluateFilters(item, request.filters)) {
         items.push(item);
       }
@@ -311,9 +485,9 @@ var ArtifactQueryAdapter = class {
     const sorted = this.sortItems(items, request.sort);
     const total = sorted.length;
     const paged = sorted.slice(request.offset, request.offset + request.limit);
-    let explain;
+    let why;
     if (request.explain) {
-      explain = paged.map((item) => explainIntegrity(item, {
+      why = paged.map((item) => explainIntegrity(item, {
         ok: true,
         hashMatch: true,
         schemaValid: KNOWN_SCHEMAS.has(item.schema),
@@ -328,11 +502,11 @@ var ArtifactQueryAdapter = class {
       truncated: total > request.offset + request.limit,
       deterministic: true,
       queryHash: computeQueryHash(paged),
-      explain,
+      why,
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start,
-        filesScanned: files.length
+        filesScanned: docs.length
       }
     };
   }
@@ -383,9 +557,9 @@ var ArtifactQueryAdapter = class {
       staleness,
       lineageStatus
     };
-    let explain;
+    let why;
     if (request.explain) {
-      explain = [explainIntegrity(item, inspectResult.integrity)];
+      why = [explainIntegrity(item, inspectResult.integrity)];
     }
     return {
       domain: "artifacts",
@@ -395,7 +569,7 @@ var ArtifactQueryAdapter = class {
       truncated: false,
       deterministic: true,
       queryHash: computeQueryHash([inspectResult]),
-      explain,
+      why,
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start,
@@ -472,12 +646,12 @@ var ArtifactQueryAdapter = class {
   async walkDir(dir, out) {
     let entries;
     try {
-      entries = await fs.readdir(dir, { withFileTypes: true });
+      entries = await fs2.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const full = path.join(dir, entry.name);
+      const full = path2.join(dir, entry.name);
       if (entry.isDirectory()) {
         if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "keystores") continue;
         await this.walkDir(full, out);
@@ -488,7 +662,7 @@ var ArtifactQueryAdapter = class {
   }
   async readJsonSafe(filePath) {
     try {
-      const content = await fs.readFile(filePath, "utf-8");
+      const content = await fs2.readFile(filePath, "utf-8");
       return JSON.parse(content);
     } catch {
       return null;
@@ -496,7 +670,7 @@ var ArtifactQueryAdapter = class {
   }
   async resolveTarget(target) {
     if (target.includes("/") || target.includes("\\") || target.endsWith(".json")) {
-      return path.resolve(target);
+      return path2.resolve(target);
     }
     const files = await this.scanArtifactFiles();
     for (const f of files) {
@@ -517,7 +691,7 @@ var ArtifactQueryAdapter = class {
       });
     } else {
       sorted.sort((a, b) => {
-        const cmp = b.createdAt.localeCompare(a.createdAt);
+        const cmp = (b.createdAt ?? "").localeCompare(a.createdAt ?? "");
         return cmp !== 0 ? cmp : a.schema.localeCompare(b.schema);
       });
     }
@@ -533,6 +707,7 @@ function toArtifactQueryItem(raw, filePath) {
     mode: raw.mode || "unknown",
     createdAt: raw.createdAt || "",
     contentHash: raw.contentHash,
+    payload: raw,
     from: raw.from,
     to: raw.to,
     amountSompi: raw.amountSompi,
@@ -554,8 +729,8 @@ function classifyStaleness(hours) {
 }
 
 // src/adapters/lineage-adapter.ts
-import fs2 from "fs/promises";
-import path2 from "path";
+import fs3 from "fs/promises";
+import path3 from "path";
 var VALID_TRANSITIONS2 = {
   "hardkas.snapshot": ["hardkas.txPlan"],
   "hardkas.txPlan": ["hardkas.signedTx"],
@@ -564,8 +739,10 @@ var VALID_TRANSITIONS2 = {
 var LineageQueryAdapter = class {
   domain = "lineage";
   rootDir;
-  constructor(rootDir) {
+  backend;
+  constructor(rootDir, backend) {
     this.rootDir = rootDir;
+    this.backend = backend;
   }
   supportedOps() {
     return ["chain", "transitions", "orphans"];
@@ -611,9 +788,9 @@ var LineageQueryAdapter = class {
       transitions,
       complete
     };
-    let explain;
+    let why;
     if (request.explain) {
-      explain = transitions.map((t) => explainTransition(t));
+      why = transitions.map((t) => explainTransition(t));
     }
     return {
       domain: "lineage",
@@ -623,7 +800,7 @@ var LineageQueryAdapter = class {
       truncated: false,
       deterministic: true,
       queryHash: computeQueryHash([result]),
-      explain,
+      why,
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start,
@@ -660,9 +837,9 @@ var LineageQueryAdapter = class {
       return a.from.contentHash.localeCompare(b.from.contentHash);
     });
     const paged = transitions.slice(request.offset, request.offset + request.limit);
-    let explain;
+    let why;
     if (request.explain) {
-      explain = paged.map((t) => explainTransition(t));
+      why = paged.map((t) => explainTransition(t));
     }
     return {
       domain: "lineage",
@@ -672,7 +849,7 @@ var LineageQueryAdapter = class {
       truncated: transitions.length > request.offset + request.limit,
       deterministic: true,
       queryHash: computeQueryHash(paged),
-      explain,
+      why,
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start,
@@ -700,9 +877,9 @@ var LineageQueryAdapter = class {
     }
     orphans.sort((a, b) => a.node.contentHash.localeCompare(b.node.contentHash));
     const paged = orphans.slice(request.offset, request.offset + request.limit);
-    let explain;
+    let why;
     if (request.explain) {
-      explain = paged.map((o) => explainOrphan(o.node, o.missingParentId));
+      why = paged.map((o) => explainOrphan(o.node, o.missingParentId));
     }
     return {
       domain: "lineage",
@@ -712,7 +889,7 @@ var LineageQueryAdapter = class {
       truncated: orphans.length > request.offset + request.limit,
       deterministic: true,
       queryHash: computeQueryHash(paged),
-      explain,
+      why,
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start,
@@ -728,22 +905,22 @@ var LineageQueryAdapter = class {
     const byArtifactId = /* @__PURE__ */ new Map();
     const byContentHash = /* @__PURE__ */ new Map();
     const children = /* @__PURE__ */ new Map();
-    const files = await this.scanJsonFiles();
-    for (const filePath of files) {
-      const raw = await this.readJsonSafe(filePath);
+    const docs = await this.backend.findArtifacts();
+    for (const doc of docs) {
+      const raw = doc.payload;
       if (!raw?.schema || !raw.lineage) continue;
       const node = {
-        contentHash: raw.contentHash || "",
-        schema: raw.schema,
+        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,
-        filePath,
-        networkId: raw.networkId || "unknown",
-        mode: raw.mode || "unknown",
-        createdAt: raw.createdAt || ""
+        filePath: doc.path,
+        networkId: doc.networkId,
+        mode: doc.mode,
+        createdAt: doc.createdAt || ""
       };
       nodes.push(node);
       if (node.artifactId) byArtifactId.set(node.artifactId, node);
@@ -754,7 +931,7 @@ var LineageQueryAdapter = class {
         children.set(node.parentArtifactId, existing);
       }
     }
-    return { nodes, byArtifactId, byContentHash, children, totalFiles: files.length };
+    return { nodes, byArtifactId, byContentHash, children, totalFiles: docs.length };
   }
   // -------------------------------------------------------------------------
   // Graph Traversal
@@ -812,12 +989,12 @@ var LineageQueryAdapter = class {
   async walkDir(dir, out) {
     let entries;
     try {
-      entries = await fs2.readdir(dir, { withFileTypes: true });
+      entries = await fs3.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const full = path2.join(dir, entry.name);
+      const full = path3.join(dir, entry.name);
       if (entry.isDirectory()) {
         if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "keystores") continue;
         await this.walkDir(full, out);
@@ -828,7 +1005,7 @@ var LineageQueryAdapter = class {
   }
   async readJsonSafe(filePath) {
     try {
-      const content = await fs2.readFile(filePath, "utf-8");
+      const content = await fs3.readFile(filePath, "utf-8");
       return JSON.parse(content);
     } catch {
       return null;
@@ -837,14 +1014,15 @@ var LineageQueryAdapter = class {
 };
 
 // src/adapters/replay-adapter.ts
-import fs3 from "fs/promises";
-import path3 from "path";
+import fs4 from "fs/promises";
 import { calculateContentHash as calculateContentHash2 } from "@hardkas/artifacts";
 var ReplayQueryAdapter = class {
   domain = "replay";
   rootDir;
-  constructor(rootDir) {
+  backend;
+  constructor(rootDir, backend) {
     this.rootDir = rootDir;
+    this.backend = backend;
   }
   supportedOps() {
     return ["list", "summary", "divergences", "invariants"];
@@ -871,13 +1049,15 @@ var ReplayQueryAdapter = class {
   // -------------------------------------------------------------------------
   async executeList(request) {
     const start = Date.now();
-    const receipts = await this.loadAllReceipts();
-    const traces = await this.loadAllTraces();
+    const receipts = await this.backend.findReceipts({
+      status: request.filters.find((f) => f.field === "status")?.value
+    });
+    const traces = await this.backend.findTraces();
     const traceMap = new Map(traces.map((t) => [t.txId, t]));
     const items = [];
     for (const r of receipts) {
       const trace = traceMap.get(r.txId);
-      const item = toSummary(r, trace);
+      const item = toSummary(r.payload, trace?.payload);
       if (evaluateFilters(item, request.filters)) {
         items.push(item);
       }
@@ -910,10 +1090,11 @@ var ReplayQueryAdapter = class {
     const start = Date.now();
     const txId = request.params["txId"];
     if (!txId) throw new Error("summary requires params.txId");
-    const receipt = await this.loadReceipt(txId);
-    if (!receipt) throw new Error(`Receipt not found for txId: ${txId}`);
-    const trace = await this.loadTrace(txId);
-    const item = toSummary(receipt, trace);
+    const receipt = await this.backend.getArtifact(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);
     return {
       domain: "replay",
       op: "summary",
@@ -934,9 +1115,10 @@ var ReplayQueryAdapter = class {
   // -------------------------------------------------------------------------
   async executeDivergences(request) {
     const start = Date.now();
-    const receipts = await this.loadAllReceipts();
+    const receipts = await this.backend.findReceipts();
     const divergences = [];
-    for (const receipt of receipts) {
+    for (const doc of receipts) {
+      const receipt = doc.payload;
       if (receipt.contentHash) {
         const recomputed = computeContentHashSafe(receipt);
         if (recomputed !== receipt.contentHash) {
@@ -994,9 +1176,9 @@ var ReplayQueryAdapter = class {
     }
     divergences.sort((a, b) => a.txId.localeCompare(b.txId));
     const paged = divergences.slice(request.offset, request.offset + request.limit);
-    let explain;
+    let why;
     if (request.explain) {
-      explain = paged.map((d) => explainDivergence(d));
+      why = paged.map((d) => explainDivergence(d));
     }
     return {
       domain: "replay",
@@ -1006,7 +1188,7 @@ var ReplayQueryAdapter = class {
       truncated: divergences.length > request.offset + request.limit,
       deterministic: true,
       queryHash: computeQueryHash(paged),
-      explain,
+      why,
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start,
@@ -1021,8 +1203,9 @@ var ReplayQueryAdapter = class {
     const start = Date.now();
     const txId = request.params["txId"];
     if (!txId) throw new Error("invariants requires params.txId");
-    const receipt = await this.loadReceipt(txId);
-    if (!receipt) throw new Error(`Receipt not found for txId: ${txId}`);
+    const doc = await this.backend.getArtifact(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;
     if (!planIntegrity) {
@@ -1065,9 +1248,9 @@ var ReplayQueryAdapter = class {
       utxoConservation,
       issues
     };
-    let explain;
+    let why;
     if (request.explain) {
-      explain = [explainInvariants(result)];
+      why = [explainInvariants(result)];
     }
     return {
       domain: "replay",
@@ -1077,7 +1260,7 @@ var ReplayQueryAdapter = class {
       truncated: false,
       deterministic: true,
       queryHash: computeQueryHash([result]),
-      explain,
+      why,
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start,
@@ -1085,43 +1268,9 @@ var ReplayQueryAdapter = class {
       }
     };
   }
-  // -------------------------------------------------------------------------
-  // Filesystem
-  // -------------------------------------------------------------------------
-  async loadAllReceipts() {
-    const dir = path3.join(this.rootDir, ".hardkas", "receipts");
-    return this.loadJsonDir(dir);
-  }
-  async loadAllTraces() {
-    const dir = path3.join(this.rootDir, ".hardkas", "traces");
-    return this.loadJsonDir(dir);
-  }
-  async loadReceipt(txId) {
-    const filePath = path3.join(this.rootDir, ".hardkas", "receipts", `${txId}.json`);
-    return this.readJsonSafe(filePath);
-  }
-  async loadTrace(txId) {
-    const filePath = path3.join(this.rootDir, ".hardkas", "traces", `${txId}.trace.json`);
-    return this.readJsonSafe(filePath);
-  }
-  async loadJsonDir(dir) {
-    const results = [];
-    let entries;
-    try {
-      entries = await fs3.readdir(dir);
-    } catch {
-      return results;
-    }
-    for (const file of entries.sort()) {
-      if (!file.endsWith(".json")) continue;
-      const raw = await this.readJsonSafe(path3.join(dir, file));
-      if (raw) results.push(raw);
-    }
-    return results;
-  }
   async readJsonSafe(filePath) {
     try {
-      const content = await fs3.readFile(filePath, "utf-8");
+      const content = await fs4.readFile(filePath, "utf-8");
       return JSON.parse(content);
     } catch {
       return null;
@@ -1164,43 +1313,55 @@ var DIVERGENCE_RULES = {
 };
 function explainDivergence(d) {
   return {
-    question: `Why is tx ${d.txId.slice(0, 16)}... flagged as divergent?`,
-    conclusion: `Divergence type: ${d.kind}. Field "${d.field}" expected ${d.expected.slice(0, 40)}${d.expected.length > 40 ? "..." : ""}, got ${d.actual.slice(0, 40)}${d.actual.length > 40 ? "..." : ""}.`,
-    steps: [
-      { order: 1, assertion: `Field "${d.field}" does not match expected value`, evidence: `expected: ${d.expected}, actual: ${d.actual}`, rule: DIVERGENCE_RULES[d.kind] },
-      { order: 2, assertion: `Classified as ${d.kind}`, evidence: `Divergence category based on field and semantic context`, rule: "Replay divergence classification (query/replay-adapter.ts)" }
+    question: `Why is tx ${d.txId.slice(0, 16)}... divergent?`,
+    answer: `Field "${d.field}" shows unexpected non-deterministic behavior (${d.kind}).`,
+    evidence: [{ type: "txId", value: d.txId }],
+    causalChain: [
+      {
+        order: 1,
+        assertion: `Value mismatch in "${d.field}"`,
+        evidence: `Expected: ${d.expected.slice(0, 40)}, Actual: ${d.actual.slice(0, 40)}`,
+        rule: DIVERGENCE_RULES[d.kind]
+      },
+      {
+        order: 2,
+        assertion: "Divergence detected in replay comparison",
+        evidence: "Verification engine mismatch",
+        rule: "Invariant validation policy"
+      }
     ],
-    model: "replay-invariants",
-    confidence: "definitive",
-    references: [d.txId]
+    model: "replay-analysis",
+    confidence: "definitive"
   };
 }
 function explainInvariants(result) {
-  const steps = [];
+  const causalChain = [];
   let order = 1;
-  steps.push({ order: order++, assertion: result.planIntegrity ? "Plan contentHash is stable" : "Plan contentHash MISMATCH", evidence: `planIntegrity=${result.planIntegrity}`, rule: "canonicalStringify + SHA-256 determinism" });
-  steps.push({ order: order++, assertion: result.receiptReproducible ? "Receipt has pre/post state hashes for comparison" : "Receipt missing state hashes \u2014 replay comparison not possible", evidence: `receiptReproducible=${result.receiptReproducible}`, rule: "preStateHash + postStateHash required for replay verification" });
-  steps.push({ order: order++, assertion: result.stateTransitionValid ? "State transition is consistent with status" : "State transition INCONSISTENT with status", evidence: `stateTransitionValid=${result.stateTransitionValid}`, rule: "Confirmed tx must change state. Failed tx must not." });
-  steps.push({ order: order++, assertion: result.utxoConservation ? "UTXO conservation holds" : "UTXO conservation VIOLATION", evidence: `utxoConservation=${result.utxoConservation}`, rule: "Confirmed tx must consume and produce UTXOs" });
+  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)}...?`,
-    conclusion: allOk ? "All replay invariants satisfied." : `Invariant violations: ${result.issues.join("; ")}`,
-    steps,
+    answer: allOk ? "All replay invariants satisfied." : `Violations found: ${result.issues.join("; ")}`,
+    evidence: [{ type: "txId", value: result.txId }],
+    causalChain,
     model: "replay-invariants",
-    confidence: "definitive",
-    references: [result.txId]
+    confidence: "definitive"
   };
 }
 
 // src/adapters/dag-adapter.ts
-import fs4 from "fs/promises";
+import fs5 from "fs/promises";
 import path4 from "path";
 var DagQueryAdapter = class {
   domain = "dag";
   rootDir;
-  constructor(rootDir) {
+  backend;
+  constructor(rootDir, backend) {
     this.rootDir = rootDir;
+    this.backend = backend;
   }
   supportedOps() {
     return ["conflicts", "displaced", "history", "sink-path", "anomalies"];
@@ -1240,9 +1401,9 @@ var DagQueryAdapter = class {
     }));
     items.sort((a, b) => a.outpoint.localeCompare(b.outpoint));
     const paged = items.slice(request.offset, request.offset + request.limit);
-    let explain;
+    let why;
     if (request.explain) {
-      explain = paged.map((c) => explainConflict(c, dag));
+      why = paged.map((c) => explainConflict(c, dag));
     }
     return {
       domain: "dag",
@@ -1252,7 +1413,7 @@ var DagQueryAdapter = class {
       truncated: items.length > request.offset + request.limit,
       deterministic: true,
       queryHash: computeQueryHash(paged),
-      explain,
+      why,
       annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
     };
   }
@@ -1276,9 +1437,9 @@ var DagQueryAdapter = class {
     });
     items.sort((a, b) => a.txId.localeCompare(b.txId));
     const paged = items.slice(request.offset, request.offset + request.limit);
-    let explain;
+    let why;
     if (request.explain) {
-      explain = paged.map((d) => explainDisplacement(d, dag));
+      why = paged.map((d) => explainDisplacement(d, dag));
     }
     return {
       domain: "dag",
@@ -1288,7 +1449,7 @@ var DagQueryAdapter = class {
       truncated: items.length > request.offset + request.limit,
       deterministic: true,
       queryHash: computeQueryHash(paged),
-      explain,
+      why,
       annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
     };
   }
@@ -1328,9 +1489,9 @@ var DagQueryAdapter = class {
       }
     }
     entries.sort((a, b) => a.daaScore.localeCompare(b.daaScore));
-    let explain;
+    let why;
     if (request.explain) {
-      explain = entries.map((e) => explainTxHistory(e, dag));
+      why = entries.map((e) => explainTxHistory(e, dag));
     }
     return {
       domain: "dag",
@@ -1340,7 +1501,7 @@ var DagQueryAdapter = class {
       truncated: false,
       deterministic: true,
       queryHash: computeQueryHash(entries),
-      explain,
+      why,
       annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
     };
   }
@@ -1428,9 +1589,9 @@ var DagQueryAdapter = class {
     }
     anomalies.sort((a, b) => a.kind.localeCompare(b.kind));
     const paged = anomalies.slice(request.offset, request.offset + request.limit);
-    let explain;
+    let why;
     if (request.explain) {
-      explain = paged.map((a) => explainAnomaly(a, dag));
+      why = paged.map((a) => explainAnomaly(a, dag));
     }
     return {
       domain: "dag",
@@ -1440,7 +1601,7 @@ var DagQueryAdapter = class {
       truncated: anomalies.length > request.offset + request.limit,
       deterministic: true,
       queryHash: computeQueryHash(paged),
-      explain,
+      why,
       annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
     };
   }
@@ -1450,7 +1611,7 @@ var DagQueryAdapter = class {
   async loadDag() {
     const statePath = path4.join(this.rootDir, ".hardkas", "state.json");
     try {
-      const content = await fs4.readFile(statePath, "utf-8");
+      const content = await fs5.readFile(statePath, "utf-8");
       const state = JSON.parse(content);
       return state.dag ?? null;
     } catch {
@@ -1471,7 +1632,7 @@ function emptyDagResult(op, start) {
   };
 }
 function explainConflict(conflict, dag) {
-  const steps = [];
+  const causalChain = [];
   let order = 1;
   let winnerBlockId;
   let winnerDaaScore = "0";
@@ -1484,92 +1645,87 @@ function explainConflict(conflict, dag) {
       break;
     }
   }
-  steps.push({
+  causalChain.push({
     order: order++,
-    assertion: `Outpoint ${conflict.outpoint} was spent by multiple transactions`,
+    assertion: `Outpoint ${conflict.outpoint} spent by multiple txs`,
     evidence: `Winner: ${conflict.winnerTxId}, Losers: ${conflict.loserTxIds.join(", ")}`,
-    rule: "UTXO double-spend detection (dag.ts:moveSink)"
+    rule: "UTXO double-spend detection"
   });
   if (winnerBlockId) {
-    steps.push({
-      order: order++,
-      assertion: `Winner tx is in block ${winnerBlockId} (daaScore: ${winnerDaaScore})`,
-      evidence: `Block ${winnerBlockId} contains tx ${conflict.winnerTxId}`,
-      rule: "Block tx membership"
-    });
-    steps.push({
+    causalChain.push({
       order: order++,
-      assertion: winnerInSinkPath ? `Block ${winnerBlockId} IS in the sink path \u2014 has priority` : `Block ${winnerBlockId} is NOT in the sink path`,
-      evidence: `selectedPathToSink.includes("${winnerBlockId}") = ${winnerInSinkPath}`,
-      rule: "Sink-ancestry priority (dag.ts:resolveConflictsDeterministically)"
+      assertion: `Winner in block ${winnerBlockId} (daaScore: ${winnerDaaScore})`,
+      evidence: `In sink path: ${winnerInSinkPath}`,
+      rule: "Sink-ancestry priority"
     });
   }
-  steps.push({
-    order: order++,
-    assertion: `Conflict resolved: ${conflict.winnerTxId.slice(0, 16)}... accepted, ${conflict.loserTxIds.length} tx(s) displaced`,
-    evidence: `Resolution based on: 1) sink-path priority, 2) daaScore ordering, 3) blockId tie-break`,
-    rule: "Deterministic conflict resolution (dag.ts:187-248)"
-  });
   return {
-    question: `Why did ${conflict.winnerTxId.slice(0, 16)}... win the conflict on outpoint ${conflict.outpoint}?`,
-    conclusion: `Winner has ${winnerInSinkPath ? "sink-path priority" : "block ordering priority"}. ${conflict.loserTxIds.length} tx(s) displaced. Model: deterministic-light-model (NOT GHOSTDAG).`,
-    steps,
+    question: `Why winner ${conflict.winnerTxId.slice(0, 8)} on outpoint ${conflict.outpoint}?`,
+    answer: `Winner has ${winnerInSinkPath ? "sink-path priority" : "block ordering priority"}.`,
+    evidence: [
+      { type: "txId", value: conflict.winnerTxId },
+      ...conflict.loserTxIds.map((id) => ({ type: "txId", value: id }))
+    ],
+    causalChain,
     model: "deterministic-light-model",
-    confidence: "definitive",
-    references: [conflict.winnerTxId, ...conflict.loserTxIds]
+    confidence: "definitive"
   };
 }
 function explainDisplacement(d, _dag) {
   return {
-    question: `Why was tx ${d.txId.slice(0, 16)}... displaced?`,
-    conclusion: `${d.reason}. Currently accepted: ${d.currentlyAccepted}. Model: deterministic-light-model (NOT GHOSTDAG).`,
-    steps: [
-      { order: 1, assertion: `Transaction ${d.txId.slice(0, 16)}... is in displacedTxIds`, evidence: `dag.displacedTxIds includes "${d.txId}"`, rule: "DAG sink movement (dag.ts:moveSink)" },
-      { order: 2, assertion: d.reason, evidence: d.reason, rule: "Conflict resolution or DAG reorganization" }
+    question: `Why displaced tx ${d.txId.slice(0, 8)}?`,
+    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: 2, assertion: "Status: displaced", evidence: d.reason }
     ],
     model: "deterministic-light-model",
-    confidence: "definitive",
-    references: [d.txId]
+    confidence: "definitive"
   };
 }
 function explainTxHistory(entry, _dag) {
   const status = entry.accepted ? "ACCEPTED" : entry.displaced ? "DISPLACED" : "UNKNOWN";
   return {
-    question: `What is the DAG lifecycle status of tx ${entry.txId.slice(0, 16)}...?`,
-    conclusion: `Status: ${status}. Block: ${entry.blockId} (daaScore: ${entry.daaScore}). In sink path: ${entry.inSinkPath}. Model: deterministic-light-model (NOT GHOSTDAG).`,
-    steps: [
-      { order: 1, assertion: `Transaction is in block ${entry.blockId}`, evidence: `block.acceptedTxIds includes "${entry.txId}"`, rule: "Block membership scan" },
-      { order: 2, assertion: `Block daaScore = ${entry.daaScore}`, evidence: `dag.blocks["${entry.blockId}"].daaScore = "${entry.daaScore}"` },
-      { order: 3, assertion: entry.inSinkPath ? "Block IS in selected path to sink" : "Block is NOT in selected path to sink", evidence: `selectedPathToSink.includes("${entry.blockId}") = ${entry.inSinkPath}`, rule: "Sink path computation (dag.ts:calculateSelectedPath)" },
-      { order: 4, assertion: `Current status: ${status}`, evidence: `accepted=${entry.accepted}, displaced=${entry.displaced}`, rule: "DAG accepted/displaced set membership" }
+    question: `Causal history of tx ${entry.txId.slice(0, 8)}?`,
+    answer: `Status is ${status} in block ${entry.blockId}.`,
+    evidence: [
+      { type: "txId", value: entry.txId },
+      { 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}")` }
     ],
     model: "deterministic-light-model",
-    confidence: "definitive",
-    references: [entry.txId]
+    confidence: "definitive"
   };
 }
 function explainAnomaly(a, _dag) {
+  const evidence = [];
+  if (a.txId) evidence.push({ type: "txId", value: a.txId });
+  if (a.blockId) evidence.push({ type: "blockId", value: a.blockId });
   return {
-    question: `Why is this a DAG anomaly?`,
-    conclusion: `${a.description}. Model: deterministic-light-model (NOT GHOSTDAG).`,
-    steps: [
-      { order: 1, assertion: a.description, evidence: `Anomaly kind: ${a.kind}`, rule: "DAG invariant check (query/dag-adapter.ts)" }
+    question: `Why anomaly: ${a.kind}?`,
+    answer: a.description,
+    evidence,
+    causalChain: [
+      { order: 1, assertion: a.description, evidence: `Anomaly: ${a.kind}`, rule: "DAG invariant check" }
     ],
     model: "deterministic-light-model",
-    confidence: "definitive",
-    references: [a.txId ?? a.blockId ?? ""]
+    confidence: "definitive"
   };
 }
 
 // src/adapters/events-adapter.ts
-import fs5 from "fs/promises";
 import path5 from "path";
-import { validateEventEnvelope } from "@hardkas/core";
 var EventsQueryAdapter = class {
   domain = "events";
   rootDir;
-  constructor(rootDir) {
+  backend;
+  constructor(rootDir, backend) {
     this.rootDir = rootDir;
+    this.backend = backend;
   }
   supportedOps() {
     return ["list", "summary"];
@@ -1588,7 +1744,7 @@ var EventsQueryAdapter = class {
   async executeList(request) {
     const start = Date.now();
     const events = await this.loadEvents();
-    const backendUsed = "filesystem";
+    const backendUsed = this.backend.kind();
     const eventsPath = path5.join(this.rootDir, ".hardkas", "events.jsonl");
     const filtered = [];
     const txFilter = request.params["tx"] || request.params["txId"];
@@ -1619,67 +1775,52 @@ var EventsQueryAdapter = class {
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start,
-        filesScanned: 1
+        filesScanned: backendUsed === "sqlite" ? 0 : 1
       },
-      ...request.explain ? {
-        explain: [{
-          question: "How were events loaded?",
-          conclusion: `Loaded ${events.length} events from ${backendUsed}. Applied ${effectiveFilters.length} filter(s). Returned ${paged.length}/${total} results sorted by timestamp+eventId.`,
-          steps: [
-            { order: 1, assertion: `Backend: ${backendUsed} (events.jsonl)`, evidence: eventsPath, rule: "Filesystem fallback" },
-            { order: 2, assertion: `Filters applied: ${effectiveFilters.length}`, evidence: effectiveFilters.map((f) => `${f.field} ${f.op} ${f.value}`).join(", ") || "none" },
-            { order: 3, assertion: `Ordering: timestamp ASC + eventId tiebreaker`, evidence: "Deterministic" }
-          ],
-          model: "events-query",
-          confidence: "definitive",
-          references: []
-        }]
-      } : {}
+      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() {
-    const eventsPath = path5.join(this.rootDir, ".hardkas", "events.jsonl");
-    let content;
-    try {
-      content = await fs5.readFile(eventsPath, "utf-8");
-    } catch {
-      return [];
-    }
-    const lines = content.split("\n").filter((l) => l.trim() !== "");
+    const docs = await this.backend.getEvents();
     const events = [];
-    for (const line of lines) {
-      try {
-        const parsed = JSON.parse(line);
-        if (!validateEventEnvelope(parsed)) continue;
-        events.push({
-          eventId: parsed.eventId,
-          kind: parsed.kind,
-          domain: parsed.domain,
-          timestamp: parsed.timestamp || "",
-          workflowId: parsed.workflowId,
-          correlationId: parsed.correlationId,
-          causationId: parsed.causationId,
-          txId: parsed.txId,
-          artifactId: parsed.artifactId,
-          networkId: parsed.networkId,
-          payload: parsed.payload
-        });
-      } catch {
-      }
+    for (const doc of docs) {
+      events.push({
+        eventId: doc.eventId,
+        kind: doc.kind,
+        domain: doc.domain,
+        timestamp: doc.timestamp || "",
+        workflowId: doc.workflowId,
+        correlationId: doc.correlationId,
+        causationId: doc.causationId || void 0,
+        txId: doc.txId || void 0,
+        artifactId: doc.artifactId || void 0,
+        networkId: doc.networkId,
+        payload: doc.payload
+      });
     }
     return events;
   }
 };
 
 // src/adapters/tx-adapter.ts
-import fs6 from "fs/promises";
-import path6 from "path";
-import { validateEventEnvelope as validateEventEnvelope2 } from "@hardkas/core";
 var TxQueryAdapter = class {
   domain = "tx";
   rootDir;
-  constructor(rootDir) {
+  backend;
+  constructor(rootDir, backend) {
     this.rootDir = rootDir;
+    this.backend = backend;
   }
   supportedOps() {
     return ["aggregate"];
@@ -1716,20 +1857,19 @@ var TxQueryAdapter = class {
       warnings,
       complete
     };
-    let explain;
+    let why;
     if (request.explain) {
-      explain = [{
-        question: `What data exists for transaction ${txId}?`,
-        conclusion: complete ? `Found ${artifacts.length} artifact(s) and ${events.length} event(s). Workflow appears complete.` : `Found ${artifacts.length} artifact(s) and ${events.length} event(s). ${warnings.join(". ")}.`,
-        steps: [
-          { order: 1, assertion: `Backend: filesystem`, evidence: path6.join(this.rootDir, ".hardkas"), rule: "Filesystem scan" },
-          { order: 2, assertion: `Artifacts found: ${artifacts.length}`, evidence: artifacts.map((a) => `${a.schema} (${a.role})`).join(", ") || "none" },
-          { order: 3, assertion: `Events found: ${events.length}`, evidence: events.map((e) => e.kind).join(", ") || "none" },
-          { order: 4, assertion: `Completeness: ${complete ? "yes" : "no"}`, evidence: warnings.join("; ") || "all artifacts present" }
+      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-aggregation",
-        confidence: "definitive",
-        references: [txId]
+        model: "tx-causality",
+        confidence: "definitive"
       }];
     }
     return {
@@ -1740,7 +1880,7 @@ var TxQueryAdapter = class {
       truncated: false,
       deterministic: true,
       queryHash: computeQueryHash([result]),
-      explain,
+      why,
       annotations: {
         executedAt: (/* @__PURE__ */ new Date()).toISOString(),
         executionMs: Date.now() - start
@@ -1748,92 +1888,96 @@ var TxQueryAdapter = class {
     };
   }
   async findArtifactsByTxId(txId) {
+    const docs = await this.backend.findArtifacts();
     const results = [];
-    const files = await this.scanJsonFiles();
-    for (const filePath of files) {
-      try {
-        const content = await fs6.readFile(filePath, "utf-8");
-        const parsed = JSON.parse(content);
-        if (!parsed.schema) continue;
-        const matchesTx = parsed.txId === txId || parsed.transaction?.id === txId || parsed.lineage?.artifactId && parsed.txId === txId;
-        if (!matchesTx) continue;
-        const schema = String(parsed.schema);
-        let role = "unknown";
-        if (schema.includes("txPlan")) role = "plan";
-        else if (schema.includes("signedTx")) role = "signed";
-        else if (schema.includes("txReceipt")) role = "receipt";
-        results.push({
-          filePath,
-          schema,
-          contentHash: parsed.contentHash,
-          role
-        });
-      } catch {
-      }
+    for (const doc of docs) {
+      const parsed = doc.payload;
+      const matchesTx = parsed.txId === txId || parsed.transaction?.id === txId || parsed.lineage?.artifactId === txId;
+      if (!matchesTx) continue;
+      const schema = String(doc.schema);
+      let role = "unknown";
+      if (schema.includes("txPlan")) role = "plan";
+      else if (schema.includes("signedTx")) role = "signed";
+      else if (schema.includes("txReceipt")) role = "receipt";
+      results.push({
+        filePath: doc.path,
+        schema,
+        contentHash: doc.contentHash,
+        role
+      });
     }
     return results.sort((a, b) => a.filePath.localeCompare(b.filePath));
   }
   async findEventsByTxId(txId) {
-    const eventsPath = path6.join(this.rootDir, ".hardkas", "events.jsonl");
-    let content;
-    try {
-      content = await fs6.readFile(eventsPath, "utf-8");
-    } catch {
-      return [];
-    }
-    const lines = content.split("\n").filter((l) => l.trim() !== "");
+    const docs = await this.backend.getEvents({ txId });
     const results = [];
-    for (const line of lines) {
-      try {
-        const parsed = JSON.parse(line);
-        if (!validateEventEnvelope2(parsed)) continue;
-        if (parsed.txId !== txId) continue;
-        results.push({
-          eventId: parsed.eventId,
-          kind: parsed.kind,
-          timestamp: parsed.timestamp || ""
-        });
-      } catch {
-      }
+    for (const doc of docs) {
+      results.push({
+        eventId: doc.eventId,
+        kind: doc.kind,
+        timestamp: doc.timestamp || ""
+      });
     }
     return results;
   }
-  async scanJsonFiles() {
-    const files = [];
-    const hardkasDir = path6.join(this.rootDir, ".hardkas");
-    await this.walkDir(hardkasDir, files);
-    return files.sort();
-  }
-  async walkDir(dir, out) {
-    let entries;
-    try {
-      entries = await fs6.readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const full = path6.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (entry.name === "node_modules" || entry.name === ".git") continue;
-        await this.walkDir(full, out);
-      } else if (entry.name.endsWith(".json") && !entry.name.endsWith(".enc.json") && entry.name !== "events.jsonl") {
-        out.push(full);
-      }
-    }
-  }
 };
 
 // src/engine.ts
-var QueryEngine = class {
+import { withLock } from "@hardkas/core";
+import fs6 from "fs";
+import path6 from "path";
+var QueryEngine = class _QueryEngine {
   adapters;
+  backend;
+  /**
+   * Primary entry point for creating a QueryEngine with auto-discovery.
+   */
+  static async create(options) {
+    let backend = options.backend;
+    if (!backend) {
+      const dbPath = path6.join(options.artifactDir, ".hardkas", "store.db");
+      if (fs6.existsSync(dbPath)) {
+        try {
+          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();
+            });
+          } else {
+            store.connect();
+          }
+          backend = new SqliteQueryBackend(store);
+        } catch (e) {
+          backend = new FilesystemQueryBackend(options.artifactDir);
+        }
+      } else {
+        backend = new FilesystemQueryBackend(options.artifactDir);
+      }
+    }
+    return new _QueryEngine({
+      artifactDir: options.artifactDir,
+      backend
+    });
+  }
   constructor(options) {
+    this.backend = options.backend || new FilesystemQueryBackend(options.artifactDir);
     this.adapters = /* @__PURE__ */ new Map();
-    this.adapters.set("artifacts", new ArtifactQueryAdapter(options.artifactDir));
-    this.adapters.set("lineage", new LineageQueryAdapter(options.artifactDir));
-    this.adapters.set("replay", new ReplayQueryAdapter(options.artifactDir));
-    this.adapters.set("dag", new DagQueryAdapter(options.artifactDir));
-    this.adapters.set("events", new EventsQueryAdapter(options.artifactDir));
-    this.adapters.set("tx", new TxQueryAdapter(options.artifactDir));
+    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("tx", new TxQueryAdapter(options.artifactDir, this.backend));
   }
   /**
    * Execute a query request against the appropriate adapter.
@@ -1848,7 +1992,31 @@ var QueryEngine = class {
         `Operation "${request.op}" is not supported by the "${request.domain}" adapter. Supported: ${adapter.supportedOps().join(", ")}`
       );
     }
-    return adapter.execute(request);
+    const result = await adapter.execute(request);
+    const freshness = await this.backend.getStoreStatus();
+    const backendUsed = this.backend.kind();
+    let explain = void 0;
+    if (request.explain) {
+      explain = {
+        backend: backendUsed,
+        executionPlan: ["Discovery", "Filter", "Sort", "Paginate"],
+        indexesUsed: backendUsed === "sqlite" ? ["PRIMARY", "idx_artifacts_schema"] : [],
+        filtersApplied: request.filters.map((f) => `${f.field} ${f.op} ${f.value}`),
+        rowsRead: result.items.length,
+        scannedFiles: result.annotations.filesScanned || 0,
+        freshness,
+        warnings: freshness === "stale" ? ["Index is STALE. mtime mismatch detected. Run 'hardkas query store rebuild'."] : []
+      };
+    }
+    return {
+      ...result,
+      explain,
+      annotations: {
+        ...result.annotations,
+        backendUsed,
+        freshness
+      }
+    };
   }
   /**
    * List available domains and their operations.
@@ -1886,14 +2054,15 @@ export {
   ReplayQueryAdapter,
   TxQueryAdapter,
   computeQueryHash,
+  createExplainBlock,
   createQueryRequest,
   evaluateFilter,
   evaluateFilters,
   explainIntegrity,
   explainOrphan,
   explainTransition,
-  formatExplainBrief,
-  formatExplainFull,
+  formatExplainBlock,
+  formatWhyBlock,
   resolveFieldPath,
   serializeQueryResult
 };