@hardkas/core 0.2.2-alpha.1 → 0.3.0-alpha

package/dist/index.d.ts

@@ -286,6 +286,126 @@ declare function maskSecrets(data: any): any;
  */
 declare function redactSecret(value: string): string;
 
+/**
+ * Options for atomic file writing.
+ */
+interface WriteFileAtomicOptions {
+    /** Encoding for string data (default: utf-8) */
+    encoding?: BufferEncoding;
+    /** File mode (permissions) */
+    mode?: number;
+    /** If true, calls fsync on the parent directory (Linux/macOS) */
+    fsyncParent?: boolean;
+}
+/**
+ * Writes a file atomically using the temp-file-and-rename pattern.
+ * Ensures that either the entire file is written or no changes are made.
+ *
+ * Pattern:
+ * 1. Write data to a temporary file in the same directory.
+ * 2. fsync the temporary file to ensure data is on disk.
+ * 3. Close the temporary file.
+ * 4. Rename the temporary file to the target path (atomic operation).
+ * 5. Optional: fsync the parent directory to ensure metadata is on disk.
+ */
+declare function writeFileAtomic(targetPath: string, data: string | Buffer, options?: WriteFileAtomicOptions): Promise<void>;
+/**
+ * Synchronous version of writeFileAtomic.
+ */
+declare function writeFileAtomicSync(targetPath: string, data: string | Buffer, options?: WriteFileAtomicOptions): void;
+
+/**
+ * HardKAS Corruption Taxonomy & Issue Reporting
+ */
+type CorruptionCode = "ARTIFACT_JSON_INVALID" | "ARTIFACT_SCHEMA_MISSING" | "ARTIFACT_SCHEMA_INVALID" | "ARTIFACT_HASH_MISMATCH" | "ARTIFACT_ID_INVALID" | "ARTIFACT_LINEAGE_INVALID" | "EVENT_JSON_INVALID" | "EVENT_SCHEMA_INVALID" | "EVENT_LINE_CORRUPT" | "STORE_STALE" | "STORE_CORRUPT" | "STORE_REBUILD_REQUIRED" | "DUPLICATE_ARTIFACT" | "DUPLICATE_EVENT" | "SEMANTIC_DIVERGENCE" | "REPLAY_PARTIAL" | "REPLAY_UNSUPPORTED_CHECK" | "LOCK_HELD" | "LOCK_TIMEOUT" | "STALE_LOCK" | "LOCK_RELEASE_FAILED" | "LOCK_OWNER_MISMATCH" | "LOCK_METADATA_INVALID" | "STORE_MIGRATION_REQUIRED" | "STORE_MIGRATION_FAILED" | "STORE_MIGRATION_CHECKSUM_MISMATCH" | "STORE_SCHEMA_UNSUPPORTED" | "STORE_LEGACY_BOOTSTRAPPED";
+type CorruptionSeverity = "warning" | "error";
+interface CorruptionIssue {
+    readonly code: CorruptionCode;
+    readonly severity: CorruptionSeverity;
+    readonly message: string;
+    readonly path?: string;
+    readonly lineNumber?: number;
+    readonly artifactId?: string;
+    readonly contentHash?: string;
+    readonly suggestion?: string;
+}
+/**
+ * Formats a corruption issue for human-readable output.
+ */
+declare function formatCorruptionIssue(issue: CorruptionIssue): string;
+
+/**
+ * HardKAS Lock Metadata schema v1
+ */
+interface LockMetadata {
+    schema: "hardkas.lock.v1";
+    name: string;
+    pid: number;
+    command: string;
+    cwd: string;
+    hostname: string;
+    createdAt: string;
+    expiresAt: string | null;
+}
+interface LockHandle {
+    readonly path: string;
+    readonly metadata: LockMetadata;
+    release(): Promise<void>;
+}
+interface AcquireLockArgs {
+    rootDir: string;
+    name: string;
+    command?: string;
+    staleMs?: number;
+    wait?: boolean;
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/**
+ * Deterministic lock ordering to avoid deadlocks.
+ * workspace > node > accounts > artifacts > events > query-store
+ */
+declare const LOCK_ORDER: string[];
+/**
+ * Acquires a named lock for the workspace.
+ */
+declare function acquireLock(args: AcquireLockArgs): Promise<LockHandle>;
+/**
+ * Helper to run a task with a single lock.
+ */
+declare function withLock<T>(args: AcquireLockArgs, fn: (handle: LockHandle) => Promise<T>): Promise<T>;
+/**
+ * Helper to run a task with multiple locks in deterministic order.
+ */
+declare function withLocks<T>(rootDir: string, names: string[], fn: () => Promise<T>, options?: {
+    command?: string;
+    wait?: boolean;
+    timeoutMs?: number;
+}): Promise<T>;
+/**
+ * Checks if a process is alive.
+ */
+declare function isProcessAlive(pid: number): boolean;
+/**
+ * Lists all active locks in the workspace.
+ */
+declare function listLocks(rootDir: string): Array<{
+    name: string;
+    metadata: LockMetadata;
+    path: string;
+    isAlive: boolean;
+}>;
+/**
+ * Safely clears a lock if criteria are met.
+ */
+declare function clearLock(rootDir: string, name: string, options?: {
+    force?: boolean;
+    ifDead?: boolean;
+}): {
+    cleared: boolean;
+    reason?: string;
+};
+
 declare const SOMPI_PER_KAS = 100000000n;
 declare const kaspaNetworkIdSchema: z.ZodEnum<["mainnet", "testnet-10", "testnet-11", "testnet-12", "simnet", "simnet-1", "devnet"]>;
 type NetworkId = Brand<z.infer<typeof kaspaNetworkIdSchema>, "NetworkId">;
@@ -376,4 +496,4 @@ declare function parseHardkasConfig(input: unknown): HardkasConfig;
 declare function parseKasToSompi(input: string): bigint;
 declare function formatSompi(amountSompi: bigint): string;
 
-export { type ArtifactId, type ArtifactType, ArtifactTypeSchema, type Brand, type Branded, type ContentHash, type CoreEvent, type CoreEventListener, type CorrelationId, type DaaScore, type EventDomain, type EventEnvelope, type EventId, type EventKind, type EventPayloadByKind, type EventSequence, type ExecutionMode, ExecutionModeSchema, type HardkasConfig, HardkasError, type InvariantDomain, type InvariantSeverity, InvariantViolationError, type KaspaAddress, type LineageId, type NetworkId, NetworkIdSchema, type RpcEndpointId, SOMPI_PER_KAS, type StampedEvent, type TxId, type UnknownEventPayload, type WorkflowId, artifactTypeSchema, asArtifactId, asContentHash, asCorrelationId, asDaaScore, asEventId, asEventSequence, asKaspaAddress, asLineageId, asNetworkId, asRpcEndpointId, asTxId, asWorkflowId, coreEvents, createEventEnvelope, executionModeSchema, formatSompi, hardkasConfigSchema, kaspaNetworkIdSchema, maskSecrets, parseHardkasConfig, parseKasToSompi, redactSecret, validateEventEnvelope };
+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 DaaScore, type EventDomain, type EventEnvelope, type EventId, type EventKind, type EventPayloadByKind, type EventSequence, type ExecutionMode, ExecutionModeSchema, type HardkasConfig, HardkasError, type InvariantDomain, type InvariantSeverity, InvariantViolationError, type KaspaAddress, LOCK_ORDER, type LineageId, type LockHandle, type LockMetadata, type NetworkId, NetworkIdSchema, type RpcEndpointId, SOMPI_PER_KAS, type StampedEvent, 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, executionModeSchema, formatCorruptionIssue, formatSompi, hardkasConfigSchema, isProcessAlive, kaspaNetworkIdSchema, listLocks, maskSecrets, parseHardkasConfig, parseKasToSompi, redactSecret, validateEventEnvelope, withLock, withLocks, writeFileAtomic, writeFileAtomicSync };

package/dist/index.js

@@ -111,6 +111,315 @@ function redactSecret(value) {
   return `${value.slice(0, 6)}...${value.slice(-4)}`;
 }
 
+// src/fs.ts
+import fs from "fs";
+import path from "path";
+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)}`);
+  let fd = null;
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fd = fs.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);
+    fd = null;
+    let attempts = 0;
+    const maxAttempts = process.platform === "win32" ? 5 : 1;
+    while (attempts < maxAttempts) {
+      try {
+        fs.renameSync(tempPath, targetPath);
+        break;
+      } catch (e) {
+        attempts++;
+        if (attempts >= maxAttempts) throw e;
+        if (e.code === "EPERM" || e.code === "EBUSY") {
+          await new Promise((resolve) => setTimeout(resolve, 10 * attempts));
+          continue;
+        }
+        throw e;
+      }
+    }
+    if (options.fsyncParent && process.platform !== "win32") {
+      let dirFd = null;
+      try {
+        dirFd = fs.openSync(dir, "r");
+        fs.fsyncSync(dirFd);
+      } catch (e) {
+      } finally {
+        if (dirFd !== null) fs.closeSync(dirFd);
+      }
+    }
+  } catch (err) {
+    throw new HardkasError(
+      "IO_ERROR",
+      `Failed to write file atomically: ${targetPath}`,
+      { cause: err }
+    );
+  } finally {
+    if (fs.existsSync(tempPath)) {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch (e) {
+      }
+    }
+    if (fd !== null) {
+      try {
+        fs.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)}`);
+  let fd = null;
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fd = fs.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);
+    fd = null;
+    let attempts = 0;
+    const maxAttempts = process.platform === "win32" ? 5 : 1;
+    while (attempts < maxAttempts) {
+      try {
+        fs.renameSync(tempPath, targetPath);
+        break;
+      } catch (e) {
+        attempts++;
+        if (attempts >= maxAttempts) throw e;
+        if (e.code === "EPERM" || e.code === "EBUSY") {
+          continue;
+        }
+        throw e;
+      }
+    }
+    if (options.fsyncParent && process.platform !== "win32") {
+      let dirFd = null;
+      try {
+        dirFd = fs.openSync(dir, "r");
+        fs.fsyncSync(dirFd);
+      } catch (e) {
+      } finally {
+        if (dirFd !== null) fs.closeSync(dirFd);
+      }
+    }
+  } catch (err) {
+    throw new HardkasError(
+      "IO_ERROR",
+      `Failed to write file atomically (sync): ${targetPath}`,
+      { cause: err }
+    );
+  } finally {
+    if (fs.existsSync(tempPath)) {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch (e) {
+      }
+    }
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch (e) {
+      }
+    }
+  }
+}
+
+// src/corruption.ts
+function formatCorruptionIssue(issue) {
+  const parts = [];
+  const icon = issue.severity === "error" ? "\u274C" : "\u26A0\uFE0F";
+  parts.push(`${icon} [${issue.code}] ${issue.message}`);
+  if (issue.path) {
+    const loc = issue.lineNumber ? `${issue.path}:${issue.lineNumber}` : issue.path;
+    parts.push(`   Location: ${loc}`);
+  }
+  if (issue.artifactId) {
+    parts.push(`   Artifact: ${issue.artifactId}`);
+  }
+  if (issue.suggestion) {
+    parts.push(`   Suggestion: ${issue.suggestion}`);
+  }
+  return parts.join("\n");
+}
+
+// src/lock.ts
+import fs2 from "fs";
+import path2 from "path";
+import os from "os";
+var LOCK_ORDER = [
+  "workspace",
+  "node",
+  "accounts",
+  "artifacts",
+  "events",
+  "query-store"
+];
+async function acquireLock(args) {
+  const lockDir = path2.join(args.rootDir, ".hardkas", "locks");
+  const lockPath = path2.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 });
+  }
+  while (true) {
+    try {
+      const metadata = {
+        schema: "hardkas.lock.v1",
+        name: args.name,
+        pid: process.pid,
+        command: args.command || process.argv.join(" "),
+        cwd: process.cwd(),
+        hostname: os.hostname(),
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        expiresAt: null
+      };
+      const fd = fs2.openSync(lockPath, "wx");
+      fs2.writeSync(fd, JSON.stringify(metadata, null, 2));
+      fs2.closeSync(fd);
+      return {
+        path: lockPath,
+        metadata,
+        release: async () => {
+          if (fs2.existsSync(lockPath)) {
+            try {
+              const current = JSON.parse(fs2.readFileSync(lockPath, "utf-8"));
+              if (current.pid === process.pid) {
+                fs2.unlinkSync(lockPath);
+              }
+            } catch (e) {
+            }
+          }
+        }
+      };
+    } catch (e) {
+      if (e.code === "EEXIST") {
+        let existingMetadata = null;
+        try {
+          existingMetadata = JSON.parse(fs2.readFileSync(lockPath, "utf-8"));
+        } catch (err) {
+          throw new HardkasError("LOCK_METADATA_INVALID", `Lock file at ${lockPath} is corrupted.`, { cause: err });
+        }
+        if (existingMetadata) {
+          const isAlive = isProcessAlive(existingMetadata.pid);
+          if (!isAlive) {
+            throw new HardkasError(
+              "STALE_LOCK",
+              `Workspace is locked by a dead process (PID: ${existingMetadata.pid}).`,
+              { cause: existingMetadata }
+            );
+          }
+          if (args.wait && Date.now() - start < timeoutMs) {
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+            continue;
+          }
+          throw new HardkasError(
+            args.wait ? "LOCK_TIMEOUT" : "LOCK_HELD",
+            `Workspace is locked by another HardKAS process (PID: ${existingMetadata.pid}).`,
+            { cause: existingMetadata }
+          );
+        }
+      }
+      throw e;
+    }
+  }
+}
+async function withLock(args, fn) {
+  const handle = await acquireLock(args);
+  try {
+    return await fn(handle);
+  } finally {
+    await handle.release();
+  }
+}
+async function withLocks(rootDir, names, fn, options = {}) {
+  const sortedNames = [...names].sort((a, b) => {
+    const idxA = LOCK_ORDER.indexOf(a);
+    const idxB = LOCK_ORDER.indexOf(b);
+    return idxA - idxB;
+  });
+  const handles = [];
+  try {
+    for (const name of sortedNames) {
+      handles.push(await acquireLock({ rootDir, name, ...options }));
+    }
+    return await fn();
+  } finally {
+    for (const handle of handles.reverse()) {
+      await handle.release();
+    }
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code !== "ESRCH";
+  }
+}
+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 result = [];
+  for (const file of files) {
+    const lockPath = path2.join(lockDir, file);
+    try {
+      const metadata = JSON.parse(fs2.readFileSync(lockPath, "utf-8"));
+      result.push({
+        name: path2.basename(file, ".lock"),
+        metadata,
+        path: lockPath,
+        isAlive: metadata.hostname === os.hostname() ? isProcessAlive(metadata.pid) : true
+        // Assume alive if remote
+      });
+    } catch (e) {
+    }
+  }
+  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" };
+  let metadata;
+  try {
+    metadata = JSON.parse(fs2.readFileSync(lockPath, "utf-8"));
+  } catch (e) {
+    if (options.force) {
+      fs2.unlinkSync(lockPath);
+      return { cleared: true };
+    }
+    return { cleared: false, reason: "Corrupt metadata (use --force to clear)" };
+  }
+  const isLocal = metadata.hostname === os.hostname();
+  const isAlive = isLocal ? isProcessAlive(metadata.pid) : true;
+  if (options.ifDead) {
+    if (!isLocal) return { cleared: false, reason: "Cannot verify liveness of remote lock (host: " + metadata.hostname + ")" };
+    if (isAlive) return { cleared: false, reason: `Process (PID: ${metadata.pid}) is still alive` };
+  } else if (!options.force) {
+    return { cleared: false, reason: "Lock is potentially active. Use --force or --if-dead." };
+  }
+  fs2.unlinkSync(lockPath);
+  return { cleared: true };
+}
+
 // src/index.ts
 var SOMPI_PER_KAS = 100000000n;
 var kaspaNetworkIdSchema = z.enum([
@@ -205,8 +514,10 @@ export {
   ExecutionModeSchema,
   HardkasError,
   InvariantViolationError,
+  LOCK_ORDER,
   NetworkIdSchema,
   SOMPI_PER_KAS,
+  acquireLock,
   artifactTypeSchema,
   asArtifactId,
   asContentHash,
@@ -220,15 +531,23 @@ export {
   asRpcEndpointId,
   asTxId,
   asWorkflowId,
+  clearLock,
   coreEvents,
   createEventEnvelope,
   executionModeSchema,
+  formatCorruptionIssue,
   formatSompi,
   hardkasConfigSchema,
+  isProcessAlive,
   kaspaNetworkIdSchema,
+  listLocks,
   maskSecrets,
   parseHardkasConfig,
   parseKasToSompi,
   redactSecret,
-  validateEventEnvelope
+  validateEventEnvelope,
+  withLock,
+  withLocks,
+  writeFileAtomic,
+  writeFileAtomicSync
 };

package/package.json

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