@hardkas/core 0.7.10-alpha → 0.7.11-alpha

package/README.md

@@ -0,0 +1,48 @@
+# `@hardkas/core`
+
+The Core package provides the foundational safety rails, filesystem abstractions, and atomic persistence primitives for the entire HardKAS ecosystem.
+
+## 1. Atomic Persistence Variants
+
+All state mutation in HardKAS relies on strict atomic persistence to prevent corruption during unexpected crashes or power loss. The standard flow follows the `temp + rename + fsync` pattern.
+
+### Flow: Standard Atomic Write
+1. Data is written to a temporary file (`.hardkas/tmp/<uuid>.json`).
+2. `fs.fsyncSync()` is called on the temporary file to flush buffers to disk.
+3. The temporary file is atomically renamed over the target file (e.g., `state.json`).
+4. `fs.fsyncSync()` is called on the **parent directory** (`.hardkas/`) to ensure the directory entry is durably linked.
+
+### Variant: Fallback Write
+If the filesystem does not support directory `fsync` (e.g., certain Windows/WSL configurations), the engine catches `EINVAL` or `EISDIR` and gracefully degrades to a standard atomic rename without the parent directory flush, logging a warning to the telemetry stream.
+
+## 2. Workspace Lock Mechanisms
+
+To prevent concurrent modifications to the developer workspace, `@hardkas/core` uses a conservative file-based locking strategy (`.hardkas/locks/<domain>.lock`).
+
+### Flow: Lock Acquisition
+1. Process attempts to create a lock file using `fs.openSync(path, 'wx')` (exclusive write).
+2. If successful, the process PID and timestamp are written.
+3. If `EEXIST` is thrown, the process enters a **spin-wait loop** with exponential backoff (up to 30 seconds).
+
+### Variant: Stale Lock Detection & Recovery (LockHell Defense)
+If a lock cannot be acquired after 30 seconds, the engine checks if the holding process is still alive.
+- **Dead Process:** If `process.kill(pid, 0)` fails (indicating the PID no longer exists), the lock is deemed **stale**. The engine atomically overrides the lock and logs a `STALE_LOCK_RECOVERY` telemetry event.
+- **Live Process:** If the PID is active, HardKAS strictly aborts with `HARDKAS_LOCK_CONTENTION`. It will *never* violently break a lock held by a live process.
+- **Zero-Byte Locks:** If a system crash occurs precisely when the `wx` descriptor is created but before the PID is written (a TOCTOU scenario), HardKAS considers any 0-byte lock older than 10 seconds as implicitly stale.
+
+## 3. AppendCoordinator (Event Ledger)
+
+The `events.jsonl` ledger is the source of truth for the workspace. It is strictly append-only.
+
+### Flow: Ledger Append
+1. Acquire the exclusive `events` lock.
+2. Read the tail of the stream to determine the last `eventId`.
+3. Append the new JSON payload with a trailing newline.
+4. `fs.fsyncSync()` the file descriptor.
+
+### Variant: Tail Corruption Repair
+If the chaos engine (or a crash) leaves a partial JSON object at the tail of `events.jsonl` (e.g., `{"eventId": 142, "domain": "tx"` missing the closing brace):
+1. The `AppendCoordinator` detects `Unexpected end of JSON input` during tail-read.
+2. It explicitly scans backward to find the last valid newline boundary.
+3. The corrupted tail is truncated automatically.
+4. A `CORRUPT_TAIL_RECOVERY` event is dispatched to `telemetry.jsonl`.

package/dist/index.d.ts

@@ -787,7 +787,7 @@ declare class AppendCoordinator {
     };
 }
 
-declare const CURRENT_RUNTIME_VERSION = "0.7.10-alpha";
+declare const CURRENT_RUNTIME_VERSION = "0.7.11-alpha";
 declare const MIN_SUPPORTED_VERSION = "0.5.0-alpha";
 interface MigrationStatus {
     needsMigration: boolean;

package/dist/index.js

@@ -956,7 +956,7 @@ async function createSnapshot(options) {
   const manifest = {
     snapshotVersion: 1,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    hardkasVersion: "0.7.10-alpha",
+    hardkasVersion: "0.7.11-alpha",
     stateAuthority: "filesystem",
     projectionAuthority: "sqlite",
     deterministicScope,
@@ -1205,7 +1205,7 @@ Resolution Command: ${report.exactReplayCommand}`
 // src/migrations.ts
 import fs6 from "fs";
 import path8 from "path";
-var CURRENT_RUNTIME_VERSION = "0.7.10-alpha";
+var CURRENT_RUNTIME_VERSION = "0.7.11-alpha";
 var MIN_SUPPORTED_VERSION = "0.5.0-alpha";
 var MigrationManager = class {
   static checkVersion(rootDir) {

package/package.json

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