@hardkas/artifacts 0.5.5-alpha → 0.6.1-alpha

package/dist/index.js

@@ -1,5 +1,48 @@
+// package.json
+var package_default = {
+  name: "@hardkas/artifacts",
+  version: "0.6.1-alpha",
+  type: "module",
+  license: "MIT",
+  author: "Javier Rodriguez",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/KasLabDevs/HardKas.git",
+    directory: "packages/artifacts"
+  },
+  homepage: "https://github.com/KasLabDevs/HardKas/tree/main/packages/artifacts#readme",
+  bugs: {
+    url: "https://github.com/KasLabDevs/HardKas/issues"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  exports: {
+    ".": "./dist/index.js"
+  },
+  types: "./dist/index.d.ts",
+  scripts: {
+    build: "tsup src/index.ts --format esm --dts --clean",
+    dev: "tsup src/index.ts --format esm --watch --dts",
+    test: "vitest run",
+    lint: "tsc --noEmit"
+  },
+  dependencies: {
+    "@hardkas/core": "workspace:*",
+    "@hardkas/tx-builder": "workspace:*",
+    zod: "^3.24.1"
+  },
+  devDependencies: {
+    tsup: "^8.3.5",
+    typescript: "^5.6.3",
+    vitest: "^2.1.4"
+  }
+};
+
 // src/constants.ts
-var HARDKAS_VERSION = "0.5.5-alpha";
+var HARDKAS_VERSION = package_default.version;
 var ARTIFACT_SCHEMAS = {
   LOCALNET_STATE: "hardkas.localnetState.v1",
   REAL_ACCOUNT_STORE: "hardkas.realAccountStore.v1",
@@ -133,6 +176,7 @@ function createIgraDeployPlanId(hash) {
 
 // src/canonical.ts
 import { createHash } from "crypto";
+import { deterministicCompare } from "@hardkas/core";
 var SEMANTIC_EXCLUSIONS = /* @__PURE__ */ new Set([
   "contentHash",
   "artifactId",
@@ -140,6 +184,8 @@ var SEMANTIC_EXCLUSIONS = /* @__PURE__ */ new Set([
   "lineage",
   "createdAt",
   "rpcUrl",
+  "rpcHost",
+  "latencyMs",
   "indexedAt",
   "file_path",
   "file_mtime_ms",
@@ -148,7 +194,15 @@ var SEMANTIC_EXCLUSIONS = /* @__PURE__ */ new Set([
   // Exclude hash version from hash
   "parentArtifactId",
   "signedId",
-  "deployedAt"
+  "deployedAt",
+  "tracePath",
+  "receiptPath",
+  "events",
+  "status",
+  "sourceSignedId",
+  "submittedAt",
+  "confirmedAt",
+  "dagContext"
 ]);
 var CURRENT_HASH_VERSION = 3;
 function canonicalStringify(obj, version = CURRENT_HASH_VERSION) {
@@ -160,7 +214,7 @@ function canonicalStringify(obj, version = CURRENT_HASH_VERSION) {
       return JSON.stringify(obj.toString());
     }
     if (typeof obj === "string" && version >= 3) {
-      const normalized = obj.normalize("NFC").replace(/\r\n/g, "\n");
+      const normalized = obj.normalize("NFC").replace(/\r\n/g, "\n").replace(/\\/g, "/");
       return JSON.stringify(normalized);
     }
     return JSON.stringify(obj);
@@ -168,9 +222,22 @@ function canonicalStringify(obj, version = CURRENT_HASH_VERSION) {
   if (Array.isArray(obj)) {
     return "[" + obj.map((item) => canonicalStringify(item, version)).join(",") + "]";
   }
+  if (obj instanceof Map) {
+    throw new Error("Map is not canonicalizable. Use a plain object.");
+  }
+  if (obj instanceof Set) {
+    throw new Error("Set is not canonicalizable. Use an array.");
+  }
+  if (obj instanceof Date) {
+    throw new Error("Date must be serialized explicitly.");
+  }
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== Object.prototype && proto !== null) {
+    throw new Error("Non-plain object encountered in canonicalizer.");
+  }
   const sortedKeys = Object.keys(obj).filter(
     (key) => !SEMANTIC_EXCLUSIONS.has(key) && obj[key] !== void 0
-  ).sort();
+  ).sort(deterministicCompare);
   const result = sortedKeys.map((key) => {
     const value = obj[key];
     return JSON.stringify(key) + ":" + canonicalStringify(value, version);
@@ -293,6 +360,7 @@ var TxReceiptSchema = BaseArtifactSchema.extend({
   tracePath: z.string().optional(),
   rpcUrl: z.string().optional(),
   sourceSignedId: z.string().optional(),
+  errors: z.array(z.string()).optional(),
   metadata: z.any().optional()
 });
 var SignedTxSchema = BaseArtifactSchema.extend({
@@ -325,6 +393,42 @@ var TxTraceSchema = BaseArtifactSchema.extend({
   })),
   dagContext: DagContextSchema.optional()
 });
+var WorkflowSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.workflow.v1"),
+  workflowId: z.string(),
+  status: z.enum(["pending", "running", "completed", "failed"]),
+  inputs: z.record(z.any()).optional(),
+  steps: z.array(z.object({
+    type: z.string(),
+    status: z.enum(["pending", "success", "failed", "skipped"]),
+    startedAt: z.string().datetime().optional(),
+    completedAt: z.string().datetime().optional(),
+    producedArtifactId: z.string().optional(),
+    error: z.string().optional()
+  })),
+  parentArtifacts: z.array(z.string()).optional(),
+  producedArtifacts: z.array(z.string()),
+  generationRange: z.object({
+    start: z.string().optional(),
+    end: z.string().optional()
+  }).optional(),
+  policy: z.object({
+    allowNetwork: z.boolean(),
+    allowMainnet: z.boolean(),
+    allowExternalWallet: z.boolean(),
+    requireDryRun: z.boolean()
+  }).optional(),
+  generationId: z.string().optional(),
+  replayResult: z.object({
+    verified: z.boolean(),
+    stateHash: z.string().optional()
+  }).optional(),
+  errorEnvelope: z.object({
+    code: z.string(),
+    message: z.string(),
+    redacted: z.boolean()
+  }).optional()
+});
 
 // src/verify.ts
 import fs from "fs";
@@ -414,8 +518,11 @@ function verifyLineage(artifact, parent, options = {}) {
   };
   const lineage = artifact.lineage;
   if (!lineage) {
-    const severity = options.strict ? "error" : "warning";
-    addIssue("MISSING_LINEAGE", "Artifact has no lineage metadata", severity);
+    const isWorkflow = artifact.schema === "hardkas.workflow.v1";
+    const severity = options.strict && !isWorkflow ? "error" : "warning";
+    if (!isWorkflow || options.strict) {
+      addIssue("MISSING_LINEAGE", "Artifact has no lineage metadata", severity);
+    }
     return {
       ok: issues.every((i) => i.severity !== "error"),
       issues
@@ -488,12 +595,20 @@ function verifyLineage(artifact, parent, options = {}) {
 // src/verify.ts
 var defaultClock = {
   now: () => Date.now()
+  // hardkas-determinism-allow: default clock ambient source
 };
+function deterministicCompare2(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
 function sortUtxosByOutpoint(utxos) {
   return [...utxos].sort((a, b) => {
-    const aId = a.id || (a.outpoint ? `${a.outpoint.transactionId}:${a.outpoint.index}` : "");
-    const bId = b.id || (b.outpoint ? `${b.outpoint.transactionId}:${b.outpoint.index}` : "");
-    return aId.localeCompare(bId);
+    const aRec = a;
+    const bRec = b;
+    const aOutpoint = aRec.outpoint;
+    const bOutpoint = bRec.outpoint;
+    const aId = aRec.id || (aOutpoint ? `${aOutpoint.transactionId}:${aOutpoint.index}` : "");
+    const bId = bRec.id || (bOutpoint ? `${bOutpoint.transactionId}:${bOutpoint.index}` : "");
+    return deterministicCompare2(aId, bId);
   });
 }
 async function verifyArtifactIntegrity(artifactOrPath) {
@@ -525,6 +640,10 @@ async function verifyArtifactIntegrity(artifactOrPath) {
     result.artifactType = v.schema;
     result.version = v.version;
     result.expectedHash = v.contentHash;
+    if (v.schema === "hardkas.replayReport.v1") {
+      result.ok = true;
+      return result;
+    }
     if (!v.version || !v.schema) {
       addError("ARTIFACT_SCHEMA_MISSING", "Missing version or schema (Artifact might be v1 or legacy)");
       return result;
@@ -560,6 +679,9 @@ async function verifyArtifactIntegrity(artifactOrPath) {
       case "hardkas.signedTx":
         schema = SignedTxSchema;
         break;
+      case "hardkas.workflow.v1":
+        schema = WorkflowSchema;
+        break;
     }
     if (schema) {
       const validation = schema.safeParse(v);
@@ -577,8 +699,10 @@ async function verifyArtifactIntegrity(artifactOrPath) {
   } catch (e) {
     if (e instanceof SyntaxError) {
       addError("ARTIFACT_JSON_INVALID", `Invalid JSON: ${e.message}`);
-    } else {
+    } else if (e instanceof Error) {
       addError("ARTIFACT_ID_INVALID", `Unexpected verification error: ${e.message}`);
+    } else {
+      addError("ARTIFACT_ID_INVALID", `Unexpected verification error: ${String(e)}`);
     }
     return result;
   }
@@ -626,19 +750,19 @@ function verifyArtifactSemantics(artifact, context = {}) {
     }
   }
   const lineageAudit = verifyLineage(v, context.parent, { strict });
-  if (!lineageAudit.ok || strict && !v.lineage) {
+  if (!lineageAudit.ok || strict && !v.lineage && v.schema !== "hardkas.workflow.v1") {
     lineageAudit.issues.forEach((issue) => {
       addIssue(issue);
     });
   }
   if (strict) {
     if (!v.workflowId) addIssue({ code: "MISSING_WORKFLOW_ID", severity: "error", message: "Strict mode requires workflowId" });
-    if (!v.assumptionLevel) addIssue({ code: "MISSING_ASSUMPTION_LEVEL", severity: "error", message: "Strict mode requires assumptionLevel" });
-    if (!v.executionMode) addIssue({ code: "MISSING_EXECUTION_MODE", severity: "error", message: "Strict mode requires executionMode" });
+    if (!v.assumptionLevel && v.schema !== "hardkas.workflow.v1") addIssue({ code: "MISSING_ASSUMPTION_LEVEL", severity: "error", message: "Strict mode requires assumptionLevel" });
+    if (!v.executionMode && !v.mode) addIssue({ code: "MISSING_EXECUTION_MODE", severity: "error", message: "Strict mode requires executionMode" });
   } else {
     if (!v.workflowId) addIssue({ code: "MISSING_WORKFLOW_ID", severity: "warning", message: "Missing workflowId" });
-    if (!v.assumptionLevel) addIssue({ code: "MISSING_ASSUMPTION_LEVEL", severity: "warning", message: "Missing assumptionLevel" });
-    if (!v.executionMode) addIssue({ code: "MISSING_EXECUTION_MODE", severity: "warning", message: "Missing executionMode" });
+    if (!v.assumptionLevel && v.schema !== "hardkas.workflow.v1") addIssue({ code: "MISSING_ASSUMPTION_LEVEL", severity: "warning", message: "Missing assumptionLevel" });
+    if (!v.executionMode && !v.mode) addIssue({ code: "MISSING_EXECUTION_MODE", severity: "warning", message: "Missing executionMode" });
   }
   const networkId = context.networkId || v.networkId;
   const networkIdStr = networkId;
@@ -800,7 +924,7 @@ var ReplayInvariant = class {
 };
 
 // src/invariants/watcher.ts
-import { createEventEnvelope } from "@hardkas/core";
+import { createEventEnvelope, asWorkflowId, asCorrelationId, asNetworkId, asEventSequence } from "@hardkas/core";
 var InvariantWatcher = class {
   invariants;
   eventBus;
@@ -853,9 +977,12 @@ var InvariantWatcher = class {
     const integrityEvent = createEventEnvelope({
       kind: "integrity.violation",
       domain: "integrity",
-      workflowId: sourceEvent.workflowId,
-      correlationId: sourceEvent.correlationId,
-      networkId: sourceEvent.networkId,
+      workflowId: asWorkflowId("system-watcher"),
+      correlationId: asCorrelationId(sourceEvent.correlationId),
+      networkId: asNetworkId(sourceEvent.networkId),
+      sequenceNumber: asEventSequence(0),
+      // Root event for watcher
+      sourceSubsystem: "artifact_watcher",
       payload: {
         violationCode: violation.code,
         severity: violation.severity,
@@ -869,30 +996,148 @@ var InvariantWatcher = class {
 };
 
 // src/migration.ts
-function migrateToCanonical(v1Artifact) {
-  if (v1Artifact.version === ARTIFACT_VERSION) {
-    return v1Artifact;
+var migrationRegistry = [];
+function registerMigrationStep(step) {
+  const existing = migrationRegistry.find(
+    (s) => s.fromVersion === step.fromVersion && s.toVersion === step.toVersion
+  );
+  if (existing) {
+    throw new Error(
+      `Duplicate migration step: ${step.fromVersion} \u2192 ${step.toVersion} already registered`
+    );
+  }
+  migrationRegistry.push(step);
+}
+function getRegisteredMigrationSteps() {
+  return [...migrationRegistry];
+}
+registerMigrationStep({
+  fromVersion: "0.1.0",
+  toVersion: ARTIFACT_VERSION,
+  description: "Legacy v1 schemas to canonical 1.0.0-alpha format",
+  transform(artifact) {
+    const migrated = { ...artifact };
+    if (typeof migrated.schema === "string" && migrated.schema.endsWith(".v1")) {
+      if (migrated.schema !== "hardkas.workflow.v1") {
+        migrated.schema = migrated.schema.replace(/\.v1$/, "");
+      }
+    }
+    migrated.version = ARTIFACT_VERSION;
+    if (migrated.schema === "hardkas.txPlan" && migrated.selectedUtxos !== void 0) {
+      migrated.inputs = migrated.selectedUtxos;
+      delete migrated.selectedUtxos;
+    }
+    if (migrated.schema === "hardkas.snapshot" && Array.isArray(migrated.utxos)) {
+      migrated.utxos = sortUtxosByOutpoint(migrated.utxos);
+    }
+    if (!migrated.hardkasVersion) {
+      migrated.hardkasVersion = HARDKAS_VERSION;
+    }
+    if (!migrated.createdAt) {
+      migrated.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+    if (migrated.hashVersion === void 0 || migrated.hashVersion === null) {
+      migrated.hashVersion = CURRENT_HASH_VERSION;
+    }
+    return migrated;
   }
-  const v2Artifact = { ...v1Artifact };
-  if (v1Artifact.schema) {
-    v2Artifact.schema = v1Artifact.schema.replace(".v1", "");
+});
+function detectArtifactVersion(artifact) {
+  if (typeof artifact.version === "string" && artifact.version.length > 0) {
+    return artifact.version;
   }
-  v2Artifact.version = ARTIFACT_VERSION;
-  if (v2Artifact.schema === "hardkas.txPlan" && v1Artifact.selectedUtxos) {
-    v2Artifact.inputs = v1Artifact.selectedUtxos;
-    delete v2Artifact.selectedUtxos;
+  if (typeof artifact.schema === "string" && artifact.schema.endsWith(".v1")) {
+    return "0.1.0";
   }
-  if (v2Artifact.schema === "hardkas.snapshot" && v1Artifact.utxos) {
-    v2Artifact.utxos = sortUtxosByOutpoint(v1Artifact.utxos);
+  return "0.1.0";
+}
+function getMigrationPath(fromVersion, toVersion) {
+  if (fromVersion === toVersion) {
+    return [];
   }
-  if (!v2Artifact.hardkasVersion) {
-    v2Artifact.hardkasVersion = HARDKAS_VERSION;
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [
+    { version: fromVersion, path: [] }
+  ];
+  visited.add(fromVersion);
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const outgoing = migrationRegistry.filter(
+      (s) => s.fromVersion === current.version
+    );
+    for (const step of outgoing) {
+      const newPath = [...current.path, step];
+      if (step.toVersion === toVersion) {
+        return newPath;
+      }
+      if (!visited.has(step.toVersion)) {
+        visited.add(step.toVersion);
+        queue.push({ version: step.toVersion, path: newPath });
+      }
+    }
   }
-  if (!v2Artifact.createdAt) {
-    v2Artifact.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+  return [];
+}
+function canMigrate(artifact, targetVersion = ARTIFACT_VERSION) {
+  const currentVersion = detectArtifactVersion(artifact);
+  if (currentVersion === targetVersion) {
+    return true;
   }
-  v2Artifact.contentHash = calculateContentHash(v2Artifact);
-  return v2Artifact;
+  const path4 = getMigrationPath(currentVersion, targetVersion);
+  return path4.length > 0;
+}
+function migrateArtifactPayload(artifact, targetVersion = ARTIFACT_VERSION) {
+  const currentVersion = detectArtifactVersion(artifact);
+  if (currentVersion === targetVersion) {
+    return {
+      artifact,
+      migrated: false,
+      originalContentHash: artifact.contentHash,
+      appliedSteps: []
+    };
+  }
+  const path4 = getMigrationPath(currentVersion, targetVersion);
+  if (path4.length === 0) {
+    throw new Error(
+      `No migration path from version "${currentVersion}" to "${targetVersion}". Registered steps: [${migrationRegistry.map((s) => `${s.fromVersion}\u2192${s.toVersion}`).join(", ")}]`
+    );
+  }
+  const originalContentHash = artifact.contentHash;
+  const originalLineage = artifact.lineage;
+  let current = { ...artifact };
+  const appliedSteps = [];
+  for (const step of path4) {
+    current = step.transform(current);
+    appliedSteps.push({
+      fromVersion: step.fromVersion,
+      toVersion: step.toVersion,
+      description: step.description
+    });
+  }
+  if (originalContentHash) {
+    current.originalContentHash = originalContentHash;
+  }
+  if (originalLineage && typeof originalLineage === "object") {
+    const migratedLineage = current.lineage;
+    if (migratedLineage && typeof migratedLineage === "object") {
+      migratedLineage.rootArtifactId = originalLineage.rootArtifactId;
+    }
+  }
+  current.hashVersion = CURRENT_HASH_VERSION;
+  current.contentHash = calculateContentHash(current, CURRENT_HASH_VERSION);
+  return {
+    artifact: current,
+    migrated: true,
+    originalContentHash,
+    appliedSteps
+  };
+}
+function migrateToCanonical(v1Artifact) {
+  if (v1Artifact.version === ARTIFACT_VERSION) {
+    return v1Artifact;
+  }
+  const result = migrateArtifactPayload(v1Artifact, ARTIFACT_VERSION);
+  return result.artifact;
 }
 
 // src/io.ts
@@ -968,6 +1213,17 @@ function formatTxPlanArtifact(artifact) {
   lines.push(`Outputs:      ${artifact.outputs.length}`);
   lines.push(`Fee:          ${formatSompi(BigInt(artifact.estimatedFeeSompi))}`);
   lines.push(`Mass:         ${artifact.estimatedMass}`);
+  lines.push("");
+  lines.push("Deterministic Planning Specifications:");
+  lines.push("  Coin Selection:");
+  lines.push("    deterministic canonical ordering enabled");
+  lines.push("  Input Ordering:");
+  lines.push("    amountSompi ASC");
+  lines.push("    txid ASC");
+  lines.push("    index ASC");
+  lines.push("  Output Ordering:");
+  lines.push("    amountSompi ASC");
+  lines.push("    address ASC");
   return lines.join("\n");
 }
 function formatTxReceiptArtifact(artifact) {
@@ -1006,40 +1262,30 @@ function formatSignedTxArtifact(artifact) {
 
 // src/conversions.ts
 function utxoToArtifact(utxo) {
-  const artifact = {
+  return {
     outpoint: {
       transactionId: utxo.outpoint.transactionId,
       index: utxo.outpoint.index
     },
     address: utxo.address,
     amountSompi: utxo.amountSompi.toString(),
-    scriptPublicKey: utxo.scriptPublicKey
+    scriptPublicKey: utxo.scriptPublicKey,
+    ...utxo.blockDaaScore !== void 0 ? { blockDaaScore: utxo.blockDaaScore.toString() } : {},
+    ...utxo.isCoinbase !== void 0 ? { isCoinbase: utxo.isCoinbase } : {}
   };
-  if (utxo.blockDaaScore !== void 0) {
-    artifact.blockDaaScore = utxo.blockDaaScore.toString();
-  }
-  if (utxo.isCoinbase !== void 0) {
-    artifact.isCoinbase = utxo.isCoinbase;
-  }
-  return artifact;
 }
 function utxoFromArtifact(artifact) {
-  const utxo = {
+  return {
     outpoint: {
       transactionId: artifact.outpoint.transactionId,
       index: artifact.outpoint.index
     },
     address: artifact.address,
     amountSompi: safeParseBigInt(artifact.amountSompi, "UtxoArtifact.amountSompi"),
-    scriptPublicKey: artifact.scriptPublicKey
+    scriptPublicKey: artifact.scriptPublicKey,
+    ...artifact.blockDaaScore !== void 0 ? { blockDaaScore: safeParseBigInt(artifact.blockDaaScore, "UtxoArtifact.blockDaaScore") } : {},
+    ...artifact.isCoinbase !== void 0 ? { isCoinbase: artifact.isCoinbase } : {}
   };
-  if (artifact.blockDaaScore !== void 0) {
-    utxo.blockDaaScore = safeParseBigInt(artifact.blockDaaScore, "UtxoArtifact.blockDaaScore");
-  }
-  if (artifact.isCoinbase !== void 0) {
-    utxo.isCoinbase = artifact.isCoinbase;
-  }
-  return utxo;
 }
 function txOutputToArtifact(output) {
   return {
@@ -1068,7 +1314,7 @@ function createTxPlanArtifact(options) {
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
     hashVersion: CURRENT_HASH_VERSION,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    createdAt: new Date(options.ctx.clock.now()).toISOString(),
     networkId: options.networkId,
     mode: options.mode,
     from: {
@@ -1109,13 +1355,13 @@ function createTxPlanArtifact(options) {
 }
 
 // src/signed-tx.ts
-function createSimulatedSignedTxArtifact(plan, payload) {
+function createSimulatedSignedTxArtifact(plan, payload, ctx) {
   const artifact = {
     schema: "hardkas.signedTx",
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
     hashVersion: CURRENT_HASH_VERSION,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    createdAt: new Date(ctx.clock.now()).toISOString(),
     status: "signed",
     sourcePlanId: plan.planId,
     networkId: plan.networkId,
@@ -1134,13 +1380,13 @@ function createSimulatedSignedTxArtifact(plan, payload) {
   artifact.contentHash = hash;
   return artifact;
 }
-function createSimulatedTxReceipt(plan, txId, extra) {
+function createSimulatedTxReceipt(plan, txId, ctx, extra) {
   const artifact = {
     schema: "hardkas.txReceipt",
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
     hashVersion: CURRENT_HASH_VERSION,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    createdAt: new Date(ctx.clock.now()).toISOString(),
     txId,
     status: "accepted",
     mode: "simulated",
@@ -1203,7 +1449,8 @@ function validateSignedTxArtifact(value) {
   if (!v.signedTransaction) {
     errors.push("Missing signedTransaction object");
   } else {
-    if (!["kaspa-sdk", "hex", "simulated", "unknown"].includes(v.signedTransaction.format)) {
+    const st = v.signedTransaction;
+    if (!["kaspa-sdk", "hex", "simulated", "unknown"].includes(st.format)) {
       errors.push("Invalid signedTransaction.format");
     }
   }
@@ -1265,7 +1512,8 @@ function assertDecimalBigIntString2(value, field, errors) {
 }
 
 // src/explain.ts
-async function explainArtifact(artifact) {
+async function explainArtifact(artifactUnknown) {
+  const artifact = artifactUnknown;
   const schema = artifact.schema || "unknown";
   const type = schema.split(".")[1] || "unknown";
   const integrity = await verifyArtifactIntegrity(artifact);
@@ -1336,6 +1584,7 @@ async function explainArtifact(artifact) {
 // src/igra-io.ts
 import fs3 from "fs/promises";
 import path2 from "path";
+import { deterministicCompare as deterministicCompare3 } from "@hardkas/core";
 function getDefaultL2ReceiptsDir(cwd = process.cwd()) {
   return path2.join(cwd, ".hardkas", "l2-receipts");
 }
@@ -1371,7 +1620,7 @@ async function listIgraTxReceiptArtifacts(options) {
       } catch (e) {
       }
     }
-    return receipts.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    return receipts.sort((a, b) => deterministicCompare3(b.createdAt, a.createdAt));
   } catch (e) {
     if (e.code === "ENOENT") return [];
     throw e;
@@ -1440,7 +1689,7 @@ function isPrimitive(val) {
 
 // src/deployment.ts
 function createDeploymentRecord(opts) {
-  const record = {
+  const recordDraft = {
     schema: "hardkas.deployment.v1",
     label: opts.label,
     networkId: opts.networkId,
@@ -1449,28 +1698,33 @@ function createDeploymentRecord(opts) {
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    mode: "real"
+    mode: "real",
+    ...opts.txId ? { txId: opts.txId } : {},
+    ...opts.planArtifactId ? { planArtifactId: opts.planArtifactId } : {},
+    ...opts.receiptArtifactId ? { receiptArtifactId: opts.receiptArtifactId } : {},
+    ...opts.deployedAddresses ? { deployedAddresses: opts.deployedAddresses } : {},
+    ...opts.deployer ? { deployer: opts.deployer } : {},
+    ...opts.payloadHash ? { payloadHash: opts.payloadHash } : {},
+    ...opts.notes ? { notes: opts.notes } : {}
+  };
+  const contentHash = calculateContentHash(recordDraft, CURRENT_HASH_VERSION);
+  return {
+    ...recordDraft,
+    contentHash
   };
-  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 = {
+  const updatedDraft = {
     ...record,
     status: newStatus,
-    deployedAt: (/* @__PURE__ */ new Date()).toISOString()
+    deployedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...txId ? { txId } : {}
+  };
+  const contentHash = calculateContentHash(updatedDraft, CURRENT_HASH_VERSION);
+  return {
+    ...updatedDraft,
+    contentHash
   };
-  if (txId) updated.txId = txId;
-  delete updated.contentHash;
-  updated.contentHash = calculateContentHash(updated, CURRENT_HASH_VERSION);
-  return updated;
 }
 
 // src/deployment-store.ts
@@ -1562,6 +1816,7 @@ export {
   TxPlanSchema,
   TxReceiptSchema,
   TxTraceSchema,
+  WorkflowSchema,
   assertDecimalBigIntString,
   assertEvmAddress,
   assertEvmTxHash,
@@ -1574,6 +1829,7 @@ export {
   assertValidTxReceiptArtifact,
   bigIntReplacer,
   calculateContentHash,
+  canMigrate,
   canonicalStringify,
   createDeploymentRecord,
   createIgraDeployPlanId,
@@ -1584,6 +1840,7 @@ export {
   createTxPlanArtifact,
   defaultClock,
   deleteDeployment,
+  detectArtifactVersion,
   diffArtifacts,
   explainArtifact,
   formatSignedTxArtifact,
@@ -1593,17 +1850,21 @@ export {
   getDefaultL2ReceiptsDir,
   getDefaultReceiptPath,
   getL2ReceiptPath,
+  getMigrationPath,
+  getRegisteredMigrationSteps,
   isIgraTxPlanArtifact,
   listDeployments,
   listIgraTxReceiptArtifacts,
   loadDeployment,
   loadIgraTxReceiptArtifact,
+  migrateArtifactPayload,
   migrateToCanonical,
   readArtifact,
   readSignedTxArtifact,
   readTxPlanArtifact,
   readTxReceiptArtifact,
   recomputeMass,
+  registerMigrationStep,
   saveDeployment,
   saveIgraTxReceiptArtifact,
   sortUtxosByOutpoint,