@volter/supercode-orchestrator 0.4.4

package/apply/state.mjs

@@ -0,0 +1,142 @@
+// The applier's own state (docs/plans/content-spec-status.md §7 "Base"): per home, what it owns —
+// each record's key, the harness's id, the declared values it applied, their normalized read-back,
+// and the last lifecycle it saw — plus the intents of creates in flight. It lives in the applier's
+// state directory, never in the harness's folder and never in a git checkout, with generations and a
+// lock. A home with no state file is plan-only until it is provisioned or adopted.
+
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { leaseIsLive, thisHost } from '../lease.mjs';
+
+export const STATE_VERSION = 1;
+/** Earlier generations kept beside the current state. */
+export const GENERATIONS = 5;
+
+/** Canonical JSON: keys sorted at every depth, so equal values hash equally. */
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).filter((k) => value[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+export function hash(value) {
+  return createHash('sha256').update(canonical(value)).digest('hex');
+}
+
+/** The applier's state root: `$XDG_STATE_HOME/supercode/apply`, else `~/.local/state/supercode/apply`. */
+export function stateRoot(env = process.env) {
+  return join(env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'supercode', 'apply');
+}
+
+function homeDir(root, homeId) {
+  if (!/^[A-Za-z0-9._-]{1,128}$/.test(String(homeId ?? ''))) throw new Error(`home id ${JSON.stringify(homeId)} must be 1-128 letters, digits, '.', '_' or '-'`);
+  return join(root, homeId);
+}
+
+/** The home's state, or null when the applier has none (plan-only). */
+export function readState(root, homeId) {
+  const file = join(homeDir(root, homeId), 'state.json');
+  if (!existsSync(file)) return null;
+  const state = JSON.parse(readFileSync(file, 'utf8'));
+  if (state.version !== STATE_VERSION) throw new Error(`${file}: apply state version ${state.version} is not ${STATE_VERSION}`);
+  return state;
+}
+
+/**
+ * Write the state. A new generation keeps the previous one as `state.<n>.json`
+ * (the oldest beyond GENERATIONS dropped); `{ generation: false }` rewrites the
+ * current one in place, which apply does after every verb so a crash loses no
+ * record, one generation per apply.
+ */
+export function writeState(root, homeId, state, { generation = true } = {}) {
+  const dir = homeDir(root, homeId);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = join(dir, 'state.json');
+  const next = { ...state, version: STATE_VERSION, generation: (state.generation ?? 0) + (generation ? 1 : 0) };
+  if (generation && existsSync(file)) {
+    const previous = JSON.parse(readFileSync(file, 'utf8'));
+    writeFileSync(join(dir, `state.${previous.generation ?? 0}.json`), JSON.stringify(previous, null, 2));
+    const old = readdirSync(dir).map((f) => /^state\.(\d+)\.json$/.exec(f)).filter(Boolean).map((m) => Number(m[1])).sort((a, b) => b - a);
+    for (const n of old.slice(GENERATIONS)) rmSync(join(dir, `state.${n}.json`), { force: true });
+  }
+  const tmp = join(dir, `state.json.${process.pid}.tmp`);
+  writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
+  renameSync(tmp, file);
+  return next;
+}
+
+/**
+ * Creates in flight, kept apart from the state so writing one is not a
+ * generation: each is written before the create's verb and cleared after its
+ * record reaches the state.
+ */
+export function readIntents(root, homeId) {
+  const file = join(homeDir(root, homeId), 'intents.json');
+  return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : [];
+}
+
+export function writeIntents(root, homeId, intents) {
+  const dir = homeDir(root, homeId);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = join(dir, 'intents.json');
+  const tmp = join(dir, `intents.json.${process.pid}.tmp`);
+  writeFileSync(tmp, JSON.stringify(intents, null, 2), { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+/** A record's durable data, captured before its delete, kept beside the state. */
+export function writeCapture(root, homeId, key, id, data) {
+  const dir = join(homeDir(root, homeId), 'captures');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = join(dir, `${String(key).replace(/[^A-Za-z0-9._-]/g, '_')}-${String(id).replace(/[^A-Za-z0-9._-]/g, '_')}-${Date.now()}.json`);
+  writeFileSync(file, JSON.stringify(data, null, 2), { mode: 0o600 });
+  return file;
+}
+
+/** Provisioning: an empty state, so the runtime's own home creates its declared records from the first apply. */
+export function provision(root, homeId) {
+  return readState(root, homeId) ?? writeState(root, homeId, { records: {}, generation: 0 });
+}
+
+/**
+ * One apply per home at a time: a lock file naming its holder. A lock whose
+ * holder is gone is stale; it is taken over under a takeover file only one
+ * taker can create, which re-checks the staleness before it replaces the lock.
+ */
+export function lock(root, homeId) {
+  const dir = homeDir(root, homeId);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = join(dir, 'lock');
+  const take = () => {
+    const fd = openSync(file, 'wx', 0o600);
+    // the holder's machine too: a home on a shared volume outlives the machine that locked it
+    writeFileSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString(), ...thisHost() }));
+    closeSync(fd);
+    return () => rmSync(file, { force: true });
+  };
+  const holder = () => { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } };
+  try { return take(); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const seen = holder();
+  if (seen && leaseIsLive(seen)) throw new Error(`home ${homeId} is being applied by pid ${seen.pid} since ${seen.at}`);
+  const takeover = `${file}.takeover`;
+  // a takeover whose taker died mid-way is itself stale after a minute
+  try { if (Date.now() - statSync(takeover).mtimeMs > 60_000) rmSync(takeover, { force: true }); } catch { /* none */ }
+  let fd;
+  try { fd = openSync(takeover, 'wx', 0o600); } catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`home ${homeId}: another process is taking over a stale lock (${takeover})`);
+    throw error;
+  }
+  try {
+    closeSync(fd);
+    const now = holder();
+    if (now && leaseIsLive(now)) throw new Error(`home ${homeId} is being applied by pid ${now.pid} since ${now.at}`);
+    rmSync(file, { force: true });
+    return take();
+  } finally {
+    rmSync(takeover, { force: true });
+  }
+}

package/bin/hermes-worker.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The command Hermes's board dispatcher runs as its worker when the orchestrator serves the home: the
+// loop sets `HERMES_BIN` to this file (docs/plans/hermes-compat.md row 14). Hermes's own argv and
+// environment; see `kanban-worker.mjs`.
+import { runKanbanWorker } from '../kanban-worker.mjs';
+
+// Hermes watches this pid: it exits the moment the turn is over, whatever handle is still open.
+process.exit(await runKanbanWorker(process.argv.slice(2), process.env).catch((error) => {
+  process.stdout.write(`hermes-worker: ${error.stack ?? error.message}\n`);
+  return 1;
+}));