@hardkas/testing 0.2.2-alpha.1 → 0.3.0-alpha

package/dist/adversarial-fixtures.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Generates artifacts with semantic or structural flaws for adversarial testing.
+ */
+declare const AdversarialFixtures: {
+    /**
+     * Circular lineage: A -> B -> A
+     */
+    circularLineage(): {
+        artifactA: any;
+        artifactB: any;
+    };
+    /**
+     * Artifact where the contentHash does not match the actual content calculation.
+     */
+    hashMismatch(): any;
+    /**
+     * Artifact with a parent from a different network (Security Violation).
+     */
+    crossNetworkLineage(): {
+        parent: any;
+        child: any;
+    };
+    /**
+     * Trace with duplicate event IDs (Corruption).
+     */
+    duplicateEventTrace(): {
+        schema: string;
+        workflowId: string;
+        events: {
+            eventId: string;
+            kind: string;
+        }[];
+    };
+    /**
+     * Malformed JSONL snippet (truncated).
+     */
+    malformedJsonl(): string;
+    /**
+     * Lineage with sequence rollback (corrupted history).
+     */
+    sequenceRollback(): ({
+        artifactId: string;
+        lineage: {
+            sequenceId: number;
+            contentHash: string;
+            parentArtifactId?: never;
+        };
+        schema: string;
+        version: string;
+        networkId: string;
+        mode: string;
+    } | {
+        artifactId: string;
+        lineage: {
+            sequenceId: number;
+            contentHash: string;
+            parentArtifactId: string;
+        };
+        schema: string;
+        version: string;
+        networkId: string;
+        mode: string;
+    })[];
+    /**
+     * Artifact with a future timestamp (anomaly).
+     * Intentionally uses Date.now() to generate a timestamp far in the future.
+     */
+    futureTimestamp(): {
+        schema: string;
+        version: string;
+        artifactId: string;
+        contentHash: string;
+        networkId: string;
+        mode: string;
+        createdAt: string;
+    };
+    /**
+     * Artifact with an unsupported version.
+     */
+    unsupportedVersion(): {
+        schema: string;
+        version: string;
+        artifactId: string;
+        contentHash: string;
+        networkId: string;
+        mode: string;
+    };
+};
+
+export { AdversarialFixtures };

package/dist/adversarial-fixtures.js

@@ -0,0 +1,6 @@
+import {
+  AdversarialFixtures
+} from "./chunk-3EK7ATR5.js";
+export {
+  AdversarialFixtures
+};

package/dist/chunk-3EK7ATR5.js

@@ -0,0 +1,152 @@
+// src/adversarial-fixtures.ts
+import { calculateContentHash, CURRENT_HASH_VERSION, ARTIFACT_VERSION } from "@hardkas/artifacts";
+var AdversarialFixtures = {
+  /**
+   * Circular lineage: A -> B -> A
+   */
+  circularLineage() {
+    const artifactA = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      artifactId: "art-a",
+      contentHash: "hash-a",
+      networkId: "simnet",
+      mode: "simulated",
+      lineage: { parentArtifactId: "art-b" }
+    };
+    const artifactB = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      artifactId: "art-b",
+      contentHash: "hash-b",
+      networkId: "simnet",
+      mode: "simulated",
+      lineage: { parentArtifactId: "art-a" }
+    };
+    return { artifactA, artifactB };
+  },
+  /**
+   * Artifact where the contentHash does not match the actual content calculation.
+   */
+  hashMismatch() {
+    const artifact = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      networkId: "simnet",
+      mode: "simulated",
+      amountSompi: "1000",
+      estimatedFeeSompi: "1",
+      estimatedMass: "1",
+      from: { address: "kaspasim:qz0s9xrz5y5e8dq5azmpg756aeepm6fesq82ye7wv" },
+      to: { address: "kaspasim:qq0d6h0prjm5mpdld5pncst3adu0yam6xch9fkr6eg" },
+      inputs: [],
+      outputs: [],
+      hashVersion: CURRENT_HASH_VERSION
+    };
+    const realHash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
+    artifact.contentHash = "f" + realHash.slice(1);
+    artifact.artifactId = `plan-${artifact.contentHash.slice(0, 16)}`;
+    artifact.planId = artifact.artifactId;
+    return artifact;
+  },
+  /**
+   * Artifact with a parent from a different network (Security Violation).
+   */
+  crossNetworkLineage() {
+    const parent = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      artifactId: "parent-mainnet",
+      contentHash: "hash-mainnet",
+      networkId: "mainnet",
+      mode: "l1-rpc"
+    };
+    const child = {
+      schema: "hardkas.signedTx",
+      version: ARTIFACT_VERSION,
+      artifactId: "child-simnet",
+      contentHash: "hash-simnet",
+      networkId: "simnet",
+      mode: "simulated",
+      lineage: {
+        artifactId: "hash-simnet",
+        parentArtifactId: "parent-mainnet",
+        lineageId: "b".repeat(64),
+        rootArtifactId: "c".repeat(64)
+      }
+    };
+    return { parent, child };
+  },
+  /**
+   * Trace with duplicate event IDs (Corruption).
+   */
+  duplicateEventTrace() {
+    return {
+      schema: "hardkas.trace",
+      workflowId: "wf-1",
+      events: [
+        { eventId: "ev-1", kind: "start" },
+        { eventId: "ev-1", kind: "step" }
+        // Duplicate ID
+      ]
+    };
+  },
+  /**
+   * Malformed JSONL snippet (truncated).
+   */
+  malformedJsonl() {
+    return `{"eventId":"ev-1","kind":"start"}
+{"eventId":"ev-2","kind":"step",`;
+  },
+  /**
+   * Lineage with sequence rollback (corrupted history).
+   */
+  sequenceRollback() {
+    const common = {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      networkId: "simnet",
+      mode: "simulated"
+    };
+    return [
+      { ...common, artifactId: "art-1", lineage: { sequenceId: 1, contentHash: "hash-1" } },
+      { ...common, artifactId: "art-2", lineage: { sequenceId: 2, contentHash: "hash-2", parentArtifactId: "art-1" } },
+      { ...common, artifactId: "art-3", lineage: { sequenceId: 2, contentHash: "hash-3-BAD", parentArtifactId: "art-1" } }
+      // Duplicate sequenceId 2
+    ];
+  },
+  /**
+   * Artifact with a future timestamp (anomaly).
+   * Intentionally uses Date.now() to generate a timestamp far in the future.
+   */
+  futureTimestamp() {
+    const farFuture = new Date(Date.now() + 1e3 * 60 * 60 * 24 * 365 * 10).toISOString();
+    return {
+      schema: "hardkas.txPlan",
+      version: ARTIFACT_VERSION,
+      artifactId: "art-future",
+      contentHash: "hash-future",
+      networkId: "simnet",
+      mode: "simulated",
+      createdAt: farFuture
+    };
+  },
+  /**
+   * Artifact with an unsupported version.
+   */
+  unsupportedVersion() {
+    return {
+      schema: "hardkas.txPlan",
+      version: "99.9.9",
+      // Future version
+      artifactId: "art-vnext",
+      contentHash: "hash-vnext",
+      networkId: "simnet",
+      mode: "simulated"
+    };
+  }
+};
+
+export {
+  AdversarialFixtures
+};

package/dist/chunk-CUJL53GG.js

@@ -0,0 +1,90 @@
+// src/harness.ts
+import {
+  createInitialLocalnetState,
+  applySimulatedPayment,
+  getAccountBalanceSompi,
+  createLocalnetSnapshot
+} from "@hardkas/localnet";
+var massRecords = [];
+var massTrackingEnabled = false;
+function enableMassTracking() {
+  massTrackingEnabled = true;
+}
+function disableMassTracking() {
+  massTrackingEnabled = false;
+}
+function getMassRecords() {
+  return [...massRecords];
+}
+function clearMassRecords() {
+  massRecords = [];
+}
+function createTestHarness(config) {
+  const accountCount = config?.accounts ?? 3;
+  const initialBalanceSompi = config?.initialBalance ?? 100000000000n;
+  let currentState = createInitialLocalnetState({
+    accounts: accountCount,
+    initialBalanceSompi
+  });
+  if (config?.networkId) {
+    currentState.networkId = config.networkId;
+  }
+  const initialState = structuredClone(currentState);
+  const harness = {
+    get state() {
+      return currentState;
+    },
+    send(opts) {
+      const preBalance = {
+        from: getAccountBalanceSompi(currentState, opts.from),
+        to: getAccountBalanceSompi(currentState, opts.to)
+      };
+      const result = applySimulatedPayment(currentState, opts);
+      if (result.ok) {
+        currentState = result.state;
+      }
+      const postBalance = {
+        from: getAccountBalanceSompi(currentState, opts.from),
+        to: getAccountBalanceSompi(currentState, opts.to)
+      };
+      if (result.ok && massTrackingEnabled && result.planArtifact) {
+        massRecords.push({
+          txId: result.receipt.txId,
+          inputCount: result.planArtifact.inputs.length,
+          outputCount: result.planArtifact.outputs.length,
+          estimatedMass: BigInt(result.planArtifact.estimatedMass),
+          estimatedFeeSompi: BigInt(result.planArtifact.estimatedFeeSompi),
+          timestamp: Date.now()
+        });
+      }
+      return {
+        ok: result.ok,
+        receipt: result.receipt,
+        plan: result.planArtifact,
+        preBalance,
+        postBalance
+      };
+    },
+    balanceOf(name) {
+      return getAccountBalanceSompi(currentState, name);
+    },
+    accountNames() {
+      return currentState.accounts.map((a) => a.name);
+    },
+    snapshot() {
+      return createLocalnetSnapshot(currentState);
+    },
+    reset() {
+      currentState = structuredClone(initialState);
+    }
+  };
+  return harness;
+}
+
+export {
+  enableMassTracking,
+  disableMassTracking,
+  getMassRecords,
+  clearMassRecords,
+  createTestHarness
+};

package/dist/chunk-UHH25II3.js

@@ -0,0 +1,103 @@
+// src/setup.ts
+import { expect } from "vitest";
+
+// src/matchers.ts
+var hardKasMatchers = {
+  toBeAccepted(received) {
+    const pass = received?.status === "accepted";
+    return {
+      pass,
+      message: () => pass ? `Expected receipt NOT to be accepted, but status is "${received.status}"` : `Expected receipt to be accepted, but status is "${received?.status ?? "undefined"}"`
+    };
+  },
+  toBeFailed(received) {
+    const pass = received?.status === "failed";
+    return {
+      pass,
+      message: () => pass ? `Expected receipt NOT to be failed, but status is "failed"` : `Expected receipt to be failed, but status is "${received?.status ?? "undefined"}"`
+    };
+  },
+  toHaveValidTxId(received) {
+    const txId = received?.txId || (typeof received === "string" ? received : "");
+    const pass = typeof txId === "string" && (txId.startsWith("simtx_") || /^[0-9a-fA-F]{64}$/.test(txId));
+    return {
+      pass,
+      message: () => pass ? `Expected "${txId}" NOT to be a valid txId` : `Expected "${txId}" to be a valid txId (starts with "simtx_" or is 64-char hex)`
+    };
+  },
+  toHaveValidContentHash(received) {
+    const hash = received?.contentHash || (typeof received === "string" ? received : "");
+    const pass = typeof hash === "string" && /^[0-9a-fA-F]{64}$/.test(hash);
+    return {
+      pass,
+      message: () => pass ? `Expected "${hash}" NOT to be a valid content hash` : `Expected "${hash}" to be a valid content hash (64-char hex)`
+    };
+  },
+  toPassLineageCheck(received) {
+    const pass = Array.isArray(received?.lineage) && received.lineage.length > 0;
+    return {
+      pass,
+      message: () => pass ? `Expected artifact NOT to pass lineage check` : `Expected artifact to pass lineage check (missing or empty lineage)`
+    };
+  },
+  toBeBlueBlock(received) {
+    const pass = received?.isBlue === true;
+    return {
+      pass,
+      message: () => pass ? `Expected block NOT to be blue, but it is` : `Expected block to be blue, but it is red or unknown`
+    };
+  },
+  toBeRedBlock(received) {
+    const pass = received?.isBlue === false;
+    return {
+      pass,
+      message: () => pass ? `Expected block NOT to be red, but it is` : `Expected block to be red, but it is blue or unknown`
+    };
+  },
+  toHaveIncreasedBy(received, amount) {
+    const actual = BigInt(received);
+    const pass = actual >= amount;
+    return {
+      pass,
+      message: () => pass ? `Expected increase NOT to be at least ${amount}, but got ${actual}` : `Expected increase to be at least ${amount}, but got ${actual}`
+    };
+  },
+  toHaveDecreasedBy(received, amount) {
+    const actual = BigInt(received);
+    const pass = actual >= amount;
+    return {
+      pass,
+      message: () => pass ? `Expected decrease NOT to be at least ${amount}, but got ${actual}` : `Expected decrease to be at least ${amount}, but got ${actual}`
+    };
+  },
+  toHaveNoRedBlocks(received) {
+    const redBlocks = Object.values(received?.blocks || {}).filter((b) => b.isBlue === false);
+    const pass = redBlocks.length === 0;
+    return {
+      pass,
+      message: () => pass ? `Expected DAG to have red blocks, but it has none` : `Expected DAG to have no red blocks, but found ${redBlocks.length}`
+    };
+  },
+  toHaveDagWidth(received, width) {
+    const allBlockIds = Object.keys(received?.blocks || {});
+    const parentIds = /* @__PURE__ */ new Set();
+    for (const block of Object.values(received?.blocks || {})) {
+      for (const p of block.parents) {
+        parentIds.add(p);
+      }
+    }
+    const tips = allBlockIds.filter((id) => !parentIds.has(id));
+    const pass = tips.length === width;
+    return {
+      pass,
+      message: () => pass ? `Expected DAG NOT to have width ${width}, but it does` : `Expected DAG to have width ${width}, but got ${tips.length}`
+    };
+  }
+};
+
+// src/setup.ts
+expect.extend(hardKasMatchers);
+
+export {
+  hardKasMatchers
+};

package/dist/chunk-WIN7YDBM.js

@@ -0,0 +1,108 @@
+import {
+  createTestHarness
+} from "./chunk-CUJL53GG.js";
+
+// src/reproducibility.ts
+import { calculateContentHash } from "@hardkas/artifacts";
+import { runLinearChain, runWideDag, profileMass } from "@hardkas/simulator";
+function generateReproducibilityReport() {
+  const l1Plan = {
+    schema: "hardkas.txPlan",
+    networkId: "simnet",
+    mode: "simulated",
+    from: { address: "kaspatest:qz0s9xrz5y5e8dq5azmpg756aeepm6fesq82ye7wv" },
+    to: { address: "kaspatest:qq0d6h0prjm5mpdld5pncst3adu0yam6xch9fkr6eg" },
+    amountSompi: "100000000",
+    inputs: [
+      { outpoint: { transactionId: "a".repeat(64), index: 0 }, amountSompi: "200000000" }
+    ],
+    outputs: [
+      { address: "kaspatest:qq0d6h0prjm5mpdld5pncst3adu0yam6xch9fkr6eg", amountSompi: "100000000" },
+      { address: "kaspatest:qz0s9xrz5y5e8dq5azmpg756aeepm6fesq82ye7wv", amountSompi: "99998000" }
+    ],
+    estimatedMass: "2000",
+    estimatedFeeSompi: "2000"
+  };
+  const l1Signed = {
+    schema: "hardkas.signedTx",
+    networkId: "simnet",
+    mode: "simulated",
+    rawTransaction: "0".repeat(128),
+    inputs: l1Plan.inputs,
+    outputs: l1Plan.outputs,
+    mass: "2000",
+    feeSompi: "2000"
+  };
+  const igraPlan = {
+    schema: "hardkas.igraTxPlan.v1",
+    networkId: "simnet",
+    mode: "l2-rpc",
+    l2Network: "igra-devnet",
+    chainId: 42069,
+    request: {
+      from: "0x1234567890123456789012345678901234567890",
+      to: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+      data: "0x",
+      valueWei: "1000000000000000000"
+    },
+    status: "built"
+  };
+  const linearResult = runLinearChain({ name: "repro-linear", blockCount: 10 });
+  const wideResult = runWideDag({ name: "repro-wide", blockCount: 10, k: 18 });
+  const linearTotal = linearResult.metrics.blueBlocks + linearResult.metrics.redBlocks;
+  const linearRedPpm = linearTotal > 0 ? Math.trunc(linearResult.metrics.redBlocks * 1e6 / linearTotal) : 0;
+  const wideTotal = wideResult.metrics.blueBlocks + wideResult.metrics.redBlocks;
+  const wideRedPpm = wideTotal > 0 ? Math.trunc(wideResult.metrics.redBlocks * 1e6 / wideTotal) : 0;
+  const massResult = profileMass({ inputCount: 3, outputCount: 2, payloadBytes: 0, feeRate: 1n });
+  const nestedObj = {
+    z: { b: 2, a: 1 },
+    y: [3, 1, 2],
+    x: null,
+    w: "test",
+    v: 123456789012345678901234567890n
+  };
+  const harness = createTestHarness({ accounts: 3, initialBalance: 100000000000n });
+  const names = harness.accountNames();
+  const txResult = harness.send({
+    from: names[0],
+    to: names[1],
+    amountSompi: 10000000000n
+  });
+  return {
+    proofVersion: "repro-v0",
+    hardkasVersion: "0.3.0-alpha",
+    artifacts: {
+      l1Plan: calculateContentHash(l1Plan),
+      l1Signed: calculateContentHash(l1Signed),
+      igraPlan: calculateContentHash(igraPlan),
+      dagLinearScenario: calculateContentHash({
+        totalBlocks: linearResult.metrics.totalBlocks,
+        blueBlocks: linearResult.metrics.blueBlocks,
+        redBlocks: linearResult.metrics.redBlocks,
+        redRatioPpm: linearRedPpm,
+        selectedChainLength: linearResult.metrics.selectedChainLength
+      }),
+      dagWideScenario: calculateContentHash({
+        totalBlocks: wideResult.metrics.totalBlocks,
+        blueBlocks: wideResult.metrics.blueBlocks,
+        redBlocks: wideResult.metrics.redBlocks,
+        redRatioPpm: wideRedPpm
+      }),
+      massProfile: calculateContentHash({
+        totalMass: massResult.totalMass.toString(),
+        inputMass: massResult.inputMass.toString(),
+        outputMass: massResult.outputMass.toString(),
+        estimatedFeeSompi: massResult.estimatedFeeSompi.toString()
+      }),
+      canonicalNested: calculateContentHash(nestedObj),
+      simulatedTxReceipt: txResult.ok ? calculateContentHash({
+        status: txResult.receipt.status,
+        txId: txResult.receipt.txId
+      }) : "TX_FAILED"
+    }
+  };
+}
+
+export {
+  generateReproducibilityReport
+};

package/dist/harness.d.ts

@@ -0,0 +1,55 @@
+import { LocalnetState } from '@hardkas/localnet';
+
+interface HarnessConfig {
+    accounts?: number | undefined;
+    initialBalance?: bigint | undefined;
+    networkId?: string | undefined;
+    ghostdagK?: number | undefined;
+}
+interface TestHarness {
+    /** The current localnet state. */
+    state: LocalnetState;
+    /** Send KAS from one account to another. Returns the receipt. */
+    send(opts: {
+        from: string;
+        to: string;
+        amountSompi: bigint;
+    }): SendResult;
+    /** Get balance of an account by name (e.g., "alice"). */
+    balanceOf(name: string): bigint;
+    /** Get all account names. */
+    accountNames(): string[];
+    /** Take a snapshot of current state. */
+    snapshot(): any;
+    /** Reset to initial state. */
+    reset(): void;
+}
+interface SendResult {
+    ok: boolean;
+    receipt: any;
+    plan: any;
+    preBalance: {
+        from: bigint;
+        to: bigint;
+    };
+    postBalance: {
+        from: bigint;
+        to: bigint;
+    };
+}
+interface MassRecord {
+    testName?: string;
+    txId: string;
+    inputCount: number;
+    outputCount: number;
+    estimatedMass: bigint;
+    estimatedFeeSompi: bigint;
+    timestamp: number;
+}
+declare function enableMassTracking(): void;
+declare function disableMassTracking(): void;
+declare function getMassRecords(): MassRecord[];
+declare function clearMassRecords(): void;
+declare function createTestHarness(config?: HarnessConfig): TestHarness;
+
+export { type HarnessConfig, type MassRecord, type SendResult, type TestHarness, clearMassRecords, createTestHarness, disableMassTracking, enableMassTracking, getMassRecords };

package/dist/harness.js

@@ -0,0 +1,14 @@
+import {
+  clearMassRecords,
+  createTestHarness,
+  disableMassTracking,
+  enableMassTracking,
+  getMassRecords
+} from "./chunk-CUJL53GG.js";
+export {
+  clearMassRecords,
+  createTestHarness,
+  disableMassTracking,
+  enableMassTracking,
+  getMassRecords
+};

package/dist/index.d.ts

@@ -1,69 +1,100 @@
-import { Hardkas } from '@hardkas/sdk';
-import { CoreEvent, NetworkId } from '@hardkas/core';
-import { BaseArtifact } from '@hardkas/artifacts';
+import { TestHarness } from './harness.js';
+export { HarnessConfig, SendResult, clearMassRecords, createTestHarness, disableMassTracking, enableMassTracking, getMassRecords } from './harness.js';
+export { ReproducibilityReport, generateReproducibilityReport } from './reproducibility.js';
+export { AdversarialFixtures } from './adversarial-fixtures.js';
+import '@hardkas/localnet';
 
-/**
- * System Invariant Verifiers
- *
- * Instead of just unit tests, these provide "System Guarantees".
- */
-declare const Invariants: {
-    /**
-     * Guarantee: An artifact's content hash MUST match its current state.
-     */
-    verifyArtifactIntegrity(artifact: BaseArtifact<any>, calculateHash: (a: any) => string): Promise<boolean>;
-    /**
-     * Guarantee: A Lineage chain MUST be strictly monotonic and linked.
-     */
-    verifyLineageContinuity(artifacts: BaseArtifact<any>[]): boolean;
-    /**
-     * Guarantee: Every emission to the event bus MUST have a timestamp.
-     */
-    verifyEventCompliance(event: CoreEvent): boolean;
-};
-/**
- * Invariant Watcher
- * Can be hooked into the event bus to detect violations in real-time.
- */
-declare class InvariantWatcher {
-    private violations;
-    constructor();
-    getViolations(): string[];
-    hasViolations(): boolean;
-}
-
-interface FuzzResult {
-    ok: boolean;
-    iterations: number;
-    violations: string[];
+interface FixtureDefinition {
+    name: string;
+    accounts?: number;
+    initialBalance?: bigint;
+    /** Pre-run transactions to set up state. */
+    setup?: Array<{
+        from: string;
+        to: string;
+        amountSompi: bigint;
+    }>;
 }
 /**
- * Custom Scenario Fuzzer for UTXO Invariants.
- * Verifies that sum(inputs) == sum(outputs) + fee across random transaction sequences.
+ * Create a fixture — a pre-configured harness with setup transactions already applied.
  */
-declare function runUtxoFuzzer(iterations?: number): Promise<FuzzResult>;
+declare function createFixture(def: FixtureDefinition): TestHarness;
 
-/**
- * HardKAS Testing Runtime
- */
-interface HardkasTestRuntime {
-    readonly hardkas: Hardkas;
-    readonly network: NetworkId;
-    readonly accounts: Hardkas["accounts"];
-    readonly tx: Hardkas["tx"];
-    readonly localnet: Hardkas["localnet"];
-    readonly query: Hardkas["query"];
+interface HardKasMatchers<R = void> {
+    /** Assert a receipt has status "accepted". */
+    toBeAccepted(): R;
+    /** Assert a receipt has status "failed". */
+    toBeFailed(): R;
+    /** Assert a receipt contains a valid txId (starts with "simtx_" or is 64-char hex). */
+    toHaveValidTxId(): R;
+    /** Assert an artifact has a valid contentHash (64-char hex). */
+    toHaveValidContentHash(): R;
+    /** Assert an artifact passes lineage verification. */
+    toPassLineageCheck(): R;
+    /** Assert a GHOSTDAG result colors this block as blue. */
+    toBeBlueBlock(): R;
+    /** Assert a GHOSTDAG result colors this block as red. */
+    toBeRedBlock(): R;
+    /** Assert a balance (bigint sompi) increased by at least `amount`. */
+    toHaveIncreasedBy(amount: bigint): R;
+    /** Assert a balance (bigint sompi) decreased by at least `amount`. */
+    toHaveDecreasedBy(amount: bigint): R;
+    /** Assert a simulated DAG has no red blocks. */
+    toHaveNoRedBlocks(): R;
+    /** Assert a simulated DAG has exactly N tips. */
+    toHaveDagWidth(width: number): R;
 }
-interface HardkasTestOptions {
-    cwd?: string;
-    network?: NetworkId;
-    autoStartLocalnet?: boolean;
-    resetBetweenTests?: boolean;
+declare module "vitest" {
+    interface Assertion<T = any> extends HardKasMatchers<T> {
+    }
+    interface AsymmetricMatchersContaining extends HardKasMatchers {
+    }
 }
-/**
- * The main helper for HardKAS tests.
- * Injects hooks for Vitest and provides access to the SDK.
- */
-declare function hardkasTest(options?: HardkasTestOptions): HardkasTestRuntime;
+declare const hardKasMatchers: {
+    toBeAccepted(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toBeFailed(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveValidTxId(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveValidContentHash(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toPassLineageCheck(received: any): {
+        pass: boolean;
+        message: () => "Expected artifact NOT to pass lineage check" | "Expected artifact to pass lineage check (missing or empty lineage)";
+    };
+    toBeBlueBlock(received: any): {
+        pass: boolean;
+        message: () => "Expected block NOT to be blue, but it is" | "Expected block to be blue, but it is red or unknown";
+    };
+    toBeRedBlock(received: any): {
+        pass: boolean;
+        message: () => "Expected block NOT to be red, but it is" | "Expected block to be red, but it is blue or unknown";
+    };
+    toHaveIncreasedBy(received: any, amount: bigint): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveDecreasedBy(received: any, amount: bigint): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveNoRedBlocks(received: any): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHaveDagWidth(received: any, width: number): {
+        pass: boolean;
+        message: () => string;
+    };
+};
 
-export { type FuzzResult, type HardkasTestOptions, type HardkasTestRuntime, InvariantWatcher, Invariants, hardkasTest, runUtxoFuzzer };
+export { type FixtureDefinition, type HardKasMatchers, TestHarness, createFixture, hardKasMatchers };

package/dist/index.js

@@ -1,170 +1,45 @@
-// src/index.ts
-import { Hardkas } from "@hardkas/sdk";
-import { beforeAll, beforeEach } from "vitest";
+import {
+  AdversarialFixtures
+} from "./chunk-3EK7ATR5.js";
+import {
+  generateReproducibilityReport
+} from "./chunk-WIN7YDBM.js";
+import {
+  clearMassRecords,
+  createTestHarness,
+  disableMassTracking,
+  enableMassTracking,
+  getMassRecords
+} from "./chunk-CUJL53GG.js";
+import {
+  hardKasMatchers
+} from "./chunk-UHH25II3.js";
 
-// src/invariants.ts
-import { coreEvents } from "@hardkas/core";
-var Invariants = {
-  /**
-   * Guarantee: An artifact's content hash MUST match its current state.
-   */
-  async verifyArtifactIntegrity(artifact, calculateHash) {
-    if (!artifact.contentHash) return true;
-    const actual = calculateHash(artifact);
-    return artifact.contentHash === actual;
-  },
-  /**
-   * Guarantee: A Lineage chain MUST be strictly monotonic and linked.
-   */
-  verifyLineageContinuity(artifacts) {
-    if (artifacts.length < 2) return true;
-    const sorted = [...artifacts].sort(
-      (a, b) => (a.lineage?.sequence ?? 0) - (b.lineage?.sequence ?? 0)
-    );
-    for (let i = 1; i < sorted.length; i++) {
-      const prev = sorted[i - 1];
-      const curr = sorted[i];
-      if (!prev || !curr) continue;
-      if (curr.lineage?.parentArtifactId !== prev.lineage?.artifactId) {
-        return false;
-      }
-      if (curr.lineage?.lineageId !== prev.lineage?.lineageId) {
-        return false;
-      }
-    }
-    return true;
-  },
-  /**
-   * Guarantee: Every emission to the event bus MUST have a timestamp.
-   */
-  verifyEventCompliance(event) {
-    return !!event.timestamp;
-  }
-};
-var InvariantWatcher = class {
-  violations = [];
-  constructor() {
-    coreEvents.on((event) => {
-      if (!Invariants.verifyEventCompliance(event)) {
-        this.violations.push(`Event compliance violation: ${event.kind}`);
-      }
-      if (event.kind === "integrity.hash_mismatch") {
-        const payload = event.payload;
-        this.violations.push(`Hash mismatch detected: ${payload.artifactId || event.artifactId}`);
-      }
-    });
-  }
-  getViolations() {
-    return this.violations;
-  }
-  hasViolations() {
-    return this.violations.length > 0;
-  }
-};
-
-// src/utxo-fuzzer.ts
-import { SOMPI_PER_KAS } from "@hardkas/core";
-import { buildPaymentPlan } from "@hardkas/tx-builder";
-import { applySimulatedPayment, createInitialLocalnetState } from "@hardkas/localnet";
-async function runUtxoFuzzer(iterations = 50) {
-  let state = createInitialLocalnetState({ accounts: 5, initialBalanceSompi: 1000n * SOMPI_PER_KAS });
-  const violations = [];
-  for (let i = 0; i < iterations; i++) {
-    const fromIdx = Math.floor(Math.random() * state.accounts.length);
-    let toIdx = Math.floor(Math.random() * state.accounts.length);
-    if (fromIdx === toIdx) toIdx = (toIdx + 1) % state.accounts.length;
-    const fromAccount = state.accounts[fromIdx];
-    const toAccount = state.accounts[toIdx];
-    const amountSompi = BigInt(Math.floor(Math.random() * 10)) * SOMPI_PER_KAS + BigInt(Math.floor(Math.random() * 1e6));
-    try {
-      const unspent = state.utxos.filter((u) => u.address === fromAccount.address && !u.spent);
-      if (unspent.length === 0) continue;
-      const builderUtxos = unspent.map((u) => ({
-        outpoint: { transactionId: u.id.split(":")[0], index: 0 },
-        address: u.address,
-        amountSompi: BigInt(u.amountSompi),
-        scriptPublicKey: "mock"
-      }));
-      const plan = buildPaymentPlan({
-        fromAddress: fromAccount.address,
-        availableUtxos: builderUtxos,
-        outputs: [{ address: toAccount.address, amountSompi }],
-        feeRateSompiPerMass: 1n
-      });
-      const inputSum = plan.inputs.reduce((s, x) => s + x.amountSompi, 0n);
-      const outputSum = plan.outputs.reduce((s, x) => s + x.amountSompi, 0n) + (plan.change?.amountSompi || 0n);
-      const fee = plan.estimatedFeeSompi;
-      if (inputSum !== outputSum + fee) {
-        violations.push(`Iteration ${i}: Planning Invariant Violated! ${inputSum} != ${outputSum} + ${fee}`);
-      }
-      const result = applySimulatedPayment(state, {
-        from: fromAccount.name,
-        to: toAccount.name,
-        amountSompi
-      });
-      state = result.state;
-      const totalInState = state.utxos.filter((u) => !u.spent).reduce((s, x) => s + BigInt(x.amountSompi), 0n);
-      const expectedTotal = BigInt(state.accounts.length) * 1000n * SOMPI_PER_KAS - BigInt(i + 1) * fee;
-      const utxoIds = state.utxos.map((u) => u.id);
-      const uniqueIds = new Set(utxoIds);
-      if (utxoIds.length !== uniqueIds.size) {
-        violations.push(`Iteration ${i}: Duplicate UTXO IDs detected in state!`);
-      }
-    } catch (e) {
-      if (!e.message.includes("Insufficient funds")) {
-        violations.push(`Iteration ${i}: Unexpected Error: ${e.message}`);
+// src/fixtures.ts
+function createFixture(def) {
+  const config = {
+    accounts: def.accounts,
+    initialBalance: def.initialBalance
+  };
+  const harness = createTestHarness(config);
+  if (def.setup) {
+    for (const tx of def.setup) {
+      const result = harness.send(tx);
+      if (!result.ok) {
+        throw new Error(`Fixture "${def.name}" failed during setup: ${tx.from} -> ${tx.to} (${tx.amountSompi} sompi). Error: ${result.receipt?.errors?.join(", ") || "Unknown error"}`);
       }
     }
   }
-  return {
-    ok: violations.length === 0,
-    iterations,
-    violations
-  };
-}
-
-// src/index.ts
-function hardkasTest(options = {}) {
-  const cwd = options.cwd || process.env.HARDKAS_CWD || ".";
-  const network = options.network || process.env.HARDKAS_NETWORK || "simnet";
-  const autoStart = options.autoStartLocalnet ?? true;
-  const autoReset = options.resetBetweenTests ?? true;
-  let sdk;
-  beforeAll(async () => {
-    sdk = await Hardkas.open(cwd);
-    if (autoStart && network === "simnet") {
-      await sdk.localnet.start();
-    }
-  });
-  beforeEach(async () => {
-    if (autoReset && network === "simnet") {
-      await sdk.localnet.reset();
-    }
-  });
-  return {
-    get hardkas() {
-      return sdk;
-    },
-    get network() {
-      return network;
-    },
-    get accounts() {
-      return sdk.accounts;
-    },
-    get tx() {
-      return sdk.tx;
-    },
-    get localnet() {
-      return sdk.localnet;
-    },
-    get query() {
-      return sdk.query;
-    }
-  };
+  return harness;
 }
 export {
-  InvariantWatcher,
-  Invariants,
-  hardkasTest,
-  runUtxoFuzzer
+  AdversarialFixtures,
+  clearMassRecords,
+  createFixture,
+  createTestHarness,
+  disableMassTracking,
+  enableMassTracking,
+  generateReproducibilityReport,
+  getMassRecords,
+  hardKasMatchers
 };

package/dist/mass-setup.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/mass-setup.js

@@ -0,0 +1,8 @@
+import {
+  enableMassTracking
+} from "./chunk-CUJL53GG.js";
+
+// src/mass-setup.ts
+if (process.env.HARDKAS_MASS_TRACKING === "1") {
+  enableMassTracking();
+}

package/dist/reproducibility.d.ts

@@ -0,0 +1,24 @@
+interface ReproducibilityReport {
+    /** Fixed proof version — does NOT change between releases. */
+    proofVersion: "repro-v0";
+    /** Informational only — NOT part of hash comparison. */
+    hardkasVersion: string;
+    artifacts: {
+        l1Plan: string;
+        l1Signed: string;
+        igraPlan: string;
+        dagLinearScenario: string;
+        dagWideScenario: string;
+        massProfile: string;
+        canonicalNested: string;
+        simulatedTxReceipt: string;
+    };
+}
+/**
+ * Generate the reproducibility report.
+ * This function MUST be fully deterministic.
+ * Same code version → same output → always → everywhere.
+ */
+declare function generateReproducibilityReport(): ReproducibilityReport;
+
+export { type ReproducibilityReport, generateReproducibilityReport };

package/dist/reproducibility.js

@@ -0,0 +1,7 @@
+import {
+  generateReproducibilityReport
+} from "./chunk-WIN7YDBM.js";
+import "./chunk-CUJL53GG.js";
+export {
+  generateReproducibilityReport
+};

package/dist/setup.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/setup.js

@@ -0,0 +1 @@
+import "./chunk-UHH25II3.js";

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "@hardkas/testing",
-  "version": "0.2.2-alpha.1",
+  "version": "0.3.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/index.js",
+    "./harness": "./dist/harness.js",
+    "./setup": "./dist/setup.js",
+    "./adversarial-fixtures": "./dist/adversarial-fixtures.js",
+    "./mass-setup": "./dist/mass-setup.js"
   },
   "dependencies": {
-    "@hardkas/artifacts": "0.2.2-alpha.1",
-    "@hardkas/sdk": "0.2.2-alpha.1",
-    "@hardkas/kaspa-rpc": "0.2.2-alpha.1",
-    "@hardkas/core": "0.2.2-alpha.1",
-    "@hardkas/localnet": "0.2.2-alpha.1",
-    "@hardkas/simulator": "0.2.2-alpha.1",
-    "@hardkas/tx-builder": "0.2.2-alpha.1"
+    "@hardkas/artifacts": "0.3.0-alpha",
+    "@hardkas/kaspa-rpc": "0.3.0-alpha",
+    "@hardkas/localnet": "0.3.0-alpha",
+    "@hardkas/core": "0.3.0-alpha",
+    "@hardkas/tx-builder": "0.3.0-alpha",
+    "@hardkas/query-store": "0.3.0-alpha",
+    "@hardkas/simulator": "0.3.0-alpha",
+    "@hardkas/sdk": "0.3.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -38,8 +43,9 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --external vitest",
-    "test": "vitest run",
+    "build": "tsup src/index.ts src/harness.ts src/setup.ts src/reproducibility.ts src/adversarial-fixtures.ts src/mass-setup.ts --format esm --dts --clean --external vitest",
+    "test": "vitest run && pnpm test:gauntlet",
+    "test:gauntlet": "node --import tsx --test test/gauntlet.node.ts",
     "typecheck": "tsc --noEmit",
     "lint": "eslint ."
   }