@hardkas/artifacts 0.6.0-alpha → 0.7.0-alpha

package/dist/index.js

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "@hardkas/artifacts",
-  version: "0.6.0-alpha",
+  version: "0.7.0-alpha",
   type: "module",
   license: "MIT",
   author: "Javier Rodriguez",
@@ -205,7 +205,18 @@ var SEMANTIC_EXCLUSIONS = /* @__PURE__ */ new Set([
   "dagContext"
 ]);
 var CURRENT_HASH_VERSION = 3;
-function canonicalStringify(obj, version = CURRENT_HASH_VERSION) {
+var STRICT_PATH_KEYS = /* @__PURE__ */ new Set([
+  "file_path",
+  "sandboxSnapshotPath",
+  "receiptPath",
+  "tracePath",
+  "outputPath",
+  "artifactPath",
+  "workspacePath",
+  "relativePath",
+  "absolutePath"
+]);
+function canonicalStringify(obj, version = CURRENT_HASH_VERSION, keyName) {
   if (obj === null || typeof obj !== "object") {
     if (typeof obj === "bigint") {
       if (version >= 2) {
@@ -214,13 +225,16 @@ 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");
+      let normalized = obj.normalize("NFC").replace(/\r\n/g, "\n");
+      if (keyName && STRICT_PATH_KEYS.has(keyName)) {
+        normalized = normalized.replace(/\\/g, "/");
+      }
       return JSON.stringify(normalized);
     }
     return JSON.stringify(obj);
   }
   if (Array.isArray(obj)) {
-    return "[" + obj.map((item) => canonicalStringify(item, version)).join(",") + "]";
+    return "[" + obj.map((item) => canonicalStringify(item, version, keyName)).join(",") + "]";
   }
   if (obj instanceof Map) {
     throw new Error("Map is not canonicalizable. Use a plain object.");
@@ -240,7 +254,7 @@ function canonicalStringify(obj, version = CURRENT_HASH_VERSION) {
   ).sort(deterministicCompare);
   const result = sortedKeys.map((key) => {
     const value = obj[key];
-    return JSON.stringify(key) + ":" + canonicalStringify(value, version);
+    return JSON.stringify(key) + ":" + canonicalStringify(value, version, key);
   }).join(",");
   return "{" + result + "}";
 }
@@ -260,8 +274,24 @@ var ArtifactLineageSchema = z.object({
   rootArtifactId: z.string(),
   sequence: z.number().optional()
 });
+var ScriptCapabilitySchema = z.enum([
+  "p2pk",
+  "multisig",
+  "timelock",
+  "covenant-experimental",
+  "silverscript-experimental",
+  "tockata-experimental"
+]);
+var ScriptMetadataSchema = z.object({
+  language: z.enum(["native", "silverscript", "tockata"]).optional(),
+  version: z.string().optional(),
+  experimental: z.boolean(),
+  notes: z.array(z.string()).optional(),
+  consensusImpact: z.enum(["none", "experimental"]).optional()
+});
 var BaseArtifactSchema = z.object({
   schema: z.string(),
+  schemaVersion: z.string().optional(),
   hardkasVersion: z.string(),
   version: z.literal(ARTIFACT_VERSION),
   hashVersion: z.union([z.number(), z.string()]).optional(),
@@ -269,7 +299,13 @@ var BaseArtifactSchema = z.object({
   mode: executionModeSchema,
   contentHash: z.string().optional(),
   createdAt: z.string().datetime(),
-  lineage: ArtifactLineageSchema.optional()
+  lineage: ArtifactLineageSchema.optional(),
+  parents: z.array(z.string()).optional(),
+  lineageDepth: z.number().optional(),
+  workflowId: z.string().optional(),
+  scriptProfile: z.enum(["standard", "experimental"]).optional(),
+  scriptCapabilities: z.array(ScriptCapabilitySchema).optional(),
+  scriptMetadata: ScriptMetadataSchema.optional()
 });
 var AccountRefSchema = z.object({
   address: z.string(),
@@ -429,6 +465,17 @@ var WorkflowSchema = BaseArtifactSchema.extend({
     redacted: z.boolean()
   }).optional()
 });
+var RuntimeSessionSchema = BaseArtifactSchema.extend({
+  sessionId: z.string(),
+  workflowIds: z.array(z.string()),
+  artifactIds: z.array(z.string()),
+  startedAt: z.string().datetime(),
+  network: z.string(),
+  deterministic: z.boolean(),
+  snapshotOf: z.string().optional(),
+  parentSessionId: z.string().optional(),
+  notes: z.string().optional()
+});
 
 // src/verify.ts
 import fs from "fs";
@@ -595,6 +642,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 +1043,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 });
+      }
+    }
+  }
+  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 (!v2Artifact.createdAt) {
-    v2Artifact.createdAt = (/* @__PURE__ */ new Date()).toISOString();
+  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
@@ -1193,6 +1359,7 @@ function createTxPlanArtifact(options) {
   const artifact = {
     schema: "hardkas.txPlan",
     hardkasVersion: HARDKAS_VERSION,
+    schemaVersion: "hardkas.artifact.v1",
     version: ARTIFACT_VERSION,
     hashVersion: CURRENT_HASH_VERSION,
     createdAt: new Date(options.ctx.clock.now()).toISOString(),
@@ -1239,6 +1406,7 @@ function createTxPlanArtifact(options) {
 function createSimulatedSignedTxArtifact(plan, payload, ctx) {
   const artifact = {
     schema: "hardkas.signedTx",
+    schemaVersion: "hardkas.artifact.v1",
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
     hashVersion: CURRENT_HASH_VERSION,
@@ -1264,6 +1432,7 @@ function createSimulatedSignedTxArtifact(plan, payload, ctx) {
 function createSimulatedTxReceipt(plan, txId, ctx, extra) {
   const artifact = {
     schema: "hardkas.txReceipt",
+    schemaVersion: "hardkas.receipt.v1",
     hardkasVersion: HARDKAS_VERSION,
     version: ARTIFACT_VERSION,
     hashVersion: CURRENT_HASH_VERSION,
@@ -1690,8 +1859,12 @@ export {
   LocalnetUtxoSchemaV2,
   NetworkInvariant,
   ReplayInvariant,
+  RuntimeSessionSchema,
   SEMANTIC_EXCLUSIONS,
+  STRICT_PATH_KEYS,
   SchemaInvariant,
+  ScriptCapabilitySchema,
+  ScriptMetadataSchema,
   SignedTxSchema,
   SnapshotSchema,
   TxPlanSchema,
@@ -1710,6 +1883,7 @@ export {
   assertValidTxReceiptArtifact,
   bigIntReplacer,
   calculateContentHash,
+  canMigrate,
   canonicalStringify,
   createDeploymentRecord,
   createIgraDeployPlanId,
@@ -1720,6 +1894,7 @@ export {
   createTxPlanArtifact,
   defaultClock,
   deleteDeployment,
+  detectArtifactVersion,
   diffArtifacts,
   explainArtifact,
   formatSignedTxArtifact,
@@ -1729,17 +1904,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.7.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.6.0-alpha",
-    "@hardkas/tx-builder": "0.6.0-alpha"
+    "@hardkas/core": "0.7.0-alpha",
+    "@hardkas/tx-builder": "0.7.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",