@hardkas/artifacts 0.8.2-alpha → 0.8.4-alpha

package/dist/index.js

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "@hardkas/artifacts",
-  version: "0.8.1-alpha",
+  version: "0.8.4-alpha",
   type: "module",
   license: "MIT",
   author: "Javier Rodriguez",
@@ -53,7 +53,11 @@ var ARTIFACT_SCHEMAS = {
   SNAPSHOT: "hardkas.snapshot",
   IGRA_TX_PLAN: "hardkas.igraTxPlan.v1",
   IGRA_SIGNED_TX: "hardkas.igraSignedTx.v1",
-  IGRA_TX_RECEIPT: "hardkas.igraTxReceipt.v1"
+  IGRA_TX_RECEIPT: "hardkas.igraTxReceipt.v1",
+  POLICY: "hardkas.policy.v1",
+  NETWORK_PROFILE: "hardkas.networkProfile.v1",
+  ASSUMPTION: "hardkas.assumption.v1",
+  MIGRATION_RECEIPT: "hardkas.migrationReceipt.v1"
 };
 
 // src/igra-artifacts.ts
@@ -345,6 +349,41 @@ var AccountRefSchema = z.object({
   accountName: z.string().optional(),
   input: z.string().optional()
 });
+var PolicySchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.policy.v1"),
+  decision: z.enum(["ALLOW", "DENY"]),
+  rules: z.array(
+    z.object({
+      id: z.string(),
+      result: z.enum(["PASS", "FAIL"]),
+      inputHash: z.string().optional()
+    })
+  )
+});
+var NetworkProfileSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.networkProfile.v1"),
+  networkProfileId: z.string(),
+  layer: z.string(),
+  capabilities: z.record(z.any())
+});
+var AssumptionSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.assumption.v1"),
+  settlement: z.string().optional(),
+  securityModel: z.string().optional(),
+  bridgePhase: z.string().optional(),
+  exitModel: z.string().optional(),
+  customAssumptions: z.record(z.any()).optional()
+});
+var MigrationReceiptSchema = BaseArtifactSchema.extend({
+  schema: z.literal("hardkas.migrationReceipt.v1"),
+  oldHash: z.string(),
+  newHash: z.string(),
+  fromSchema: z.string(),
+  toSchema: z.string(),
+  migrationId: z.string(),
+  migrationVersion: z.string().optional(),
+  decision: z.literal("MIGRATED_WITH_PROOF")
+});
 var TxPlanSchema = BaseArtifactSchema.extend({
   schema: z.literal("hardkas.txPlan"),
   networkId: kaspaNetworkIdSchema,
@@ -374,7 +413,11 @@ var TxPlanSchema = BaseArtifactSchema.extend({
     address: z.string(),
     amountSompi: z.string()
   }).optional(),
-  rpcUrl: z.string().optional()
+  rpcUrl: z.string().optional(),
+  networkProfileRef: z.string().optional(),
+  policyRef: z.string().optional(),
+  policyRefs: z.array(z.string()).optional(),
+  assumptionRef: z.string().optional()
 });
 var DagContextSchema = z.object({
   mode: z.enum(["linear", "dag-light"]),
@@ -539,6 +582,7 @@ var RuntimeSessionSchema = BaseArtifactSchema.extend({
 
 // src/verify.ts
 import fs from "fs";
+import path from "path";
 
 // src/feeVerify.ts
 import {
@@ -727,12 +771,21 @@ function verifyLineage(artifact, parent, options = {}) {
   }
   if (parent) {
     const validTransitions = {
-      "hardkas.snapshot": ["hardkas.txPlan"],
-      "hardkas.txPlan": ["hardkas.signedTx"],
-      "hardkas.signedTx": ["hardkas.txReceipt"]
+      "hardkas.snapshot": ["hardkas.txPlan", "hardkas.migrationReceipt.v1"],
+      "hardkas.txPlan": ["hardkas.signedTx", "hardkas.migrationReceipt.v1"],
+      "hardkas.signedTx": ["hardkas.txReceipt", "hardkas.signedTx", "hardkas.migrationReceipt.v1"],
+      "hardkas.txReceipt": ["hardkas.txTrace", "hardkas.migrationReceipt.v1"]
     };
-    const allowed = validTransitions[parent.schema] || [];
-    if (!allowed.includes(artifact.schema)) {
+    let isValidTransition = false;
+    if (parent.schema === "hardkas.migrationReceipt.v1") {
+      isValidTransition = parent.toSchema === artifact.schema;
+    } else if (artifact.schema === "hardkas.migrationReceipt.v1") {
+      isValidTransition = artifact.fromSchema === parent.schema;
+    } else {
+      const allowed = validTransitions[parent.schema] || [];
+      isValidTransition = allowed.includes(artifact.schema);
+    }
+    if (!isValidTransition) {
       addIssue(
         "INVALID_TRANSITION",
         `Invalid lineage transition: ${parent.schema} -> ${artifact.schema}`
@@ -764,15 +817,15 @@ function sortUtxosByOutpoint(utxos) {
     return deterministicCompare2(aId, bId);
   });
 }
-async function verifyArtifactIntegrity(artifactOrPath) {
+function verifyArtifactIntegritySync(artifactOrPath) {
   const result = {
     ok: false,
     errors: [],
     issues: []
   };
-  const addError = (code, message, path4) => {
+  const addError = (code, message, path5) => {
     result.errors.push(message);
-    result.issues.push({ code, severity: "error", message, path: path4 });
+    result.issues.push({ code, severity: "error", message, path: path5 });
   };
   let artifact;
   try {
@@ -844,6 +897,18 @@ async function verifyArtifactIntegrity(artifactOrPath) {
       case "hardkas.workflow.v1":
         schema = WorkflowSchema;
         break;
+      case "hardkas.policy.v1":
+        schema = PolicySchema;
+        break;
+      case "hardkas.networkProfile.v1":
+        schema = NetworkProfileSchema;
+        break;
+      case "hardkas.assumption.v1":
+        schema = AssumptionSchema;
+        break;
+      case "hardkas.migrationReceipt.v1":
+        schema = MigrationReceiptSchema;
+        break;
     }
     if (schema) {
       const validation = schema.safeParse(v);
@@ -874,6 +939,37 @@ async function verifyArtifactIntegrity(artifactOrPath) {
     return result;
   }
 }
+async function verifyArtifactIntegrity(artifactOrPath) {
+  return verifyArtifactIntegritySync(artifactOrPath);
+}
+function findFileByHash(hash, dirs) {
+  const shortHash = hash.startsWith("plan-") || hash.startsWith("signed-") ? hash : hash.slice(0, 16);
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+    try {
+      const files = fs.readdirSync(dir);
+      if (files.includes(`${hash}.json`)) {
+        return path.join(dir, `${hash}.json`);
+      }
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        if (file.includes(hash) || file.includes(shortHash) || file.includes(hash.slice(0, 8))) {
+          const filePath = path.join(dir, file);
+          try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            const obj = JSON.parse(content);
+            if (obj.contentHash === hash || obj.artifactId === hash || obj.planId === hash || obj.signedId === hash || obj.txId === hash) {
+              return filePath;
+            }
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return null;
+}
 function verifyArtifactSemantics(artifact, context = {}) {
   const result = {
     ok: true,
@@ -899,6 +995,225 @@ function verifyArtifactSemantics(artifact, context = {}) {
     });
   }
   const v = artifact;
+  let parentObj = null;
+  if (strict) {
+    const searchDirs = [];
+    if (context.artifactsDir) {
+      searchDirs.push(context.artifactsDir);
+    }
+    searchDirs.push(path.join(process.cwd(), ".hardkas", "artifacts"));
+    searchDirs.push(path.join(process.cwd(), "artifacts"));
+    const policyRefs = [];
+    if (Array.isArray(v.policyRefs)) {
+      policyRefs.push(...v.policyRefs);
+    } else if (typeof v.policyRef === "string") {
+      policyRefs.push(v.policyRef);
+    }
+    for (const ref of policyRefs) {
+      let refObj = context.resolveArtifact ? context.resolveArtifact(ref) : null;
+      if (!refObj) {
+        const refFile = findFileByHash(ref, searchDirs);
+        if (refFile) {
+          try {
+            const content = fs.readFileSync(refFile, "utf-8");
+            refObj = JSON.parse(content);
+          } catch (e) {
+            addIssue({
+              code: "REFERENCE_CORRUPT",
+              severity: "error",
+              message: `Failed to read policy ${ref}: ${e.message}`
+            });
+          }
+        }
+      }
+      if (!refObj) {
+        addIssue({
+          code: "REFERENCE_MISSING",
+          severity: "error",
+          message: `Referenced policy artifact ${ref} not found in workspace`
+        });
+      } else {
+        try {
+          const integrity = verifyArtifactIntegritySync(refObj);
+          if (!integrity.ok) {
+            addIssue({
+              code: "REFERENCE_HASH_MISMATCH",
+              severity: "error",
+              message: `Referenced policy ${ref} integrity check failed: ${integrity.errors.join(", ")}`
+            });
+          } else if (refObj.contentHash !== ref && refObj.artifactId !== ref) {
+            addIssue({
+              code: "REFERENCE_HASH_MISMATCH",
+              severity: "error",
+              message: `Policy reference mismatch: expected ${ref}, got ${refObj.contentHash}`
+            });
+          } else {
+            if (refObj.schema === "hardkas.policy.v1") {
+              if (refObj.decision === "DENY") {
+                addIssue({
+                  code: "POLICY_VIOLATION",
+                  severity: "error",
+                  message: `Policy evaluation rejected: decision is DENY`
+                });
+              } else if (refObj.decision !== "ALLOW") {
+                addIssue({
+                  code: "POLICY_VIOLATION",
+                  severity: "error",
+                  message: `Policy evaluation rejected: decision is invalid (${refObj.decision})`
+                });
+              }
+              const failedRules = refObj.rules?.filter((r) => r.result === "FAIL") || [];
+              if (failedRules.length > 0) {
+                addIssue({
+                  code: "POLICY_VIOLATION",
+                  severity: "error",
+                  message: `Policy rules failed: ${failedRules.map((r) => r.id).join(", ")}`
+                });
+              }
+            }
+          }
+        } catch (e) {
+          addIssue({
+            code: "REFERENCE_CORRUPT",
+            severity: "error",
+            message: `Failed to read/verify policy ${ref}: ${e.message}`
+          });
+        }
+      }
+    }
+    if (typeof v.networkProfileRef === "string") {
+      const ref = v.networkProfileRef;
+      let refObj = context.resolveArtifact ? context.resolveArtifact(ref) : null;
+      if (!refObj) {
+        const refFile = findFileByHash(ref, searchDirs);
+        if (refFile) {
+          try {
+            refObj = JSON.parse(fs.readFileSync(refFile, "utf-8"));
+          } catch {
+          }
+        }
+      }
+      if (!refObj) {
+        addIssue({
+          code: "REFERENCE_MISSING",
+          severity: "error",
+          message: `Referenced network profile ${ref} not found in workspace`
+        });
+      } else {
+        try {
+          const integrity = verifyArtifactIntegritySync(refObj);
+          if (!integrity.ok) {
+            addIssue({
+              code: "REFERENCE_HASH_MISMATCH",
+              severity: "error",
+              message: `Referenced profile ${ref} integrity check failed`
+            });
+          } else if (refObj.contentHash !== ref && refObj.artifactId !== ref) {
+            addIssue({
+              code: "REFERENCE_HASH_MISMATCH",
+              severity: "error",
+              message: `Profile reference mismatch: expected ${ref}, got ${refObj.contentHash}`
+            });
+          }
+        } catch (e) {
+          addIssue({
+            code: "REFERENCE_CORRUPT",
+            severity: "error",
+            message: `Failed to verify profile ${ref}`
+          });
+        }
+      }
+    }
+    if (typeof v.assumptionRef === "string") {
+      const ref = v.assumptionRef;
+      let refObj = context.resolveArtifact ? context.resolveArtifact(ref) : null;
+      if (!refObj) {
+        const refFile = findFileByHash(ref, searchDirs);
+        if (refFile) {
+          try {
+            refObj = JSON.parse(fs.readFileSync(refFile, "utf-8"));
+          } catch {
+          }
+        }
+      }
+      if (!refObj) {
+        addIssue({
+          code: "REFERENCE_MISSING",
+          severity: "error",
+          message: `Referenced assumption ${ref} not found in workspace`
+        });
+      } else {
+        try {
+          const integrity = verifyArtifactIntegritySync(refObj);
+          if (!integrity.ok) {
+            addIssue({
+              code: "REFERENCE_HASH_MISMATCH",
+              severity: "error",
+              message: `Referenced assumption ${ref} integrity check failed`
+            });
+          } else if (refObj.contentHash !== ref && refObj.artifactId !== ref) {
+            addIssue({
+              code: "REFERENCE_HASH_MISMATCH",
+              severity: "error",
+              message: `Assumption reference mismatch: expected ${ref}, got ${refObj.contentHash}`
+            });
+          }
+        } catch (e) {
+          addIssue({
+            code: "REFERENCE_CORRUPT",
+            severity: "error",
+            message: `Failed to verify assumption ${ref}`
+          });
+        }
+      }
+    }
+    let parentId;
+    const lineage = v.lineage;
+    if (lineage?.parentArtifactId && lineage?.parentArtifactId !== lineage?.artifactId) {
+      parentId = lineage?.parentArtifactId;
+    } else if (v.schema === "hardkas.signedTx") {
+      parentId = v.sourcePlanId;
+    } else if (v.schema === "hardkas.txReceipt") {
+      parentId = v.sourceSignedId || lineage?.parentArtifactId;
+    }
+    if (parentId) {
+      parentObj = context.resolveArtifact ? context.resolveArtifact(parentId) : null;
+      if (!parentObj) {
+        const parentFile = findFileByHash(parentId, searchDirs);
+        if (parentFile) {
+          try {
+            parentObj = JSON.parse(fs.readFileSync(parentFile, "utf-8"));
+          } catch (e) {
+            addIssue({
+              code: "PARENT_CORRUPT",
+              severity: "error",
+              message: `Failed to read parent ${parentId}: ${e.message}`
+            });
+          }
+        }
+      }
+      if (!parentObj) {
+        addIssue({
+          code: "PARENT_MISSING",
+          severity: "warning",
+          message: `Parent artifact ${parentId} not found in workspace`
+        });
+      } else {
+        try {
+          const parentSem = verifyArtifactSemantics(parentObj, { ...context, strict: true });
+          if (!parentSem.ok) {
+            parentSem.issues.forEach((issue) => addIssue(issue));
+          }
+        } catch (e) {
+          addIssue({
+            code: "PARENT_CORRUPT",
+            severity: "error",
+            message: `Failed to verify parent ${parentId}: ${e.message}`
+          });
+        }
+      }
+    }
+  }
   if (v.createdAt && typeof v.createdAt === "string") {
     const created = new Date(v.createdAt).getTime();
     const now = clock.now();
@@ -917,31 +1232,47 @@ function verifyArtifactSemantics(artifact, context = {}) {
       });
     }
   }
-  const lineageAudit = verifyLineage(v, context.parent, { strict });
+  const lineageAudit = verifyLineage(v, parentObj || context.parent, { strict });
   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 && 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"
-      });
+    const enforceMetadata = context.enforceMetadata ?? true;
+    if (enforceMetadata) {
+      if (!v.workflowId)
+        addIssue({
+          code: "MISSING_WORKFLOW_ID",
+          severity: "error",
+          message: "Strict mode requires workflowId"
+        });
+      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 && v.schema !== "hardkas.workflow.v1")
+        addIssue({
+          code: "MISSING_ASSUMPTION_LEVEL",
+          severity: "warning",
+          message: "Missing assumptionLevel"
+        });
+    }
   } else {
     if (!v.workflowId)
       addIssue({
@@ -1214,6 +1545,16 @@ var InvariantWatcher = class {
 };
 
 // src/migration.ts
+var MigrationRequiredError = class extends Error {
+  constructor(oldVersion, targetVersion) {
+    super(`MIGRATION_REQUIRED: Artifact requires explicit migration from ${oldVersion} to ${targetVersion}`);
+    this.oldVersion = oldVersion;
+    this.targetVersion = targetVersion;
+    this.name = "MigrationRequiredError";
+  }
+  oldVersion;
+  targetVersion;
+};
 var migrationRegistry = [];
 function registerMigrationStep(step) {
   const existing = migrationRegistry.find(
@@ -1235,6 +1576,9 @@ registerMigrationStep({
   description: "Legacy v1 schemas to canonical 1.0.0-alpha format",
   transform(artifact) {
     const migrated = { ...artifact };
+    if (migrated.lineage) {
+      migrated.lineage = { ...migrated.lineage };
+    }
     if (typeof migrated.schema === "string" && migrated.schema.endsWith(".v1")) {
       if (migrated.schema !== "hardkas.workflow.v1") {
         migrated.schema = migrated.schema.replace(/\.v1$/, "");
@@ -1299,10 +1643,10 @@ function canMigrate(artifact, targetVersion = ARTIFACT_VERSION) {
   if (currentVersion === targetVersion) {
     return true;
   }
-  const path4 = getMigrationPath(currentVersion, targetVersion);
-  return path4.length > 0;
+  const path5 = getMigrationPath(currentVersion, targetVersion);
+  return path5.length > 0;
 }
-function migrateArtifactPayload(artifact, targetVersion = ARTIFACT_VERSION) {
+function migrateArtifactPayload(artifact, targetVersion = ARTIFACT_VERSION, options) {
   const currentVersion = detectArtifactVersion(artifact);
   if (currentVersion === targetVersion) {
     return {
@@ -1312,8 +1656,11 @@ function migrateArtifactPayload(artifact, targetVersion = ARTIFACT_VERSION) {
       appliedSteps: []
     };
   }
-  const path4 = getMigrationPath(currentVersion, targetVersion);
-  if (path4.length === 0) {
+  if (options?.strictPolicy) {
+    throw new MigrationRequiredError(currentVersion, targetVersion);
+  }
+  const path5 = getMigrationPath(currentVersion, targetVersion);
+  if (path5.length === 0) {
     throw new Error(
       `No migration path from version "${currentVersion}" to "${targetVersion}". Registered steps: [${migrationRegistry.map((s) => `${s.fromVersion}\u2192${s.toVersion}`).join(", ")}]`
     );
@@ -1322,7 +1669,7 @@ function migrateArtifactPayload(artifact, targetVersion = ARTIFACT_VERSION) {
   const originalLineage = artifact.lineage;
   let current = { ...artifact };
   const appliedSteps = [];
-  for (const step of path4) {
+  for (const step of path5) {
     current = step.transform(current);
     appliedSteps.push({
       fromVersion: step.fromVersion,
@@ -1355,10 +1702,51 @@ function migrateToCanonical(v1Artifact) {
   const result = migrateArtifactPayload(v1Artifact, ARTIFACT_VERSION);
   return result.artifact;
 }
+function generateMigrationReceipt(oldArtifact, newArtifact, migrationId) {
+  const oldHash = oldArtifact.contentHash || calculateContentHash(oldArtifact, CURRENT_HASH_VERSION);
+  const newHash = newArtifact.contentHash || calculateContentHash(newArtifact, CURRENT_HASH_VERSION);
+  const receipt = {
+    schema: "hardkas.migrationReceipt.v1",
+    hardkasVersion: HARDKAS_VERSION,
+    version: ARTIFACT_VERSION,
+    hashVersion: CURRENT_HASH_VERSION,
+    networkId: oldArtifact.networkId || "simnet",
+    mode: oldArtifact.mode || "simulated",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    oldHash,
+    newHash,
+    fromSchema: oldArtifact.schema || "unknown",
+    toSchema: newArtifact.schema || "unknown",
+    migrationId,
+    decision: "MIGRATED_WITH_PROOF",
+    lineage: {
+      artifactId: "",
+      // Filled after hash
+      lineageId: oldArtifact.lineage?.lineageId || ("migration" + oldHash).padEnd(64, "0").slice(0, 64),
+      parentArtifactId: oldHash,
+      rootArtifactId: oldArtifact.lineage?.rootArtifactId || oldHash
+    }
+  };
+  receipt.contentHash = calculateContentHash(receipt, CURRENT_HASH_VERSION);
+  receipt.lineage.artifactId = receipt.contentHash;
+  if (!newArtifact.lineage) {
+    newArtifact.lineage = {
+      artifactId: newHash,
+      lineageId: receipt.lineage.lineageId,
+      parentArtifactId: receipt.contentHash,
+      rootArtifactId: receipt.lineage.rootArtifactId
+    };
+  } else {
+    newArtifact.lineage.parentArtifactId = receipt.contentHash;
+  }
+  newArtifact.contentHash = calculateContentHash(newArtifact, CURRENT_HASH_VERSION);
+  newArtifact.lineage.artifactId = newArtifact.contentHash;
+  return receipt;
+}
 
 // src/io.ts
 import fs2 from "fs/promises";
-import path from "path";
+import path2 from "path";
 import { writeFileAtomic } from "@hardkas/core";
 var bigIntReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
 async function writeArtifact(filePath, artifact) {
@@ -1369,10 +1757,10 @@ async function writeArtifact(filePath, artifact) {
       const artifactObj = typeof artifact === "string" ? JSON.parse(artifact) : artifact;
       const id = artifactObj.planId || artifactObj.signedId || artifactObj.txId || Date.now().toString(36);
       const prefix = artifactObj.schema ? artifactObj.schema.split(".")[1] || "artifact" : "artifact";
-      targetPath = path.join(filePath, `${prefix}-${id}.json`);
+      targetPath = path2.join(filePath, `${prefix}-${id}.json`);
       console.log(
         `
-Note: Provided path is a directory. Auto-generating artifact filename: ${path.basename(targetPath)}`
+Note: Provided path is a directory. Auto-generating artifact filename: ${path2.basename(targetPath)}`
       );
     }
   } catch (e) {
@@ -1380,14 +1768,14 @@ Note: Provided path is a directory. Auto-generating artifact filename: ${path.ba
       const artifactObj = typeof artifact === "string" ? JSON.parse(artifact) : artifact;
       const id = artifactObj.planId || artifactObj.signedId || artifactObj.txId || Date.now().toString(36);
       const prefix = artifactObj.schema ? artifactObj.schema.split(".")[1] || "artifact" : "artifact";
-      targetPath = path.join(filePath, `${prefix}-${id}.json`);
+      targetPath = path2.join(filePath, `${prefix}-${id}.json`);
     }
   }
   const content = typeof artifact === "string" ? artifact : JSON.stringify(artifact, bigIntReplacer, 2) + "\n";
   await writeFileAtomic(targetPath, content);
 }
 function getDefaultReceiptPath(txId, cwd = process.cwd()) {
-  return path.join(cwd, "artifacts", "receipts", `${txId}.json`);
+  return path2.join(cwd, "artifacts", "receipts", `${txId}.json`);
 }
 async function readArtifact(filePath) {
   try {
@@ -1593,6 +1981,14 @@ function createTxPlanArtifact(options) {
       amountSompi: o.amountSompi.toString()
     })),
     rpcUrl: options.rpcUrl,
+    lineage: {
+      artifactId: "",
+      lineageId: "0".repeat(64),
+      // placeholder, will be replaced if empty
+      parentArtifactId: "",
+      rootArtifactId: "",
+      sequence: 1
+    },
     ...options.ctx.workflowId ? { workflowId: options.ctx.workflowId } : {}
   };
   if (options.plan.change) {
@@ -1604,6 +2000,18 @@ function createTxPlanArtifact(options) {
   const hash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
   artifact.planId = `plan-${hash.slice(0, 16)}`;
   artifact.contentHash = hash;
+  if (artifact.lineage) {
+    artifact.lineage.lineageId = artifact.contentHash;
+    artifact.lineage.artifactId = artifact.contentHash;
+    artifact.lineage.parentArtifactId = artifact.contentHash;
+    artifact.lineage.rootArtifactId = artifact.contentHash;
+    const finalHash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
+    artifact.planId = `plan-${finalHash.slice(0, 16)}`;
+    artifact.contentHash = finalHash;
+    artifact.lineage.artifactId = finalHash;
+    artifact.lineage.parentArtifactId = finalHash;
+    artifact.lineage.rootArtifactId = finalHash;
+  }
   return artifact;
 }
 
@@ -1628,11 +2036,21 @@ function createSimulatedSignedTxArtifact(plan, payload, ctx) {
       format: "simulated",
       payload
     },
+    lineage: {
+      artifactId: "",
+      lineageId: plan.lineage?.lineageId || plan.contentHash || "0".repeat(64),
+      parentArtifactId: plan.contentHash || "0".repeat(64),
+      rootArtifactId: plan.lineage?.rootArtifactId || plan.contentHash || "0".repeat(64),
+      sequence: (plan.lineage?.sequence || 0) + 1
+    },
     ...plan.workflowId ? { workflowId: plan.workflowId } : {}
   };
   const hash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
   artifact.signedId = `signed-${hash.slice(0, 16)}`;
   artifact.contentHash = hash;
+  if (artifact.lineage) {
+    artifact.lineage.artifactId = hash;
+  }
   return artifact;
 }
 function createSimulatedTxReceipt(plan, txId, ctx, extra) {
@@ -1658,10 +2076,22 @@ function createSimulatedTxReceipt(plan, txId, ctx, extra) {
     preStateHash: extra?.preStateHash,
     postStateHash: extra?.postStateHash,
     dagContext: extra?.dagContext,
+    lineage: {
+      artifactId: "",
+      lineageId: plan.lineage?.lineageId || plan.contentHash || "0".repeat(64),
+      parentArtifactId: "0".repeat(64),
+      // Will set to contentHash of signedTx later
+      rootArtifactId: plan.lineage?.rootArtifactId || plan.contentHash || "0".repeat(64),
+      sequence: (plan.lineage?.sequence || 1) + 1
+    },
     ...plan.workflowId ? { workflowId: plan.workflowId } : {}
   };
   const hash = calculateContentHash(artifact, CURRENT_HASH_VERSION);
   artifact.contentHash = hash;
+  if (artifact.lineage) {
+    artifact.lineage.artifactId = hash;
+    artifact.lineage.parentArtifactId = extra?.preStateHash || txId.replace("simulated-", "").replace("-tx", "").padEnd(64, "0").slice(0, 64);
+  }
   return artifact;
 }
 function getBroadcastableSignedTransaction(artifact) {
@@ -1878,15 +2308,15 @@ async function explainArtifact(artifactUnknown) {
 
 // src/igra-io.ts
 import fs3 from "fs/promises";
-import path2 from "path";
+import path3 from "path";
 import { deterministicCompare as deterministicCompare3 } from "@hardkas/core";
 function getDefaultL2ReceiptsDir(cwd = process.cwd()) {
-  return path2.join(cwd, ".hardkas", "l2-receipts");
+  return path3.join(cwd, ".hardkas", "l2-receipts");
 }
 function getL2ReceiptPath(txHash, options) {
   validateTxHash(txHash);
   const dir = getDefaultL2ReceiptsDir(options?.cwd);
-  return path2.join(dir, `${txHash}.igra.receipt.json`);
+  return path3.join(dir, `${txHash}.igra.receipt.json`);
 }
 async function saveIgraTxReceiptArtifact(receipt, options) {
   assertValidIgraTxReceiptArtifact(receipt);
@@ -1908,7 +2338,7 @@ async function listIgraTxReceiptArtifacts(options) {
     const receipts = [];
     for (const file of receiptFiles) {
       try {
-        const data = await readArtifact(path2.join(dir, file));
+        const data = await readArtifact(path3.join(dir, file));
         if (data && typeof data === "object" && data.schema === "hardkas.igraTxReceipt.v1") {
           receipts.push(data);
         }
@@ -1941,26 +2371,26 @@ function diffArtifacts(left, right) {
     entries
   };
 }
-function compareRecursive(left, right, path4, entries) {
+function compareRecursive(left, right, path5, entries) {
   if (isPrimitive(left) || isPrimitive(right)) {
     if (left !== right) {
-      entries.push({ path: path4, kind: "changed", left, right });
+      entries.push({ path: path5, 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 });
+      entries.push({ path: path5, 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] });
+        entries.push({ path: `${path5}[${i}]`, kind: "added", right: right[i] });
       } else if (i >= right.length) {
-        entries.push({ path: `${path4}[${i}]`, kind: "removed", left: left[i] });
+        entries.push({ path: `${path5}[${i}]`, kind: "removed", left: left[i] });
       } else {
-        compareRecursive(left[i], right[i], `${path4}[${i}]`, entries);
+        compareRecursive(left[i], right[i], `${path5}[${i}]`, entries);
       }
     }
     return;
@@ -1969,7 +2399,7 @@ function compareRecursive(left, right, path4, entries) {
   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}`;
+    const nextPath = path5 === "$" ? key : `${path5}.${key}`;
     if (!leftKeys.includes(key)) {
       entries.push({ path: nextPath, kind: "added", right: right[key] });
     } else if (!rightKeys.includes(key)) {
@@ -2033,16 +2463,16 @@ function updateDeploymentStatus(record, newStatus, txId) {
 // src/deployment-store.ts
 import fs4 from "fs/promises";
 import { existsSync } from "fs";
-import path3 from "path";
+import path4 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`);
+  const deploymentsDir = path4.join(rootDir, ".hardkas", "deployments", record.networkId);
+  const targetPath = path4.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(
+  const targetPath = path4.join(
     rootDir,
     ".hardkas",
     "deployments",
@@ -2054,18 +2484,18 @@ async function loadDeployment(rootDir, networkId, label) {
   return JSON.parse(content);
 }
 async function listDeployments(rootDir, networkId) {
-  const baseDir = path3.join(rootDir, ".hardkas", "deployments");
+  const baseDir = path4.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);
+    const netDir = path4.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 content = await fs4.readFile(path4.join(netDir, file), "utf-8");
         const record = JSON.parse(content);
         const summary = {
           label: record.label,
@@ -2098,7 +2528,7 @@ async function updateDeployment(rootDir, networkId, label, update) {
   return updated;
 }
 async function deleteDeployment(rootDir, networkId, label) {
-  const targetPath = path3.join(
+  const targetPath = path4.join(
     rootDir,
     ".hardkas",
     "deployments",
@@ -2114,6 +2544,7 @@ export {
   ARTIFACT_VERSION,
   AccountRefSchema,
   ArtifactLineageSchema,
+  AssumptionSchema,
   BaseArtifactSchema,
   BasicCorrelationInvariant,
   BasicLineageInvariant,
@@ -2124,7 +2555,11 @@ export {
   InvariantWatcher,
   LifecycleInvariant,
   LocalnetUtxoSchemaV2,
+  MigrationReceiptSchema,
+  MigrationRequiredError,
   NetworkInvariant,
+  NetworkProfileSchema,
+  PolicySchema,
   ReplayInvariant,
   RuntimeSessionSchema,
   SEMANTIC_EXCLUSIONS,
@@ -2169,6 +2604,7 @@ export {
   formatSignedTxArtifact,
   formatTxPlanArtifact,
   formatTxReceiptArtifact,
+  generateMigrationReceipt,
   getBroadcastableSignedTransaction,
   getDefaultL2ReceiptsDir,
   getDefaultReceiptPath,
@@ -2207,6 +2643,7 @@ export {
   verifyArtifact,
   verifyArtifactFile,
   verifyArtifactIntegrity,
+  verifyArtifactIntegritySync,
   verifyArtifactReplay,
   verifyArtifactSemantics,
   verifyFeeSemantics,