@hardkas/query 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+import { NetworkId, ContentHash, KaspaAddress, ArtifactId, LineageId, TxId } from '@hardkas/core';
+
+/**
+ * @hardkas/query — Core types for the HardKAS query and introspection engine.
+ *
+ * All query operations are deterministic pure functions over immutable artifact data.
+ * Non-deterministic metadata (timestamps, execution time) is isolated in `annotations`.
+ */
+
+/** Query domains available. */
+type QueryDomain = "artifacts" | "lineage" | "replay" | "dag" | "events" | "tx";
+/** Operations supported by the artifact adapter. */
+type ArtifactOp = "list" | "inspect" | "diff" | "verify";
+/** Operations supported by the lineage adapter. */
+type LineageOp = "chain" | "transitions" | "orphans";
+/** Operations supported by the replay adapter. */
+type ReplayOp = "list" | "summary" | "divergences" | "invariants";
+/** Operations supported by the DAG adapter. */
+type DagOp = "conflicts" | "displaced" | "history" | "sink-path" | "anomalies";
+/** Operations supported by the events adapter. */
+type EventsOp = "list" | "summary";
+/** Operations supported by the transaction aggregator. */
+type TxOp = "aggregate";
+type FilterOp = "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "in" | "contains" | "exists";
+interface QueryFilter {
+    readonly field: string;
+    readonly op: FilterOp;
+    readonly value: string | number | boolean | readonly string[];
+}
+interface QuerySort {
+    readonly field: string;
+    readonly direction: "asc" | "desc";
+}
+interface QueryRequest {
+    readonly domain: QueryDomain;
+    readonly op: string;
+    readonly filters: readonly QueryFilter[];
+    readonly sort?: QuerySort | undefined;
+    readonly limit: number;
+    readonly offset: number;
+    readonly explain: "brief" | "full" | false;
+    readonly params: Readonly<Record<string, string>>;
+}
+interface QueryResult<T = unknown> {
+    readonly domain: QueryDomain;
+    readonly op: string;
+    readonly items: readonly T[];
+    readonly total: number;
+    readonly truncated: boolean;
+    readonly deterministic: boolean;
+    readonly queryHash: string;
+    readonly explain?: readonly ExplainChain[] | undefined;
+    readonly annotations: QueryAnnotations;
+}
+/** Non-deterministic metadata, always isolated from deterministic fields. */
+interface QueryAnnotations {
+    readonly executedAt: string;
+    readonly executionMs: number;
+    readonly filesScanned?: number | undefined;
+}
+interface ExplainChain {
+    readonly question: string;
+    readonly conclusion: string;
+    readonly steps: readonly ReasoningStep[];
+    readonly model: string;
+    readonly confidence: "definitive" | "probable";
+    readonly references: readonly string[];
+}
+interface ReasoningStep {
+    readonly order: number;
+    readonly assertion: string;
+    readonly evidence: string;
+    readonly rule?: string | undefined;
+}
+interface QueryAdapter<T = unknown> {
+    readonly domain: QueryDomain;
+    execute(request: QueryRequest): Promise<QueryResult<T>>;
+    supportedOps(): readonly string[];
+    supportedFilters(): readonly string[];
+}
+interface ArtifactQueryItem {
+    readonly filePath: string;
+    readonly schema: string;
+    readonly version: string;
+    readonly networkId: NetworkId;
+    readonly mode: string;
+    readonly createdAt: string;
+    readonly contentHash?: ContentHash | undefined;
+    readonly from?: {
+        readonly address: KaspaAddress;
+    } | undefined;
+    readonly to?: {
+        readonly address: KaspaAddress;
+    } | undefined;
+    readonly amountSompi?: string | undefined;
+    readonly status?: string | undefined;
+    readonly lineage?: {
+        readonly artifactId: ArtifactId;
+        readonly parentArtifactId?: ArtifactId | undefined;
+        readonly rootArtifactId: ArtifactId;
+        readonly lineageId: LineageId;
+        readonly sequence?: number | undefined;
+    } | undefined;
+}
+interface ArtifactInspectResult {
+    readonly item: ArtifactQueryItem;
+    readonly integrity: {
+        readonly ok: boolean;
+        readonly hashMatch: boolean;
+        readonly schemaValid: boolean;
+        readonly errors: readonly string[];
+    };
+    readonly economics?: {
+        readonly ok: boolean;
+        readonly massReported: string;
+        readonly massRecomputed: string;
+        readonly feeReported: string;
+        readonly feeRecomputed: string;
+        readonly feeRate: string;
+    } | undefined;
+    readonly staleness: {
+        readonly ageHours: number;
+        readonly stale: boolean;
+        readonly classification: "fresh" | "aging" | "stale" | "expired";
+    };
+    readonly lineageStatus: "valid" | "orphan" | "missing" | "unknown";
+}
+interface ArtifactDiffEntry {
+    readonly field: string;
+    readonly left: string | undefined;
+    readonly right: string | undefined;
+    readonly kind: "value-change" | "added" | "removed" | "type-change";
+}
+interface ArtifactDiffResult {
+    readonly leftPath: string;
+    readonly rightPath: string;
+    readonly leftSchema: string;
+    readonly rightSchema: string;
+    readonly identical: boolean;
+    readonly entries: readonly ArtifactDiffEntry[];
+}
+interface LineageNode {
+    readonly contentHash: ContentHash;
+    readonly schema: string;
+    readonly artifactId: ArtifactId;
+    readonly parentArtifactId?: ArtifactId | undefined;
+    readonly rootArtifactId: ArtifactId;
+    readonly lineageId: LineageId;
+    readonly sequence?: number | undefined;
+    readonly filePath: string;
+    readonly networkId: NetworkId;
+    readonly mode: string;
+    readonly createdAt: string;
+}
+interface LineageTransition {
+    readonly from: LineageNode;
+    readonly to: LineageNode;
+    readonly valid: boolean;
+    readonly rule: string;
+}
+interface LineageChainResult {
+    readonly anchor: string;
+    readonly direction: "ancestors" | "descendants";
+    readonly nodes: readonly LineageNode[];
+    readonly transitions: readonly LineageTransition[];
+    readonly complete: boolean;
+}
+interface LineageOrphan {
+    readonly node: LineageNode;
+    readonly missingParentId: string;
+    readonly reason: string;
+}
+type DivergenceKind = "state-hash-mismatch" | "fee-mismatch" | "utxo-count-mismatch" | "status-mismatch" | "txid-mismatch" | "ordering-divergence";
+interface ReplayDivergence {
+    readonly txId: string;
+    readonly kind: DivergenceKind;
+    readonly field: string;
+    readonly expected: string;
+    readonly actual: string;
+}
+interface ReplaySummaryResult {
+    readonly txId: TxId;
+    readonly status: string;
+    readonly mode: string;
+    readonly networkId: NetworkId;
+    readonly from: KaspaAddress;
+    readonly to: KaspaAddress;
+    readonly amountSompi: string;
+    readonly feeSompi: string;
+    readonly daaScore: string;
+    readonly preStateHash?: string | undefined;
+    readonly postStateHash?: string | undefined;
+    readonly spentUtxoCount: number;
+    readonly createdUtxoCount: number;
+    readonly hasTrace: boolean;
+    readonly traceEventCount: number;
+}
+interface ReplayInvariantsResult {
+    readonly txId: TxId;
+    readonly planIntegrity: boolean;
+    readonly receiptReproducible: boolean;
+    readonly stateTransitionValid: boolean;
+    readonly utxoConservation: boolean;
+    readonly issues: readonly string[];
+}
+interface DagConflict {
+    readonly outpoint: string;
+    readonly winnerTxId: TxId;
+    readonly loserTxIds: readonly TxId[];
+}
+interface DagDisplacement {
+    readonly txId: TxId;
+    readonly reason: string;
+    readonly currentlyAccepted: boolean;
+}
+interface DagTxHistory {
+    readonly txId: TxId;
+    readonly blockId: string;
+    readonly accepted: boolean;
+    readonly displaced: boolean;
+    readonly inSinkPath: boolean;
+    readonly daaScore: string;
+}
+interface DagSinkPath {
+    readonly nodes: readonly DagSinkPathNode[];
+    readonly sink: string;
+    readonly depth: number;
+}
+interface DagSinkPathNode {
+    readonly blockId: string;
+    readonly daaScore: string;
+    readonly acceptedTxCount: number;
+    readonly isGenesis: boolean;
+}
+interface DagAnomaly {
+    readonly kind: "displaced-never-reaccepted" | "unreachable-block" | "invariant-violation";
+    readonly description: string;
+    readonly txId?: string | undefined;
+    readonly blockId?: string | undefined;
+}
+
+interface QueryEngineOptions {
+    /** Root directory for artifact/lineage scanning (typically .hardkas/ or project root). */
+    readonly artifactDir: string;
+}
+declare class QueryEngine {
+    private readonly adapters;
+    constructor(options: QueryEngineOptions);
+    /**
+     * Execute a query request against the appropriate adapter.
+     */
+    execute<T = unknown>(request: QueryRequest): Promise<QueryResult<T>>;
+    /**
+     * List available domains and their operations.
+     */
+    listCapabilities(): Array<{
+        domain: QueryDomain;
+        ops: readonly string[];
+        filters: readonly string[];
+    }>;
+}
+/**
+ * Creates a default QueryRequest with sensible defaults.
+ */
+declare function createQueryRequest(overrides: Partial<QueryRequest> & {
+    domain: QueryDomain;
+    op: string;
+}): QueryRequest;
+
+/**
+ * Filter evaluation engine.
+ * Evaluates QueryFilter[] predicates against arbitrary objects using dot-path field access.
+ * All evaluation is deterministic and null-safe.
+ */
+
+/**
+ * Resolves a dot-separated field path on an object.
+ * Returns undefined if any segment is missing.
+ */
+declare function resolveFieldPath(obj: unknown, path: string): unknown;
+/**
+ * Evaluates a single filter predicate against an item.
+ */
+declare function evaluateFilter(item: unknown, filter: QueryFilter): boolean;
+/**
+ * Evaluates all filters (AND semantics). Returns true only if all pass.
+ */
+declare function evaluateFilters(item: unknown, filters: readonly QueryFilter[]): boolean;
+
+/**
+ * Computes a SHA-256 hash of the deterministic serialization of items.
+ * This hash is stable: identical items always produce identical hashes.
+ */
+declare function computeQueryHash(items: readonly unknown[]): string;
+/**
+ * Serializes a QueryResult to deterministic JSON.
+ * The `annotations` block is included but clearly non-deterministic.
+ * The `queryHash` enables diffing results across environments.
+ */
+declare function serializeQueryResult(result: QueryResult): string;
+
+/**
+ * Explainability 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.
+ */
+
+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;
+
+declare class ArtifactQueryAdapter implements QueryAdapter {
+    readonly domain: "artifacts";
+    private readonly rootDir;
+    constructor(rootDir: string);
+    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>;
+    private executeList;
+    private executeInspect;
+    private executeDiff;
+    private executeVerify;
+    private scanArtifactFiles;
+    private walkDir;
+    private readJsonSafe;
+    private resolveTarget;
+    private sortItems;
+}
+
+declare class LineageQueryAdapter implements QueryAdapter {
+    readonly domain: "lineage";
+    private readonly rootDir;
+    constructor(rootDir: string);
+    supportedOps(): readonly ["chain", "transitions", "orphans"];
+    supportedFilters(): readonly ["schema", "networkId", "mode", "rootArtifactId", "lineageId"];
+    execute(request: QueryRequest): Promise<QueryResult<any>>;
+    private executeChain;
+    private executeTransitions;
+    private executeOrphans;
+    private buildGraph;
+    private walkAncestors;
+    private walkDescendants;
+    private scanJsonFiles;
+    private walkDir;
+    private readJsonSafe;
+}
+
+declare class ReplayQueryAdapter implements QueryAdapter {
+    readonly domain: "replay";
+    private readonly rootDir;
+    constructor(rootDir: string);
+    supportedOps(): readonly ["list", "summary", "divergences", "invariants"];
+    supportedFilters(): readonly ["txId", "status", "networkId", "mode", "daaScore", "from.address", "to.address"];
+    execute(request: QueryRequest): Promise<QueryResult>;
+    private executeList;
+    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);
+    supportedOps(): readonly ["conflicts", "displaced", "history", "sink-path", "anomalies"];
+    supportedFilters(): readonly ["txId", "blockId", "daaScore"];
+    execute(request: QueryRequest): Promise<QueryResult>;
+    private executeConflicts;
+    private executeDisplaced;
+    private executeHistory;
+    private executeSinkPath;
+    private executeAnomalies;
+    private loadDag;
+}
+
+declare class EventsQueryAdapter implements QueryAdapter {
+    readonly domain: "events";
+    private readonly rootDir;
+    constructor(rootDir: string);
+    supportedOps(): readonly ["list", "summary"];
+    supportedFilters(): readonly ["txId", "workflowId", "domain", "kind", "networkId", "artifactId"];
+    execute(request: QueryRequest): Promise<QueryResult>;
+    private executeList;
+    private loadEvents;
+}
+
+declare class TxQueryAdapter implements QueryAdapter {
+    readonly domain: "tx";
+    private readonly rootDir;
+    constructor(rootDir: string);
+    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 };