@hardkas/core 0.5.5-alpha → 0.6.1-alpha

package/dist/index.js

@@ -1,7 +1,244 @@
 // src/index.ts
 import { z } from "zod";
 
+// src/append-coordinator.ts
+import fs from "fs";
+import path2 from "path";
+
+// src/telemetry.ts
+import path from "path";
+import crypto2 from "crypto";
+import { AsyncLocalStorage } from "async_hooks";
+var TelemetryManager = class {
+  rootDir = null;
+  currentContext = {};
+  // Track sandboxes that need to be preserved because they hit severe anomalies
+  preservedSandboxes = /* @__PURE__ */ new Set();
+  constructor(rootDir) {
+    if (rootDir) this.rootDir = rootDir;
+  }
+  init(rootDir) {
+    this.rootDir = rootDir;
+  }
+  setContext(context) {
+    this.currentContext = { ...this.currentContext, ...context };
+  }
+  clearContext() {
+    this.currentContext = {};
+  }
+  getContext() {
+    return this.currentContext;
+  }
+  logAnomaly(anomalyType, severity, subsystem, details, sandboxOverride) {
+    const logDir = this.rootDir ? path.join(this.rootDir, ".hardkas", "telemetry") : sandboxOverride ? path.join(sandboxOverride, ".hardkas", "telemetry") : null;
+    if (!logDir) return;
+    const nowStr = (/* @__PURE__ */ new Date()).toISOString();
+    const runId = this.currentContext.seed ? `run-${this.currentContext.seed}` : "run-core";
+    const bucket = this.currentContext.bucket || "core";
+    let mappedSeverity = "nominal";
+    if (severity === "medium") mappedSeverity = "elevated";
+    else if (severity === "high" || severity === "critical") mappedSeverity = "critical";
+    const canonicalPayloadRaw = JSON.stringify({
+      runId,
+      bucket,
+      type: anomalyType,
+      severity: mappedSeverity,
+      caseId: this.currentContext.caseId,
+      payload: {
+        subsystem,
+        details,
+        sandbox: sandboxOverride
+      }
+    });
+    const eventHash = crypto2.createHash("sha256").update(canonicalPayloadRaw).digest("hex").slice(0, 32);
+    const eventIdRaw = `${eventHash}-${nowStr}`;
+    const eventId = crypto2.createHash("sha256").update(eventIdRaw).digest("hex").slice(0, 32);
+    const event = {
+      schemaVersion: "hardkas.telemetry.v1",
+      eventId,
+      eventHash,
+      timestamp: nowStr,
+      source: "core-runtime",
+      runId,
+      bucket,
+      type: anomalyType,
+      severity: mappedSeverity,
+      caseId: this.currentContext.caseId,
+      payload: {
+        subsystem,
+        details,
+        sandbox: sandboxOverride
+      }
+    };
+    if (severity === "high" || severity === "critical" || anomalyType === "REPLAY_RECONCILIATION" || anomalyType === "NORMALIZATION_COLLISION") {
+      if (sandboxOverride) {
+        this.preservedSandboxes.add(sandboxOverride);
+      }
+    }
+    try {
+      const logFile = path.join(logDir, "telemetry.jsonl");
+      const root = this.rootDir || sandboxOverride || process.cwd();
+      AppendCoordinator.appendAtomic(logFile, JSON.stringify(event), root);
+    } catch (err) {
+    }
+  }
+  shouldPreserveSandbox(sandboxDir) {
+    return this.preservedSandboxes.has(sandboxDir);
+  }
+};
+var telemetryContextStorage = new AsyncLocalStorage();
+var globalTelemetry = new TelemetryManager();
+function getTelemetry() {
+  return telemetryContextStorage.getStore() || globalTelemetry;
+}
+var TelemetryProxy = class {
+  logAnomaly(anomalyType, severity, subsystem, details, sandboxOverride) {
+    return getTelemetry().logAnomaly(anomalyType, severity, subsystem, details, sandboxOverride);
+  }
+  init(rootDir) {
+    return getTelemetry().init(rootDir);
+  }
+  setContext(context) {
+    return getTelemetry().setContext(context);
+  }
+  clearContext() {
+    return getTelemetry().clearContext();
+  }
+  getContext() {
+    return getTelemetry().getContext();
+  }
+  shouldPreserveSandbox(sandboxDir) {
+    return getTelemetry().shouldPreserveSandbox(sandboxDir);
+  }
+};
+var EnvironmentTelemetry = new TelemetryProxy();
+
+// src/append-coordinator.ts
+var AppendCoordinator = class _AppendCoordinator {
+  /**
+   * Safely appends a line to a JSONL log under process coordination locks.
+   * Performs an immediate fsync to ensure data durability.
+   * Also repairs the trailing line if it is corrupted, emitting an anomaly.
+   */
+  static appendAtomic(filePath, line, rootDir) {
+    const lockDir = path2.join(rootDir, ".hardkas", "locks");
+    if (!fs.existsSync(lockDir)) {
+      fs.mkdirSync(lockDir, { recursive: true });
+    }
+    const logBase = path2.basename(filePath);
+    const lockPath = path2.join(lockDir, `append-${logBase}.lock`);
+    let fd = null;
+    let repaired = false;
+    let linesDiscarded = 0;
+    let originalTail = "";
+    try {
+      const start = Date.now();
+      const timeoutMs = 1e4;
+      while (true) {
+        try {
+          fd = fs.openSync(lockPath, "wx");
+          break;
+        } catch (e) {
+          if (e.code === "EEXIST") {
+            if (Date.now() - start > timeoutMs) {
+              throw new Error(`[AppendCoordinator] Timeout waiting for lock on ${lockPath}`);
+            }
+            const sleepMs = 5 + Math.floor(Math.random() * 15);
+            const sharedBuf = new Int32Array(new SharedArrayBuffer(4));
+            Atomics.wait(sharedBuf, 0, 0, sleepMs);
+            continue;
+          }
+          throw e;
+        }
+      }
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, time: (/* @__PURE__ */ new Date()).toISOString() }));
+      const recovery = _AppendCoordinator.recoverCorruptedTail(filePath);
+      if (recovery.repaired) {
+        repaired = true;
+        linesDiscarded = recovery.linesDiscarded;
+        originalTail = recovery.originalTail;
+      }
+      const logDir = path2.dirname(filePath);
+      if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+      }
+      const logFd = fs.openSync(filePath, "a");
+      const buffer = Buffer.from(line.endsWith("\n") ? line : line + "\n", "utf-8");
+      fs.writeSync(logFd, buffer, 0, buffer.length);
+      fs.fsyncSync(logFd);
+      fs.closeSync(logFd);
+    } finally {
+      if (fd !== null) {
+        fs.closeSync(fd);
+        try {
+          fs.unlinkSync(lockPath);
+        } catch {
+        }
+      }
+    }
+    if (repaired) {
+      try {
+        const telemetry = getTelemetry();
+        telemetry.logAnomaly(
+          "EXTERNAL_MUTATION",
+          "medium",
+          "fs",
+          `Recovered corrupted trailing line in ${logBase}. Discarded ${linesDiscarded} malformed bytes. Original tail snippet: "${originalTail.slice(0, 60)}..."`,
+          rootDir
+        );
+      } catch {
+      }
+    }
+  }
+  /**
+   * Scans a JSONL stream for corruption, truncating malformed trailing lines.
+   */
+  static recoverCorruptedTail(filePath) {
+    if (!fs.existsSync(filePath)) return { repaired: false, linesDiscarded: 0, originalTail: "" };
+    const stat = fs.statSync(filePath);
+    if (stat.size === 0) return { repaired: false, linesDiscarded: 0, originalTail: "" };
+    const TAIL_SIZE = 4096;
+    const readStart = Math.max(0, stat.size - TAIL_SIZE);
+    const fd = fs.openSync(filePath, "r");
+    const buf = Buffer.alloc(Math.min(TAIL_SIZE, stat.size));
+    fs.readSync(fd, buf, 0, buf.length, readStart);
+    fs.closeSync(fd);
+    const tail = buf.toString("utf-8");
+    const lines = tail.split("\n");
+    if (lines.length === 0) return { repaired: false, linesDiscarded: 0, originalTail: "" };
+    let lastLine = "";
+    let lastLineIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const l = lines[i].trim();
+      if (l) {
+        lastLine = l;
+        lastLineIdx = i;
+        break;
+      }
+    }
+    if (!lastLine) return { repaired: false, linesDiscarded: 0, originalTail: "" };
+    if (readStart > 0 && lastLineIdx === 0) {
+      return { repaired: false, linesDiscarded: 0, originalTail: "" };
+    }
+    try {
+      JSON.parse(lastLine);
+      return { repaired: false, linesDiscarded: 0, originalTail: "" };
+    } catch (err) {
+      const linesAfterCorrupt = lines.slice(lastLineIdx).join("\n");
+      const bytesToRemove = Buffer.byteLength(linesAfterCorrupt, "utf-8");
+      const truncateTo = stat.size - bytesToRemove;
+      fs.truncateSync(filePath, truncateTo > 0 ? truncateTo : 0);
+      return {
+        repaired: true,
+        linesDiscarded: stat.size - truncateTo,
+        originalTail: lastLine
+      };
+    }
+  }
+};
+
 // src/events.ts
+import path3 from "path";
 var CoreEventBus = class {
   listeners = [];
   on(listener) {
@@ -37,13 +274,16 @@ var CoreEventBus = class {
 };
 var coreEvents = new CoreEventBus();
 function createEventEnvelope(params) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   return {
     schema: "hardkas.event",
     version: "1.0.0",
     eventId: params.eventId || crypto.randomUUID(),
     domain: params.domain,
     kind: params.kind,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    timestamp,
+    emittedAt: timestamp,
+    sourceSubsystem: params.sourceSubsystem,
     workflowId: params.workflowId,
     correlationId: params.correlationId,
     causationId: params.causationId,
@@ -51,7 +291,8 @@ function createEventEnvelope(params) {
     txId: params.txId,
     networkId: params.networkId,
     payload: params.payload,
-    ...params.sequence !== void 0 ? { sequence: params.sequence } : {}
+    sequenceNumber: params.sequenceNumber,
+    globalOffset: params.globalOffset
   };
 }
 function validateEventEnvelope(event) {
@@ -62,6 +303,25 @@ function validateEventEnvelope(event) {
   if (typeof event.payload !== "object") return false;
   return true;
 }
+function attachLedgerAppender(workspaceRoot) {
+  const seenEventIds = /* @__PURE__ */ new Set();
+  const eventsFile = path3.join(workspaceRoot, "events.jsonl");
+  return coreEvents.on((event) => {
+    if (seenEventIds.has(event.eventId)) {
+      return;
+    }
+    seenEventIds.add(event.eventId);
+    if (seenEventIds.size > 1e5) {
+      const iterator = seenEventIds.keys();
+      for (let i = 0; i < 1e4; i++) seenEventIds.delete(iterator.next().value);
+    }
+    const payload = JSON.stringify(event) + "\n";
+    try {
+      AppendCoordinator.appendAtomic(eventsFile, payload, workspaceRoot);
+    } catch (e) {
+    }
+  });
+}
 
 // src/domain-types.ts
 var asTxId = (id) => id;
@@ -112,33 +372,35 @@ function redactSecret(value) {
 }
 
 // src/fs.ts
-import fs from "fs";
-import path from "path";
+import fs2 from "fs";
+import path4 from "path";
+import crypto3 from "crypto";
 async function writeFileAtomic(targetPath, data, options = {}) {
-  const dir = path.dirname(targetPath);
-  const base = path.basename(targetPath);
-  const tempPath = path.join(dir, `.tmp.${base}.${Math.random().toString(36).slice(2)}`);
+  const dir = path4.dirname(targetPath);
+  const base = path4.basename(targetPath);
+  const tempPath = path4.join(dir, `.tmp.${base}.${crypto3.randomUUID()}`);
   let fd = null;
   try {
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
+    if (!fs2.existsSync(dir)) {
+      fs2.mkdirSync(dir, { recursive: true });
     }
-    fd = fs.openSync(tempPath, "w", options.mode);
+    fd = fs2.openSync(tempPath, "w", options.mode);
     const buffer = typeof data === "string" ? Buffer.from(data, options.encoding || "utf-8") : data;
-    fs.writeSync(fd, buffer, 0, buffer.length);
-    fs.fsyncSync(fd);
-    fs.closeSync(fd);
+    fs2.writeSync(fd, buffer, 0, buffer.length);
+    fs2.fsyncSync(fd);
+    fs2.closeSync(fd);
     fd = null;
     let attempts = 0;
     const maxAttempts = process.platform === "win32" ? 5 : 1;
     while (attempts < maxAttempts) {
       try {
-        fs.renameSync(tempPath, targetPath);
+        fs2.renameSync(tempPath, targetPath);
         break;
       } catch (e) {
         attempts++;
         if (attempts >= maxAttempts) throw e;
         if (e.code === "EPERM" || e.code === "EBUSY") {
+          EnvironmentTelemetry.logAnomaly("FS_RETRY", "low", "fs", `Retrying rename of ${targetPath} due to ${e.code}`);
           await new Promise((resolve) => setTimeout(resolve, 10 * attempts));
           continue;
         }
@@ -148,11 +410,11 @@ async function writeFileAtomic(targetPath, data, options = {}) {
     if (options.fsyncParent && process.platform !== "win32") {
       let dirFd = null;
       try {
-        dirFd = fs.openSync(dir, "r");
-        fs.fsyncSync(dirFd);
+        dirFd = fs2.openSync(dir, "r");
+        fs2.fsyncSync(dirFd);
       } catch (e) {
       } finally {
-        if (dirFd !== null) fs.closeSync(dirFd);
+        if (dirFd !== null) fs2.closeSync(dirFd);
       }
     }
   } catch (err) {
@@ -162,45 +424,46 @@ async function writeFileAtomic(targetPath, data, options = {}) {
       { cause: err }
     );
   } finally {
-    if (fs.existsSync(tempPath)) {
+    if (fs2.existsSync(tempPath)) {
       try {
-        fs.unlinkSync(tempPath);
+        fs2.unlinkSync(tempPath);
       } catch (e) {
       }
     }
     if (fd !== null) {
       try {
-        fs.closeSync(fd);
+        fs2.closeSync(fd);
       } catch (e) {
       }
     }
   }
 }
 function writeFileAtomicSync(targetPath, data, options = {}) {
-  const dir = path.dirname(targetPath);
-  const base = path.basename(targetPath);
-  const tempPath = path.join(dir, `.tmp.${base}.${Math.random().toString(36).slice(2)}`);
+  const dir = path4.dirname(targetPath);
+  const base = path4.basename(targetPath);
+  const tempPath = path4.join(dir, `.tmp.${base}.${crypto3.randomUUID()}`);
   let fd = null;
   try {
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
+    if (!fs2.existsSync(dir)) {
+      fs2.mkdirSync(dir, { recursive: true });
     }
-    fd = fs.openSync(tempPath, "w", options.mode);
+    fd = fs2.openSync(tempPath, "w", options.mode);
     const buffer = typeof data === "string" ? Buffer.from(data, options.encoding || "utf-8") : data;
-    fs.writeSync(fd, buffer, 0, buffer.length);
-    fs.fsyncSync(fd);
-    fs.closeSync(fd);
+    fs2.writeSync(fd, buffer, 0, buffer.length);
+    fs2.fsyncSync(fd);
+    fs2.closeSync(fd);
     fd = null;
     let attempts = 0;
     const maxAttempts = process.platform === "win32" ? 5 : 1;
     while (attempts < maxAttempts) {
       try {
-        fs.renameSync(tempPath, targetPath);
+        fs2.renameSync(tempPath, targetPath);
         break;
       } catch (e) {
         attempts++;
         if (attempts >= maxAttempts) throw e;
         if (e.code === "EPERM" || e.code === "EBUSY") {
+          EnvironmentTelemetry.logAnomaly("FS_RETRY", "low", "fs", `Retrying rename sync of ${targetPath} due to ${e.code}`);
           continue;
         }
         throw e;
@@ -209,11 +472,11 @@ function writeFileAtomicSync(targetPath, data, options = {}) {
     if (options.fsyncParent && process.platform !== "win32") {
       let dirFd = null;
       try {
-        dirFd = fs.openSync(dir, "r");
-        fs.fsyncSync(dirFd);
+        dirFd = fs2.openSync(dir, "r");
+        fs2.fsyncSync(dirFd);
       } catch (e) {
       } finally {
-        if (dirFd !== null) fs.closeSync(dirFd);
+        if (dirFd !== null) fs2.closeSync(dirFd);
       }
     }
   } catch (err) {
@@ -223,15 +486,15 @@ function writeFileAtomicSync(targetPath, data, options = {}) {
       { cause: err }
     );
   } finally {
-    if (fs.existsSync(tempPath)) {
+    if (fs2.existsSync(tempPath)) {
       try {
-        fs.unlinkSync(tempPath);
+        fs2.unlinkSync(tempPath);
       } catch (e) {
       }
     }
     if (fd !== null) {
       try {
-        fs.closeSync(fd);
+        fs2.closeSync(fd);
       } catch (e) {
       }
     }
@@ -257,8 +520,8 @@ function formatCorruptionIssue(issue) {
 }
 
 // src/lock.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path5 from "path";
 import os from "os";
 var LOCK_ORDER = [
   "workspace",
@@ -269,13 +532,14 @@ var LOCK_ORDER = [
   "query-store"
 ];
 async function acquireLock(args) {
-  const lockDir = path2.join(args.rootDir, ".hardkas", "locks");
-  const lockPath = path2.join(lockDir, `${args.name}.lock`);
+  const lockDir = path5.join(args.rootDir, ".hardkas", "locks");
+  const lockPath = path5.join(lockDir, `${args.name}.lock`);
   const timeoutMs = args.timeoutMs ?? 3e4;
   const pollMs = args.pollMs ?? 250;
   const start = Date.now();
-  if (!fs2.existsSync(lockDir)) {
-    fs2.mkdirSync(lockDir, { recursive: true });
+  let staleRecoveryAttempted = false;
+  if (!fs3.existsSync(lockDir)) {
+    fs3.mkdirSync(lockDir, { recursive: true });
   }
   while (true) {
     try {
@@ -289,18 +553,18 @@ async function acquireLock(args) {
         createdAt: (/* @__PURE__ */ new Date()).toISOString(),
         expiresAt: null
       };
-      const fd = fs2.openSync(lockPath, "wx");
-      fs2.writeSync(fd, JSON.stringify(metadata, null, 2));
-      fs2.closeSync(fd);
+      const fd = fs3.openSync(lockPath, "wx");
+      fs3.writeSync(fd, JSON.stringify(metadata, null, 2));
+      fs3.closeSync(fd);
       return {
         path: lockPath,
         metadata,
         release: async () => {
-          if (fs2.existsSync(lockPath)) {
+          if (fs3.existsSync(lockPath)) {
             try {
-              const current = JSON.parse(fs2.readFileSync(lockPath, "utf-8"));
+              const current = JSON.parse(fs3.readFileSync(lockPath, "utf-8"));
               if (current.pid === process.pid) {
-                fs2.unlinkSync(lockPath);
+                fs3.unlinkSync(lockPath);
               }
             } catch (e) {
             }
@@ -311,12 +575,49 @@ async function acquireLock(args) {
       if (e.code === "EEXIST") {
         let existingMetadata = null;
         try {
-          existingMetadata = JSON.parse(fs2.readFileSync(lockPath, "utf-8"));
+          existingMetadata = JSON.parse(fs3.readFileSync(lockPath, "utf-8"));
         } catch (err) {
+          const LOCK_CREATION_GRACE_MS = 2e3;
+          let stats = null;
+          try {
+            stats = fs3.statSync(lockPath);
+          } catch {
+            continue;
+          }
+          const ageMs = Date.now() - stats.mtimeMs;
+          if (ageMs < LOCK_CREATION_GRACE_MS) {
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+            continue;
+          }
+          if (!staleRecoveryAttempted) {
+            staleRecoveryAttempted = true;
+            try {
+              fs3.unlinkSync(lockPath);
+              EnvironmentTelemetry.logAnomaly("STALE_LOCK_RECOVERY", "medium", "lock", `Recovered corrupted lock file at ${lockPath} (Age: ${ageMs}ms)`, args.rootDir);
+              continue;
+            } catch {
+              throw new HardkasError("LOCK_METADATA_INVALID", `Lock file at ${lockPath} is corrupted and cannot be recovered.`, { cause: err });
+            }
+          }
           throw new HardkasError("LOCK_METADATA_INVALID", `Lock file at ${lockPath} is corrupted.`, { cause: err });
         }
         if (existingMetadata) {
-          const isAlive = isProcessAlive(existingMetadata.pid);
+          const isLocal = existingMetadata.hostname === os.hostname();
+          const isAlive = isLocal ? isProcessAlive(existingMetadata.pid) : true;
+          if (!isAlive && !staleRecoveryAttempted) {
+            staleRecoveryAttempted = true;
+            try {
+              fs3.unlinkSync(lockPath);
+              EnvironmentTelemetry.logAnomaly("STALE_LOCK_RECOVERY", "medium", "lock", `Recovered lock held by dead process (PID: ${existingMetadata.pid})`, args.rootDir);
+              continue;
+            } catch (unlinkErr) {
+              throw new HardkasError(
+                "STALE_LOCK",
+                `Workspace is locked by a dead process (PID: ${existingMetadata.pid}). Failed to auto-recover: ${unlinkErr}`,
+                { cause: existingMetadata }
+              );
+            }
+          }
           if (!isAlive) {
             throw new HardkasError(
               "STALE_LOCK",
@@ -325,6 +626,7 @@ async function acquireLock(args) {
             );
           }
           if (args.wait && Date.now() - start < timeoutMs) {
+            EnvironmentTelemetry.logAnomaly("LOCK_CONTENTION", "low", "lock", `Waiting for lock ${args.name} held by PID ${existingMetadata.pid}`, args.rootDir);
             await new Promise((resolve) => setTimeout(resolve, pollMs));
             continue;
           }
@@ -370,20 +672,22 @@ function isProcessAlive(pid) {
     process.kill(pid, 0);
     return true;
   } catch (e) {
-    return e.code !== "ESRCH";
+    if (e.code === "EPERM") return true;
+    if (e.code === "ESRCH") return false;
+    return true;
   }
 }
 function listLocks(rootDir) {
-  const lockDir = path2.join(rootDir, ".hardkas", "locks");
-  if (!fs2.existsSync(lockDir)) return [];
-  const files = fs2.readdirSync(lockDir).filter((f) => f.endsWith(".lock"));
+  const lockDir = path5.join(rootDir, ".hardkas", "locks");
+  if (!fs3.existsSync(lockDir)) return [];
+  const files = fs3.readdirSync(lockDir).filter((f) => f.endsWith(".lock"));
   const result = [];
   for (const file of files) {
-    const lockPath = path2.join(lockDir, file);
+    const lockPath = path5.join(lockDir, file);
     try {
-      const metadata = JSON.parse(fs2.readFileSync(lockPath, "utf-8"));
+      const metadata = JSON.parse(fs3.readFileSync(lockPath, "utf-8"));
       result.push({
-        name: path2.basename(file, ".lock"),
+        name: path5.basename(file, ".lock"),
         metadata,
         path: lockPath,
         isAlive: metadata.hostname === os.hostname() ? isProcessAlive(metadata.pid) : true
@@ -395,15 +699,15 @@ function listLocks(rootDir) {
   return result;
 }
 function clearLock(rootDir, name, options = {}) {
-  const lockDir = path2.join(rootDir, ".hardkas", "locks");
-  const lockPath = path2.join(lockDir, `${name}.lock`);
-  if (!fs2.existsSync(lockPath)) return { cleared: false, reason: "Lock not found" };
+  const lockDir = path5.join(rootDir, ".hardkas", "locks");
+  const lockPath = path5.join(lockDir, `${name}.lock`);
+  if (!fs3.existsSync(lockPath)) return { cleared: false, reason: "Lock not found" };
   let metadata;
   try {
-    metadata = JSON.parse(fs2.readFileSync(lockPath, "utf-8"));
+    metadata = JSON.parse(fs3.readFileSync(lockPath, "utf-8"));
   } catch (e) {
     if (options.force) {
-      fs2.unlinkSync(lockPath);
+      fs3.unlinkSync(lockPath);
       return { cleared: true };
     }
     return { cleared: false, reason: "Corrupt metadata (use --force to clear)" };
@@ -416,10 +720,417 @@ function clearLock(rootDir, name, options = {}) {
   } else if (!options.force) {
     return { cleared: false, reason: "Lock is potentially active. Use --force or --if-dead." };
   }
-  fs2.unlinkSync(lockPath);
+  fs3.unlinkSync(lockPath);
   return { cleared: true };
 }
 
+// src/replay.ts
+function diffReplays(replayA, replayB) {
+  const diff = {
+    schema: "hardkas.replayDiff.v1",
+    structural: {
+      missingArtifacts: [],
+      excludedArtifacts: [],
+      missingProjections: []
+    },
+    deterministic: {
+      stateRootDiverged: false,
+      lineageDiverged: false,
+      graphDiverged: false,
+      differences: []
+    },
+    observational: {
+      timestampShifts: [],
+      eventOrderingShifts: [],
+      metadataDrift: []
+    }
+  };
+  if (replayA.artifacts?.length !== replayB.artifacts?.length) {
+    diff.structural.missingArtifacts.push("artifact_count_mismatch");
+  }
+  const stateA = replayA.stateRoot || replayA.postStateHash;
+  const stateB = replayB.stateRoot || replayB.postStateHash;
+  if (stateA !== stateB) {
+    diff.deterministic.stateRootDiverged = true;
+    diff.deterministic.differences.push({
+      path: "stateRoot",
+      a: stateA,
+      b: stateB
+    });
+  }
+  if (replayA.amountSompi !== void 0 && replayB.amountSompi !== void 0 && replayA.amountSompi !== replayB.amountSompi) {
+    diff.deterministic.differences.push({
+      path: "amountSompi",
+      a: replayA.amountSompi,
+      b: replayB.amountSompi
+    });
+  }
+  const tsA = replayA.timestamp || replayA.createdAt;
+  const tsB = replayB.timestamp || replayB.createdAt;
+  if (tsA && tsB) {
+    const timeA = new Date(tsA).getTime();
+    const timeB = new Date(tsB).getTime();
+    if (timeA !== timeB) {
+      diff.observational.timestampShifts.push({ path: "timestamp", shiftMs: Math.abs(timeA - timeB) });
+    }
+  }
+  return diff;
+}
+
+// src/snapshot.ts
+import fs4 from "fs/promises";
+import path6 from "path";
+async function createSnapshot(options) {
+  const { hardkasDir, outputDir, deterministicScope = "local-only" } = options;
+  await fs4.mkdir(outputDir, { recursive: true });
+  await fs4.mkdir(path6.join(outputDir, "artifacts"), { recursive: true });
+  await fs4.mkdir(path6.join(outputDir, "projections"), { recursive: true });
+  await fs4.mkdir(path6.join(outputDir, "events"), { recursive: true });
+  await fs4.mkdir(path6.join(outputDir, "replay"), { recursive: true });
+  await fs4.mkdir(path6.join(outputDir, "metadata"), { recursive: true });
+  let included = 0;
+  let excluded = 0;
+  let corrupted = 0;
+  const artifactsDir = path6.join(hardkasDir, "artifacts");
+  try {
+    const list = await fs4.readdir(artifactsDir);
+    for (const f of list) {
+      if (f.endsWith(".json")) {
+        const src = path6.join(artifactsDir, f);
+        const dest = path6.join(outputDir, "artifacts", f);
+        try {
+          const content = await fs4.readFile(src, "utf-8");
+          const parsed = JSON.parse(content);
+          if (parsed.schema && parsed.schema.startsWith("hardkas.")) {
+            await fs4.copyFile(src, dest);
+            included++;
+          } else {
+            excluded++;
+          }
+        } catch {
+          corrupted++;
+        }
+      }
+    }
+  } catch {
+  }
+  try {
+    const eventsLog = path6.join(hardkasDir, "events.jsonl");
+    await fs4.copyFile(eventsLog, path6.join(outputDir, "events", "events.jsonl"));
+  } catch {
+  }
+  try {
+    const dbPath = path6.join(hardkasDir, "store.db");
+    await fs4.copyFile(dbPath, path6.join(outputDir, "projections", "store.db"));
+  } catch {
+  }
+  const manifest = {
+    snapshotVersion: 1,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    hardkasVersion: "0.6.1-alpha",
+    stateAuthority: "filesystem",
+    projectionAuthority: "sqlite",
+    deterministicScope,
+    consensusValidated: deterministicScope === "consensus-validated",
+    includedArtifacts: included,
+    excludedArtifacts: excluded,
+    corruptedArtifacts: corrupted
+  };
+  await fs4.writeFile(
+    path6.join(outputDir, "manifest.json"),
+    JSON.stringify(manifest, null, 2),
+    "utf-8"
+  );
+  return manifest;
+}
+async function readSnapshotManifest(snapshotDir) {
+  const manifestPath = path6.join(snapshotDir, "manifest.json");
+  const content = await fs4.readFile(manifestPath, "utf-8");
+  return JSON.parse(content);
+}
+
+// src/deterministic.ts
+function deterministicCompare(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// src/retention.ts
+import fs5 from "fs";
+import path7 from "path";
+var TelemetryRotator = class {
+  static DEFAULT_MAX_SIZE_BYTES = 10 * 1024 * 1024;
+  // 10MB
+  /**
+   * Rotates the telemetry stream if it exceeds the maximum size.
+   * This is a safe operation that renames the active file to an archive directory.
+   */
+  static rotateIfNeeded(rootDir, maxSizeBytes = this.DEFAULT_MAX_SIZE_BYTES) {
+    const telemetryDir = path7.join(rootDir, ".hardkas", "telemetry");
+    const activeFile = path7.join(telemetryDir, "telemetry.jsonl");
+    if (!fs5.existsSync(activeFile)) {
+      return { rotated: false, reason: "File does not exist" };
+    }
+    const stats = fs5.statSync(activeFile);
+    if (stats.size < maxSizeBytes) {
+      return { rotated: false, reason: `File size (${stats.size}) is below threshold (${maxSizeBytes})` };
+    }
+    return this.forceRotate(rootDir);
+  }
+  /**
+   * Forces a rotation regardless of file size.
+   */
+  static forceRotate(rootDir) {
+    const telemetryDir = path7.join(rootDir, ".hardkas", "telemetry");
+    const activeFile = path7.join(telemetryDir, "telemetry.jsonl");
+    if (!fs5.existsSync(activeFile)) {
+      return { rotated: false, reason: "File does not exist" };
+    }
+    const archiveDir = path7.join(telemetryDir, "archive");
+    if (!fs5.existsSync(archiveDir)) {
+      fs5.mkdirSync(archiveDir, { recursive: true });
+    }
+    const stats = fs5.statSync(activeFile);
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const archiveFile = path7.join(archiveDir, `telemetry-${timestamp}.jsonl`);
+    try {
+      fs5.renameSync(activeFile, archiveFile);
+      return {
+        rotated: true,
+        archivePath: archiveFile,
+        bytesRotated: stats.size
+      };
+    } catch (err) {
+      return { rotated: false, reason: `Rename failed: ${err.message}` };
+    }
+  }
+  /**
+   * Lists all archived telemetry segments.
+   */
+  static listArchivedSegments(rootDir) {
+    const archiveDir = path7.join(rootDir, ".hardkas", "telemetry", "archive");
+    if (!fs5.existsSync(archiveDir)) return [];
+    return fs5.readdirSync(archiveDir).filter((f) => f.startsWith("telemetry-") && f.endsWith(".jsonl")).sort();
+  }
+};
+
+// src/runtime-context.ts
+var systemRuntimeContext = {
+  clock: {
+    now: () => Date.now()
+  },
+  random: {
+    next: () => Math.random()
+  },
+  ids: {
+    execution: () => `exec_${Date.now().toString(36)}`,
+    workflow: () => `wf_${Date.now().toString(36)}`
+  },
+  telemetry: globalTelemetry
+};
+
+// src/semantics/status.ts
+var LEGAL_TRANSITIONS = {
+  UNKNOWN: ["PROJECTED", "QUARANTINED", "CORRUPTED"],
+  PROJECTED: ["VERIFIED", "CORRUPTED"],
+  VERIFIED: ["STALE", "REPLAY_VERIFIED", "CORRUPTED"],
+  STALE: ["VERIFIED", "REPLAY_VERIFIED", "CORRUPTED"],
+  REPLAY_VERIFIED: ["STALE", "CORRUPTED"],
+  CORRUPTED: ["QUARANTINED"],
+  QUARANTINED: []
+  // Terminal state
+};
+function validateStatusTransition(from, to) {
+  if (from === to) return;
+  const allowed = LEGAL_TRANSITIONS[from];
+  if (!allowed.includes(to)) {
+    throw new Error(
+      `[CRITICAL SEMANTIC ERROR] Illegal artifact status transition attempted: ${from} -> ${to}. This is a violation of the semantic artifact status lattice.`
+    );
+  }
+}
+
+// src/semantics/api.ts
+function resolveCanonicalArtifact(params) {
+  if (!params.artifactId && !params.lineageId && !params.semanticHash) {
+    throw new Error(
+      `[CRITICAL SEMANTIC ERROR] Implicit resolution forbidden. You must pin resolution by providing an explicit artifactId, lineageId, or semanticHash.`
+    );
+  }
+  return params.artifactId || params.semanticHash || params.lineageId || "";
+}
+function verifyArtifactIntegrity(identity, computedHash) {
+  if (identity.semanticHash !== computedHash) {
+    throw new Error(
+      `[CRITICAL SEMANTIC ERROR] Integrity mismatch for artifact ${identity.artifactId}: expected hash ${identity.semanticHash}, got ${computedHash}`
+    );
+  }
+}
+function verifyReplay(identity, replayCtx) {
+  if (identity.semanticHash !== replayCtx.semanticHash) {
+    throw new Error(`[CRITICAL SEMANTIC ERROR] Replay semantic hash divergence: expected ${identity.semanticHash}, got ${replayCtx.semanticHash}`);
+  }
+  validateStatusTransition(identity.status, "REPLAY_VERIFIED");
+  return "REPLAY_VERIFIED";
+}
+function verifyProjectionFreshness(identity, currentLineageHead) {
+  return true;
+}
+function classifyArtifactStatus(identity, isReadable, isCorrupted) {
+  if (isCorrupted) return "CORRUPTED";
+  if (!isReadable) return "UNKNOWN";
+  if (identity.status === "UNKNOWN") return "PROJECTED";
+  return identity.status;
+}
+function resolveLineage(artifactId) {
+  return [artifactId];
+}
+function verifyCapabilityBoundary(identity, capability) {
+}
+
+// src/semantics/migration.ts
+function verifyMigrationIntegrity(preMigration, postMigration) {
+  if (preMigration.artifactId !== postMigration.artifactId) {
+    throw new Error(`[CRITICAL SEMANTIC ERROR] Migration unexpectedly altered canonical artifact ID: ${preMigration.artifactId} -> ${postMigration.artifactId}`);
+  }
+  if (postMigration.schemaVersion < preMigration.schemaVersion) {
+    throw new Error(`[CRITICAL SEMANTIC ERROR] Invalid migration: schema downgraded from ${preMigration.schemaVersion} to ${postMigration.schemaVersion}`);
+  }
+}
+function migrateArtifact(identity, targetVersion) {
+  if (identity.schemaVersion === targetVersion) {
+    return { migratedIdentity: identity, success: true };
+  }
+  return {
+    migratedIdentity: identity,
+    success: false,
+    error: `No migration path from ${identity.schemaVersion} to ${targetVersion}`
+  };
+}
+function comparePrePostMigrationLineage(preLineageId, postLineageId) {
+  if (preLineageId !== postLineageId) {
+    throw new Error(`[CRITICAL SEMANTIC ERROR] Lineage broken across schema migration: ${preLineageId} -> ${postLineageId}`);
+  }
+}
+
+// src/semantics/drift.ts
+function detectSemanticDrift(dashboardView, queryStoreView, replayView, filesystemView) {
+  const views = {
+    Dashboard: dashboardView,
+    QueryStore: queryStoreView,
+    Replay: replayView,
+    Filesystem: filesystemView
+  };
+  let referenceView = filesystemView;
+  for (const [subsystem, view] of Object.entries(views)) {
+    if (view.semanticHash !== referenceView.semanticHash) {
+      return {
+        hasDrift: true,
+        conflictingSubsystem: subsystem,
+        exactReplayCommand: `hardkas verify-replay --artifact ${referenceView.artifactId}`,
+        severity: "CRITICAL",
+        details: `Hash mismatch: ${subsystem} (${view.semanticHash}) vs Reference (${referenceView.semanticHash})`
+      };
+    }
+    if (view.status !== referenceView.status) {
+      if (subsystem === "Dashboard" && view.status === "VERIFIED" && replayView.status === "STALE") {
+        return {
+          hasDrift: true,
+          conflictingSubsystem: subsystem,
+          exactReplayCommand: `hardkas verify-replay --artifact ${referenceView.artifactId}`,
+          severity: "CRITICAL",
+          details: `Dashboard claims VERIFIED but Replay claims STALE.`
+        };
+      }
+    }
+  }
+  return { hasDrift: false, severity: "NONE" };
+}
+function assertNoSemanticDrift(dashboardView, queryStoreView, replayView, filesystemView) {
+  const report = detectSemanticDrift(dashboardView, queryStoreView, replayView, filesystemView);
+  if (report.hasDrift) {
+    throw new Error(
+      `[CRITICAL SEMANTIC DRIFT] Subsystem disagreement detected.
+Conflicting Subsystem: ${report.conflictingSubsystem}
+Details: ${report.details}
+Resolution Command: ${report.exactReplayCommand}`
+    );
+  }
+}
+
+// src/migrations.ts
+import fs6 from "fs";
+import path8 from "path";
+var CURRENT_RUNTIME_VERSION = "0.6.1-alpha";
+var MIN_SUPPORTED_VERSION = "0.5.0-alpha";
+var MigrationManager = class {
+  static checkVersion(rootDir) {
+    const versionFile = path8.join(rootDir, ".hardkas", "version.json");
+    if (!fs6.existsSync(versionFile)) {
+      this.writeVersion(rootDir, CURRENT_RUNTIME_VERSION);
+      return { needsMigration: false, canDowngrade: true, currentVersion: CURRENT_RUNTIME_VERSION };
+    }
+    try {
+      const data = JSON.parse(fs6.readFileSync(versionFile, "utf-8"));
+      const wsVersion = data.runtimeVersion || "0.0.0";
+      if (wsVersion === CURRENT_RUNTIME_VERSION) {
+        return { needsMigration: false, canDowngrade: true, currentVersion: wsVersion };
+      }
+      if (this.compareSemver(wsVersion, CURRENT_RUNTIME_VERSION) > 0) {
+        return { needsMigration: false, canDowngrade: false, currentVersion: wsVersion };
+      }
+      if (this.compareSemver(wsVersion, MIN_SUPPORTED_VERSION) < 0) {
+        throw new HardkasError("MIGRATION_UNSUPPORTED", `Workspace version ${wsVersion} is too old to migrate to ${CURRENT_RUNTIME_VERSION}`);
+      }
+      return { needsMigration: true, canDowngrade: true, currentVersion: wsVersion };
+    } catch (err) {
+      if (err instanceof HardkasError) throw err;
+      throw new HardkasError("MIGRATION_ERROR", `Failed to parse version.json: ${err.message}`);
+    }
+  }
+  static migrate(rootDir, dryRun = false) {
+    const status = this.checkVersion(rootDir);
+    if (!status.canDowngrade) {
+      throw new HardkasError("DOWNGRADE_REFUSED", `Cannot safely downgrade from workspace version ${status.currentVersion} to runtime version ${CURRENT_RUNTIME_VERSION}.`);
+    }
+    if (!status.needsMigration) return;
+    if (dryRun) {
+      console.log(`[DRY-RUN] Would migrate workspace from ${status.currentVersion} to ${CURRENT_RUNTIME_VERSION}`);
+      return;
+    }
+    this.backupWorkspace(rootDir);
+    try {
+      this.writeVersion(rootDir, CURRENT_RUNTIME_VERSION);
+    } catch (err) {
+      getTelemetry().logAnomaly("EXTERNAL_MUTATION", "critical", "projection", `Migration failed: ${err.message}`);
+      throw new HardkasError("MIGRATION_FAILED", `Migration failed, workspace might be corrupted: ${err.message}`);
+    }
+  }
+  static writeVersion(rootDir, version) {
+    const versionFile = path8.join(rootDir, ".hardkas", "version.json");
+    if (!fs6.existsSync(path8.dirname(versionFile))) {
+      fs6.mkdirSync(path8.dirname(versionFile), { recursive: true });
+    }
+    fs6.writeFileSync(versionFile, JSON.stringify({ runtimeVersion: version }, null, 2));
+  }
+  static backupWorkspace(rootDir) {
+    const hardkasDir = path8.join(rootDir, ".hardkas");
+    const backupDir = path8.join(rootDir, `.hardkas-backup-${Date.now()}`);
+    if (fs6.existsSync(hardkasDir)) {
+      fs6.cpSync(hardkasDir, backupDir, { recursive: true });
+    }
+  }
+  static compareSemver(v1, v2) {
+    const parse = (v) => v.replace("-alpha", "").split(".").map(Number);
+    const p1 = parse(v1);
+    const p2 = parse(v2);
+    for (let i = 0; i < 3; i++) {
+      if ((p1[i] || 0) > (p2[i] || 0)) return 1;
+      if ((p1[i] || 0) < (p2[i] || 0)) return -1;
+    }
+    return 0;
+  }
+};
+
 // src/index.ts
 var SOMPI_PER_KAS = 100000000n;
 var kaspaNetworkIdSchema = z.enum([
@@ -429,7 +1140,8 @@ var kaspaNetworkIdSchema = z.enum([
   "testnet-12",
   "simnet",
   "simnet-1",
-  "devnet"
+  "devnet",
+  "simulated"
 ]);
 var executionModeSchema = z.enum([
   "simulated",
@@ -441,7 +1153,8 @@ var artifactTypeSchema = z.enum([
   "signedTx",
   "txReceipt",
   "txTrace",
-  "snapshot"
+  "snapshot",
+  "workflow.v1"
 ]);
 var NetworkIdSchema = kaspaNetworkIdSchema;
 var ExecutionModeSchema = executionModeSchema;
@@ -510,13 +1223,20 @@ function formatSompi(amountSompi) {
   return `${sign}${whole}.${fractional.toString().padStart(8, "0")} KAS`;
 }
 export {
+  AppendCoordinator,
   ArtifactTypeSchema,
+  CURRENT_RUNTIME_VERSION,
+  EnvironmentTelemetry,
   ExecutionModeSchema,
   HardkasError,
   InvariantViolationError,
   LOCK_ORDER,
+  MIN_SUPPORTED_VERSION,
+  MigrationManager,
   NetworkIdSchema,
   SOMPI_PER_KAS,
+  TelemetryManager,
+  TelemetryRotator,
   acquireLock,
   artifactTypeSchema,
   asArtifactId,
@@ -531,21 +1251,43 @@ export {
   asRpcEndpointId,
   asTxId,
   asWorkflowId,
+  assertNoSemanticDrift,
+  attachLedgerAppender,
+  classifyArtifactStatus,
   clearLock,
+  comparePrePostMigrationLineage,
   coreEvents,
   createEventEnvelope,
+  createSnapshot,
+  detectSemanticDrift,
+  deterministicCompare,
+  diffReplays,
   executionModeSchema,
   formatCorruptionIssue,
   formatSompi,
+  getTelemetry,
+  globalTelemetry,
   hardkasConfigSchema,
   isProcessAlive,
   kaspaNetworkIdSchema,
   listLocks,
   maskSecrets,
+  migrateArtifact,
   parseHardkasConfig,
   parseKasToSompi,
+  readSnapshotManifest,
   redactSecret,
+  resolveCanonicalArtifact,
+  resolveLineage,
+  systemRuntimeContext,
+  telemetryContextStorage,
   validateEventEnvelope,
+  validateStatusTransition,
+  verifyArtifactIntegrity,
+  verifyCapabilityBoundary,
+  verifyMigrationIntegrity,
+  verifyProjectionFreshness,
+  verifyReplay,
   withLock,
   withLocks,
   writeFileAtomic,