@hardkas/query 0.1.0

package/dist/index.js

@@ -0,0 +1,1899 @@
+// src/adapters/artifact-adapter.ts
+import fs from "fs/promises";
+import path from "path";
+import {
+  calculateContentHash,
+  verifyArtifactIntegrity,
+  verifyArtifactSemantics,
+  verifyFeeSemantics,
+  verifyLineage,
+  ARTIFACT_SCHEMAS
+} from "@hardkas/artifacts";
+
+// src/filter.ts
+function resolveFieldPath(obj, path7) {
+  if (obj === null || obj === void 0) return void 0;
+  const segments = path7.split(".");
+  let current = obj;
+  for (const seg of segments) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[seg];
+  }
+  return current;
+}
+function evaluateFilter(item, filter) {
+  const value = resolveFieldPath(item, filter.field);
+  return applyOp(value, filter.op, filter.value);
+}
+function evaluateFilters(item, filters) {
+  for (const f of filters) {
+    if (!evaluateFilter(item, f)) return false;
+  }
+  return true;
+}
+function applyOp(resolved, op, target) {
+  if (op === "eq") {
+    if (resolved === target) return true;
+    if (typeof resolved === "bigint" && typeof target === "string") {
+      try {
+        return resolved === BigInt(target);
+      } catch {
+        return false;
+      }
+    }
+    return false;
+  }
+  if (op === "neq") {
+    return !applyOp(resolved, "eq", target);
+  }
+  if (op === "exists") {
+    return resolved !== void 0 && resolved !== null;
+  }
+  if (op === "gt" || op === "lt" || op === "gte" || op === "lte") {
+    const rNum = toNumber(resolved);
+    const tNum = toNumber(target);
+    if (rNum === null || tNum === null) return false;
+    switch (op) {
+      case "gt":
+        return rNum > tNum;
+      case "lt":
+        return rNum < tNum;
+      case "gte":
+        return rNum >= tNum;
+      case "lte":
+        return rNum <= tNum;
+    }
+  }
+  if (op === "in") {
+    if (!Array.isArray(target)) return false;
+    return target.some((t) => applyOp(resolved, "eq", t));
+  }
+  if (op === "contains") {
+    if (typeof resolved !== "string") return false;
+    return resolved.includes(String(target));
+  }
+  return false;
+}
+function toNumber(v) {
+  if (typeof v === "number" && !Number.isNaN(v)) return v;
+  if (typeof v === "bigint") return v;
+  if (typeof v === "string") {
+    try {
+      if (v.includes(".")) return parseFloat(v);
+      return BigInt(v);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+// src/serialize.ts
+import { createHash } from "crypto";
+import { canonicalStringify } from "@hardkas/artifacts";
+function computeQueryHash(items) {
+  const canonical = canonicalStringify(items);
+  return createHash("sha256").update(canonical).digest("hex");
+}
+function serializeQueryResult(result) {
+  const output = {
+    annotations: result.annotations,
+    deterministic: result.deterministic,
+    domain: result.domain,
+    items: result.items,
+    op: result.op,
+    queryHash: result.queryHash,
+    total: result.total,
+    truncated: result.truncated
+  };
+  if (result.explain) {
+    output["explain"] = result.explain;
+  }
+  return JSON.stringify(output, bigIntReplacer, 2);
+}
+function bigIntReplacer(_key, value) {
+  return typeof value === "bigint" ? value.toString() : value;
+}
+
+// src/explain.ts
+var VALID_TRANSITIONS = {
+  "hardkas.snapshot": ["hardkas.txPlan"],
+  "hardkas.txPlan": ["hardkas.signedTx"],
+  "hardkas.signedTx": ["hardkas.txReceipt"]
+};
+function explainIntegrity(artifact, integrity) {
+  const steps = [];
+  let order = 1;
+  steps.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({
+      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}"`,
+      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({
+        order: order++,
+        assertion: `Integrity issue: ${err}`,
+        evidence: err,
+        rule: "verifyArtifactIntegrity (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] : []
+  };
+}
+function explainTransition(transition) {
+  const steps = [];
+  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({
+    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)"
+  });
+  const networkMatch = transition.from.networkId === transition.to.networkId;
+  steps.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)"
+  });
+  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]
+  };
+}
+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: [
+      {
+        order: 1,
+        assertion: `Artifact declares parentArtifactId = "${missingParentId}"`,
+        evidence: `artifact.lineage.parentArtifactId = "${missingParentId}"`,
+        rule: "Lineage parent resolution"
+      },
+      {
+        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"
+      }
+    ],
+    model: "lineage-rules",
+    confidence: "definitive",
+    references: [node.contentHash, missingParentId]
+  };
+}
+function formatExplainBrief(chain) {
+  return `${chain.conclusion} [model: ${chain.model}, confidence: ${chain.confidence}]`;
+}
+function formatExplainFull(chain) {
+  const lines = [];
+  lines.push(`Q: ${chain.question}`);
+  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}`);
+    }
+  }
+  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(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+// src/adapters/artifact-adapter.ts
+var KNOWN_SCHEMAS = new Set(Object.values(ARTIFACT_SCHEMAS));
+var ArtifactQueryAdapter = class {
+  domain = "artifacts";
+  rootDir;
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  supportedOps() {
+    return ["list", "inspect", "diff", "verify"];
+  }
+  supportedFilters() {
+    return ["schema", "version", "networkId", "mode", "from.address", "to.address", "amountSompi", "status", "contentHash", "createdAt"];
+  }
+  async execute(request) {
+    switch (request.op) {
+      case "list":
+        return this.executeList(request);
+      case "inspect":
+        return this.executeInspect(request);
+      case "diff":
+        return this.executeDiff(request);
+      case "verify":
+        return this.executeVerify(request);
+      default:
+        throw new Error(`Unknown artifact op: ${request.op}`);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // List — scan, filter, sort, paginate
+  // -------------------------------------------------------------------------
+  async executeList(request) {
+    const start = Date.now();
+    const files = await this.scanArtifactFiles();
+    const items = [];
+    for (const filePath of files) {
+      const raw = await this.readJsonSafe(filePath);
+      if (!raw || !raw.schema) continue;
+      const item = toArtifactQueryItem(raw, filePath);
+      if (evaluateFilters(item, request.filters)) {
+        items.push(item);
+      }
+    }
+    const sorted = this.sortItems(items, request.sort);
+    const total = sorted.length;
+    const paged = sorted.slice(request.offset, request.offset + request.limit);
+    let explain;
+    if (request.explain) {
+      explain = paged.map((item) => explainIntegrity(item, {
+        ok: true,
+        hashMatch: true,
+        schemaValid: KNOWN_SCHEMAS.has(item.schema),
+        errors: []
+      }));
+    }
+    return {
+      domain: "artifacts",
+      op: "list",
+      items: paged,
+      total,
+      truncated: total > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      explain,
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: files.length
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Inspect — deep structural analysis
+  // -------------------------------------------------------------------------
+  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)");
+    const filePath = await this.resolveTarget(target);
+    const raw = await this.readJsonSafe(filePath);
+    if (!raw) throw new Error(`Cannot read artifact at: ${filePath}`);
+    const item = toArtifactQueryItem(raw, filePath);
+    const integrityResult = await verifyArtifactIntegrity(raw);
+    const semanticResult = verifyArtifactSemantics(raw, { strict: true });
+    const hashMatch = raw.contentHash ? calculateContentHash(raw) === raw.contentHash : true;
+    let economics;
+    const artifactType = item.schema.split(".")[1];
+    if (artifactType === "txPlan" || artifactType === "signedTx" || artifactType === "txReceipt") {
+      const feeAudit = verifyFeeSemantics(raw);
+      economics = {
+        ok: feeAudit.ok,
+        massReported: feeAudit.actualMass.toString(),
+        massRecomputed: feeAudit.expectedMass.toString(),
+        feeReported: feeAudit.actualFeeSompi.toString(),
+        feeRecomputed: feeAudit.expectedFeeSompi.toString(),
+        feeRate: feeAudit.feeRateSompiPerMass.toString()
+      };
+    }
+    const ageHours = item.createdAt ? (Date.now() - new Date(item.createdAt).getTime()) / (1e3 * 60 * 60) : 0;
+    const staleness = {
+      ageHours: Math.round(ageHours * 100) / 100,
+      stale: ageHours > 24,
+      classification: classifyStaleness(ageHours)
+    };
+    const lineageResult = verifyLineage(raw);
+    const lineageStatus = !raw.lineage ? "missing" : lineageResult.ok ? "valid" : "orphan";
+    const inspectResult = {
+      item,
+      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)]
+      },
+      economics,
+      staleness,
+      lineageStatus
+    };
+    let explain;
+    if (request.explain) {
+      explain = [explainIntegrity(item, inspectResult.integrity)];
+    }
+    return {
+      domain: "artifacts",
+      op: "inspect",
+      items: [inspectResult],
+      total: 1,
+      truncated: false,
+      deterministic: true,
+      queryHash: computeQueryHash([inspectResult]),
+      explain,
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: 1
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Diff — semantic field-by-field comparison
+  // -------------------------------------------------------------------------
+  async executeDiff(request) {
+    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");
+    const leftRaw = await this.readJsonSafe(leftPath);
+    const rightRaw = await this.readJsonSafe(rightPath);
+    if (!leftRaw) throw new Error(`Cannot read left artifact: ${leftPath}`);
+    if (!rightRaw) throw new Error(`Cannot read right artifact: ${rightPath}`);
+    const entries = [];
+    const allKeys = /* @__PURE__ */ new Set([...Object.keys(leftRaw), ...Object.keys(rightRaw)]);
+    const excluded = /* @__PURE__ */ new Set(["contentHash", "artifactId", "lineage"]);
+    for (const key of [...allKeys].sort()) {
+      if (excluded.has(key)) continue;
+      const leftVal = leftRaw[key];
+      const rightVal = rightRaw[key];
+      const leftStr = leftVal !== void 0 ? JSON.stringify(leftVal) : void 0;
+      const rightStr = rightVal !== void 0 ? JSON.stringify(rightVal) : void 0;
+      if (leftStr === rightStr) continue;
+      let kind;
+      if (leftStr === void 0) kind = "added";
+      else if (rightStr === void 0) kind = "removed";
+      else if (typeof leftVal !== typeof rightVal) kind = "type-change";
+      else kind = "value-change";
+      entries.push({ field: key, left: leftStr, right: rightStr, kind });
+    }
+    const result = {
+      leftPath,
+      rightPath,
+      leftSchema: leftRaw.schema || "unknown",
+      rightSchema: rightRaw.schema || "unknown",
+      identical: entries.length === 0,
+      entries
+    };
+    return {
+      domain: "artifacts",
+      op: "diff",
+      items: [result],
+      total: 1,
+      truncated: false,
+      deterministic: true,
+      queryHash: computeQueryHash([result]),
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: 2
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Verify — deep verification with optional explain
+  // -------------------------------------------------------------------------
+  async executeVerify(request) {
+    return this.executeInspect(request);
+  }
+  // -------------------------------------------------------------------------
+  // Helpers
+  // -------------------------------------------------------------------------
+  async scanArtifactFiles() {
+    const files = [];
+    await this.walkDir(this.rootDir, files);
+    return files.sort();
+  }
+  async walkDir(dir, out) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        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);
+      }
+    }
+  }
+  async readJsonSafe(filePath) {
+    try {
+      const content = await fs.readFile(filePath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+  async resolveTarget(target) {
+    if (target.includes("/") || target.includes("\\") || target.endsWith(".json")) {
+      return path.resolve(target);
+    }
+    const files = await this.scanArtifactFiles();
+    for (const f of files) {
+      const raw = await this.readJsonSafe(f);
+      if (raw?.contentHash === target) return f;
+      if (raw?.lineage?.artifactId === target) return f;
+    }
+    throw new Error(`No artifact found with hash or ID: ${target}`);
+  }
+  sortItems(items, sort) {
+    const sorted = [...items];
+    if (sort) {
+      sorted.sort((a, b) => {
+        const aVal = String(a[sort.field] ?? "");
+        const bVal = String(b[sort.field] ?? "");
+        const cmp = aVal.localeCompare(bVal);
+        return sort.direction === "desc" ? -cmp : cmp;
+      });
+    } else {
+      sorted.sort((a, b) => {
+        const cmp = b.createdAt.localeCompare(a.createdAt);
+        return cmp !== 0 ? cmp : a.schema.localeCompare(b.schema);
+      });
+    }
+    return sorted;
+  }
+};
+function toArtifactQueryItem(raw, filePath) {
+  return {
+    filePath,
+    schema: raw.schema || "unknown",
+    version: raw.version || "unknown",
+    networkId: raw.networkId || "unknown",
+    mode: raw.mode || "unknown",
+    createdAt: raw.createdAt || "",
+    contentHash: raw.contentHash,
+    from: raw.from,
+    to: raw.to,
+    amountSompi: raw.amountSompi,
+    status: raw.status,
+    lineage: raw.lineage ? {
+      artifactId: raw.lineage.artifactId,
+      parentArtifactId: raw.lineage.parentArtifactId,
+      rootArtifactId: raw.lineage.rootArtifactId,
+      lineageId: raw.lineage.lineageId,
+      sequence: raw.lineage.sequence
+    } : void 0
+  };
+}
+function classifyStaleness(hours) {
+  if (hours < 1) return "fresh";
+  if (hours < 24) return "aging";
+  if (hours < 168) return "stale";
+  return "expired";
+}
+
+// src/adapters/lineage-adapter.ts
+import fs2 from "fs/promises";
+import path2 from "path";
+var VALID_TRANSITIONS2 = {
+  "hardkas.snapshot": ["hardkas.txPlan"],
+  "hardkas.txPlan": ["hardkas.signedTx"],
+  "hardkas.signedTx": ["hardkas.txReceipt"]
+};
+var LineageQueryAdapter = class {
+  domain = "lineage";
+  rootDir;
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  supportedOps() {
+    return ["chain", "transitions", "orphans"];
+  }
+  supportedFilters() {
+    return ["schema", "networkId", "mode", "rootArtifactId", "lineageId"];
+  }
+  async execute(request) {
+    switch (request.op) {
+      case "chain":
+        return this.executeChain(request);
+      case "transitions":
+        return this.executeTransitions(request);
+      case "orphans":
+        return this.executeOrphans(request);
+      default:
+        throw new Error(`Unknown lineage op: ${request.op}`);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Chain — walk ancestors or descendants from an anchor
+  // -------------------------------------------------------------------------
+  async executeChain(request) {
+    const start = Date.now();
+    const anchor = request.params["anchor"];
+    if (!anchor) throw new Error("chain requires params.anchor (contentHash or artifactId)");
+    const direction = request.params["direction"] ?? "ancestors";
+    const graph = await this.buildGraph();
+    const anchorNode = graph.byArtifactId.get(anchor) ?? graph.byContentHash.get(anchor);
+    if (!anchorNode) throw new Error(`Anchor not found: ${anchor}`);
+    const nodes = [];
+    const transitions = [];
+    if (direction === "ancestors") {
+      this.walkAncestors(anchorNode, graph, nodes, transitions);
+    } else {
+      this.walkDescendants(anchorNode, graph, nodes, transitions);
+    }
+    const complete = direction === "ancestors" ? nodes.length > 0 && !nodes[0].parentArtifactId : true;
+    const result = {
+      anchor,
+      direction,
+      nodes,
+      transitions,
+      complete
+    };
+    let explain;
+    if (request.explain) {
+      explain = transitions.map((t) => explainTransition(t));
+    }
+    return {
+      domain: "lineage",
+      op: "chain",
+      items: [result],
+      total: 1,
+      truncated: false,
+      deterministic: true,
+      queryHash: computeQueryHash([result]),
+      explain,
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: graph.totalFiles
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Transitions — list all edges in a lineage tree
+  // -------------------------------------------------------------------------
+  async executeTransitions(request) {
+    const start = Date.now();
+    const graph = await this.buildGraph();
+    const rootId = request.params["root"];
+    const transitions = [];
+    for (const node of graph.nodes) {
+      if (!node.parentArtifactId) continue;
+      if (rootId && node.rootArtifactId !== rootId) continue;
+      const parent = graph.byArtifactId.get(node.parentArtifactId);
+      if (!parent) continue;
+      const allowed = VALID_TRANSITIONS2[parent.schema] ?? [];
+      const valid = allowed.includes(node.schema);
+      transitions.push({
+        from: parent,
+        to: node,
+        valid,
+        rule: valid ? `${parent.schema} \u2192 ${node.schema} (valid)` : `${parent.schema} \u2192 ${node.schema} (INVALID \u2014 allowed: ${allowed.join(", ") || "none"})`
+      });
+    }
+    transitions.sort((a, b) => {
+      const seqA = a.from.sequence ?? 0;
+      const seqB = b.from.sequence ?? 0;
+      if (seqA !== seqB) return seqA - seqB;
+      return a.from.contentHash.localeCompare(b.from.contentHash);
+    });
+    const paged = transitions.slice(request.offset, request.offset + request.limit);
+    let explain;
+    if (request.explain) {
+      explain = paged.map((t) => explainTransition(t));
+    }
+    return {
+      domain: "lineage",
+      op: "transitions",
+      items: paged,
+      total: transitions.length,
+      truncated: transitions.length > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      explain,
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: graph.totalFiles
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Orphans — artifacts with broken parent references
+  // -------------------------------------------------------------------------
+  async executeOrphans(request) {
+    const start = Date.now();
+    const graph = await this.buildGraph();
+    const orphans = [];
+    for (const node of graph.nodes) {
+      if (!node.parentArtifactId) continue;
+      const parent = graph.byArtifactId.get(node.parentArtifactId);
+      if (!parent) {
+        orphans.push({
+          node,
+          missingParentId: node.parentArtifactId,
+          reason: `Parent artifactId "${node.parentArtifactId}" not found in artifact store`
+        });
+      }
+    }
+    orphans.sort((a, b) => a.node.contentHash.localeCompare(b.node.contentHash));
+    const paged = orphans.slice(request.offset, request.offset + request.limit);
+    let explain;
+    if (request.explain) {
+      explain = paged.map((o) => explainOrphan(o.node, o.missingParentId));
+    }
+    return {
+      domain: "lineage",
+      op: "orphans",
+      items: paged,
+      total: orphans.length,
+      truncated: orphans.length > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      explain,
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: graph.totalFiles
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Graph Construction
+  // -------------------------------------------------------------------------
+  async buildGraph() {
+    const nodes = [];
+    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);
+      if (!raw?.schema || !raw.lineage) continue;
+      const node = {
+        contentHash: raw.contentHash || "",
+        schema: raw.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 || ""
+      };
+      nodes.push(node);
+      if (node.artifactId) byArtifactId.set(node.artifactId, 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);
+      }
+    }
+    return { nodes, byArtifactId, byContentHash, children, totalFiles: files.length };
+  }
+  // -------------------------------------------------------------------------
+  // Graph Traversal
+  // -------------------------------------------------------------------------
+  walkAncestors(node, graph, nodes, transitions) {
+    const chain = [node];
+    let current = 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;
+    }
+    nodes.push(...chain);
+  }
+  walkDescendants(node, graph, nodes, transitions) {
+    const queue = [node];
+    const visited = /* @__PURE__ */ new Set();
+    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) ?? [];
+      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)`
+        });
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Filesystem
+  // -------------------------------------------------------------------------
+  async scanJsonFiles() {
+    const files = [];
+    await this.walkDir(this.rootDir, files);
+    return files.sort();
+  }
+  async walkDir(dir, out) {
+    let entries;
+    try {
+      entries = await fs2.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    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;
+        await this.walkDir(full, out);
+      } else if (entry.name.endsWith(".json") && !entry.name.endsWith(".enc.json")) {
+        out.push(full);
+      }
+    }
+  }
+  async readJsonSafe(filePath) {
+    try {
+      const content = await fs2.readFile(filePath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/adapters/replay-adapter.ts
+import fs3 from "fs/promises";
+import path3 from "path";
+import { calculateContentHash as calculateContentHash2 } from "@hardkas/artifacts";
+var ReplayQueryAdapter = class {
+  domain = "replay";
+  rootDir;
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  supportedOps() {
+    return ["list", "summary", "divergences", "invariants"];
+  }
+  supportedFilters() {
+    return ["txId", "status", "networkId", "mode", "daaScore", "from.address", "to.address"];
+  }
+  async execute(request) {
+    switch (request.op) {
+      case "list":
+        return this.executeList(request);
+      case "summary":
+        return this.executeSummary(request);
+      case "divergences":
+        return this.executeDivergences(request);
+      case "invariants":
+        return this.executeInvariants(request);
+      default:
+        throw new Error(`Unknown replay op: ${request.op}`);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // List — enumerate all stored receipts
+  // -------------------------------------------------------------------------
+  async executeList(request) {
+    const start = Date.now();
+    const receipts = await this.loadAllReceipts();
+    const traces = await this.loadAllTraces();
+    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);
+      if (evaluateFilters(item, request.filters)) {
+        items.push(item);
+      }
+    }
+    items.sort((a, b) => {
+      const cmp = b.daaScore.localeCompare(a.daaScore);
+      return cmp !== 0 ? cmp : a.txId.localeCompare(b.txId);
+    });
+    const total = items.length;
+    const paged = items.slice(request.offset, request.offset + request.limit);
+    return {
+      domain: "replay",
+      op: "list",
+      items: paged,
+      total,
+      truncated: total > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: receipts.length + traces.length
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Summary — detailed summary for a specific txId
+  // -------------------------------------------------------------------------
+  async executeSummary(request) {
+    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);
+    return {
+      domain: "replay",
+      op: "summary",
+      items: [item],
+      total: 1,
+      truncated: false,
+      deterministic: true,
+      queryHash: computeQueryHash([item]),
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: trace ? 2 : 1
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Divergences — detect receipts that show signs of non-determinism
+  // -------------------------------------------------------------------------
+  async executeDivergences(request) {
+    const start = Date.now();
+    const receipts = await this.loadAllReceipts();
+    const divergences = [];
+    for (const receipt of receipts) {
+      if (receipt.contentHash) {
+        const recomputed = computeContentHashSafe(receipt);
+        if (recomputed !== receipt.contentHash) {
+          divergences.push({
+            txId: receipt.txId,
+            kind: "state-hash-mismatch",
+            field: "contentHash",
+            expected: receipt.contentHash,
+            actual: recomputed
+          });
+        }
+      }
+      if (receipt.preStateHash && receipt.postStateHash && receipt.preStateHash === receipt.postStateHash && receipt.status === "confirmed") {
+        divergences.push({
+          txId: receipt.txId,
+          kind: "state-hash-mismatch",
+          field: "stateTransition",
+          expected: "preStateHash !== postStateHash for confirmed tx",
+          actual: `both are ${receipt.preStateHash}`
+        });
+      }
+      if (receipt.mass && receipt.feeSompi) {
+        const mass = BigInt(receipt.mass);
+        const fee = BigInt(receipt.feeSompi);
+        if (mass > 0n && fee > 0n && fee > mass * 10n) {
+          divergences.push({
+            txId: receipt.txId,
+            kind: "fee-mismatch",
+            field: "feeSompi",
+            expected: `fee proportional to mass (mass=${mass})`,
+            actual: `fee=${fee} (ratio=${fee / mass})`
+          });
+        }
+      }
+      const spentCount = receipt.spentUtxoIds?.length ?? 0;
+      const createdCount = receipt.createdUtxoIds?.length ?? 0;
+      if (receipt.status === "confirmed" && spentCount === 0) {
+        divergences.push({
+          txId: receipt.txId,
+          kind: "utxo-count-mismatch",
+          field: "spentUtxoIds",
+          expected: "at least 1 spent UTXO for confirmed tx",
+          actual: `${spentCount} spent`
+        });
+      }
+      if (receipt.status === "failed" && receipt.postStateHash && receipt.postStateHash !== receipt.preStateHash) {
+        divergences.push({
+          txId: receipt.txId,
+          kind: "status-mismatch",
+          field: "status",
+          expected: "failed tx should not change state",
+          actual: `state changed: ${receipt.preStateHash} \u2192 ${receipt.postStateHash}`
+        });
+      }
+    }
+    divergences.sort((a, b) => a.txId.localeCompare(b.txId));
+    const paged = divergences.slice(request.offset, request.offset + request.limit);
+    let explain;
+    if (request.explain) {
+      explain = paged.map((d) => explainDivergence(d));
+    }
+    return {
+      domain: "replay",
+      op: "divergences",
+      items: paged,
+      total: divergences.length,
+      truncated: divergences.length > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      explain,
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: receipts.length
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Invariants — check replay invariants for a specific txId
+  // -------------------------------------------------------------------------
+  async executeInvariants(request) {
+    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 issues = [];
+    const planIntegrity = receipt.contentHash ? computeContentHashSafe(receipt) === receipt.contentHash : true;
+    if (!planIntegrity) {
+      issues.push("Receipt contentHash does not match recomputed hash");
+    }
+    const receiptReproducible = !!(receipt.preStateHash && receipt.postStateHash);
+    if (!receiptReproducible) {
+      issues.push("Missing pre/post state hashes \u2014 replay comparison not possible");
+    }
+    let stateTransitionValid = true;
+    if (receipt.status === "confirmed") {
+      if (receipt.preStateHash === receipt.postStateHash) {
+        stateTransitionValid = false;
+        issues.push("Confirmed tx did not change state (pre === post)");
+      }
+    } else if (receipt.status === "failed") {
+      if (receipt.preStateHash && receipt.postStateHash && receipt.preStateHash !== receipt.postStateHash) {
+        stateTransitionValid = false;
+        issues.push("Failed tx changed state (pre !== post)");
+      }
+    }
+    const spentCount = receipt.spentUtxoIds?.length ?? 0;
+    const createdCount = receipt.createdUtxoIds?.length ?? 0;
+    let utxoConservation = true;
+    if (receipt.status === "confirmed") {
+      if (spentCount === 0) {
+        utxoConservation = false;
+        issues.push("Confirmed tx spent 0 UTXOs");
+      }
+      if (createdCount === 0) {
+        utxoConservation = false;
+        issues.push("Confirmed tx created 0 UTXOs");
+      }
+    }
+    const result = {
+      txId,
+      planIntegrity,
+      receiptReproducible,
+      stateTransitionValid,
+      utxoConservation,
+      issues
+    };
+    let explain;
+    if (request.explain) {
+      explain = [explainInvariants(result)];
+    }
+    return {
+      domain: "replay",
+      op: "invariants",
+      items: [result],
+      total: 1,
+      truncated: false,
+      deterministic: true,
+      queryHash: computeQueryHash([result]),
+      explain,
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: 1
+      }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // 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");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+};
+function toSummary(receipt, trace) {
+  return {
+    txId: receipt.txId || "unknown",
+    status: receipt.status || "unknown",
+    mode: receipt.mode || "unknown",
+    networkId: receipt.networkId || "unknown",
+    from: receipt.from?.address || "unknown",
+    to: receipt.to?.address || "unknown",
+    amountSompi: receipt.amountSompi || "0",
+    feeSompi: receipt.feeSompi || "0",
+    daaScore: receipt.daaScore || "0",
+    preStateHash: receipt.preStateHash,
+    postStateHash: receipt.postStateHash,
+    spentUtxoCount: receipt.spentUtxoIds?.length ?? 0,
+    createdUtxoCount: receipt.createdUtxoIds?.length ?? 0,
+    hasTrace: !!trace,
+    traceEventCount: trace?.events?.length ?? 0
+  };
+}
+function computeContentHashSafe(obj) {
+  try {
+    return calculateContentHash2(obj);
+  } catch {
+    return "error-computing-hash";
+  }
+}
+var DIVERGENCE_RULES = {
+  "state-hash-mismatch": "Deterministic replay invariant: identical plan + identical state = identical postStateHash",
+  "fee-mismatch": "Fee must be proportional to estimated mass. Disproportionate fees indicate estimation drift.",
+  "utxo-count-mismatch": "Confirmed transactions must spend at least 1 UTXO (inputs) and create at least 1 (outputs).",
+  "status-mismatch": "Failed transactions must not modify state. Confirmed transactions must modify state.",
+  "txid-mismatch": "Deterministic txId generation: same plan + same state + same daaScore = same txId.",
+  "ordering-divergence": "UTXO selection order must be deterministic. Non-deterministic ordering breaks replay invariants."
+};
+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)" }
+    ],
+    model: "replay-invariants",
+    confidence: "definitive",
+    references: [d.txId]
+  };
+}
+function explainInvariants(result) {
+  const steps = [];
+  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" });
+  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,
+    model: "replay-invariants",
+    confidence: "definitive",
+    references: [result.txId]
+  };
+}
+
+// src/adapters/dag-adapter.ts
+import fs4 from "fs/promises";
+import path4 from "path";
+var DagQueryAdapter = class {
+  domain = "dag";
+  rootDir;
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  supportedOps() {
+    return ["conflicts", "displaced", "history", "sink-path", "anomalies"];
+  }
+  supportedFilters() {
+    return ["txId", "blockId", "daaScore"];
+  }
+  async execute(request) {
+    switch (request.op) {
+      case "conflicts":
+        return this.executeConflicts(request);
+      case "displaced":
+        return this.executeDisplaced(request);
+      case "history":
+        return this.executeHistory(request);
+      case "sink-path":
+        return this.executeSinkPath(request);
+      case "anomalies":
+        return this.executeAnomalies(request);
+      default:
+        throw new Error(`Unknown dag op: ${request.op}`);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Conflicts — double-spend conflict analysis
+  // -------------------------------------------------------------------------
+  async executeConflicts(request) {
+    const start = Date.now();
+    const dag = await this.loadDag();
+    if (!dag) {
+      return emptyDagResult("conflicts", start);
+    }
+    const items = dag.conflictSet.map((c) => ({
+      outpoint: c.outpoint,
+      winnerTxId: c.winnerTxId,
+      loserTxIds: c.loserTxIds
+    }));
+    items.sort((a, b) => a.outpoint.localeCompare(b.outpoint));
+    const paged = items.slice(request.offset, request.offset + request.limit);
+    let explain;
+    if (request.explain) {
+      explain = paged.map((c) => explainConflict(c, dag));
+    }
+    return {
+      domain: "dag",
+      op: "conflicts",
+      items: paged,
+      total: items.length,
+      truncated: items.length > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      explain,
+      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Displaced — transactions that were accepted then displaced
+  // -------------------------------------------------------------------------
+  async executeDisplaced(request) {
+    const start = Date.now();
+    const dag = await this.loadDag();
+    if (!dag) {
+      return emptyDagResult("displaced", start);
+    }
+    const items = dag.displacedTxIds.map((txId) => {
+      const conflict = dag.conflictSet.find((c) => c.loserTxIds.includes(txId));
+      const reason = conflict ? `Double-spend on outpoint ${conflict.outpoint}. Winner: ${conflict.winnerTxId}` : "Displaced by DAG reorganization";
+      return {
+        txId,
+        reason,
+        currentlyAccepted: dag.acceptedTxIds.includes(txId)
+      };
+    });
+    items.sort((a, b) => a.txId.localeCompare(b.txId));
+    const paged = items.slice(request.offset, request.offset + request.limit);
+    let explain;
+    if (request.explain) {
+      explain = paged.map((d) => explainDisplacement(d, dag));
+    }
+    return {
+      domain: "dag",
+      op: "displaced",
+      items: paged,
+      total: items.length,
+      truncated: items.length > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      explain,
+      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // History — full lifecycle of a tx through the DAG
+  // -------------------------------------------------------------------------
+  async executeHistory(request) {
+    const start = Date.now();
+    const txId = request.params["txId"];
+    if (!txId) throw new Error("history requires params.txId");
+    const dag = await this.loadDag();
+    if (!dag) throw new Error("No DAG state found. Run a simulation first.");
+    const entries = [];
+    for (const [blockId, block] of Object.entries(dag.blocks)) {
+      if (!block) continue;
+      if (block.acceptedTxIds.includes(txId)) {
+        entries.push({
+          txId,
+          blockId,
+          accepted: dag.acceptedTxIds.includes(txId),
+          displaced: dag.displacedTxIds.includes(txId),
+          inSinkPath: dag.selectedPathToSink.includes(blockId),
+          daaScore: block.daaScore
+        });
+      }
+    }
+    if (entries.length === 0) {
+      if (dag.displacedTxIds.includes(txId)) {
+        entries.push({
+          txId,
+          blockId: "unknown",
+          accepted: false,
+          displaced: true,
+          inSinkPath: false,
+          daaScore: "0"
+        });
+      }
+    }
+    entries.sort((a, b) => a.daaScore.localeCompare(b.daaScore));
+    let explain;
+    if (request.explain) {
+      explain = entries.map((e) => explainTxHistory(e, dag));
+    }
+    return {
+      domain: "dag",
+      op: "history",
+      items: entries,
+      total: entries.length,
+      truncated: false,
+      deterministic: true,
+      queryHash: computeQueryHash(entries),
+      explain,
+      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Sink Path — current selected path from genesis to sink
+  // -------------------------------------------------------------------------
+  async executeSinkPath(request) {
+    const start = Date.now();
+    const dag = await this.loadDag();
+    if (!dag) {
+      return emptyDagResult("sink-path", start);
+    }
+    const nodes = dag.selectedPathToSink.map((blockId) => {
+      const block = dag.blocks[blockId];
+      return {
+        blockId,
+        daaScore: block?.daaScore ?? "0",
+        acceptedTxCount: block?.acceptedTxIds.length ?? 0,
+        isGenesis: block?.isGenesis ?? false
+      };
+    });
+    const result = {
+      nodes,
+      sink: dag.sink,
+      depth: nodes.length
+    };
+    return {
+      domain: "dag",
+      op: "sink-path",
+      items: [result],
+      total: 1,
+      truncated: false,
+      deterministic: true,
+      queryHash: computeQueryHash([result]),
+      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Anomalies — transactions in unexpected states
+  // -------------------------------------------------------------------------
+  async executeAnomalies(request) {
+    const start = Date.now();
+    const dag = await this.loadDag();
+    if (!dag) {
+      return emptyDagResult("anomalies", start);
+    }
+    const anomalies = [];
+    for (const txId of dag.displacedTxIds) {
+      if (!dag.acceptedTxIds.includes(txId)) {
+        anomalies.push({
+          kind: "displaced-never-reaccepted",
+          description: `Transaction ${txId} was displaced and has not been re-accepted`,
+          txId
+        });
+      }
+    }
+    const reachable = /* @__PURE__ */ new Set();
+    const stack = [dag.sink];
+    while (stack.length > 0) {
+      const id = stack.pop();
+      if (reachable.has(id)) continue;
+      reachable.add(id);
+      const block = dag.blocks[id];
+      if (block) {
+        for (const p of block.parents) stack.push(p);
+      }
+    }
+    for (const blockId of Object.keys(dag.blocks)) {
+      if (!reachable.has(blockId)) {
+        anomalies.push({
+          kind: "unreachable-block",
+          description: `Block ${blockId} is not reachable from current sink ${dag.sink}`,
+          blockId
+        });
+      }
+    }
+    for (const txId of dag.acceptedTxIds) {
+      if (dag.displacedTxIds.includes(txId)) {
+        anomalies.push({
+          kind: "invariant-violation",
+          description: `Transaction ${txId} is in both acceptedTxIds and displacedTxIds`,
+          txId
+        });
+      }
+    }
+    anomalies.sort((a, b) => a.kind.localeCompare(b.kind));
+    const paged = anomalies.slice(request.offset, request.offset + request.limit);
+    let explain;
+    if (request.explain) {
+      explain = paged.map((a) => explainAnomaly(a, dag));
+    }
+    return {
+      domain: "dag",
+      op: "anomalies",
+      items: paged,
+      total: anomalies.length,
+      truncated: anomalies.length > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      explain,
+      annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Load DAG from state.json
+  // -------------------------------------------------------------------------
+  async loadDag() {
+    const statePath = path4.join(this.rootDir, ".hardkas", "state.json");
+    try {
+      const content = await fs4.readFile(statePath, "utf-8");
+      const state = JSON.parse(content);
+      return state.dag ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+function emptyDagResult(op, start) {
+  return {
+    domain: "dag",
+    op,
+    items: [],
+    total: 0,
+    truncated: false,
+    deterministic: true,
+    queryHash: computeQueryHash([]),
+    annotations: { executedAt: (/* @__PURE__ */ new Date()).toISOString(), executionMs: Date.now() - start }
+  };
+}
+function explainConflict(conflict, dag) {
+  const steps = [];
+  let order = 1;
+  let winnerBlockId;
+  let winnerDaaScore = "0";
+  let winnerInSinkPath = false;
+  for (const [blockId, block] of Object.entries(dag.blocks)) {
+    if (block?.acceptedTxIds.includes(conflict.winnerTxId)) {
+      winnerBlockId = blockId;
+      winnerDaaScore = block.daaScore;
+      winnerInSinkPath = dag.selectedPathToSink.includes(blockId);
+      break;
+    }
+  }
+  steps.push({
+    order: order++,
+    assertion: `Outpoint ${conflict.outpoint} was spent by multiple transactions`,
+    evidence: `Winner: ${conflict.winnerTxId}, Losers: ${conflict.loserTxIds.join(", ")}`,
+    rule: "UTXO double-spend detection (dag.ts:moveSink)"
+  });
+  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({
+      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)"
+    });
+  }
+  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,
+    model: "deterministic-light-model",
+    confidence: "definitive",
+    references: [conflict.winnerTxId, ...conflict.loserTxIds]
+  };
+}
+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" }
+    ],
+    model: "deterministic-light-model",
+    confidence: "definitive",
+    references: [d.txId]
+  };
+}
+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" }
+    ],
+    model: "deterministic-light-model",
+    confidence: "definitive",
+    references: [entry.txId]
+  };
+}
+function explainAnomaly(a, _dag) {
+  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)" }
+    ],
+    model: "deterministic-light-model",
+    confidence: "definitive",
+    references: [a.txId ?? a.blockId ?? ""]
+  };
+}
+
+// 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) {
+    this.rootDir = rootDir;
+  }
+  supportedOps() {
+    return ["list", "summary"];
+  }
+  supportedFilters() {
+    return ["txId", "workflowId", "domain", "kind", "networkId", "artifactId"];
+  }
+  async execute(request) {
+    switch (request.op) {
+      case "list":
+        return this.executeList(request);
+      default:
+        throw new Error(`Unknown events op: ${request.op}`);
+    }
+  }
+  async executeList(request) {
+    const start = Date.now();
+    const events = await this.loadEvents();
+    const backendUsed = "filesystem";
+    const eventsPath = path5.join(this.rootDir, ".hardkas", "events.jsonl");
+    const filtered = [];
+    const txFilter = request.params["tx"] || request.params["txId"];
+    const effectiveFilters = [...request.filters];
+    if (txFilter) {
+      effectiveFilters.push({ field: "txId", op: "eq", value: txFilter });
+    }
+    for (const event of events) {
+      if (evaluateFilters(event, effectiveFilters)) {
+        filtered.push(event);
+      }
+    }
+    const sorted = [...filtered].sort((a, b) => {
+      const cmp = a.timestamp.localeCompare(b.timestamp);
+      if (cmp !== 0) return cmp;
+      return a.eventId.localeCompare(b.eventId);
+    });
+    const total = sorted.length;
+    const paged = sorted.slice(request.offset, request.offset + request.limit);
+    return {
+      domain: "events",
+      op: "list",
+      items: paged,
+      total,
+      truncated: total > request.offset + request.limit,
+      deterministic: true,
+      queryHash: computeQueryHash(paged),
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start,
+        filesScanned: 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: []
+        }]
+      } : {}
+    };
+  }
+  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 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 {
+      }
+    }
+    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) {
+    this.rootDir = rootDir;
+  }
+  supportedOps() {
+    return ["aggregate"];
+  }
+  supportedFilters() {
+    return ["txId"];
+  }
+  async execute(request) {
+    switch (request.op) {
+      case "aggregate":
+        return this.executeAggregate(request);
+      default:
+        throw new Error(`Unknown tx op: ${request.op}`);
+    }
+  }
+  async executeAggregate(request) {
+    const start = Date.now();
+    const txId = request.params["txId"];
+    if (!txId) throw new Error("tx aggregate requires params.txId");
+    const warnings = [];
+    const artifacts = await this.findArtifactsByTxId(txId);
+    const events = await this.findEventsByTxId(txId);
+    if (artifacts.length === 0) warnings.push("No artifacts found for this txId");
+    if (events.length === 0) warnings.push("No events found for this txId");
+    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)");
+    const complete = roles.has("plan") && roles.has("signed");
+    const result = {
+      txId,
+      artifacts,
+      events: events.sort((a, b) => a.timestamp.localeCompare(b.timestamp) || a.eventId.localeCompare(b.eventId)),
+      warnings,
+      complete
+    };
+    let explain;
+    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" }
+        ],
+        model: "tx-aggregation",
+        confidence: "definitive",
+        references: [txId]
+      }];
+    }
+    return {
+      domain: "tx",
+      op: "aggregate",
+      items: [result],
+      total: 1,
+      truncated: false,
+      deterministic: true,
+      queryHash: computeQueryHash([result]),
+      explain,
+      annotations: {
+        executedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        executionMs: Date.now() - start
+      }
+    };
+  }
+  async findArtifactsByTxId(txId) {
+    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 {
+      }
+    }
+    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 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 {
+      }
+    }
+    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 {
+  adapters;
+  constructor(options) {
+    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));
+  }
+  /**
+   * Execute a query request against the appropriate adapter.
+   */
+  async execute(request) {
+    const adapter = this.adapters.get(request.domain);
+    if (!adapter) {
+      throw new Error(`No adapter registered for domain: ${request.domain}`);
+    }
+    if (!adapter.supportedOps().includes(request.op)) {
+      throw new Error(
+        `Operation "${request.op}" is not supported by the "${request.domain}" adapter. Supported: ${adapter.supportedOps().join(", ")}`
+      );
+    }
+    return adapter.execute(request);
+  }
+  /**
+   * List available domains and their operations.
+   */
+  listCapabilities() {
+    const result = [];
+    for (const [domain, adapter] of this.adapters.entries()) {
+      result.push({
+        domain,
+        ops: adapter.supportedOps(),
+        filters: adapter.supportedFilters()
+      });
+    }
+    return result;
+  }
+};
+function createQueryRequest(overrides) {
+  return {
+    domain: overrides.domain,
+    op: overrides.op,
+    filters: overrides.filters ?? [],
+    sort: overrides.sort,
+    limit: overrides.limit ?? 100,
+    offset: overrides.offset ?? 0,
+    explain: overrides.explain ?? false,
+    params: overrides.params ?? {}
+  };
+}
+export {
+  ArtifactQueryAdapter,
+  DagQueryAdapter,
+  EventsQueryAdapter,
+  LineageQueryAdapter,
+  QueryEngine,
+  ReplayQueryAdapter,
+  TxQueryAdapter,
+  computeQueryHash,
+  createQueryRequest,
+  evaluateFilter,
+  evaluateFilters,
+  explainIntegrity,
+  explainOrphan,
+  explainTransition,
+  formatExplainBrief,
+  formatExplainFull,
+  resolveFieldPath,
+  serializeQueryResult
+};