@avee1234/worklease 0.1.1

package/src/registry.js

@@ -0,0 +1,233 @@
+// worklease — the append-only registry store.
+//
+// A registry is an append-only JSONL file (one JSON record per line). This
+// module is the single home for the store: a small set of *pure* functions
+// (canonical serialization, content-hash ids, log resolution) plus a thin I/O
+// layer (`appendRecord`, `loadRegistry`) that keeps every filesystem access in
+// one place. The design is deliberately lock-free — writes are single-line
+// `O_APPEND` writes, reads fold the whole log into the current claim array, and
+// every record self-identifies by a content hash, so concurrent or duplicated
+// appends resolve cleanly instead of conflicting. Node's built-in `crypto` is
+// the only "dependency"; there are zero runtime packages.
+
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// --- pure core -------------------------------------------------------------
+
+// canonicalize(record) → deterministic JSON string with sorted keys and no
+// incidental whitespace, over the record EXCLUDING its own `id`. Recurses so
+// key ordering can never perturb the digest at any depth. Used only as the hash
+// pre-image, so it does not need to round-trip to a value.
+export function canonicalize(record) {
+  const { id: _id, ...rest } = record;
+  return stableStringify(rest);
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  if (value !== null && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return (
+      "{" +
+      keys.map((k) => JSON.stringify(k) + ":" + stableStringify(value[k])).join(",") +
+      "}"
+    );
+  }
+  return JSON.stringify(value);
+}
+
+// computeRecordId(record) → the sha256 content hash of the record (its `id`
+// excluded). Deterministic and content-addressed: identical content ⇒ identical
+// id, so a duplicated append is idempotent on read and a tampered line no longer
+// matches its own id. `claim` (#2) uses this same helper so a claim's `id` IS its
+// content hash — one shared implementation across every record type.
+export function computeRecordId(record) {
+  return createHash("sha256").update(canonicalize(record)).digest("hex");
+}
+
+// shortId(id) → first 8 hex chars, the compact id `list` shows and `release`
+// accepts as a prefix.
+export function shortId(id) {
+  return typeof id === "string" ? id.slice(0, 8) : String(id);
+}
+
+// formatRelative(expires, now) → a short human relative expiry: "in 40s",
+// "in 12m", "in 3h", or "expired" (also "unknown" for an unparseable value).
+export function formatRelative(expires, now = Date.now()) {
+  const ms = Date.parse(expires);
+  if (Number.isNaN(ms)) return "unknown";
+  const delta = ms - now;
+  if (delta <= 0) return "expired";
+  const s = Math.round(delta / 1000);
+  if (s < 60) return `in ${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `in ${m}m`;
+  return `in ${Math.round(m / 60)}h`;
+}
+
+// listActive(claims) → the subset whose effective status is "active". Pure
+// selector kept here for direct unit testing.
+export function listActive(claims) {
+  return claims.filter((c) => c.status === "active");
+}
+
+// resolveRecords(records, { now, expire }) → { claims, notes }
+//
+// Folds an already-parsed append log (order = append order) into the current
+// claim array. Pure and total: `now` (epoch ms) is injected so expiry is
+// deterministic, and no bad field value throws. Nothing is written back — every
+// derived status is computed here at read time.
+//
+//   1. Integrity filter — drop any record whose `id` doesn't equal its own
+//      content hash (tamper/corruption), with a note. One bad line never
+//      discards the rest of the registry.
+//   2. Fold claims — latest claim record per `id` wins (content-addressed, so
+//      normally identical; tolerant of a re-append → idempotent).
+//   3. Apply releases — a `release` record moves its `claim_id` to `released`;
+//      an unknown `claim_id` is noted and ignored; a releaser who isn't the
+//      holder is noted (advisory ownership hint).
+//   4. Derive TTL expiry — an `active` claim whose `expires <= now` becomes
+//      effective status `expired` (derived, with a note); released claims stay
+//      released. Skipped when `expire` is false, so the stored claim state
+//      (active/released, no wall-clock decay) is returned — `conformance` needs
+//      this because it audits *after* short TTLs have elapsed and does its own
+//      temporal reasoning against each merge's `at`.
+//
+// Returns the claims sorted by `expires` ascending plus the collected notes.
+export function resolveRecords(records, opts = {}) {
+  const { now = Date.now(), expire = true } = opts;
+  const notes = [];
+
+  // 1. Integrity filter (also drops non-objects, which can't self-hash).
+  const valid = [];
+  records.forEach((r, i) => {
+    if (r === null || typeof r !== "object" || Array.isArray(r)) {
+      notes.push(`skipped record ${i}: not an object`);
+      return;
+    }
+    if (r.id !== computeRecordId(r)) {
+      notes.push(`skipped record ${i}: id/content mismatch`);
+      return;
+    }
+    valid.push(r);
+  });
+
+  // 2. Fold claims / collect releases (a record is a release iff type ===
+  //    "release"; a claim iff no type or type === "claim"; anything else is
+  //    forward-compat noise, skipped).
+  const claims = new Map();
+  const releases = [];
+  for (const r of valid) {
+    const type = r.type == null ? "claim" : r.type;
+    if (type === "claim") {
+      claims.set(r.id, { ...r });
+    } else if (type === "release") {
+      releases.push(r);
+    } else {
+      notes.push(`skipped record ${shortId(r.id)}: unknown type "${r.type}"`);
+    }
+  }
+
+  // 3. Apply releases.
+  for (const rel of releases) {
+    const claim = claims.get(rel.claim_id);
+    if (!claim) {
+      notes.push(`release for unknown claim_id ${shortId(rel.claim_id)} ignored`);
+      continue;
+    }
+    claim.status = "released";
+    claim.released_by = rel.agent;
+    claim.released_at = rel.at;
+    if (rel.agent !== claim.agent) {
+      notes.push(
+        `claim ${shortId(claim.id)} released by ${rel.agent}, held by ${claim.agent}`
+      );
+    }
+  }
+
+  // 4. Derive TTL expiry (a claim exactly at expires === now counts as expired).
+  for (const claim of expire ? claims.values() : []) {
+    if (claim.status === "active" && claim.expires != null) {
+      const exp = Date.parse(claim.expires);
+      if (!Number.isNaN(exp) && exp <= now) {
+        claim.status = "expired";
+        notes.push(`claim ${shortId(claim.id)} expired at ${claim.expires}`);
+      }
+    }
+  }
+
+  const resolved = [...claims.values()].sort(byExpires);
+  return { claims: resolved, notes };
+}
+
+// Sort by `expires` ascending; unparseable/absent expiries sort last, stably.
+function byExpires(a, b) {
+  const ea = Date.parse(a.expires);
+  const eb = Date.parse(b.expires);
+  const na = Number.isNaN(ea);
+  const nb = Number.isNaN(eb);
+  if (na && nb) return 0;
+  if (na) return 1;
+  if (nb) return -1;
+  return ea - eb;
+}
+
+// --- I/O layer -------------------------------------------------------------
+
+// defaultRegistryPath(cwd) → the ONE place the default registry location is
+// defined; `check`, `list`, and `release` all call it. `WORKLEASE_REGISTRY`
+// overrides, else a git-tracked `.worklease/registry.jsonl` at the repo root.
+export function defaultRegistryPath(cwd = process.cwd()) {
+  return process.env.WORKLEASE_REGISTRY || join(cwd, ".worklease", "registry.jsonl");
+}
+
+// appendRecord(path, record) → the stored record (with its content-hash `id`).
+// Assigns `id` if absent, creates the parent directory, then appends exactly one
+// JSON line terminated by "\n" with the `"a"` flag (O_APPEND). Existing lines are
+// never rewritten — this is the whole safety story. Used by `release` here and by
+// `claim` (#2).
+export function appendRecord(path, record) {
+  const stored = record.id ? record : { ...record, id: computeRecordId(record) };
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, JSON.stringify(stored) + "\n");
+  return stored;
+}
+
+// loadRegistry(path, { now, expire }) → { claims, notes }
+//
+// Reads the JSONL file (missing file → empty registry, no throw), parses each
+// non-blank line tolerantly (a line that won't parse is dropped with a note,
+// never aborting the load), and returns the resolved current registry via
+// `resolveRecords`. `expire` (default true) forwards to `resolveRecords`; pass
+// false to skip wall-clock TTL decay and see the stored claim state. Replaces
+// #3's interim reader.
+export function loadRegistry(path, opts = {}) {
+  const { now = Date.now(), expire = true } = opts;
+
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e && e.code === "ENOENT") return { claims: [], notes: [] };
+    throw e;
+  }
+
+  const parsed = [];
+  const parseNotes = [];
+  raw.split("\n").forEach((line, i) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    try {
+      parsed.push(JSON.parse(trimmed));
+    } catch {
+      parseNotes.push(`skipped unparseable line ${i + 1}`);
+    }
+  });
+
+  const resolved = resolveRecords(parsed, { now, expire });
+  return { claims: resolved.claims, notes: [...parseNotes, ...resolved.notes] };
+}

package/src/schema.js

@@ -0,0 +1,230 @@
+// worklease — claim + registry schema and validators.
+//
+// Pure, zero-dependency validators for the open `claim` shape and a registry
+// (array of claims). Neither function throws on bad input; both return
+// `{ valid, errors }` and collect *every* violation (no short-circuit) so a
+// harness or human can fix everything in one pass.
+//
+// Error = { path: string, code: string, message: string }
+//   path — dot/bracket path to the offending value ("globs[0]", "[2].ttl_seconds",
+//          or "" for the whole object).
+//   code — a stable machine-readable code from ERROR_CODES.
+//   message — one-line human explanation.
+
+export const STATUSES = ["active", "released", "expired"];
+
+// The exact set of allowed top-level claim fields, in canonical order.
+export const CLAIM_FIELDS = [
+  "id",
+  "agent",
+  "globs",
+  "intent",
+  "ttl_seconds",
+  "created",
+  "expires",
+  "status",
+];
+
+export const ERROR_CODES = {
+  MISSING_FIELD: "MISSING_FIELD",
+  UNKNOWN_FIELD: "UNKNOWN_FIELD",
+  WRONG_TYPE: "WRONG_TYPE",
+  NOT_OBJECT: "NOT_OBJECT",
+  NOT_ARRAY: "NOT_ARRAY",
+  EMPTY_STRING: "EMPTY_STRING",
+  EMPTY_ARRAY: "EMPTY_ARRAY",
+  INVALID_ENUM: "INVALID_ENUM",
+  NOT_POSITIVE_INT: "NOT_POSITIVE_INT",
+  INVALID_ISO8601: "INVALID_ISO8601",
+  EXPIRES_MISMATCH: "EXPIRES_MISMATCH",
+  INVALID_GLOB: "INVALID_GLOB",
+  DUPLICATE_ID: "DUPLICATE_ID",
+};
+
+// Strict ISO-8601 UTC: YYYY-MM-DDTHH:MM:SS(.sss)?Z. The regex gates the format
+// (UTC `Z` only, no offsets); Date.parse gates real-calendar validity so
+// impossible dates like 2026-13-40T00:00:00Z are rejected.
+const ISO8601_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+
+// Unsupported glob metacharacters for the documented v0.1 subset. Supported
+// tokens are `**`, `*`, `/`, and literal path characters; `? [ ] { }` are
+// rejected so a malformed glob is caught at claim time rather than silently
+// mis-matching later in `check`.
+const UNSUPPORTED_GLOB_CHARS = /[?[\]{}]/;
+
+export function isIso8601Utc(s) {
+  if (typeof s !== "string" || !ISO8601_UTC.test(s)) return false;
+  const ms = Date.parse(s);
+  if (Number.isNaN(ms)) return false;
+  // Date.parse silently rolls over impossible calendar dates (e.g.
+  // 2026-02-30 → Mar 2, 2026-04-31 → May 1) instead of returning NaN, so a
+  // format-valid but nonexistent date would slip through. Round-trip the
+  // parsed value and require the calendar portion to match the input.
+  return new Date(ms).toISOString().slice(0, 10) === s.slice(0, 10);
+}
+
+export function isAllowedGlob(s) {
+  return typeof s === "string" && s.length > 0 && !UNSUPPORTED_GLOB_CHARS.test(s);
+}
+
+function err(path, code, message) {
+  return { path, code, message };
+}
+
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+// Validate a single string field: present-ness is checked by the caller; here
+// we type/emptiness-check a value that exists.
+function checkStringField(errors, obj, field) {
+  const v = obj[field];
+  if (typeof v !== "string") {
+    errors.push(err(field, ERROR_CODES.WRONG_TYPE, `${field} must be a string`));
+  } else if (v.trim().length === 0) {
+    errors.push(err(field, ERROR_CODES.EMPTY_STRING, `${field} must not be empty`));
+  }
+}
+
+export function validateClaim(obj) {
+  // 1. Must be a non-null plain object.
+  if (!isPlainObject(obj)) {
+    return {
+      valid: false,
+      errors: [err("", ERROR_CODES.NOT_OBJECT, "claim must be a JSON object")],
+    };
+  }
+
+  const errors = [];
+
+  // 2. Required fields present.
+  for (const field of CLAIM_FIELDS) {
+    if (!(field in obj)) {
+      errors.push(err(field, ERROR_CODES.MISSING_FIELD, `${field} is required`));
+    }
+  }
+
+  // 3. Unknown top-level fields.
+  for (const key of Object.keys(obj)) {
+    if (!CLAIM_FIELDS.includes(key)) {
+      errors.push(err(key, ERROR_CODES.UNKNOWN_FIELD, `unknown field: ${key}`));
+    }
+  }
+
+  // 4. Per-field type/shape (only for fields that are present).
+  if ("id" in obj) checkStringField(errors, obj, "id");
+  if ("agent" in obj) checkStringField(errors, obj, "agent");
+  if ("intent" in obj) checkStringField(errors, obj, "intent");
+
+  if ("globs" in obj) {
+    const globs = obj.globs;
+    if (!Array.isArray(globs)) {
+      errors.push(err("globs", ERROR_CODES.WRONG_TYPE, "globs must be an array"));
+    } else if (globs.length === 0) {
+      errors.push(err("globs", ERROR_CODES.EMPTY_ARRAY, "globs must have at least one entry"));
+    } else {
+      globs.forEach((g, i) => {
+        if (typeof g !== "string") {
+          errors.push(err(`globs[${i}]`, ERROR_CODES.WRONG_TYPE, "glob must be a string"));
+        } else if (g.length === 0) {
+          errors.push(err(`globs[${i}]`, ERROR_CODES.EMPTY_STRING, "glob must not be empty"));
+        } else if (!isAllowedGlob(g)) {
+          errors.push(
+            err(
+              `globs[${i}]`,
+              ERROR_CODES.INVALID_GLOB,
+              "glob uses unsupported metacharacters (? [ ] { } are not allowed)"
+            )
+          );
+        }
+      });
+    }
+  }
+
+  if ("ttl_seconds" in obj) {
+    const t = obj.ttl_seconds;
+    if (typeof t !== "number" || !Number.isInteger(t) || t <= 0) {
+      errors.push(
+        err("ttl_seconds", ERROR_CODES.NOT_POSITIVE_INT, "ttl_seconds must be an integer > 0")
+      );
+    }
+  }
+
+  if ("created" in obj && !isIso8601Utc(obj.created)) {
+    errors.push(err("created", ERROR_CODES.INVALID_ISO8601, "created must be ISO 8601 UTC (…Z)"));
+  }
+  if ("expires" in obj && !isIso8601Utc(obj.expires)) {
+    errors.push(err("expires", ERROR_CODES.INVALID_ISO8601, "expires must be ISO 8601 UTC (…Z)"));
+  }
+
+  if ("status" in obj && !STATUSES.includes(obj.status)) {
+    errors.push(
+      err("status", ERROR_CODES.INVALID_ENUM, `status must be one of: ${STATUSES.join(", ")}`)
+    );
+  }
+
+  // 5. Cross-field: expires === created + ttl_seconds (only when all three are
+  // individually valid, so we don't pile a mismatch on top of a format error).
+  if (
+    isIso8601Utc(obj.created) &&
+    isIso8601Utc(obj.expires) &&
+    typeof obj.ttl_seconds === "number" &&
+    Number.isInteger(obj.ttl_seconds) &&
+    obj.ttl_seconds > 0
+  ) {
+    if (Date.parse(obj.expires) !== Date.parse(obj.created) + obj.ttl_seconds * 1000) {
+      errors.push(
+        err(
+          "expires",
+          ERROR_CODES.EXPIRES_MISMATCH,
+          "expires must equal created + ttl_seconds"
+        )
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function validateRegistry(arr) {
+  // 1. Must be an array.
+  if (!Array.isArray(arr)) {
+    return {
+      valid: false,
+      errors: [err("", ERROR_CODES.NOT_ARRAY, "registry must be a JSON array")],
+    };
+  }
+
+  const errors = [];
+
+  // 2. Per-element validation, re-prefixing each error path with [i].
+  arr.forEach((claim, i) => {
+    const result = validateClaim(claim);
+    for (const e of result.errors) {
+      const path = e.path === "" ? `[${i}]` : `[${i}].${e.path}`;
+      errors.push(err(path, e.code, e.message));
+    }
+  });
+
+  // 3. Duplicate id detection among structurally-valid claims. A duplicate id
+  // signals corruption or a double-append; flag every occurrence after the
+  // first at [i].id.
+  const seen = new Set();
+  arr.forEach((claim, i) => {
+    if (isPlainObject(claim) && isNonEmptyString(claim.id)) {
+      if (seen.has(claim.id)) {
+        errors.push(
+          err(`[${i}].id`, ERROR_CODES.DUPLICATE_ID, `duplicate id: ${claim.id}`)
+        );
+      } else {
+        seen.add(claim.id);
+      }
+    }
+  });
+
+  return { valid: errors.length === 0, errors };
+}