@hardkas/core 0.6.0-alpha → 0.7.0-alpha

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { AsyncLocalStorage } from 'node:async_hooks';
 
 /**
  * Lightweight branded/nominal types for domain-critical strings/numbers.
@@ -328,6 +329,11 @@ type UnknownEventPayload = {
     readonly type: "unknown";
     readonly data: Record<string, unknown>;
 };
+/**
+ * Attaches the canonical Event Ledger appender to the core event bus.
+ * This guarantees that all formal EventEnvelopes are persisted to events.jsonl.
+ */
+declare function attachLedgerAppender(workspaceRoot: string): () => void;
 
 /**
  * @deprecated Use Brand from domain-types.js instead.
@@ -458,6 +464,7 @@ interface AcquireLockArgs {
 declare const LOCK_ORDER: string[];
 /**
  * Acquires a named lock for the workspace.
+ * Supports automatic stale lock recovery when the holding process is dead.
  */
 declare function acquireLock(args: AcquireLockArgs): Promise<LockHandle>;
 /**
@@ -553,6 +560,85 @@ declare function readSnapshotManifest(snapshotDir: string): Promise<SnapshotMani
  */
 declare function deterministicCompare(a: string, b: string): number;
 
+type TelemetrySubsystem = "lock" | "fs" | "replay" | "normalization" | "query-store" | "lineage" | "projection" | "unknown";
+type AnomalyType = "LOCK_CONTENTION" | "STALE_LOCK_RECOVERY" | "FS_RETRY" | "NORMALIZATION_COLLISION" | "REPLAY_RECONCILIATION" | "EXTERNAL_MUTATION" | "PATH_TRAVERSAL_ATTEMPT" | "ORPHAN_PROJECTION_RECOVERY";
+type Severity = "low" | "medium" | "high" | "critical";
+interface AnomalyEvent {
+    timestamp: string;
+    seed?: number | undefined;
+    caseId?: string | undefined;
+    bucket?: string | undefined;
+    anomalyType: AnomalyType;
+    severity: Severity;
+    subsystem: TelemetrySubsystem;
+    details: string;
+    sandbox?: string | undefined;
+}
+
+declare class TelemetryManager {
+    private rootDir;
+    private currentContext;
+    private preservedSandboxes;
+    constructor(rootDir?: string);
+    init(rootDir: string): void;
+    setContext(context: {
+        seed?: number;
+        caseId?: string;
+        bucket?: string;
+    }): void;
+    clearContext(): void;
+    getContext(): {
+        seed?: number;
+        caseId?: string;
+        bucket?: string;
+    };
+    logAnomaly(anomalyType: AnomalyType, severity: Severity, subsystem: TelemetrySubsystem, details: string, sandboxOverride?: string): void;
+    shouldPreserveSandbox(sandboxDir: string): boolean;
+}
+declare const telemetryContextStorage: AsyncLocalStorage<TelemetryManager>;
+declare const globalTelemetry: TelemetryManager;
+declare function getTelemetry(): TelemetryManager;
+declare class TelemetryProxy {
+    logAnomaly(anomalyType: AnomalyType, severity: Severity, subsystem: TelemetrySubsystem, details: string, sandboxOverride?: string): void;
+    init(rootDir: string): void;
+    setContext(context: {
+        seed?: number;
+        caseId?: string;
+        bucket?: string;
+    }): void;
+    clearContext(): void;
+    getContext(): {
+        seed?: number;
+        caseId?: string;
+        bucket?: string;
+    };
+    shouldPreserveSandbox(sandboxDir: string): boolean;
+}
+declare const EnvironmentTelemetry: TelemetryProxy;
+
+interface RotationResult {
+    rotated: boolean;
+    archivePath?: string;
+    bytesRotated?: number;
+    reason?: string;
+}
+declare class TelemetryRotator {
+    private static readonly DEFAULT_MAX_SIZE_BYTES;
+    /**
+     * 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: string, maxSizeBytes?: number): RotationResult;
+    /**
+     * Forces a rotation regardless of file size.
+     */
+    static forceRotate(rootDir: string): RotationResult;
+    /**
+     * Lists all archived telemetry segments.
+     */
+    static listArchivedSegments(rootDir: string): string[];
+}
+
 interface DeterministicClock {
     now(): number;
 }
@@ -567,6 +653,7 @@ interface RuntimeContext {
     clock: DeterministicClock;
     random: DeterministicRandom;
     ids: IdProvider;
+    telemetry: TelemetryManager;
 }
 /**
  * A default system runtime context (for non-deterministic contexts like dev server or CLI entry points)
@@ -574,6 +661,146 @@ interface RuntimeContext {
  */
 declare const systemRuntimeContext: RuntimeContext;
 
+/**
+ * Formal Artifact Status Lattice
+ *
+ * UNKNOWN: Unreadable, ambiguous, partially classified, migration-pending states.
+ * PROJECTED: An artifact read from disk / state whose truth has not yet been verified.
+ * STALE: An artifact whose dependencies/lineage has drifted since it was verified.
+ * VERIFIED: Integrity, signature, and internal capability constraints are verified.
+ * REPLAY_VERIFIED: Full lineage and determinism verified via an active replay.
+ * CORRUPTED: Irreparable semantic or cryptographic corruption detected.
+ * QUARANTINED: Corrupted or malicious artifact safely isolated from runtime.
+ */
+type ArtifactStatus = "UNKNOWN" | "PROJECTED" | "STALE" | "VERIFIED" | "REPLAY_VERIFIED" | "CORRUPTED" | "QUARANTINED";
+/**
+ * Baseline schema version is 1.
+ */
+type SchemaVersion = 1;
+interface SemanticIdentity {
+    /** The unique artifact ID */
+    artifactId: string;
+    /** The semantic hash of the artifact content */
+    semanticHash: string;
+    /** Formal schema version */
+    schemaVersion: SchemaVersion;
+    /** Current status in the lattice */
+    status: ArtifactStatus;
+}
+
+/**
+ * Throws a loud runtime error if a transition is invalid.
+ * Invariant: `artifact_status_transitions_are_semantically_valid`
+ */
+declare function validateStatusTransition(from: ArtifactStatus, to: ArtifactStatus): void;
+
+interface ReplayContext {
+    semanticHash: string;
+    lineageId: string;
+    replayHash: string;
+}
+/**
+ * Resolves a canonical artifact.
+ * Implicit 'latest' is STRICTLY FORBIDDEN.
+ * You must provide an explicit artifactId, lineageId, or semanticHash.
+ * Invariant: `canonical_resolution_never_depends_on_implicit_latest`
+ */
+declare function resolveCanonicalArtifact(params: {
+    artifactId?: string;
+    lineageId?: string;
+    semanticHash?: string;
+}): string;
+/**
+ * Verifies that the artifact content integrity is valid.
+ */
+declare function verifyArtifactIntegrity(identity: SemanticIdentity, computedHash: string): void;
+/**
+ * Verifies the artifact via active replay, isolating it from ambient state.
+ * Invariant: `replay_isolated_from_ambient_runtime_state`
+ */
+declare function verifyReplay(identity: SemanticIdentity, replayCtx: ReplayContext): ArtifactStatus;
+declare function verifyProjectionFreshness(identity: SemanticIdentity, currentLineageHead: string): boolean;
+declare function classifyArtifactStatus(identity: SemanticIdentity, isReadable: boolean, isCorrupted: boolean): ArtifactStatus;
+declare function resolveLineage(artifactId: string): string[];
+declare function verifyCapabilityBoundary(identity: SemanticIdentity, capability: string): void;
+
+interface MigrationResult {
+    migratedIdentity: SemanticIdentity;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Validates that an artifact migration preserves identity and lineage semantics.
+ * Invariant: `schema_evolution_preserves_semantic_identity`
+ */
+declare function verifyMigrationIntegrity(preMigration: SemanticIdentity, postMigration: SemanticIdentity): void;
+/**
+ * Handles migrating an artifact to a newer schema version.
+ * Currently, only schemaVersion: 1 exists as the baseline.
+ */
+declare function migrateArtifact(identity: SemanticIdentity, targetVersion: SchemaVersion): MigrationResult;
+/**
+ * Compares lineage before and after migration to ensure continuity.
+ */
+declare function comparePrePostMigrationLineage(preLineageId: string, postLineageId: string): void;
+
+interface SemanticDriftReport {
+    hasDrift: boolean;
+    conflictingSubsystem?: string;
+    exactReplayCommand?: string;
+    severity: "NONE" | "CRITICAL";
+    details?: string;
+}
+/**
+ * Compares the truth across different subsystems.
+ * If multiple subsystems disagree about truth, that is a CRITICAL semantic failure.
+ * Invariant: `subsystems_cannot_disagree_about_canonical_truth`
+ */
+declare function detectSemanticDrift(dashboardView: SemanticIdentity, queryStoreView: SemanticIdentity, replayView: SemanticIdentity, filesystemView: SemanticIdentity): SemanticDriftReport;
+/**
+ * Asserts no semantic drift exists. Fails loudly.
+ */
+declare function assertNoSemanticDrift(dashboardView: SemanticIdentity, queryStoreView: SemanticIdentity, replayView: SemanticIdentity, filesystemView: SemanticIdentity): void;
+
+declare class AppendCoordinator {
+    private static _lastRecovery;
+    /**
+     * 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: string, line: string, rootDir: string): void;
+    /**
+     * Scans a JSONL stream for corruption, truncating malformed trailing lines.
+     * Utilizes a backward newline scanning logic with a rolling buffer,
+     * supporting lines of arbitrary size and only truncating the last complete
+     * valid JSONL boundary if a parse failure is detected.
+     */
+    static recoverCorruptedTail(filePath: string): {
+        repaired: boolean;
+        linesDiscarded: number;
+        originalTail: string;
+        originalSize: number;
+        recoveredSize: number;
+        reason: string;
+    };
+}
+
+declare const CURRENT_RUNTIME_VERSION = "0.7.0-alpha";
+declare const MIN_SUPPORTED_VERSION = "0.5.0-alpha";
+interface MigrationStatus {
+    needsMigration: boolean;
+    canDowngrade: boolean;
+    currentVersion: string;
+}
+declare class MigrationManager {
+    static checkVersion(rootDir: string): MigrationStatus;
+    static migrate(rootDir: string, dryRun?: boolean): void;
+    private static writeVersion;
+    private static backupWorkspace;
+    private static compareSemver;
+}
+
 declare const SOMPI_PER_KAS = 100000000n;
 declare const kaspaNetworkIdSchema: z.ZodEnum<["mainnet", "testnet-10", "testnet-11", "testnet-12", "simnet", "simnet-1", "devnet", "simulated"]>;
 type NetworkId = Brand<z.infer<typeof kaspaNetworkIdSchema>, "NetworkId">;
@@ -664,4 +891,4 @@ declare function parseHardkasConfig(input: unknown): HardkasConfig;
 declare function parseKasToSompi(input: string): bigint;
 declare function formatSompi(amountSompi: bigint): string;
 
-export { type AcquireLockArgs, type ArtifactId, type ArtifactType, ArtifactTypeSchema, type Brand, type Branded, type ContentHash, type CoreEvent, type CoreEventListener, type CorrelationId, type CorruptionCode, type CorruptionIssue, type CorruptionSeverity, type CreateSnapshotOptions, type DaaScore, type DeterministicClock, type DeterministicDiff, type DeterministicRandom, type EventDomain, type EventEnvelope, type EventId, type EventKind, type EventPayloadByKind, type EventSequence, type ExecutionMode, ExecutionModeSchema, type HardkasConfig, HardkasError, type IdProvider, type IntegrityStatus, type InvariantDomain, type InvariantSeverity, InvariantViolationError, type KaspaAddress, LOCK_ORDER, type LayeredReplayDiff, type LineageId, type LockHandle, type LockMetadata, type NetworkId, NetworkIdSchema, type RpcEndpointId, type RuntimeContext, type RuntimeNoiseDiff, SOMPI_PER_KAS, type SnapshotManifest, type StampedEvent, type StateProvenance, type StructuralDiff, type TxId, type UnknownEventPayload, type WorkflowId, type WriteFileAtomicOptions, acquireLock, artifactTypeSchema, asArtifactId, asContentHash, asCorrelationId, asDaaScore, asEventId, asEventSequence, asKaspaAddress, asLineageId, asNetworkId, asRpcEndpointId, asTxId, asWorkflowId, clearLock, coreEvents, createEventEnvelope, createSnapshot, deterministicCompare, diffReplays, executionModeSchema, formatCorruptionIssue, formatSompi, hardkasConfigSchema, isProcessAlive, kaspaNetworkIdSchema, listLocks, maskSecrets, parseHardkasConfig, parseKasToSompi, readSnapshotManifest, redactSecret, systemRuntimeContext, validateEventEnvelope, withLock, withLocks, writeFileAtomic, writeFileAtomicSync };
+export { type AcquireLockArgs, type AnomalyEvent, type AnomalyType, AppendCoordinator, type ArtifactId, type ArtifactStatus, type ArtifactType, ArtifactTypeSchema, type Brand, type Branded, CURRENT_RUNTIME_VERSION, type ContentHash, type CoreEvent, type CoreEventListener, type CorrelationId, type CorruptionCode, type CorruptionIssue, type CorruptionSeverity, type CreateSnapshotOptions, type DaaScore, type DeterministicClock, type DeterministicDiff, type DeterministicRandom, EnvironmentTelemetry, type EventDomain, type EventEnvelope, type EventId, type EventKind, type EventPayloadByKind, type EventSequence, type ExecutionMode, ExecutionModeSchema, type HardkasConfig, HardkasError, type IdProvider, type IntegrityStatus, type InvariantDomain, type InvariantSeverity, InvariantViolationError, type KaspaAddress, LOCK_ORDER, type LayeredReplayDiff, type LineageId, type LockHandle, type LockMetadata, MIN_SUPPORTED_VERSION, MigrationManager, type MigrationResult, type MigrationStatus, type NetworkId, NetworkIdSchema, type ReplayContext, type RpcEndpointId, type RuntimeContext, type RuntimeNoiseDiff, SOMPI_PER_KAS, type SchemaVersion, type SemanticDriftReport, type SemanticIdentity, type Severity, type SnapshotManifest, type StampedEvent, type StateProvenance, type StructuralDiff, TelemetryManager, TelemetryRotator, type TelemetrySubsystem, type TxId, type UnknownEventPayload, type WorkflowId, type WriteFileAtomicOptions, acquireLock, artifactTypeSchema, asArtifactId, asContentHash, asCorrelationId, asDaaScore, asEventId, asEventSequence, asKaspaAddress, asLineageId, asNetworkId, 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, writeFileAtomicSync };

package/dist/index.js

@@ -1,7 +1,296 @@
 // 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 {
+  static _lastRecovery = null;
+  /**
+   * 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;
+        _AppendCoordinator._lastRecovery = recovery;
+      }
+      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 recovery = _AppendCoordinator._lastRecovery;
+        const telemetry = getTelemetry();
+        telemetry.logAnomaly(
+          "EXTERNAL_MUTATION",
+          "medium",
+          "fs",
+          `Recovered corrupted tail in ${logBase}. Original size: ${recovery.originalSize} bytes, Recovered size: ${recovery.recoveredSize} bytes, Truncated bytes: ${linesDiscarded}. Reason: ${recovery.reason}. Original tail snippet: "${originalTail.slice(0, 60)}..."`,
+          rootDir
+        );
+      } catch {
+      }
+    }
+  }
+  /**
+   * Scans a JSONL stream for corruption, truncating malformed trailing lines.
+   * Utilizes a backward newline scanning logic with a rolling buffer,
+   * supporting lines of arbitrary size and only truncating the last complete
+   * valid JSONL boundary if a parse failure is detected.
+   */
+  static recoverCorruptedTail(filePath) {
+    const defaultRes = {
+      repaired: false,
+      linesDiscarded: 0,
+      originalTail: "",
+      originalSize: 0,
+      recoveredSize: 0,
+      reason: ""
+    };
+    if (!fs.existsSync(filePath)) return defaultRes;
+    const stat = fs.statSync(filePath);
+    defaultRes.originalSize = stat.size;
+    defaultRes.recoveredSize = stat.size;
+    if (stat.size === 0) return defaultRes;
+    const fd = fs.openSync(filePath, "r");
+    try {
+      let lastCharPos = -1;
+      let precedingNewlinePos = -1;
+      const CHUNK_SIZE = 64 * 1024;
+      let position = stat.size;
+      const buffer = Buffer.alloc(CHUNK_SIZE);
+      outer1: while (position > 0) {
+        const readLength = Math.min(CHUNK_SIZE, position);
+        position -= readLength;
+        fs.readSync(fd, buffer, 0, readLength, position);
+        for (let i = readLength - 1; i >= 0; i--) {
+          const charCode = buffer[i];
+          if (charCode !== 32 && charCode !== 9 && charCode !== 10 && charCode !== 13) {
+            lastCharPos = position + i;
+            break outer1;
+          }
+        }
+      }
+      if (lastCharPos === -1) {
+        fs.closeSync(fd);
+        fs.truncateSync(filePath, 0);
+        return {
+          repaired: true,
+          linesDiscarded: stat.size,
+          originalTail: "",
+          originalSize: stat.size,
+          recoveredSize: 0,
+          reason: "File only contained whitespaces or newlines"
+        };
+      }
+      position = lastCharPos;
+      outer2: while (position > 0) {
+        const readLength = Math.min(CHUNK_SIZE, position);
+        position -= readLength;
+        fs.readSync(fd, buffer, 0, readLength, position);
+        for (let i = readLength - 1; i >= 0; i--) {
+          if (buffer[i] === 10) {
+            precedingNewlinePos = position + i;
+            break outer2;
+          }
+        }
+      }
+      const lastLineStart = precedingNewlinePos === -1 ? 0 : precedingNewlinePos + 1;
+      const lastLineEnd = lastCharPos + 1;
+      const lastLineLength = lastLineEnd - lastLineStart;
+      const lastLineBuf = Buffer.alloc(lastLineLength);
+      fs.readSync(fd, lastLineBuf, 0, lastLineLength, lastLineStart);
+      fs.closeSync(fd);
+      const lastLine = lastLineBuf.toString("utf-8");
+      try {
+        JSON.parse(lastLine);
+        return defaultRes;
+      } catch (err) {
+        const truncateTo = lastLineStart;
+        const discardedBytes = stat.size - truncateTo;
+        fs.truncateSync(filePath, truncateTo);
+        return {
+          repaired: true,
+          linesDiscarded: discardedBytes,
+          originalTail: lastLine,
+          originalSize: stat.size,
+          recoveredSize: truncateTo,
+          reason: err instanceof Error ? err.message : "Invalid JSON syntax"
+        };
+      }
+    } catch (e) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+      }
+      throw e;
+    }
+  }
+};
+
 // src/events.ts
+import path3 from "path";
 var CoreEventBus = class {
   listeners = [];
   on(listener) {
@@ -66,6 +355,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;
@@ -116,34 +424,35 @@ function redactSecret(value) {
 }
 
 // src/fs.ts
-import fs from "fs";
-import path from "path";
-import crypto2 from "crypto";
+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}.${crypto2.randomUUID()}`);
+  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;
         }
@@ -153,11 +462,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) {
@@ -167,45 +476,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}.${crypto2.randomUUID()}`);
+  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;
@@ -214,11 +524,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) {
@@ -228,15 +538,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) {
       }
     }
@@ -262,8 +572,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",
@@ -274,13 +584,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 {
@@ -294,18 +605,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) {
             }
@@ -316,12 +627,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",
@@ -330,6 +678,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;
           }
@@ -375,20 +724,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
@@ -400,15 +751,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)" };
@@ -421,7 +772,7 @@ 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 };
 }
 
@@ -479,31 +830,31 @@ function diffReplays(replayA, replayB) {
 }
 
 // src/snapshot.ts
-import fs3 from "fs/promises";
-import path3 from "path";
+import fs4 from "fs/promises";
+import path6 from "path";
 async function createSnapshot(options) {
   const { hardkasDir, outputDir, deterministicScope = "local-only" } = options;
-  await fs3.mkdir(outputDir, { recursive: true });
-  await fs3.mkdir(path3.join(outputDir, "artifacts"), { recursive: true });
-  await fs3.mkdir(path3.join(outputDir, "projections"), { recursive: true });
-  await fs3.mkdir(path3.join(outputDir, "events"), { recursive: true });
-  await fs3.mkdir(path3.join(outputDir, "replay"), { recursive: true });
-  await fs3.mkdir(path3.join(outputDir, "metadata"), { recursive: true });
+  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 = path3.join(hardkasDir, "artifacts");
+  const artifactsDir = path6.join(hardkasDir, "artifacts");
   try {
-    const list = await fs3.readdir(artifactsDir);
+    const list = await fs4.readdir(artifactsDir);
     for (const f of list) {
       if (f.endsWith(".json")) {
-        const src = path3.join(artifactsDir, f);
-        const dest = path3.join(outputDir, "artifacts", f);
+        const src = path6.join(artifactsDir, f);
+        const dest = path6.join(outputDir, "artifacts", f);
         try {
-          const content = await fs3.readFile(src, "utf-8");
+          const content = await fs4.readFile(src, "utf-8");
           const parsed = JSON.parse(content);
           if (parsed.schema && parsed.schema.startsWith("hardkas.")) {
-            await fs3.copyFile(src, dest);
+            await fs4.copyFile(src, dest);
             included++;
           } else {
             excluded++;
@@ -516,19 +867,19 @@ async function createSnapshot(options) {
   } catch {
   }
   try {
-    const eventsLog = path3.join(hardkasDir, "events.jsonl");
-    await fs3.copyFile(eventsLog, path3.join(outputDir, "events", "events.jsonl"));
+    const eventsLog = path6.join(hardkasDir, "events.jsonl");
+    await fs4.copyFile(eventsLog, path6.join(outputDir, "events", "events.jsonl"));
   } catch {
   }
   try {
-    const dbPath = path3.join(hardkasDir, "store.db");
-    await fs3.copyFile(dbPath, path3.join(outputDir, "projections", "store.db"));
+    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.0-alpha",
+    hardkasVersion: "0.7.0-alpha",
     stateAuthority: "filesystem",
     projectionAuthority: "sqlite",
     deterministicScope,
@@ -537,16 +888,16 @@ async function createSnapshot(options) {
     excludedArtifacts: excluded,
     corruptedArtifacts: corrupted
   };
-  await fs3.writeFile(
-    path3.join(outputDir, "manifest.json"),
+  await fs4.writeFile(
+    path6.join(outputDir, "manifest.json"),
     JSON.stringify(manifest, null, 2),
     "utf-8"
   );
   return manifest;
 }
 async function readSnapshotManifest(snapshotDir) {
-  const manifestPath = path3.join(snapshotDir, "manifest.json");
-  const content = await fs3.readFile(manifestPath, "utf-8");
+  const manifestPath = path6.join(snapshotDir, "manifest.json");
+  const content = await fs4.readFile(manifestPath, "utf-8");
   return JSON.parse(content);
 }
 
@@ -555,6 +906,65 @@ 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: {
@@ -566,6 +976,210 @@ var systemRuntimeContext = {
   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.7.0-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;
   }
 };
 
@@ -661,13 +1275,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,
@@ -682,26 +1303,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/core",
-  "version": "0.6.0-alpha",
+  "version": "0.7.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",