@hardkas/artifacts 0.6.0-alpha → 0.6.1-alpha

package/dist/index.d.ts

@@ -1874,11 +1874,124 @@ declare class InvariantWatcher {
     private emitViolation;
 }
 
+/**
+ * Represents the payload of any HardKAS artifact in its raw (parsed JSON) form.
+ * The migration engine operates on this untyped representation to support
+ * artifacts across schema versions.
+ */
+type ArtifactPayload = Record<string, unknown>;
+/**
+ * A single versioned migration step that transforms an artifact payload
+ * from one schema version to the next.
+ */
+interface MigrationStep {
+    /** Source version string (e.g., "0.1.0", "1.0.0-alpha") */
+    readonly fromVersion: string;
+    /** Target version string */
+    readonly toVersion: string;
+    /** Human-readable description of what this migration does */
+    readonly description: string;
+    /**
+     * Transform function. Receives a shallow clone of the artifact payload
+     * and returns the migrated payload. MUST NOT mutate the input.
+     */
+    transform(artifact: ArtifactPayload): ArtifactPayload;
+}
+/**
+ * Result of a migration operation.
+ */
+interface MigrationResult {
+    /** The migrated artifact payload */
+    artifact: ArtifactPayload;
+    /** Whether any migration was actually applied */
+    migrated: boolean;
+    /** The original content hash (before migration), preserved for lineage */
+    originalContentHash: string | undefined;
+    /** Ordered list of migration steps that were applied */
+    appliedSteps: ReadonlyArray<{
+        fromVersion: string;
+        toVersion: string;
+        description: string;
+    }>;
+}
+/**
+ * Registers a migration step in the global registry.
+ * Steps should be registered in chronological order (oldest → newest).
+ *
+ * @param step - The migration step to register
+ */
+declare function registerMigrationStep(step: MigrationStep): void;
+/**
+ * Returns all registered migration steps (read-only copy).
+ */
+declare function getRegisteredMigrationSteps(): ReadonlyArray<MigrationStep>;
+/**
+ * Determines the version of an artifact based on its `version` field,
+ * falling back to heuristics for truly legacy artifacts.
+ */
+declare function detectArtifactVersion(artifact: ArtifactPayload): string;
+/**
+ * Resolves the ordered list of migration steps needed to go from
+ * `fromVersion` to `toVersion`.
+ *
+ * Uses a simple BFS/chain walk through the migration registry.
+ * Returns an empty array if no migration path exists or if the artifact
+ * is already at the target version.
+ *
+ * @param fromVersion - The current artifact version
+ * @param toVersion - The desired target version
+ * @returns Ordered array of migration steps, or empty if no path or already current
+ */
+declare function getMigrationPath(fromVersion: string, toVersion: string): ReadonlyArray<MigrationStep>;
+/**
+ * Checks whether a migration path exists from the artifact's current
+ * version to the target version.
+ *
+ * @param artifact - The artifact payload to check
+ * @param targetVersion - The desired target version (defaults to ARTIFACT_VERSION)
+ * @returns `true` if a migration path exists or the artifact is already at the target version
+ */
+declare function canMigrate(artifact: ArtifactPayload, targetVersion?: string): boolean;
+/**
+ * Migrates an artifact payload from its current schema version to the
+ * specified target version.
+ *
+ * **Identity Preservation:**
+ * - The original `contentHash` is preserved as `originalContentHash`
+ * - The `lineage.rootArtifactId` is NEVER modified
+ * - A new `contentHash` is computed after migration using `CURRENT_HASH_VERSION`
+ *
+ * **Non-Destructive:**
+ * - The input artifact object is never mutated
+ * - The canonical artifact file on disk is never modified
+ * - Migration produces a new in-memory representation only
+ *
+ * @param artifact - The artifact payload to migrate
+ * @param targetVersion - The desired target version (defaults to ARTIFACT_VERSION)
+ * @returns MigrationResult with the migrated artifact and metadata
+ * @throws Error if no migration path exists
+ *
+ * @example
+ * ```typescript
+ * const result = migrateArtifactPayload(legacyArtifact);
+ * if (result.migrated) {
+ *   console.log(`Migrated from ${result.appliedSteps[0].fromVersion}`);
+ *   console.log(`Original hash preserved: ${result.originalContentHash}`);
+ * }
+ * ```
+ */
+declare function migrateArtifactPayload(artifact: ArtifactPayload, targetVersion?: string): MigrationResult;
 /**
  * Migrates a v1 artifact to canonical format by updating the schema, version,
  * and calculating the contentHash.
+ *
+ * @deprecated Use `migrateArtifactPayload()` instead. This function is retained
+ * for backward compatibility with existing callers.
+ *
+ * @param v1Artifact - The legacy v1 artifact to migrate
+ * @returns The migrated artifact in canonical format
  */
-declare function migrateToCanonical(v1Artifact: any): any;
+declare function migrateToCanonical(v1Artifact: ArtifactPayload): ArtifactPayload;
 
 declare const bigIntReplacer: (_key: string, value: unknown) => unknown;
 declare function writeArtifact(filePath: string, artifact: unknown): Promise<void>;
@@ -2100,4 +2213,4 @@ declare function listDeployments(rootDir: string, networkId?: string): Promise<D
 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 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 DraftArtifact, 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, type Workflow, type WorkflowArtifact, WorkflowSchema, 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 };
+export { ARTIFACT_SCHEMAS, ARTIFACT_VERSION, AccountRefSchema, type ArtifactDiff, type ArtifactExplanation, ArtifactLineageSchema, type ArtifactLookup, type ArtifactPayload, 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 DraftArtifact, 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, type MigrationResult, type MigrationStep, 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, type Workflow, type WorkflowArtifact, WorkflowSchema, assertDecimalBigIntString, assertEvmAddress, assertEvmTxHash, assertHexData, assertValidIgraSignedTxArtifact, assertValidIgraTxPlanArtifact, assertValidIgraTxReceiptArtifact, assertValidSignedTxArtifact, assertValidTxPlanArtifact, assertValidTxReceiptArtifact, bigIntReplacer, calculateContentHash, canMigrate, canonicalStringify, createDeploymentRecord, createIgraDeployPlanId, createIgraPlanId, createIgraSignedId, createSimulatedSignedTxArtifact, createSimulatedTxReceipt, createTxPlanArtifact, defaultClock, deleteDeployment, detectArtifactVersion, diffArtifacts, explainArtifact, formatSignedTxArtifact, formatTxPlanArtifact, formatTxReceiptArtifact, getBroadcastableSignedTransaction, getDefaultL2ReceiptsDir, getDefaultReceiptPath, getL2ReceiptPath, getMigrationPath, getRegisteredMigrationSteps, isIgraTxPlanArtifact, listDeployments, listIgraTxReceiptArtifacts, loadDeployment, loadIgraTxReceiptArtifact, migrateArtifactPayload, migrateToCanonical, readArtifact, readSignedTxArtifact, readTxPlanArtifact, readTxReceiptArtifact, recomputeMass, registerMigrationStep, 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,7 +1,7 @@
 // package.json
 var package_default = {
   name: "@hardkas/artifacts",
-  version: "0.6.0-alpha",
+  version: "0.6.1-alpha",
   type: "module",
   license: "MIT",
   author: "Javier Rodriguez",
@@ -214,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);
@@ -595,6 +595,7 @@ 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;
@@ -995,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;
+  }
+  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;
   }
-  v2Artifact.contentHash = calculateContentHash(v2Artifact);
-  return v2Artifact;
+  const result = migrateArtifactPayload(v1Artifact, ARTIFACT_VERSION);
+  return result.artifact;
 }
 
 // src/io.ts
@@ -1710,6 +1829,7 @@ export {
   assertValidTxReceiptArtifact,
   bigIntReplacer,
   calculateContentHash,
+  canMigrate,
   canonicalStringify,
   createDeploymentRecord,
   createIgraDeployPlanId,
@@ -1720,6 +1840,7 @@ export {
   createTxPlanArtifact,
   defaultClock,
   deleteDeployment,
+  detectArtifactVersion,
   diffArtifacts,
   explainArtifact,
   formatSignedTxArtifact,
@@ -1729,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/artifacts",
-  "version": "0.6.0-alpha",
+  "version": "0.6.1-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.6.0-alpha",
-    "@hardkas/tx-builder": "0.6.0-alpha"
+    "@hardkas/core": "0.6.1-alpha",
+    "@hardkas/tx-builder": "0.6.1-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",