opencode-wait-a-minute 0.0.0-stage → 1.1.0-rc.8

package/src/state/state-schema.js

@@ -0,0 +1,318 @@
+// state-schema.js
+// JSON Schema validation for durable state documents with corruption detection
+// (hash + schema validation). No external dependencies — uses Node's built-in.
+
+import { createHash } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Schema registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal JSON Schema subset validator. Supports:
+ *  - type: "object" | "array" | "string" | "number" | "integer" | "boolean" | "null"
+ *  - properties (with required[])
+ *  - items
+ *  - enum, const, pattern (string regex), minLength, maxLength
+ *  - minimum, maximum
+ *  - additionalProperties: false
+ *  - oneOf, anyOf (shallow)
+ *
+ * Returns { valid: boolean, errors: [{ path, message }] }
+ */
+export function validateSchema(schema, value) {
+  const errors = [];
+  walk(schema, value, "", errors);
+  return { valid: errors.length === 0, errors };
+}
+
+function walk(schema, value, path, errors) {
+  if (schema === true) return;          // any value
+  if (schema === false) {
+    errors.push({ path, message: "schema disallows this value" });
+    return;
+  }
+  if (typeof schema !== "object" || schema === null) return;
+
+  // oneOf / anyOf (shallow — first match wins, otherwise collect all)
+  if (Array.isArray(schema.oneOf)) {
+    const matched = schema.oneOf.some((sub) => validateSchema(sub, value).valid);
+    if (!matched) errors.push({ path, message: "does not match any oneOf branch" });
+    return;
+  }
+  if (Array.isArray(schema.anyOf)) {
+    const matched = schema.anyOf.some((sub) => validateSchema(sub, value).valid);
+    if (!matched) errors.push({ path, message: "does not match any anyOf branch" });
+    return;
+  }
+
+  // const / enum
+  if (Object.prototype.hasOwnProperty.call(schema, "const")) {
+    if (!deepEqual(schema.const, value))
+      errors.push({ path, message: `expected const ${JSON.stringify(schema.const)}` });
+    return;
+  }
+  if (Array.isArray(schema.enum)) {
+    if (!schema.enum.some((v) => deepEqual(v, value)))
+      errors.push({ path, message: `expected one of ${JSON.stringify(schema.enum)}` });
+    return;
+  }
+
+  // type
+  if (schema.type) {
+    const actual = jsonType(value);
+    const expected = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!expected.includes(actual)) {
+      errors.push({
+        path,
+        message: `expected type ${expected.join("|")}, got ${actual}`,
+      });
+      return;
+    }
+  }
+
+  // string constraints
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength)
+      errors.push({ path, message: `string shorter than minLength ${schema.minLength}` });
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength)
+      errors.push({ path, message: `string longer than maxLength ${schema.maxLength}` });
+    if (schema.pattern) {
+      try {
+        if (!new RegExp(schema.pattern).test(value))
+          errors.push({ path, message: `does not match pattern ${schema.pattern}` });
+      } catch {
+        /* ignore bad regex */
+      }
+    }
+  }
+
+  // numeric constraints
+  if (typeof value === "number") {
+    if (typeof schema.minimum === "number" && value < schema.minimum)
+      errors.push({ path, message: `value below minimum ${schema.minimum}` });
+    if (typeof schema.maximum === "number" && value > schema.maximum)
+      errors.push({ path, message: `value above maximum ${schema.maximum}` });
+  }
+
+  // object
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+          errors.push({ path: joinPath(path, key), message: "missing required field" });
+      }
+    }
+    if (schema.properties) {
+      for (const [k, sub] of Object.entries(schema.properties)) {
+        if (Object.prototype.hasOwnProperty.call(value, k))
+          walk(sub, value[k], joinPath(path, k), errors);
+      }
+    }
+    if (schema.additionalProperties === false && schema.properties) {
+      for (const k of Object.keys(value)) {
+        if (!Object.prototype.hasOwnProperty.call(schema.properties, k))
+          errors.push({ path: joinPath(path, k), message: "additional property not allowed" });
+      }
+    }
+  }
+
+  // array
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => walk(schema.items, item, `${path}[${i}]`, errors));
+  }
+}
+
+function joinPath(base, key) {
+  if (!base) return String(key);
+  if (/^\d+$/.test(String(key))) return `${base}[${key}]`;
+  return `${base}.${key}`;
+}
+
+function jsonType(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  if (typeof v === "number" && Number.isInteger(v)) return "integer";
+  return typeof v;
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (Array.isArray(b)) return false;
+  const ka = Object.keys(a), kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual(a[k], b[k]));
+}
+
+// ---------------------------------------------------------------------------
+// Schemas for the five state surfaces defined in design.md
+// ---------------------------------------------------------------------------
+
+const commonEnvelope = {
+  type: "object",
+  required: ["stateVersion", "lastModifiedAt"],
+  properties: {
+    stateVersion: { type: "integer", minimum: 1 },
+    lastModifiedAt: { type: "string", minLength: 1 },
+  },
+  additionalProperties: false,
+};
+
+export const SCHEMAS = {
+  assessment: {
+    ...commonEnvelope,
+    properties: {
+      ...commonEnvelope.properties,
+      taskId: { type: "string", minLength: 1 },
+      summary: { type: "string" },
+      result: { enum: ["PASS", "FAIL", "WARN", "INCONCLUSIVE"] },
+      findings: {
+        type: "array",
+        items: {
+          type: "object",
+          required: ["path", "result"],
+          properties: {
+            path: { type: "string" },
+            result: { enum: ["PASS", "FAIL", "WARN", "INCONCLUSIVE"] },
+            reason: { type: "string" },
+          },
+        },
+      },
+    },
+    required: ["stateVersion", "lastModifiedAt", "taskId", "result"],
+  },
+
+  plan: {
+    ...commonEnvelope,
+    properties: {
+      ...commonEnvelope.properties,
+      planId: { type: "string", minLength: 1 },
+      taskId: { type: "string", minLength: 1 },
+      steps: {
+        type: "array",
+        items: {
+          type: "object",
+          required: ["id", "status"],
+          properties: {
+            id: { type: "string", minLength: 1 },
+            status: { enum: ["pending", "running", "done", "failed", "skipped"] },
+            description: { type: "string" },
+          },
+        },
+      },
+    },
+    required: ["stateVersion", "lastModifiedAt", "planId", "taskId", "steps"],
+  },
+
+  evidence: {
+    ...commonEnvelope,
+    properties: {
+      ...commonEnvelope.properties,
+      taskId: { type: "string", minLength: 1 },
+      stepId: { type: "string", minLength: 1 },
+      kind: { enum: ["file", "log", "metric", "snapshot"] },
+      contentHash: { type: "string", minLength: 1 },
+    },
+    required: ["stateVersion", "lastModifiedAt", "taskId", "stepId", "kind", "contentHash"],
+  },
+
+  completion: {
+    ...commonEnvelope,
+    properties: {
+      ...commonEnvelope.properties,
+      taskId: { type: "string", minLength: 1 },
+      status: { enum: ["complete", "incomplete", "blocked"] },
+      reportPath: { type: "string" },
+    },
+    required: ["stateVersion", "lastModifiedAt", "taskId", "status"],
+  },
+
+  drift: {
+    type: "object",
+    required: ["taskId", "lastModifiedAt", "entries"],
+    properties: {
+      taskId: { type: "string", minLength: 1 },
+      lastModifiedAt: { type: "string", minLength: 1 },
+      entries: {
+        type: "array",
+        items: {
+          type: "object",
+          required: ["ts", "kind"],
+          properties: {
+            ts: { type: "string", minLength: 1 },
+            kind: { enum: ["deviation", "correction", "warning"] },
+            note: { type: "string" },
+          },
+        },
+      },
+    },
+    additionalProperties: false,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Hash + corruption detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical JSON: stable key ordering so hashing is deterministic.
+ */
+export function canonicalJSON(value) {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(v) {
+  if (v === null || typeof v !== "object") return v;
+  if (Array.isArray(v)) return v.map(sortKeys);
+  const out = {};
+  for (const k of Object.keys(v).sort()) out[k] = sortKeys(v[k]);
+  return out;
+}
+
+/**
+ * Compute a SHA-256 hash of a state document payload (excluding the `_hash` itself).
+ */
+export function computeHash(payload) {
+  const { _hash, ...rest } = payload;
+  return createHash("sha256").update(canonicalJSON(rest)).digest("hex");
+}
+
+/**
+ * Wrap a payload with a `_hash` field that commits the canonical-JSON hash.
+ */
+export function seal(payload) {
+  const hash = computeHash(payload);
+  return { ...payload, _hash: hash };
+}
+
+/**
+ * Verify a sealed payload. Returns { valid, reason? }.
+ */
+export function verify(payload) {
+  if (!payload || typeof payload !== "object" || !("_hash" in payload))
+    return { valid: false, reason: "missing _hash field" };
+  const expected = payload._hash;
+  const actual = computeHash(payload);
+  if (expected !== actual) return { valid: false, reason: "hash mismatch (corruption detected)" };
+  return { valid: true };
+}
+
+/**
+ * Validate + verify a sealed payload. Returns { valid, errors, reason? }.
+ */
+export function validateSealed(schema, payload) {
+  const v = verify(payload);
+  if (!v.valid) return { valid: false, errors: [], reason: v.reason };
+  // _hash is metadata, strip it for schema check
+  const { _hash, ...data } = payload;
+  return { ...validateSchema(schema, data), reason: undefined };
+}
+
+export const STATE_TYPES = Object.keys(SCHEMAS);

package/src/state/state-store.js

@@ -0,0 +1,335 @@
+// state-store.js
+// Atomic writes (write-to-temp + rename), crash recovery (replay pending
+// journal), and GC (max journal entries, max snapshots).
+
+import { mkdir, rename, rm, stat, readFile, writeFile, readdir } from "node:fs/promises";
+import { dirname, join, basename } from "node:path";
+import { randomBytes } from "node:crypto";
+import {
+  SCHEMAS,
+  STATE_TYPES,
+  seal,
+  validateSchema,
+  validateSealed,
+} from "./state-schema.js";
+import { TransactionLog, replay } from "../persistence/transaction-log.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+/**
+ * Atomic write: write to a temp file in the same directory (so rename is on
+ * the same filesystem), fsync, then rename over the destination.
+ *
+ * Survives crashes mid-write: either the temp file exists (no effect on
+ * target) or the rename happened (target is fully written). Never torn.
+ */
+export async function atomicWrite(path, payload) {
+  await ensureDir(dirname(path));
+  const tmp = path + ".tmp." + randomBytes(6).toString("hex");
+  const data = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+  await writeFile(tmp, data);
+  await rename(tmp, path);
+}
+
+// ---------------------------------------------------------------------------
+// StateStore
+// ---------------------------------------------------------------------------
+
+/**
+ * StateStore — durable state with atomic writes, schema validation, and a
+ * crash-safe journal for replay.
+ *
+ * Layout:
+ *   <root>/state/<type>/<id>.json      — sealed state documents
+ *   <root>/journal.log                  — append-only transaction log
+ *   <root>/state-index.json             — lightweight index
+ *   <root>/quarantine/<type>/<id>.json  — files that failed validation
+ *   <root>/snapshots/<ts>.json          — periodic snapshots (for GC)
+ *
+ * @param {string} root  base directory for state
+ * @param {object} [opts]
+ * @param {number} [opts.maxJournalEntries=1000]  GC threshold for journal size
+ * @param {number} [opts.maxSnapshots=5]          GC threshold for snapshot count
+ * @param {number} [opts.retentionMs]             ms after which a state entry
+ *                                                is eligible for GC
+ */
+export class StateStore {
+  constructor(root, opts = {}) {
+    this.root = root;
+    this.maxJournalEntries = opts.maxJournalEntries ?? 1000;
+    this.maxSnapshots = opts.maxSnapshots ?? 5;
+    this.retentionMs = opts.retentionMs ?? null;
+    this.journal = new TransactionLog(join(root, "journal.log"));
+    this.indexPath = join(root, "state-index.json");
+    this._ready = this._init();
+  }
+
+  async _init() {
+    await ensureDir(this.root);
+    for (const t of STATE_TYPES) await ensureDir(join(this.root, "state", t));
+    await ensureDir(join(this.root, "quarantine"));
+    await ensureDir(join(this.root, "snapshots"));
+    // Reset index if missing/corrupt
+    try {
+      await this._loadIndex();
+    } catch {
+      await atomicWrite(this.indexPath, { entries: {} });
+    }
+  }
+
+  async _loadIndex() {
+    const raw = await readFile(this.indexPath, "utf8");
+    const idx = JSON.parse(raw);
+    if (!idx || typeof idx !== "object" || typeof idx.entries !== "object") {
+      throw new Error("index invalid");
+    }
+    this._index = idx;
+  }
+
+  async _saveIndex() {
+    await atomicWrite(this.indexPath, this._index ?? { entries: {} });
+  }
+
+  _pathFor(type, id) {
+    return join(this.root, "state", type, `${id}.json`);
+  }
+
+  _quarantinePathFor(type, id) {
+    return join(this.root, "quarantine", type, `${id}.json`);
+  }
+
+  /**
+   * Write a state document. Validates against the schema, seals with hash,
+   * writes atomically, then appends a journal entry.
+   *
+   * Returns { ok: true, entry } on success, { ok: false, errors } on failure.
+   */
+  async write(type, id, payload) {
+    await this._ready;
+    if (!STATE_TYPES.includes(type)) {
+      return { ok: false, errors: [{ path: "", message: `unknown state type: ${type}` }] };
+    }
+    const doc = {
+      ...payload,
+      stateVersion: (payload.stateVersion ?? 0) + 1,
+      lastModifiedAt: payload.lastModifiedAt ?? new Date().toISOString(),
+    };
+    const result = validateSchema(SCHEMAS[type], doc);
+    if (!result.valid) return { ok: false, errors: result.errors };
+
+    const sealed = seal(doc);
+
+    const path = this._pathFor(type, id);
+    await atomicWrite(path, sealed);
+
+    const journalEntry = await this.journal.append({
+      type,
+      taskId: id,
+      op: "set",
+      data: sealed,
+    });
+
+    // Update index
+    this._index = this._index ?? { entries: {} };
+    this._index.entries[`${type}:${id}`] = {
+      type,
+      id,
+      stateVersion: sealed.stateVersion,
+      lastModifiedAt: sealed.lastModifiedAt,
+      journalSeq: journalEntry.seq,
+    };
+    await this._saveIndex();
+
+    await this._maybeGC();
+    return { ok: true, entry: journalEntry };
+  }
+
+  /**
+   * Read a state document. Validates schema + hash. If validation fails,
+   * quarantines the file and returns { ok: false, reason }.
+   */
+  async read(type, id) {
+    await this._ready;
+    const path = this._pathFor(type, id);
+    let raw;
+    try {
+      raw = await readFile(path, "utf8");
+    } catch (e) {
+      if (e.code === "ENOENT") return { ok: false, reason: "not_found" };
+      throw e;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      await this._quarantine(type, id, raw);
+      return { ok: false, reason: "json_parse_error" };
+    }
+    const v = validateSealed(SCHEMAS[type], parsed);
+    if (!v.valid) {
+      await this._quarantine(type, id, raw);
+      return { ok: false, reason: v.reason ?? "schema_invalid", errors: v.errors };
+    }
+    return { ok: true, data: parsed };
+  }
+
+  async _quarantine(type, id, raw) {
+    const qp = this._quarantinePathFor(type, id);
+    await ensureDir(dirname(qp));
+    await atomicWrite(qp, raw ?? "");
+    try {
+      await rm(this._pathFor(type, id));
+    } catch {
+      /* ignore */
+    }
+  }
+
+  async list(type) {
+    await this._ready;
+    const dir = join(this.root, "state", type);
+    let files;
+    try {
+      files = await readdir(dir);
+    } catch (e) {
+      if (e.code === "ENOENT") return [];
+      throw e;
+    }
+    return files.filter((f) => f.endsWith(".json")).map((f) => basename(f, ".json"));
+  }
+
+  /**
+   * Recover after a crash. Replays the journal, rehydrating the in-memory
+   * state map. Any journal entries that lack a corresponding state file are
+   * re-applied from the journal data.
+   *
+   * Returns { rehydrated, orphans, corrupted }.
+   */
+  async recover() {
+    await this._ready;
+    const entries = await this.journal.readAll();
+    const { applied, skipped, finalState } = replay(entries);
+
+    // For each applied entry, ensure the state file exists (write if missing).
+    let rehydrated = 0;
+    let orphans = 0;
+    for (const { key } of applied) {
+      const [type, id] = key.split(":");
+      const data = finalState[key];
+      const path = this._pathFor(type, id);
+      let exists = true;
+      try {
+        await stat(path);
+      } catch {
+        exists = false;
+      }
+      if (!exists) {
+        await atomicWrite(path, data);
+        rehydrated++;
+      }
+    }
+    // Skipped entries with _corrupt are quarantined into a sidecar file so
+    // the recovery operator can inspect them later.
+    const corrupted = skipped.filter((s) => s && s._corrupt);
+    if (corrupted.length) {
+      const sidecar = join(this.root, "quarantine", "journal-corrupt.json");
+      await ensureDir(dirname(sidecar));
+      await atomicWrite(sidecar, JSON.stringify(corrupted, null, 2));
+      orphans = corrupted.length;
+    }
+    return { rehydrated, orphans, corrupted };
+  }
+
+  /**
+   * Garbage collection.
+   *  - If journal entries > maxJournalEntries: snapshot the live state, then
+   *    truncate the journal.
+   *  - If snapshots > maxSnapshots: prune the oldest.
+   *  - If retentionMs is set: delete state entries whose lastModifiedAt is
+   *    older than (now - retentionMs).
+   */
+  async gc() {
+    await this._ready;
+    const journalSize = await this.journal.size();
+
+    // Journal compaction: if oversized, take a snapshot then truncate.
+    if (journalSize > this.maxJournalEntries) {
+      await this._snapshot();
+      await this.journal.truncate();
+    }
+
+    // Snapshot pruning: keep only the newest maxSnapshots.
+    const snapDir = join(this.root, "snapshots");
+    let snaps = [];
+    try {
+      snaps = await readdir(snapDir);
+    } catch {
+      /* ignore */
+    }
+    snaps = snaps.filter((f) => f.endsWith(".json")).sort();
+    while (snaps.length > this.maxSnapshots) {
+      const oldest = snaps.shift();
+      await rm(join(snapDir, oldest), { force: true });
+    }
+
+    // Retention-based eviction.
+    let evicted = 0;
+    if (this.retentionMs != null) {
+      const cutoff = Date.now() - this.retentionMs;
+      for (const type of STATE_TYPES) {
+        const dir = join(this.root, "state", type);
+        let files = [];
+        try {
+          files = await readdir(dir);
+        } catch {
+          continue;
+        }
+        for (const f of files) {
+          if (!f.endsWith(".json")) continue;
+          const full = join(dir, f);
+          try {
+            const raw = await readFile(full, "utf8");
+            const data = JSON.parse(raw);
+            const ts = Date.parse(data?.lastModifiedAt ?? "");
+            if (!Number.isFinite(ts)) continue;
+            if (ts < cutoff) {
+              await rm(full);
+              evicted++;
+            }
+          } catch {
+            /* skip unreadable */
+          }
+        }
+      }
+    }
+    return { journalCompacted: journalSize > this.maxJournalEntries, evicted };
+  }
+
+  async _maybeGC() {
+    // Cheap heuristic: only check journal size periodically.
+    if ((this._gcCounter = (this._gcCounter ?? 0) + 1) % 50 === 0) {
+      await this.gc();
+    }
+  }
+
+  async _snapshot() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const snapPath = join(this.root, "snapshots", `${stamp}.json`);
+    const entries = {};
+    for (const type of STATE_TYPES) {
+      const ids = await this.list(type);
+      for (const id of ids) {
+        const r = await this.read(type, id);
+        if (r.ok) entries[`${type}:${id}`] = r.data;
+      }
+    }
+    await atomicWrite(snapPath, { takenAt: new Date().toISOString(), entries });
+  }
+}
+
+export { TransactionLog, replay };