@hardkas/query 0.2.2-alpha → 0.3.0-alpha

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NetworkId, ContentHash, KaspaAddress, ArtifactId, LineageId, TxId } from '@hardkas/core';
+import { NetworkId, ContentHash, KaspaAddress, ArtifactId, LineageId, TxId, ExecutionMode } from '@hardkas/core';
 
 /**
  * @hardkas/query — Core types for the HardKAS query and introspection engine.
@@ -49,24 +49,42 @@ interface QueryResult<T = unknown> {
     readonly truncated: boolean;
     readonly deterministic: boolean;
     readonly queryHash: string;
-    readonly explain?: readonly ExplainChain[] | undefined;
     readonly annotations: QueryAnnotations;
+    readonly explain?: ExplainBlock | undefined;
+    readonly why?: readonly WhyBlock[] | undefined;
 }
+type QueryStoreStatus = "fresh" | "stale" | "rebuilding" | "unknown";
 /** Non-deterministic metadata, always isolated from deterministic fields. */
 interface QueryAnnotations {
     readonly executedAt: string;
     readonly executionMs: number;
     readonly filesScanned?: number | undefined;
-}
-interface ExplainChain {
+    readonly backendUsed?: string | undefined;
+    readonly freshness?: QueryStoreStatus | undefined;
+}
+interface ExplainBlock {
+    readonly backend: string;
+    readonly executionPlan: readonly string[];
+    readonly indexesUsed: readonly string[];
+    readonly filtersApplied: readonly string[];
+    readonly rowsRead: number;
+    readonly scannedFiles: number;
+    readonly freshness: QueryStoreStatus;
+    readonly warnings: readonly string[];
+}
+interface WhyBlock {
     readonly question: string;
-    readonly conclusion: string;
-    readonly steps: readonly ReasoningStep[];
-    readonly model: string;
-    readonly confidence: "definitive" | "probable";
-    readonly references: readonly string[];
+    readonly answer: string;
+    readonly evidence: readonly EvidenceRef[];
+    readonly causalChain: readonly CausalStep[];
+    readonly model?: string;
+    readonly confidence?: "definitive" | "probable";
+}
+interface EvidenceRef {
+    readonly type: "artifactId" | "contentHash" | "txId" | "traceId" | "eventId" | "blockId" | "filePath";
+    readonly value: string;
 }
-interface ReasoningStep {
+interface CausalStep {
     readonly order: number;
     readonly assertion: string;
     readonly evidence: string;
@@ -84,7 +102,8 @@ interface ArtifactQueryItem {
     readonly version: string;
     readonly networkId: NetworkId;
     readonly mode: string;
-    readonly createdAt: string;
+    readonly createdAt: string | null;
+    readonly payload: any;
     readonly contentHash?: ContentHash | undefined;
     readonly from?: {
         readonly address: KaspaAddress;
@@ -150,7 +169,7 @@ interface LineageNode {
     readonly filePath: string;
     readonly networkId: NetworkId;
     readonly mode: string;
-    readonly createdAt: string;
+    readonly createdAt: string | null;
 }
 interface LineageTransition {
     readonly from: LineageNode;
@@ -239,12 +258,112 @@ interface DagAnomaly {
     readonly blockId?: string | undefined;
 }
 
+interface ArtifactDocument {
+    readonly contentHash: string;
+    readonly schema: string;
+    readonly version: string;
+    readonly kind: string;
+    readonly mode: ExecutionMode;
+    readonly networkId: NetworkId;
+    readonly createdAt: string | null;
+    readonly txId: string | null;
+    readonly artifactId: string;
+    readonly path: string;
+    readonly payload: any;
+}
+interface EventDocument {
+    readonly eventId: string;
+    readonly kind: string;
+    readonly domain: string;
+    readonly timestamp: string | null;
+    readonly workflowId: string;
+    readonly correlationId: string;
+    readonly causationId: string | null;
+    readonly txId: string | null;
+    readonly artifactId: string | null;
+    readonly networkId: string;
+    readonly payload: any;
+}
+interface LineageEdgeDocument {
+    readonly parentArtifactId: string;
+    readonly childArtifactId: string;
+    readonly lineageId: string;
+    readonly rule: string;
+    readonly createdAt: string | null;
+}
+/**
+ * Common storage backend interface for QueryEngine.
+ * Allows switching between filesystem/memory and SQLite.
+ */
+interface QueryBackend {
+    /** Check if the backend is ready/connected. */
+    isReady(): boolean;
+    /** Backend identifier for diagnostics. */
+    kind(): "sqlite" | "filesystem";
+    /** Find artifacts matching optional basic filters. */
+    findArtifacts(filters?: {
+        schema?: string;
+        mode?: string;
+        networkId?: string;
+    }): Promise<ArtifactDocument[]>;
+    /** Get a specific artifact by content hash or artifact ID. */
+    getArtifact(idOrHash: string): Promise<ArtifactDocument | null>;
+    /** Get events matching optional filters. */
+    getEvents(filters?: {
+        kind?: string;
+        txId?: string;
+    }): Promise<EventDocument[]>;
+    /** Get lineage edges. */
+    getLineageEdges(filters?: {
+        parentHash?: string;
+        childHash?: string;
+    }): Promise<LineageEdgeDocument[]>;
+    /** Get the current freshness/health status of the store. */
+    getStoreStatus(): Promise<string>;
+    /** Perform index integrity check. */
+    doctor(): Promise<any>;
+    /** Atomic wipe and rebuild. */
+    rebuild(options?: {
+        strict?: boolean;
+    }): Promise<any>;
+    /** Incremental index update. */
+    sync(options?: {
+        strict?: boolean;
+    }): Promise<any>;
+    /** Apply pending schema migrations. */
+    migrate(): Promise<{
+        applied: number;
+    }>;
+    /** Execute raw SQL (if supported). */
+    executeRawSql(sql: string): Promise<any[]>;
+    /** Find all transaction receipts (for replay analysis). */
+    findReceipts(filters?: {
+        status?: string;
+        networkId?: string;
+    }): Promise<ArtifactDocument[]>;
+    /** Find all transaction traces. */
+    findTraces(filters?: {
+        txId?: string;
+    }): Promise<ArtifactDocument[]>;
+}
+
 interface QueryEngineOptions {
     /** Root directory for artifact/lineage scanning (typically .hardkas/ or project root). */
     readonly artifactDir: string;
+    /** Primary data backend. If not provided, defaults to auto-discovery (SQLite > Filesystem). */
+    readonly backend?: QueryBackend;
+    /** Automatically synchronize the store before queries. Requires 'query-store' lock. */
+    readonly autoSync?: boolean;
+    /** Whether to wait for the lock if held. */
+    readonly waitLock?: boolean;
 }
 declare class QueryEngine {
     private readonly adapters;
+    readonly backend: QueryBackend;
+    /**
+     * Primary entry point for creating a QueryEngine with auto-discovery.
+     */
+    static create(options: QueryEngineOptions): Promise<QueryEngine>;
     constructor(options: QueryEngineOptions);
     /**
      * Execute a query request against the appropriate adapter.
@@ -300,28 +419,48 @@ declare function computeQueryHash(items: readonly unknown[]): string;
 declare function serializeQueryResult(result: QueryResult): string;
 
 /**
- * Explainability engine.
+ * Explainability & Causal Analysis engine.
  *
- * Generates structured, rule-driven ExplainChains for query results.
- * Every explanation is based on explicit rules, deterministic evidence,
- * and actual execution state. No speculative reasoning.
+ * Generates structured, technical ExplainBlocks and causal WhyBlocks.
+ * Every analysis is based on explicit rules, deterministic evidence,
+ * and actual execution state.
  */
 
+declare function createExplainBlock(options: {
+    backend: string;
+    executionPlan: string[];
+    indexesUsed?: string[];
+    filtersApplied?: string[];
+    rowsRead: number;
+    scannedFiles: number;
+    freshness: QueryStoreStatus;
+    warnings?: string[];
+}): ExplainBlock;
+/**
+ * Why is this artifact valid or invalid?
+ */
 declare function explainIntegrity(artifact: ArtifactQueryItem, integrity: {
     ok: boolean;
     hashMatch: boolean;
     schemaValid: boolean;
     errors: readonly string[];
-}): ExplainChain;
-declare function explainTransition(transition: LineageTransition): ExplainChain;
-declare function explainOrphan(node: LineageNode, missingParentId: string): ExplainChain;
-declare function formatExplainBrief(chain: ExplainChain): string;
-declare function formatExplainFull(chain: ExplainChain): string;
+}): WhyBlock;
+/**
+ * Why is this transition valid or invalid?
+ */
+declare function explainTransition(transition: LineageTransition): WhyBlock;
+/**
+ * Why is this artifact an orphan?
+ */
+declare function explainOrphan(node: LineageNode, missingParentId: string): WhyBlock;
+declare function formatExplainBlock(block: ExplainBlock): string;
+declare function formatWhyBlock(block: WhyBlock): string;
 
 declare class ArtifactQueryAdapter implements QueryAdapter {
     readonly domain: "artifacts";
     private readonly rootDir;
-    constructor(rootDir: string);
+    private readonly backend;
+    constructor(rootDir: string, backend: QueryBackend);
     supportedOps(): readonly ["list", "inspect", "diff", "verify"];
     supportedFilters(): readonly ["schema", "version", "networkId", "mode", "from.address", "to.address", "amountSompi", "status", "contentHash", "createdAt"];
     execute(request: QueryRequest): Promise<QueryResult>;
@@ -339,7 +478,8 @@ declare class ArtifactQueryAdapter implements QueryAdapter {
 declare class LineageQueryAdapter implements QueryAdapter {
     readonly domain: "lineage";
     private readonly rootDir;
-    constructor(rootDir: string);
+    private readonly backend;
+    constructor(rootDir: string, backend: QueryBackend);
     supportedOps(): readonly ["chain", "transitions", "orphans"];
     supportedFilters(): readonly ["schema", "networkId", "mode", "rootArtifactId", "lineageId"];
     execute(request: QueryRequest): Promise<QueryResult<any>>;
@@ -357,7 +497,8 @@ declare class LineageQueryAdapter implements QueryAdapter {
 declare class ReplayQueryAdapter implements QueryAdapter {
     readonly domain: "replay";
     private readonly rootDir;
-    constructor(rootDir: string);
+    private readonly backend;
+    constructor(rootDir: string, backend: QueryBackend);
     supportedOps(): readonly ["list", "summary", "divergences", "invariants"];
     supportedFilters(): readonly ["txId", "status", "networkId", "mode", "daaScore", "from.address", "to.address"];
     execute(request: QueryRequest): Promise<QueryResult>;
@@ -365,18 +506,14 @@ declare class ReplayQueryAdapter implements QueryAdapter {
     private executeSummary;
     private executeDivergences;
     private executeInvariants;
-    private loadAllReceipts;
-    private loadAllTraces;
-    private loadReceipt;
-    private loadTrace;
-    private loadJsonDir;
     private readJsonSafe;
 }
 
 declare class DagQueryAdapter implements QueryAdapter {
     readonly domain: "dag";
     private readonly rootDir;
-    constructor(rootDir: string);
+    private readonly backend;
+    constructor(rootDir: string, backend: QueryBackend);
     supportedOps(): readonly ["conflicts", "displaced", "history", "sink-path", "anomalies"];
     supportedFilters(): readonly ["txId", "blockId", "daaScore"];
     execute(request: QueryRequest): Promise<QueryResult>;
@@ -391,7 +528,8 @@ declare class DagQueryAdapter implements QueryAdapter {
 declare class EventsQueryAdapter implements QueryAdapter {
     readonly domain: "events";
     private readonly rootDir;
-    constructor(rootDir: string);
+    private readonly backend;
+    constructor(rootDir: string, backend: QueryBackend);
     supportedOps(): readonly ["list", "summary"];
     supportedFilters(): readonly ["txId", "workflowId", "domain", "kind", "networkId", "artifactId"];
     execute(request: QueryRequest): Promise<QueryResult>;
@@ -402,15 +540,14 @@ declare class EventsQueryAdapter implements QueryAdapter {
 declare class TxQueryAdapter implements QueryAdapter {
     readonly domain: "tx";
     private readonly rootDir;
-    constructor(rootDir: string);
+    private readonly backend;
+    constructor(rootDir: string, backend: QueryBackend);
     supportedOps(): readonly ["aggregate"];
     supportedFilters(): readonly ["txId"];
     execute(request: QueryRequest): Promise<QueryResult>;
     private executeAggregate;
     private findArtifactsByTxId;
     private findEventsByTxId;
-    private scanJsonFiles;
-    private walkDir;
 }
 
-export { type ArtifactDiffEntry, type ArtifactDiffResult, type ArtifactInspectResult, type ArtifactOp, ArtifactQueryAdapter, type ArtifactQueryItem, type DagAnomaly, type DagConflict, type DagDisplacement, type DagOp, DagQueryAdapter, type DagSinkPath, type DagSinkPathNode, type DagTxHistory, type DivergenceKind, type EventsOp, EventsQueryAdapter, type ExplainChain, type FilterOp, type LineageChainResult, type LineageNode, type LineageOp, type LineageOrphan, LineageQueryAdapter, type LineageTransition, type QueryAdapter, type QueryAnnotations, type QueryDomain, QueryEngine, type QueryEngineOptions, type QueryFilter, type QueryRequest, type QueryResult, type QuerySort, type ReasoningStep, type ReplayDivergence, type ReplayInvariantsResult, type ReplayOp, ReplayQueryAdapter, type ReplaySummaryResult, type TxOp, TxQueryAdapter, computeQueryHash, createQueryRequest, evaluateFilter, evaluateFilters, explainIntegrity, explainOrphan, explainTransition, formatExplainBrief, formatExplainFull, resolveFieldPath, serializeQueryResult };
+export { type ArtifactDiffEntry, type ArtifactDiffResult, type ArtifactInspectResult, type ArtifactOp, ArtifactQueryAdapter, type ArtifactQueryItem, type CausalStep, type DagAnomaly, type DagConflict, type DagDisplacement, type DagOp, DagQueryAdapter, type DagSinkPath, type DagSinkPathNode, type DagTxHistory, type DivergenceKind, type EventsOp, EventsQueryAdapter, type EvidenceRef, type ExplainBlock, type FilterOp, type LineageChainResult, type LineageNode, type LineageOp, type LineageOrphan, LineageQueryAdapter, type LineageTransition, type QueryAdapter, type QueryAnnotations, type QueryDomain, QueryEngine, type QueryEngineOptions, type QueryFilter, type QueryRequest, type QueryResult, type QuerySort, type QueryStoreStatus, type ReplayDivergence, type ReplayInvariantsResult, type ReplayOp, ReplayQueryAdapter, type ReplaySummaryResult, type TxOp, TxQueryAdapter, type WhyBlock, computeQueryHash, createExplainBlock, createQueryRequest, evaluateFilter, evaluateFilters, explainIntegrity, explainOrphan, explainTransition, formatExplainBlock, formatWhyBlock, resolveFieldPath, serializeQueryResult };