asylumwarden 0.0.0 → 0.1.0

package/src/kernel/canon.mjs

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { fail } from "./errors.mjs";
+
+// Canonical JSON — CONTRACT §1. Recursive stable stringify: keys sorted by
+// UTF-16 code unit, arrays order-preserving, no insignificant whitespace.
+export function canon(value) {
+  return stableStringify(value, new Set());
+}
+
+function stableStringify(value, seen) {
+  if (value === null) return "null";
+  const type = typeof value;
+  if (type === "string" || type === "boolean") return JSON.stringify(value);
+  if (type === "number") {
+    if (!Number.isFinite(value)) fail("INTERNAL", "canon: non-finite number");
+    return JSON.stringify(value);
+  }
+  if (type !== "object") fail("INTERNAL", `canon: unsupported type ${type}`);
+  if (seen.has(value)) fail("INTERNAL", "canon: cyclic structure");
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => stableStringify(item, seen)).join(",")}]`;
+    }
+    const keys = Object.keys(value).sort();
+    const parts = keys.map(
+      (key) => `${JSON.stringify(key)}:${stableStringify(value[key], seen)}`,
+    );
+    return `{${parts.join(",")}}`;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+export function sha256Hex(bytesOrString) {
+  const hash = createHash("sha256");
+  hash.update(bytesOrString);
+  return hash.digest("hex");
+}
+
+export function sha256Of(value) {
+  return sha256Hex(canon(value));
+}
+
+export const GENESIS_PREV = "0".repeat(64);
+
+// Streaming file digest. Callers must have already checked the entry is a
+// regular file (not a symlink / directory) when containment matters.
+export async function sha256File(path) {
+  const hash = createHash("sha256");
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(path);
+    stream.on("error", reject);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", resolve);
+  });
+  return hash.digest("hex");
+}

package/src/kernel/errors.mjs

@@ -0,0 +1,80 @@
+// Error taxonomy — single source: docs/CONTRACT.md §8.3.
+export const EXIT_OK = 0;
+export const EXIT_BUSINESS = 1;
+export const EXIT_FAIL_CLOSED = 2;
+
+const BUSINESS_CODES = new Set([
+  "USAGE",
+  "UNKNOWN-COMMAND",
+  "LEASE-HELD",
+  "LEASE-EXPIRED",
+  "LEASE-MAX-HOLD",
+  "LEASE-BUSY",
+  "STEAL-DENIED",
+  "EPOCH-MISMATCH",
+  "ACTOR-MISMATCH",
+  "CELL-STATE",
+  "RESTART-REQUIRED",
+  "RECEIPT-COMMANDS",
+  "RECEIPT-HASH",
+  "READ-OUTSIDE",
+  "WAVE-EXISTS",
+  "WAVE-MISSING",
+  "CELL-MISSING",
+]);
+
+const FAIL_CLOSED_CODES = new Set([
+  "CONFIG-MISSING",
+  "CONFIG-INVALID",
+  "CONFIG-DRIFT",
+  "REGISTRY-MISSING",
+  "REGISTRY-INVALID",
+  "ROOTS-OVERLAP",
+  "ROOT-MISSING",
+  "FORBIDDEN-ROOT",
+  "GLOB-INVALID",
+  "UNKNOWN-KIND",
+  "MANIFEST-INVALID",
+  "DEP-UNKNOWN",
+  "DEP-CYCLE",
+  "DEP-DUPLICATE",
+  "PATH-ESCAPE",
+  "FORBIDDEN-SURFACE",
+  "SCHEMA-VIOLATION",
+  "STATE-CORRUPT",
+  "LEDGER-BROKEN",
+  "LEDGER-TORN",
+  "LEDGER-BUSY",
+  "ANCHOR-FAIL",
+  "ANCHOR-STALE",
+  "INTERNAL",
+]);
+
+export function exitClassFor(code) {
+  if (BUSINESS_CODES.has(code)) return EXIT_BUSINESS;
+  // Unknown codes can never widen the success path; fail closed.
+  if (FAIL_CLOSED_CODES.has(code)) return EXIT_FAIL_CLOSED;
+  return EXIT_FAIL_CLOSED;
+}
+
+export function isKnownCode(code) {
+  return BUSINESS_CODES.has(code) || FAIL_CLOSED_CODES.has(code);
+}
+
+export class WardenError extends Error {
+  constructor(code, message, violations = []) {
+    super(message);
+    this.name = "WardenError";
+    this.code = code;
+    this.violations = violations;
+    this.exitClass = exitClassFor(code);
+  }
+}
+
+export function violation(field, rule, detail) {
+  return { field, rule, detail };
+}
+
+export function fail(code, message, violations = []) {
+  throw new WardenError(code, message, violations);
+}

package/src/kernel/fsutil.mjs

@@ -0,0 +1,147 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { fail, violation } from "./errors.mjs";
+
+export const CAP_CONFIG = 1_048_576; // 1 MiB — config / registry / manifest / receipt
+export const CAP_LINE = 262_144; // 256 KiB — one ledger line
+export const CAP_STRING = 4096;
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function expandHome(raw) {
+  if (typeof raw !== "string") fail("INTERNAL", "expandHome: non-string path");
+  if (raw === "~") return os.homedir();
+  if (raw.startsWith("~/")) return path.join(os.homedir(), raw.slice(2));
+  return raw;
+}
+
+const FORBIDDEN_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+function guardKeys(node, where) {
+  if (node === null || typeof node !== "object") return;
+  for (const key of Object.getOwnPropertyNames(node)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      fail("SCHEMA-VIOLATION", `forbidden key ${key} at ${where}`, [
+        violation(where, "forbidden-key", key),
+      ]);
+    }
+  }
+  for (const key of Object.getOwnPropertyNames(node)) {
+    guardKeys(node[key], `${where}.${key}`);
+  }
+}
+
+// Read + parse with size cap, null prototype, and forbidden-key rejection.
+// codeOnBad selects the code family: state files are STATE-CORRUPT,
+// user-supplied JSON is SCHEMA-VIOLATION.
+export async function readJsonCapped(filePath, cap = CAP_CONFIG, codeOnBad = "STATE-CORRUPT") {
+  let handle;
+  try {
+    handle = await fs.open(filePath, "r");
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+      fail(codeOnBad, `not a regular file: ${filePath}`, [violation(filePath, "not-file", "")]);
+    }
+    if (stat.size > cap) {
+      fail(codeOnBad, `file exceeds ${cap} byte cap: ${filePath}`, [
+        violation(filePath, "size-cap", String(stat.size)),
+      ]);
+    }
+    const text = await handle.readFile({ encoding: "utf8" });
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      fail(codeOnBad, `unparseable JSON: ${filePath}`, [violation(filePath, "json-parse", "")]);
+    }
+    guardKeys(parsed, path.basename(filePath));
+    return { value: deepNullProto(parsed), size: stat.size };
+  } catch (error) {
+    if (error && error.code === "ENOENT") throw error;
+    if (error && error.name === "WardenError") throw error;
+    fail(codeOnBad, `cannot read ${filePath}: ${error.message}`, [
+      violation(filePath, "read-error", error.message),
+    ]);
+  } finally {
+    await handle?.close();
+  }
+}
+
+function deepNullProto(node) {
+  if (node === null || typeof node !== "object") return node;
+  // Arrays keep Array.prototype: JSON arrays cannot carry __proto__ via
+  // index keys, and consumers legitimately call .map/.filter/.every.
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i += 1) node[i] = deepNullProto(node[i]);
+    return node;
+  }
+  for (const key of Object.getOwnPropertyNames(node)) {
+    node[key] = deepNullProto(node[key]);
+  }
+  Object.setPrototypeOf(node, null);
+  return node;
+}
+
+// Atomic JSON write: tmp (same dir) → full write → fsync → rename → re-read.
+export async function atomicWriteJson(filePath, value) {
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(
+    dir,
+    `.${path.basename(filePath)}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`,
+  );
+  const payload = `${JSON.stringify(value, null, 2)}\n`;
+  let handle;
+  try {
+    handle = await fs.open(tmp, "w", 0o600);
+    await handle.writeFile(payload, "utf8");
+    await handle.sync();
+  } finally {
+    await handle?.close();
+  }
+  try {
+    await fs.rename(tmp, filePath);
+  } catch (error) {
+    await fs.rm(tmp, { force: true });
+    fail("INTERNAL", `atomic rename failed for ${filePath}: ${error.message}`);
+  }
+  // Read-back verification per write protocol.
+  const back = await fs.readFile(filePath, "utf8");
+  if (back !== payload) {
+    fail("INTERNAL", `atomic write read-back mismatch: ${filePath}`);
+  }
+}
+
+export async function ensureDir(dirPath, mode = 0o700) {
+  await fs.mkdir(dirPath, { recursive: true, mode });
+}
+
+export async function fileExists(filePath) {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function pidAlive(pid, host) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (host !== os.hostname()) {
+    // Cannot probe foreign hosts: assume alive; expiry is time-gated.
+    return true;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+export { existsSync };

package/src/kernel/glob.mjs

@@ -0,0 +1,70 @@
+// Glob matching for forbidden patterns — CONTRACT §1.
+// `**` matches zero or more path segments; `*` one segment interior; `?` one
+// char. A trailing `/**` also matches the directory itself, so directory
+// patterns cover their contents conservatively. No char classes, no braces.
+
+import { fail } from "./errors.mjs";
+
+const cache = new Map();
+
+export function compileGlob(pattern) {
+  const hit = cache.get(pattern);
+  if (hit) return hit;
+  if (typeof pattern !== "string" || !pattern.startsWith("/")) {
+    fail("GLOB-INVALID", `glob pattern must be absolute: ${String(pattern)}`);
+  }
+  const raw = pattern.split("/");
+  const segs = [];
+  for (const seg of raw) {
+    if (seg === "**" && segs.at(-1) === "**") continue; // collapse **/**
+    if (seg === "" && segs.length > 0) continue; // collapse //
+    segs.push(seg);
+  }
+  let re = "";
+  let needSep = false;
+  for (let i = 0; i < segs.length; i += 1) {
+    const seg = segs[i];
+    if (seg === "") {
+      re += "/";
+      continue;
+    }
+    if (seg === "**") {
+      if (i === segs.length - 1) {
+        re += re.endsWith("/") ? ".*" : "(?:/.*)?";
+        needSep = false;
+      } else {
+        if (needSep) re += "/";
+        re += "(?:[^/]+/)*";
+        needSep = false;
+      }
+      continue;
+    }
+    if (needSep) re += "/";
+    re += segmentToRe(seg);
+    needSep = true;
+  }
+  const compiled = new RegExp(`^${re}$`);
+  cache.set(pattern, compiled);
+  return compiled;
+}
+
+function segmentToRe(seg) {
+  let out = "";
+  for (const ch of seg) {
+    if (ch === "*") out += "[^/]*";
+    else if (ch === "?") out += "[^/]";
+    else out += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return out;
+}
+
+export function matchGlob(pattern, absPath) {
+  return compileGlob(pattern).test(absPath);
+}
+
+export function matchAny(patterns, absPath) {
+  for (const pattern of patterns) {
+    if (matchGlob(pattern, absPath)) return pattern;
+  }
+  return null;
+}

package/src/kernel/lock.mjs

@@ -0,0 +1,104 @@
+// Generic exclusive lock for short critical sections (per-cell lease
+// mutation). Same posture as the ledger lock (CONTRACT §5.3): O_EXCL create,
+// forensic body, stale recovery for dead holders, fail-closed busy.
+// Not for long holds — callers run milliseconds of file work inside.
+
+import fs from "node:fs/promises";
+import os from "node:os";
+
+import { fail, violation } from "./errors.mjs";
+import { ensureDir, nowIso, pidAlive } from "./fsutil.mjs";
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function withExclusiveLock(
+  lockPath,
+  {
+    staleAfterMs = 30_000,
+    busyAfterMs = 60_000,
+    deadlineMs = 5_000,
+    pollMs = 10,
+    busyCode = "LEDGER-BUSY",
+    busyMessage = "critical section busy",
+  } = {},
+  fn,
+) {
+  await ensureDir(lockPath.slice(0, lockPath.lastIndexOf("/")) || "/");
+  const deadline = Date.now() + deadlineMs;
+  let acquired = false;
+  while (!acquired) {
+    let handle;
+    try {
+      handle = await fs.open(lockPath, "wx", 0o600);
+      await handle.writeFile(JSON.stringify({ pid: process.pid, host: os.hostname(), ts: nowIso() }));
+      acquired = true;
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        fail("INTERNAL", `lock create failed: ${lockPath}: ${error.message}`);
+      }
+      const status = await inspect(lockPath);
+      if (status === "stale") {
+        await fs.rm(lockPath, { force: true });
+        continue; // one retry loop through create
+      }
+      if (status === "busy") {
+        fail(busyCode, `${busyMessage}: ${lockPath}`, [violation(lockPath, "lock-busy", "holder alive")]);
+      }
+      if (Date.now() > deadline) {
+        fail(busyCode, `${busyMessage}: ${lockPath} (wait deadline exceeded)`, [
+          violation(lockPath, "lock-timeout", String(deadlineMs)),
+        ]);
+      }
+      await sleep(pollMs);
+    } finally {
+      await handle?.close();
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    await fs.rm(lockPath, { force: true });
+  }
+}
+
+// gone|stale|busy|contended
+async function inspect(lockPath) {
+  let text;
+  let mtimeMs;
+  try {
+    ;[text, mtimeMs] = await Promise.all([
+      fs.readFile(lockPath, "utf8"),
+      fs.stat(lockPath).then((s) => s.mtimeMs),
+    ]);
+  } catch (error) {
+    if (error?.code === "ENOENT") return "contended"; // released mid-inspect, retry
+    return "busy";
+  }
+  const trimmed = text.trim();
+  if (trimmed === "") {
+    // create-vs-write window: stale only far beyond the busy window
+    return Date.now() - mtimeMs > 60_000 ? "stale" : "contended";
+  }
+  let body;
+  try {
+    body = JSON.parse(trimmed);
+  } catch {
+    return Date.now() - mtimeMs > 60_000 ? "stale" : "busy";
+  }
+  if (
+    !body ||
+    typeof body !== "object" ||
+    !Number.isInteger(body.pid) ||
+    typeof body.ts !== "string"
+  ) {
+    return Date.now() - mtimeMs > 60_000 ? "stale" : "busy";
+  }
+  if (pidAlive(body.pid, body.host)) {
+    // A live holder older than the busy window is wedged: fail closed.
+    return Date.now() - Date.parse(body.ts) > 60_000 ? "busy" : "contended";
+  }
+  // Dead holder: stale beyond the stale window; recent death still drains.
+  return Date.now() - Date.parse(body.ts) > 30_000 ? "stale" : "contended";
+}

package/src/kernel/schemalite.mjs

@@ -0,0 +1,153 @@
+// schemalite — the zero-dependency JSON Schema subset used by core.
+// SUPPORTED keywords ONLY; a schema using anything else fails the build with
+// INTERNAL (drift guard). Semantics follow draft 2020-12 for the subset.
+
+import { fail, violation } from "./errors.mjs";
+import { canon } from "./canon.mjs";
+
+const SUPPORTED = new Set([
+  "$schema",
+  "$id",
+  "title",
+  "description",
+  "type",
+  "const",
+  "enum",
+  "required",
+  "properties",
+  "additionalProperties",
+  "items",
+  "pattern",
+  "format",
+  "minimum",
+  "maxItems",
+  "minItems",
+  "maxProperties",
+  "minProperties",
+  "maxLength",
+  "minLength",
+  "allOf",
+  "anyOf",
+]);
+
+const DATE_TIME_RE =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (Number.isInteger(value)) return "integer";
+  return typeof value; // string | number | boolean | object
+}
+
+function typeMatches(value, type) {
+  const actual = typeOf(value);
+  if (type === actual) return true;
+  if (type === "number" && actual === "integer") return true;
+  return false;
+}
+
+function push(violations, pathLabel, rule, detail) {
+  violations.push(violation(pathLabel, rule, detail));
+}
+
+export function validateSchema(schema, value, pathLabel = "$") {
+  const violations = [];
+  check(schema, value, pathLabel, violations);
+  return violations;
+}
+
+function check(schema, value, pathLabel, violations) {
+  for (const keyword of Object.getOwnPropertyNames(schema)) {
+    if (!SUPPORTED.has(keyword)) {
+      fail("INTERNAL", `schemalite: unsupported keyword "${keyword}" in schema`);
+    }
+  }
+  const { type, const: konst, enum: enumList, required, properties, additionalProperties,
+    items, pattern, format, minimum, minItems, maxItems, minProperties, maxProperties,
+    maxLength, minLength, allOf, anyOf } = schema;
+
+  if (type !== undefined) {
+    const types = Array.isArray(type) ? type : [type];
+    if (!types.some((t) => typeMatches(value, t))) {
+      push(violations, pathLabel, "type", `expected ${types.join("|")}, got ${typeOf(value)}`);
+      return; // further keyword checks would cascade
+    }
+  }
+  if (konst !== undefined && canon(value) !== canon(konst)) {
+    push(violations, pathLabel, "const", `expected ${JSON.stringify(konst)}`);
+  }
+  if (enumList !== undefined && !enumList.some((alt) => canon(value) === canon(alt))) {
+    push(violations, pathLabel, "enum", `got ${JSON.stringify(value)}`);
+  }
+  if (typeof value === "string") {
+    if (minLength !== undefined && value.length < minLength) {
+      push(violations, pathLabel, "minLength", String(value.length));
+    }
+    if (maxLength !== undefined && value.length > maxLength) {
+      push(violations, pathLabel, "maxLength", String(value.length));
+    }
+    if (pattern !== undefined && !new RegExp(pattern).test(value)) {
+      push(violations, pathLabel, "pattern", `got ${JSON.stringify(value)}`);
+    }
+    if (format === "date-time" && !DATE_TIME_RE.test(value)) {
+      push(violations, pathLabel, "format", `not RFC3339 date-time: ${value}`);
+    }
+  }
+  if (typeof value === "number" && minimum !== undefined && value < minimum) {
+    push(violations, pathLabel, "minimum", `got ${value}, min ${minimum}`);
+  }
+  if (Array.isArray(value)) {
+    if (minItems !== undefined && value.length < minItems) {
+      push(violations, pathLabel, "minItems", String(value.length));
+    }
+    if (maxItems !== undefined && value.length > maxItems) {
+      push(violations, pathLabel, "maxItems", String(value.length));
+    }
+    if (items !== undefined) {
+      for (let i = 0; i < value.length; i += 1) {
+        check(items, value[i], `${pathLabel}[${i}]`, violations);
+      }
+    }
+  }
+  if (typeOf(value) === "object") {
+    const own = Object.getOwnPropertyNames(value);
+    if (minProperties !== undefined && own.length < minProperties) {
+      push(violations, pathLabel, "minProperties", String(own.length));
+    }
+    if (maxProperties !== undefined && own.length > maxProperties) {
+      push(violations, pathLabel, "maxProperties", String(own.length));
+    }
+    if (Array.isArray(required)) {
+      for (const key of required) {
+        if (!Object.hasOwn(value, key)) {
+          push(violations, pathLabel, "required", `missing ${key}`);
+        }
+      }
+    }
+    for (const key of own) {
+      const childLabel = `${pathLabel}.${key}`;
+      if (properties !== undefined && Object.hasOwn(properties, key)) {
+        check(properties[key], value[key], childLabel, violations);
+      } else if (additionalProperties === false) {
+        push(violations, pathLabel, "additionalProperties", `unknown key ${key}`);
+      } else if (additionalProperties !== undefined && typeof additionalProperties === "object") {
+        check(additionalProperties, value[key], childLabel, violations);
+      }
+    }
+  }
+  if (Array.isArray(allOf)) {
+    for (const sub of allOf) check(sub, value, pathLabel, violations);
+  }
+  if (Array.isArray(anyOf)) {
+    const branches = anyOf.map((sub) => {
+      const local = [];
+      check(sub, value, pathLabel, local);
+      return local;
+    });
+    if (branches.every((local) => local.length > 0)) {
+      push(violations, pathLabel, "anyOf", "no variant matched");
+      for (const local of branches) violations.push(...local.map((v) => ({ ...v, rule: `anyOf:${v.rule}` })));
+    }
+  }
+}

package/src/kernel/state.mjs

@@ -0,0 +1,56 @@
+// State layout + state file accessors — CONTRACT §4. The layout is a
+// contract value; every consumer builds paths through layout().
+
+import path from "node:path";
+
+import { atomicWriteJson, CAP_CONFIG, readJsonCapped } from "./fsutil.mjs";
+
+export const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export const HEX64_RE = /^[0-9a-f]{64}$/;
+
+export function layout(stateHome) {
+  const waves = path.join(stateHome, "waves");
+  const receipts = path.join(stateHome, "receipts");
+  const locks = path.join(stateHome, "locks");
+  return {
+    stateHome,
+    ledger: path.join(stateHome, "ledger.jsonl"),
+    anchorState: path.join(stateHome, "anchor-state.json"),
+    locks,
+    ledgerLock: path.join(locks, "ledger.lock"),
+    waves,
+    receipts,
+    waveDir: (wave) => path.join(waves, wave),
+    metaFile: (wave) => path.join(waves, wave, "meta.json"),
+    cellsDir: (wave) => path.join(waves, wave, "cells"),
+    cellFile: (wave, id) => path.join(waves, wave, "cells", `${id}.json`),
+    leasesDir: (wave) => path.join(waves, wave, "leases"),
+    leaseDir: (wave, id) => path.join(waves, wave, "leases", id),
+    leaseLock: (wave, id) => path.join(waves, wave, "leases", id, "claim.lock"),
+    ownerFile: (wave, id) => path.join(waves, wave, "leases", id, "owner.json"),
+    leaseHistory: (wave, id) => path.join(waves, wave, "leases", id, "history.jsonl"),
+    receiptFile: (wave, id) => path.join(receipts, wave, `${id}.json`),
+  };
+}
+
+export async function readStateJson(filePath) {
+  const { value } = await readJsonCapped(filePath, CAP_CONFIG, "STATE-CORRUPT");
+  return value;
+}
+
+export async function writeStateJson(filePath, value) {
+  await atomicWriteJson(filePath, value);
+}
+
+export async function removeStateFile(filePath) {
+  const fs = await import("node:fs/promises");
+  await fs.rm(filePath, { force: true });
+}
+
+export async function readCell(sl, wave, id) {
+  return readStateJson(sl.cellFile(wave, id));
+}
+
+export async function writeCell(sl, wave, id, cell) {
+  await writeStateJson(sl.cellFile(wave, id), cell);
+}