@hardkas/artifacts 0.2.2-alpha.1 → 0.4.0-alpha

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { ArtifactType, NetworkId, ExecutionMode, ContentHash, WorkflowId, ArtifactId, LineageId, EventSequence, KaspaAddress, TxId, EventEnvelope } from '@hardkas/core';
+import { ArtifactType, NetworkId, ExecutionMode, ContentHash, WorkflowId, ArtifactId, LineageId, EventSequence, TxId, KaspaAddress, CorruptionCode, CorruptionSeverity, EventEnvelope } from '@hardkas/core';
 import { z } from 'zod';
 import { TxOutput, Utxo, TxPlan as TxPlan$1 } from '@hardkas/tx-builder';
 
-declare const HARDKAS_VERSION = "0.2.2-alpha.1";
+declare const HARDKAS_VERSION = "0.4.0-alpha";
 declare const ARTIFACT_SCHEMAS: {
     readonly LOCALNET_STATE: "hardkas.localnetState.v1";
     readonly REAL_ACCOUNT_STORE: "hardkas.realAccountStore.v1";
@@ -1058,6 +1058,7 @@ type Snapshot = z.infer<typeof SnapshotSchema>;
 type TxReceipt = z.infer<typeof TxReceiptSchema>;
 type SignedTx = z.infer<typeof SignedTxSchema>;
 type TxTrace = z.infer<typeof TxTraceSchema>;
+type DagContext$1 = z.infer<typeof DagContextSchema>;
 
 interface ArtifactValidationResult {
     ok: boolean;
@@ -1385,18 +1386,70 @@ interface TxTraceArtifact extends BaseArtifact<"txTrace"> {
     dagContext?: DagContext | undefined;
 }
 
+interface DeploymentRecord extends HardkasArtifactBase {
+    schema: "hardkas.deployment.v1";
+    /** Human-readable label (e.g., "initial-funding", "vault-covenant-v1") */
+    label: string;
+    /** Network where this was deployed */
+    networkId: NetworkId;
+    /** Deployment status */
+    status: "planned" | "sent" | "confirmed" | "failed" | "unknown";
+    /** The transaction ID (if sent) */
+    txId?: TxId;
+    /** Reference to the plan artifact that produced this deployment */
+    planArtifactId?: ArtifactId;
+    /** Reference to the receipt artifact (if confirmed) */
+    receiptArtifactId?: ArtifactId;
+    /** Deployed addresses or outputs (for covenant/contract deployments) */
+    deployedAddresses?: string[];
+    /** Deployment metadata */
+    deployer?: string;
+    /** Content hash of the deployed payload (bytecode, script, or tx content) */
+    payloadHash?: string;
+    /** Timestamp of deployment */
+    deployedAt: string;
+    /** HardKAS version used */
+    hardkasVersion: string;
+    /** Canonical content hash of this record */
+    contentHash?: ContentHash;
+    /** Notes */
+    notes?: string;
+}
+interface DeploymentIndex extends HardkasArtifactBase {
+    schema: "hardkas.deploymentIndex.v1";
+    networkId: NetworkId;
+    deployments: DeploymentSummary[];
+    lastUpdated: string;
+}
+interface DeploymentSummary {
+    label: string;
+    networkId: NetworkId;
+    status: string;
+    txId?: string;
+    deployedAt: string;
+    contentHash: string;
+}
+
+declare const SEMANTIC_EXCLUSIONS: Set<string>;
+/**
+ * Current canonicalization version.
+ * v1: BigInt(123) -> "123" (Collision with String "123")
+ * v2: BigInt(123) -> "n:123" (Distinguishable)
+ * v3: String normalization (\r\n -> \n, NFC) for cross-platform stability.
+ */
+declare const CURRENT_HASH_VERSION = 3;
 /**
  * Deterministically stringifies an object by sorting keys recursively.
- * Handles BigInt by converting to string.
- * Excludes 'contentHash', 'artifactId', and 'lineage' fields during serialization.
+ * Handles BigInt by converting to string with type marker.
+ * Excludes fields in SEMANTIC_EXCLUSIONS during serialization.
  * Skips keys with undefined values (matching JSON.stringify behavior).
  */
-declare function canonicalStringify(obj: any): string;
+declare function canonicalStringify(obj: any, version?: number): string;
 /**
  * Calculates a SHA-256 hash of the canonical JSON representation.
- * Always excludes the 'contentHash' field from the calculation.
+ * Always excludes fields in SEMANTIC_EXCLUSIONS from the calculation.
  */
-declare function calculateContentHash(obj: any): string;
+declare function calculateContentHash(obj: any, version?: number): string;
 
 interface Clock {
     now(): number;
@@ -1408,12 +1461,13 @@ interface VerificationContext {
     networkId?: NetworkId;
     parent?: unknown;
 }
-type VerificationSeverity = "info" | "warning" | "error" | "critical";
+type VerificationSeverity = CorruptionSeverity | "info" | "critical";
 type VerificationIssue = {
-    code: string;
+    code: CorruptionCode | string;
     severity: VerificationSeverity;
     message: string;
     path?: string | undefined;
+    pathStr?: string | undefined;
     artifactId?: string | undefined;
 };
 type ArtifactVerificationResult = {
@@ -1428,7 +1482,7 @@ type ArtifactVerificationResult = {
 /**
  * Sorts UTXOs deterministically by outpoint (transactionId:index).
  */
-declare function sortUtxosByOutpoint(utxos: unknown[]): unknown[];
+declare function sortUtxosByOutpoint<T>(utxos: T[]): T[];
 /**
  * Verifies an artifact's integrity.
  * Can take a raw object or a file path.
@@ -1440,9 +1494,9 @@ declare function verifyArtifactIntegrity(artifactOrPath: unknown): Promise<Artif
 declare function verifyArtifactSemantics(artifact: unknown, context?: VerificationContext): ArtifactVerificationResult;
 /**
  * Verifies an artifact's replay consistency.
- * Contract/Stub for Phase 4.
+ * Honest implementation: reports as unsupported or not implemented.
  */
-declare function verifyArtifactReplay(artifact: unknown, context?: VerificationContext): Promise<ArtifactVerificationResult>;
+declare function verifyArtifactReplay(artifact: unknown, _context?: VerificationContext): Promise<ArtifactVerificationResult>;
 /**
  * @deprecated Use verifyArtifactIntegrity instead.
  */
@@ -1651,6 +1705,9 @@ declare function createSimulatedTxReceipt(plan: TxPlan, txId: string, extra?: {
     spentUtxoIds?: string[];
     createdUtxoIds?: string[];
     daaScore?: string;
+    preStateHash?: string;
+    postStateHash?: string;
+    dagContext?: DagContext$1;
 }): TxReceipt;
 /**
  * Validates and extracts the raw transaction from a signed artifact.
@@ -1748,9 +1805,53 @@ interface LineageValidationResult {
     ok: boolean;
     issues: VerificationIssue[];
 }
+interface LineageOptions {
+    strict?: boolean;
+}
 /**
  * Validates the lineage relationship between an artifact and its parent.
  */
-declare function verifyLineage(artifact: any, parent?: any): LineageValidationResult;
+declare function verifyLineage(artifact: any, parent?: any, options?: LineageOptions): LineageValidationResult;
+
+interface DiffEntry {
+    path: string;
+    kind: "added" | "removed" | "changed";
+    left?: any;
+    right?: any;
+}
+interface ArtifactDiff {
+    identical: boolean;
+    entries: DiffEntry[];
+}
+/**
+ * Performs a semantic diff between two artifacts, ignoring volatile metadata.
+ * Uses the same exclusion rules as canonical hashing.
+ * Redacts secrets from the output.
+ */
+declare function diffArtifacts(left: any, right: any): ArtifactDiff;
+
+declare function createDeploymentRecord(opts: {
+    label: string;
+    networkId: NetworkId;
+    status?: "planned" | "sent" | "confirmed" | "failed" | "unknown";
+    txId?: TxId;
+    planArtifactId?: ArtifactId;
+    receiptArtifactId?: ArtifactId;
+    deployedAddresses?: string[];
+    deployer?: string;
+    payloadHash?: string;
+    notes?: string;
+}): DeploymentRecord;
+declare function updateDeploymentStatus(record: DeploymentRecord, newStatus: DeploymentRecord["status"], txId?: TxId): DeploymentRecord;
+
+/**
+ * Manages deployment records on the filesystem.
+ * Storage: .hardkas/deployments/<networkId>/<label>.json
+ */
+declare function saveDeployment(rootDir: string, record: DeploymentRecord): Promise<string>;
+declare function loadDeployment(rootDir: string, networkId: string, label: string): Promise<DeploymentRecord | null>;
+declare function listDeployments(rootDir: string, networkId?: string): Promise<DeploymentSummary[]>;
+declare function updateDeployment(rootDir: string, networkId: string, label: string, update: Partial<DeploymentRecord>): Promise<DeploymentRecord>;
+declare function deleteDeployment(rootDir: string, networkId: string, label: string): Promise<boolean>;
 
-export { ARTIFACT_SCHEMAS, ARTIFACT_VERSION, AccountRefSchema, type ArtifactExplanation, ArtifactLineageSchema, type ArtifactLookup, type ArtifactValidationResult, type ArtifactVerificationResult, type AssumptionLevel, type BaseArtifact, BaseArtifactSchema, BasicCorrelationInvariant, BasicLineageInvariant, type Clock, type CreateTxPlanArtifactOptions, type DagContext, DagContextSchema, type FeeAuditResult, HARDKAS_VERSION, type HardkasArtifactBase, type HardkasArtifactMode, type HardkasArtifactSchema, HashInvariant, type IgraSignedTxArtifact, type IgraTxPlanArtifact, type IgraTxReceiptArtifact, type IgraTxRequestArtifact, type Invariant, type InvariantContext, type InvariantViolation, InvariantWatcher, LifecycleInvariant, type LineageValidationResult, LocalnetUtxoSchemaV2, NetworkInvariant, ReplayInvariant, SchemaInvariant, type SignedTx, type SignedTxArtifact, type SignedTxArtifactV1, SignedTxSchema, type Snapshot, type SnapshotArtifact, SnapshotSchema, type TxOutputArtifact, type TxPlan, type TxPlanArtifact, type TxPlanArtifactV1, TxPlanSchema, type TxReceipt, type TxReceiptArtifact, type TxReceiptArtifactV1, TxReceiptSchema, type TxTrace, type TxTraceArtifact, type TxTraceArtifactV1, TxTraceSchema, type UtxoArtifact, type VerificationContext, type VerificationIssue, type VerificationSeverity, type WatcherOptions, assertDecimalBigIntString, assertEvmAddress, assertEvmTxHash, assertHexData, assertValidIgraSignedTxArtifact, assertValidIgraTxPlanArtifact, assertValidIgraTxReceiptArtifact, assertValidSignedTxArtifact, assertValidTxPlanArtifact, assertValidTxReceiptArtifact, bigIntReplacer, calculateContentHash, canonicalStringify, createIgraDeployPlanId, createIgraPlanId, createIgraSignedId, createSimulatedSignedTxArtifact, createSimulatedTxReceipt, createTxPlanArtifact, defaultClock, explainArtifact, formatSignedTxArtifact, formatTxPlanArtifact, formatTxReceiptArtifact, getBroadcastableSignedTransaction, getDefaultL2ReceiptsDir, getDefaultReceiptPath, getL2ReceiptPath, isIgraTxPlanArtifact, listIgraTxReceiptArtifacts, loadIgraTxReceiptArtifact, migrateToCanonical, readArtifact, readSignedTxArtifact, readTxPlanArtifact, readTxReceiptArtifact, recomputeMass, saveIgraTxReceiptArtifact, sortUtxosByOutpoint, txOutputFromArtifact, txOutputToArtifact, utxoFromArtifact, utxoToArtifact, validateArtifact, validateIgraSignedTxArtifact, validateIgraTxPlanArtifact, validateIgraTxReceiptArtifact, validateSignedTxArtifact, validateTxPlanArtifact, validateTxReceiptArtifact, verifyArtifact, verifyArtifactFile, verifyArtifactIntegrity, verifyArtifactReplay, verifyArtifactSemantics, verifyFeeSemantics, verifyLineage, writeArtifact };
+export { ARTIFACT_SCHEMAS, ARTIFACT_VERSION, AccountRefSchema, type ArtifactDiff, type ArtifactExplanation, ArtifactLineageSchema, type ArtifactLookup, type ArtifactValidationResult, type ArtifactVerificationResult, type AssumptionLevel, type BaseArtifact, BaseArtifactSchema, BasicCorrelationInvariant, BasicLineageInvariant, CURRENT_HASH_VERSION, type Clock, type CreateTxPlanArtifactOptions, type DagContext, DagContextSchema, type DeploymentIndex, type DeploymentRecord, type DeploymentSummary, type DiffEntry, type FeeAuditResult, HARDKAS_VERSION, type HardkasArtifactBase, type HardkasArtifactMode, type HardkasArtifactSchema, HashInvariant, type IgraSignedTxArtifact, type IgraTxPlanArtifact, type IgraTxReceiptArtifact, type IgraTxRequestArtifact, type Invariant, type InvariantContext, type InvariantViolation, InvariantWatcher, LifecycleInvariant, type LineageOptions, type LineageValidationResult, LocalnetUtxoSchemaV2, NetworkInvariant, ReplayInvariant, SEMANTIC_EXCLUSIONS, SchemaInvariant, type SignedTx, type SignedTxArtifact, type SignedTxArtifactV1, SignedTxSchema, type Snapshot, type SnapshotArtifact, SnapshotSchema, type TxOutputArtifact, type TxPlan, type TxPlanArtifact, type TxPlanArtifactV1, TxPlanSchema, type TxReceipt, type TxReceiptArtifact, type TxReceiptArtifactV1, TxReceiptSchema, type TxTrace, type TxTraceArtifact, type TxTraceArtifactV1, TxTraceSchema, type UtxoArtifact, type VerificationContext, type VerificationIssue, type VerificationSeverity, type WatcherOptions, assertDecimalBigIntString, assertEvmAddress, assertEvmTxHash, assertHexData, assertValidIgraSignedTxArtifact, assertValidIgraTxPlanArtifact, assertValidIgraTxReceiptArtifact, assertValidSignedTxArtifact, assertValidTxPlanArtifact, assertValidTxReceiptArtifact, bigIntReplacer, calculateContentHash, canonicalStringify, createDeploymentRecord, createIgraDeployPlanId, createIgraPlanId, createIgraSignedId, createSimulatedSignedTxArtifact, createSimulatedTxReceipt, createTxPlanArtifact, defaultClock, deleteDeployment, diffArtifacts, explainArtifact, formatSignedTxArtifact, formatTxPlanArtifact, formatTxReceiptArtifact, getBroadcastableSignedTransaction, getDefaultL2ReceiptsDir, getDefaultReceiptPath, getL2ReceiptPath, isIgraTxPlanArtifact, listDeployments, listIgraTxReceiptArtifacts, loadDeployment, loadIgraTxReceiptArtifact, migrateToCanonical, readArtifact, readSignedTxArtifact, readTxPlanArtifact, readTxReceiptArtifact, recomputeMass, saveDeployment, saveIgraTxReceiptArtifact, sortUtxosByOutpoint, txOutputFromArtifact, txOutputToArtifact, updateDeployment, updateDeploymentStatus, utxoFromArtifact, utxoToArtifact, validateArtifact, validateIgraSignedTxArtifact, validateIgraTxPlanArtifact, validateIgraTxReceiptArtifact, validateSignedTxArtifact, validateTxPlanArtifact, validateTxReceiptArtifact, verifyArtifact, verifyArtifactFile, verifyArtifactIntegrity, verifyArtifactReplay, verifyArtifactSemantics, verifyFeeSemantics, verifyLineage, writeArtifact };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/constants.ts
-var HARDKAS_VERSION = "0.2.2-alpha.1";
+var HARDKAS_VERSION = "0.4.0-alpha";
 var ARTIFACT_SCHEMAS = {
   LOCALNET_STATE: "hardkas.localnetState.v1",
   REAL_ACCOUNT_STORE: "hardkas.realAccountStore.v1",
@@ -133,42 +133,52 @@ function createIgraDeployPlanId(hash) {
 
 // src/canonical.ts
 import { createHash } from "crypto";
-function canonicalStringify(obj) {
+var SEMANTIC_EXCLUSIONS = /* @__PURE__ */ new Set([
+  "contentHash",
+  "artifactId",
+  "planId",
+  "lineage",
+  "createdAt",
+  "rpcUrl",
+  "indexedAt",
+  "file_path",
+  "file_mtime_ms",
+  "hardkasVersion",
+  "hashVersion",
+  // Exclude hash version from hash
+  "parentArtifactId",
+  "signedId",
+  "deployedAt"
+]);
+var CURRENT_HASH_VERSION = 3;
+function canonicalStringify(obj, version = CURRENT_HASH_VERSION) {
   if (obj === null || typeof obj !== "object") {
     if (typeof obj === "bigint") {
-      return obj.toString();
+      if (version >= 2) {
+        return JSON.stringify(`n:${obj.toString()}`);
+      }
+      return JSON.stringify(obj.toString());
+    }
+    if (typeof obj === "string" && version >= 3) {
+      const normalized = obj.normalize("NFC").replace(/\r\n/g, "\n");
+      return JSON.stringify(normalized);
     }
     return JSON.stringify(obj);
   }
   if (Array.isArray(obj)) {
-    return "[" + obj.map((item) => canonicalStringify(item)).join(",") + "]";
-  }
-  const SEMANTIC_EXCLUSIONS = /* @__PURE__ */ new Set([
-    "contentHash",
-    "artifactId",
-    "planId",
-    "lineage",
-    "createdAt",
-    "rpcUrl",
-    "indexedAt",
-    "file_path",
-    "file_mtime_ms",
-    "hardkasVersion",
-    "version",
-    "parentArtifactId",
-    "signedId"
-  ]);
+    return "[" + obj.map((item) => canonicalStringify(item, version)).join(",") + "]";
+  }
   const sortedKeys = Object.keys(obj).filter(
     (key) => !SEMANTIC_EXCLUSIONS.has(key) && obj[key] !== void 0
   ).sort();
   const result = sortedKeys.map((key) => {
     const value = obj[key];
-    return JSON.stringify(key) + ":" + canonicalStringify(value);
+    return JSON.stringify(key) + ":" + canonicalStringify(value, version);
   }).join(",");
   return "{" + result + "}";
 }
-function calculateContentHash(obj) {
-  const canonical = canonicalStringify(obj);
+function calculateContentHash(obj, version = CURRENT_HASH_VERSION) {
+  const canonical = canonicalStringify(obj, version);
   return createHash("sha256").update(canonical).digest("hex");
 }
 
@@ -397,14 +407,15 @@ function verifyFeeSemantics(artifact) {
 }
 
 // src/lineage.ts
-function verifyLineage(artifact, parent) {
+function verifyLineage(artifact, parent, options = {}) {
   const issues = [];
   const addIssue = (code, message, severity = "error") => {
     issues.push({ code, severity, message });
   };
   const lineage = artifact.lineage;
   if (!lineage) {
-    addIssue("MISSING_LINEAGE", "Artifact has no lineage metadata", "warning");
+    const severity = options.strict ? "error" : "warning";
+    addIssue("MISSING_LINEAGE", "Artifact has no lineage metadata", severity);
     return {
       ok: issues.every((i) => i.severity !== "error"),
       issues
@@ -429,26 +440,32 @@ function verifyLineage(artifact, parent) {
     if (!parentLineage) {
       addIssue("PARENT_MISSING_LINEAGE", "Parent artifact has no lineage metadata");
     } else {
+      if (!lineage.parentArtifactId) {
+        addIssue("MISSING_PARENT_ID", "Artifact is missing parentArtifactId reference, but parent was provided for verification.");
+      } else if (lineage.parentArtifactId !== parentLineage.artifactId) {
+        addIssue("PARENT_ID_MISMATCH", `Parent Artifact ID mismatch: expected ${parentLineage.artifactId}, got ${lineage.parentArtifactId}`);
+      }
       if (lineage.lineageId !== parentLineage.lineageId) {
         addIssue("LINEAGE_ID_MISMATCH", `Lineage ID mismatch: expected ${parentLineage.lineageId}, got ${lineage.lineageId}`);
       }
       if (lineage.rootArtifactId !== parentLineage.rootArtifactId) {
-        addIssue("ROOT_ID_MISMATCH", `Root Artifact ID mismatch: expected ${parentLineage.rootArtifactId}, got ${lineage.rootArtifactId}`);
-      }
-      if (lineage.parentArtifactId && lineage.parentArtifactId !== parentLineage.artifactId) {
-        addIssue("PARENT_ID_MISMATCH", `Parent Artifact ID mismatch: expected ${parentLineage.artifactId}, got ${lineage.parentArtifactId}`);
+        addIssue("ROOT_ARTIFACT_ID_MISMATCH", `Root Artifact ID mismatch: expected ${parentLineage.rootArtifactId}, got ${lineage.rootArtifactId}`);
       }
       if (lineage.sequence !== void 0 && parentLineage.sequence !== void 0) {
         if (lineage.sequence <= parentLineage.sequence) {
-          addIssue("INVALID_SEQUENCE", `Invalid sequence: current (${lineage.sequence}) must be greater than parent (${parentLineage.sequence})`);
+          const severity = options.strict ? "error" : "warning";
+          addIssue("NON_MONOTONIC_SEQUENCE", `Non-monotonic sequence: current (${lineage.sequence}) <= parent (${parentLineage.sequence}).`, severity);
         }
       }
     }
     if (artifact.networkId !== parent.networkId) {
-      addIssue("NETWORK_CONTAMINATION", `Network mismatch: parent is ${parent.networkId}, current is ${artifact.networkId}`);
+      addIssue("NETWORK_MISMATCH", `Network mismatch: parent is ${parent.networkId}, current is ${artifact.networkId}`);
     }
     if (artifact.mode !== parent.mode) {
-      addIssue("MODE_CONTAMINATION", `Mode mismatch: parent is ${parent.mode}, current is ${artifact.mode}`);
+      addIssue("MODE_MISMATCH", `Mode mismatch: parent is ${parent.mode}, current is ${artifact.mode}`);
+    }
+    if (lineage.artifactId === lineage.parentArtifactId) {
+      addIssue("SELF_PARENT", "Artifact cannot be its own parent.");
     }
   }
   if (parent) {
@@ -485,9 +502,9 @@ async function verifyArtifactIntegrity(artifactOrPath) {
     errors: [],
     issues: []
   };
-  const addError = (code, message, path3) => {
+  const addError = (code, message, path4) => {
     result.errors.push(message);
-    result.issues.push({ code, severity: "error", message, path: path3 });
+    result.issues.push({ code, severity: "error", message, path: path4 });
   };
   let artifact;
   try {
@@ -506,21 +523,22 @@ async function verifyArtifactIntegrity(artifactOrPath) {
     result.version = v.version;
     result.expectedHash = v.contentHash;
     if (!v.version || !v.schema) {
-      addError("MISSING_METADATA", "Missing version or schema (Artifact might be v1 or legacy)");
+      addError("ARTIFACT_SCHEMA_MISSING", "Missing version or schema (Artifact might be v1 or legacy)");
       return result;
     }
     const [currentMajor] = ARTIFACT_VERSION.split(".");
     const [artifactMajor] = v.version.split(".");
     if (currentMajor !== artifactMajor) {
-      addError("INCOMPATIBLE_VERSION", `Incompatible version: current system is v${currentMajor}, artifact is v${artifactMajor}`);
+      addError("ARTIFACT_SCHEMA_INVALID", `Incompatible version: current system is v${currentMajor}, artifact is v${artifactMajor}`);
       return result;
     }
-    const actualHash = calculateContentHash(v);
+    const hashVersion = v.hashVersion || 1;
+    const actualHash = calculateContentHash(v, hashVersion);
     result.actualHash = actualHash;
     if (!v.contentHash) {
-      addError("MISSING_HASH", "Missing contentHash field");
+      addError("ARTIFACT_HASH_MISMATCH", "Missing contentHash field");
     } else if (actualHash !== v.contentHash) {
-      addError("HASH_MISMATCH", `Hash mismatch: expected ${v.contentHash}, got ${actualHash}`);
+      addError("ARTIFACT_HASH_MISMATCH", `Hash mismatch: expected ${v.contentHash}, got ${actualHash}`);
     }
     let schema;
     switch (v.schema) {
@@ -545,16 +563,20 @@ async function verifyArtifactIntegrity(artifactOrPath) {
       if (!validation.success) {
         validation.error.issues.forEach((e) => {
           const pathStr = e.path.join(".");
-          addError("SCHEMA_VALIDATION_ERROR", `${pathStr}: ${e.message}`, pathStr);
+          addError("ARTIFACT_SCHEMA_INVALID", `${pathStr}: ${e.message}`, pathStr);
         });
       }
     } else {
-      addError("UNSUPPORTED_SCHEMA", `Unsupported or unknown artifact schema: ${v.schema}`);
+      addError("ARTIFACT_SCHEMA_INVALID", `Unsupported or unknown artifact schema: ${v.schema}`);
     }
     result.ok = result.issues.every((i) => i.severity !== "error" && i.severity !== "critical");
     return result;
   } catch (e) {
-    addError("UNEXPECTED_ERROR", `Integrity verification error: ${e.message}`);
+    if (e instanceof SyntaxError) {
+      addError("ARTIFACT_JSON_INVALID", `Invalid JSON: ${e.message}`);
+    } else {
+      addError("ARTIFACT_ID_INVALID", `Unexpected verification error: ${e.message}`);
+    }
     return result;
   }
 }
@@ -600,22 +622,10 @@ function verifyArtifactSemantics(artifact, context = {}) {
       });
     }
   }
-  if (v.schema === "hardkas.signedTx" && v.mode === "simulated") {
-  }
-  const lineageAudit = verifyLineage(v, context.parent);
+  const lineageAudit = verifyLineage(v, context.parent, { strict });
   if (!lineageAudit.ok || strict && !v.lineage) {
-    if (!v.lineage && strict) {
-      addIssue({
-        code: "MISSING_LINEAGE",
-        severity: "error",
-        message: "Strict mode requires formal lineage metadata."
-      });
-    }
     lineageAudit.issues.forEach((issue) => {
-      addIssue({
-        ...issue,
-        severity: strict ? "error" : "warning"
-      });
+      addIssue(issue);
     });
   }
   if (strict) {
@@ -642,31 +652,17 @@ function verifyArtifactSemantics(artifact, context = {}) {
       });
     }
   }
-  const lineage = v.lineage;
-  if (lineage) {
-    const { artifactId, parentArtifactId, rootArtifactId } = lineage;
-    if (artifactId === parentArtifactId) {
-      addIssue({
-        code: "LINEAGE_INCONSISTENCY",
-        severity: "error",
-        message: "Artifact cannot be its own parent."
-      });
-    }
-    if (!parentArtifactId && artifactId !== rootArtifactId) {
-      addIssue({
-        code: "LINEAGE_INCONSISTENCY",
-        severity: "error",
-        message: "Root artifactId must match artifactId when no parent exists."
-      });
-    }
-  }
   return result;
 }
-async function verifyArtifactReplay(artifact, context = {}) {
+async function verifyArtifactReplay(artifact, _context = {}) {
   return {
-    ok: true,
-    issues: [],
-    errors: []
+    ok: false,
+    issues: [{
+      code: "REPLAY_UNSUPPORTED_CHECK",
+      severity: "warning",
+      message: "Replay verification (full consensus simulation) is currently unsupported in this build."
+    }],
+    errors: ["Replay verification (consensus) unsupported"]
   };
 }
 var verifyArtifact = verifyArtifactIntegrity;
@@ -890,16 +886,11 @@ function migrateToCanonical(v1Artifact) {
 // src/io.ts
 import fs2 from "fs/promises";
 import path from "path";
+import { writeFileAtomic } from "@hardkas/core";
 var bigIntReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
 async function writeArtifact(filePath, artifact) {
-  try {
-    const dir = path.dirname(filePath);
-    await fs2.mkdir(dir, { recursive: true });
-    const content = typeof artifact === "string" ? artifact : JSON.stringify(artifact, bigIntReplacer, 2) + "\n";
-    await fs2.writeFile(filePath, content, "utf-8");
-  } catch (error) {
-    throw new Error(`Failed to write artifact at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
-  }
+  const content = typeof artifact === "string" ? artifact : JSON.stringify(artifact, bigIntReplacer, 2) + "\n";
+  await writeFileAtomic(filePath, content);
 }
 function getDefaultReceiptPath(txId, cwd = process.cwd()) {
   return path.join(cwd, "artifacts", "receipts", `${txId}.json`);
@@ -1061,6 +1052,7 @@ function createTxPlanArtifact(options) {
     schema: "hardkas.txPlan",
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
+    hashVersion: CURRENT_HASH_VERSION,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     networkId: options.networkId,
     mode: options.mode,
@@ -1095,7 +1087,7 @@ function createTxPlanArtifact(options) {
       amountSompi: options.plan.change.amountSompi.toString()
     };
   }
-  const hash = calculateContentHash(artifact);
+  const hash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
   artifact.planId = `plan-${hash.slice(0, 16)}`;
   artifact.contentHash = hash;
   return artifact;
@@ -1107,7 +1099,7 @@ function createSimulatedSignedTxArtifact(plan, payload) {
     schema: "hardkas.signedTx",
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
-    hashVersion: 1,
+    hashVersion: CURRENT_HASH_VERSION,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     status: "signed",
     sourcePlanId: plan.planId,
@@ -1121,7 +1113,7 @@ function createSimulatedSignedTxArtifact(plan, payload) {
       payload
     }
   };
-  const hash = calculateContentHash(artifact);
+  const hash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
   artifact.signedId = `signed-${hash.slice(0, 16)}`;
   artifact.txId = `simulated-${plan.planId}-${hash.slice(0, 8)}`;
   artifact.contentHash = hash;
@@ -1132,7 +1124,7 @@ function createSimulatedTxReceipt(plan, txId, extra) {
     schema: "hardkas.txReceipt",
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
-    hashVersion: 1,
+    hashVersion: CURRENT_HASH_VERSION,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     txId,
     status: "accepted",
@@ -1145,9 +1137,12 @@ function createSimulatedTxReceipt(plan, txId, extra) {
     changeSompi: plan.change?.amountSompi,
     spentUtxoIds: extra?.spentUtxoIds,
     createdUtxoIds: extra?.createdUtxoIds,
-    daaScore: extra?.daaScore
+    daaScore: extra?.daaScore,
+    preStateHash: extra?.preStateHash,
+    postStateHash: extra?.postStateHash,
+    dagContext: extra?.dagContext
   };
-  const hash = calculateContentHash(artifact);
+  const hash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
   artifact.contentHash = hash;
   return artifact;
 }
@@ -1372,6 +1367,162 @@ function validateTxHash(txHash) {
     throw new Error(`Invalid EVM txHash: must be a 0x-prefixed 64-character hex string. Got: ${txHash}`);
   }
 }
+
+// src/diff.ts
+import { maskSecrets } from "@hardkas/core";
+function diffArtifacts(left, right) {
+  const entries = [];
+  const leftRedacted = maskSecrets(left);
+  const rightRedacted = maskSecrets(right);
+  compareRecursive(leftRedacted, rightRedacted, "$", entries);
+  return {
+    identical: entries.length === 0,
+    entries
+  };
+}
+function compareRecursive(left, right, path4, entries) {
+  if (isPrimitive(left) || isPrimitive(right)) {
+    if (left !== right) {
+      entries.push({ path: path4, kind: "changed", left, right });
+    }
+    return;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right)) {
+      entries.push({ path: path4, kind: "changed", left, right });
+      return;
+    }
+    const maxLength = Math.max(left.length, right.length);
+    for (let i = 0; i < maxLength; i++) {
+      if (i >= left.length) {
+        entries.push({ path: `${path4}[${i}]`, kind: "added", right: right[i] });
+      } else if (i >= right.length) {
+        entries.push({ path: `${path4}[${i}]`, kind: "removed", left: left[i] });
+      } else {
+        compareRecursive(left[i], right[i], `${path4}[${i}]`, entries);
+      }
+    }
+    return;
+  }
+  const leftKeys = Object.keys(left).filter((k) => !SEMANTIC_EXCLUSIONS.has(k));
+  const rightKeys = Object.keys(right).filter((k) => !SEMANTIC_EXCLUSIONS.has(k));
+  const allKeys = /* @__PURE__ */ new Set([...leftKeys, ...rightKeys]);
+  for (const key of allKeys) {
+    const nextPath = path4 === "$" ? key : `${path4}.${key}`;
+    if (!leftKeys.includes(key)) {
+      entries.push({ path: nextPath, kind: "added", right: right[key] });
+    } else if (!rightKeys.includes(key)) {
+      entries.push({ path: nextPath, kind: "removed", left: left[key] });
+    } else {
+      compareRecursive(left[key], right[key], nextPath, entries);
+    }
+  }
+}
+function isPrimitive(val) {
+  if (val === null) return true;
+  return typeof val !== "object" && typeof val !== "function";
+}
+
+// src/deployment.ts
+function createDeploymentRecord(opts) {
+  const record = {
+    schema: "hardkas.deployment.v1",
+    label: opts.label,
+    networkId: opts.networkId,
+    status: opts.status || "planned",
+    deployedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    hardkasVersion: HARDKAS_VERSION,
+    version: ARTIFACT_VERSION,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    mode: "real"
+  };
+  if (opts.txId) record.txId = opts.txId;
+  if (opts.planArtifactId) record.planArtifactId = opts.planArtifactId;
+  if (opts.receiptArtifactId) record.receiptArtifactId = opts.receiptArtifactId;
+  if (opts.deployedAddresses) record.deployedAddresses = opts.deployedAddresses;
+  if (opts.deployer) record.deployer = opts.deployer;
+  if (opts.payloadHash) record.payloadHash = opts.payloadHash;
+  if (opts.notes) record.notes = opts.notes;
+  record.contentHash = calculateContentHash(record, CURRENT_HASH_VERSION);
+  return record;
+}
+function updateDeploymentStatus(record, newStatus, txId) {
+  const updated = {
+    ...record,
+    status: newStatus,
+    deployedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (txId) updated.txId = txId;
+  delete updated.contentHash;
+  updated.contentHash = calculateContentHash(updated, CURRENT_HASH_VERSION);
+  return updated;
+}
+
+// src/deployment-store.ts
+import fs4 from "fs/promises";
+import { existsSync } from "fs";
+import path3 from "path";
+import { writeFileAtomic as writeFileAtomic2 } from "@hardkas/core";
+async function saveDeployment(rootDir, record) {
+  const deploymentsDir = path3.join(rootDir, ".hardkas", "deployments", record.networkId);
+  const targetPath = path3.join(deploymentsDir, `${record.label}.json`);
+  await writeFileAtomic2(targetPath, JSON.stringify(record, null, 2));
+  return targetPath;
+}
+async function loadDeployment(rootDir, networkId, label) {
+  const targetPath = path3.join(rootDir, ".hardkas", "deployments", networkId, `${label}.json`);
+  if (!existsSync(targetPath)) return null;
+  const content = await fs4.readFile(targetPath, "utf-8");
+  return JSON.parse(content);
+}
+async function listDeployments(rootDir, networkId) {
+  const baseDir = path3.join(rootDir, ".hardkas", "deployments");
+  if (!existsSync(baseDir)) return [];
+  const summaries = [];
+  const networks = networkId ? [networkId] : await fs4.readdir(baseDir);
+  for (const net of networks) {
+    const netDir = path3.join(baseDir, net);
+    if (!existsSync(netDir)) continue;
+    const files = await fs4.readdir(netDir);
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const content = await fs4.readFile(path3.join(netDir, file), "utf-8");
+        const record = JSON.parse(content);
+        const summary = {
+          label: record.label,
+          networkId: record.networkId,
+          status: record.status,
+          deployedAt: record.deployedAt,
+          contentHash: record.contentHash || ""
+        };
+        if (record.txId) summary.txId = record.txId;
+        summaries.push(summary);
+      } catch (e) {
+      }
+    }
+  }
+  return summaries.sort((a, b) => new Date(b.deployedAt).getTime() - new Date(a.deployedAt).getTime());
+}
+async function updateDeployment(rootDir, networkId, label, update) {
+  const existing = await loadDeployment(rootDir, networkId, label);
+  if (!existing) {
+    throw new Error(`Deployment '${label}' not found on network '${networkId}'.`);
+  }
+  const updated = {
+    ...existing,
+    ...update,
+    deployedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await saveDeployment(rootDir, updated);
+  return updated;
+}
+async function deleteDeployment(rootDir, networkId, label) {
+  const targetPath = path3.join(rootDir, ".hardkas", "deployments", networkId, `${label}.json`);
+  if (!existsSync(targetPath)) return false;
+  await fs4.unlink(targetPath);
+  return true;
+}
 export {
   ARTIFACT_SCHEMAS,
   ARTIFACT_VERSION,
@@ -1380,6 +1531,7 @@ export {
   BaseArtifactSchema,
   BasicCorrelationInvariant,
   BasicLineageInvariant,
+  CURRENT_HASH_VERSION,
   DagContextSchema,
   HARDKAS_VERSION,
   HashInvariant,
@@ -1388,6 +1540,7 @@ export {
   LocalnetUtxoSchemaV2,
   NetworkInvariant,
   ReplayInvariant,
+  SEMANTIC_EXCLUSIONS,
   SchemaInvariant,
   SignedTxSchema,
   SnapshotSchema,
@@ -1407,6 +1560,7 @@ export {
   bigIntReplacer,
   calculateContentHash,
   canonicalStringify,
+  createDeploymentRecord,
   createIgraDeployPlanId,
   createIgraPlanId,
   createIgraSignedId,
@@ -1414,6 +1568,8 @@ export {
   createSimulatedTxReceipt,
   createTxPlanArtifact,
   defaultClock,
+  deleteDeployment,
+  diffArtifacts,
   explainArtifact,
   formatSignedTxArtifact,
   formatTxPlanArtifact,
@@ -1423,7 +1579,9 @@ export {
   getDefaultReceiptPath,
   getL2ReceiptPath,
   isIgraTxPlanArtifact,
+  listDeployments,
   listIgraTxReceiptArtifacts,
+  loadDeployment,
   loadIgraTxReceiptArtifact,
   migrateToCanonical,
   readArtifact,
@@ -1431,10 +1589,13 @@ export {
   readTxPlanArtifact,
   readTxReceiptArtifact,
   recomputeMass,
+  saveDeployment,
   saveIgraTxReceiptArtifact,
   sortUtxosByOutpoint,
   txOutputFromArtifact,
   txOutputToArtifact,
+  updateDeployment,
+  updateDeploymentStatus,
   utxoFromArtifact,
   utxoToArtifact,
   validateArtifact,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/artifacts",
-  "version": "0.2.2-alpha.1",
+  "version": "0.4.0-alpha",
   "type": "module",
   "license": "MIT",
   "author": "Javier Rodriguez",
@@ -24,8 +24,8 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "zod": "^3.24.1",
-    "@hardkas/core": "0.2.2-alpha.1",
-    "@hardkas/tx-builder": "0.2.2-alpha.1"
+    "@hardkas/core": "0.4.0-alpha",
+    "@hardkas/tx-builder": "0.4.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",