@volter/supercode-orchestrator 0.5.223 → 0.5.225

package/board/cli.mjs

@@ -35,6 +35,7 @@ import * as slowLog from '@volter/supercode-harness-sdk/slow-log';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir, userInfo } from 'node:os';
+import { storageContract } from './storage-contract.mjs';
 import { boardKey, cardRef, actorOf, CALLER_RUN_ADDRESS, CALLER_RUN_AGENT, SESSION_CURRENT_RUNS, SESSION_RUNS, sessionIndexed, heldConfigWatched, heldDocumentsChanged, heldDocumentsWatched, holdBoards, retireHeldBoards, releaseHeldBoards, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardCopyOf, boardPath, briefPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
 import { isLocalWorkspace } from './workspace.mjs';
 import { openZtrackBoard } from './ztrack.mjs';
@@ -1970,11 +1971,9 @@ export async function serveBoardGeneration(root, args = {}, argv = ['serve', '--
   };
   const disconnected = () => { stopDispatching(); process.exit(1); };
   process.on('message', receive); process.once('disconnect', disconnected);
-  // A transition cannot restore database files over committed card writes. Refuse a storage-code change
-  // until a compatible migration has its own protocol; retained generations must use the same storage contract.
-  const storage = createHash('sha256');
-  for (const file of ['store.mjs', 'files.mjs', 'ztrack.mjs', 'published.mjs']) storage.update(file).update(readFileSync(new URL(file, import.meta.url)));
-  tellOwner({ type: 'prepared', storage: storage.digest('hex') });
+  // A transition cannot restore database files over committed card writes: retained generations must write the same
+  // storage format (storage-contract.mjs), and a format change waits for a compatible migration with its own protocol.
+  tellOwner({ type: 'prepared', ...storageContract() });
   try { await activation; return await runVerb(argv); }
   finally { process.off('message', receive); process.off('disconnect', disconnected); unwatchHealth(); unwatchWorkflow(); }
 }

package/board/generation-owner.mjs

@@ -199,7 +199,10 @@ export async function serveBoardOwner(root, args) {
     const candidate = start(selected);
     try {
       const proof = await candidate.wait('prepared'), held = active.events.get('prepared');
-      if (!proof.storage || proof.storage !== held?.storage) throw new Error('board storage contract differs; predecessor retained without opening a writer');
+      // Both generations name their format (storage-contract.mjs): the formats are compared. A generation from before
+      // `format` names only its storage modules' source, which is then compared.
+      const same = proof.format && held?.format ? proof.format === held.format : Boolean(proof.storage) && proof.storage === held?.storage;
+      if (!same) throw new Error('board storage contract differs; predecessor retained without opening a writer');
       pending = { id, candidate, predecessor: active, older: previous, phase: 'prepared' };
       return status();
     } catch (error) { await terminate(candidate); throw error; }

package/board/storage-contract.mjs

@@ -0,0 +1,85 @@
+// The board's storage contract, which a retained handover compares between predecessor and candidate (ADR 0080,
+// generation-owner.mjs prepare). A rollback leaves the predecessor serving what the candidate wrote, so the two must
+// write the same format.
+// - `format` fails closed. It is the SQL every backing lays out, as SQLite records it once the layout has run on an
+//   empty database, and the whole source of the four storage modules except what a format cannot depend on: their
+//   import lines, whole-line comments, blank lines, and the members named in READS, which decide how a store is read or
+//   which rows a load keeps and write no format. Any other change to those modules moves it, a writer or anything a
+//   writer reads (the property sets, a file name, a number's form) alike.
+// - `storage` is the earlier contract, the modules' whole source. An owner from before `format` compares it alone, so a
+//   candidate keeps sending it; an owner that knows `format` compares that when both generations send one.
+// `format` is null when a member READS names occurs more than once (the owner then compares `storage`).
+import { createHash } from 'node:crypto';
+import fs, { readFileSync } from 'node:fs';
+import { syncBuiltinESMExports } from 'node:module';
+import { DatabaseSync } from 'node:sqlite';
+import { layOut } from './store.mjs';
+
+const MODULES = ['store.mjs', 'files.mjs', 'ztrack.mjs', 'published.mjs'];
+// Members that only read a store or choose which rows a load keeps (VO-3578 row 22's #2328 changed these): a change to
+// one keeps the format. A member joins this list only when what it writes is rows of the laid-out tables, never a file,
+// a document's text or a JSON shape.
+const READS = {
+  'store.mjs': ['unnumberTasks'],
+  'files.mjs': ['load'],
+  'ztrack.mjs': ['applyPlan', 'importRuntime'],
+};
+
+const source = (file) => readFileSync(new URL(file, import.meta.url), 'utf8');
+// A member's lines in its module: from its first line (`  name(` in a class, `function name(` or `const name =` at the
+// top) to the line that closes it at the same indent, or that line alone when it ends the member. None when absent.
+function without(text, name) {
+  const lines = text.split('\n'), opens = new RegExp(`^(?:  (?:async )?${name}\\(|(?:export )?(?:async )?function ${name}\\(|(?:export )?const ${name} = )`);
+  const starts = lines.flatMap((line, i) => opens.test(line) ? [i] : []);
+  if (starts.length > 1) throw new Error(`${name} is more than one member of its module`);
+  if (!starts.length) return text;
+  const [start] = starts, first = lines[start].trimEnd(), indent = /^ */.exec(first)[0];
+  const end = first.endsWith(';') ? start : lines.findIndex((line, i) => i > start && line === `${indent}}`);
+  if (end < 0) throw new Error(`${name} has no closing line`);
+  return [...lines.slice(0, start), ...lines.slice(end + 1)].join('\n');
+}
+// What a format cannot depend on: import statements, lines that are only a comment, and blank lines.
+function code(text) {
+  const kept = [];
+  let importing = false;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (importing || /^import\s/.test(trimmed)) { importing = !/;\s*$/.test(trimmed); continue; }
+    if (!trimmed || /^(\/\/|\/\*|\*)/.test(trimmed)) continue;
+    kept.push(line);
+  }
+  return kept.join('\n');
+}
+
+// The layout's one-time migration notices (store.mjs writes them to stderr with writeSync) describe a real store; on
+// this empty one they would put 'holds the owner event loop' lines in the board's log at every generation start. The
+// layout is synchronous, so for its call alone a stderr line that starts 'board: ' is dropped; writeSync is restored
+// before anything else runs.
+function quietly(work) {
+  const writeSync = fs.writeSync;
+  fs.writeSync = (fd, text, ...rest) => (fd === 2 && typeof text === 'string' && text.startsWith('board: ') ? text.length : writeSync(fd, text, ...rest));
+  syncBuiltinESMExports();
+  try { return work(); } finally { fs.writeSync = writeSync; syncBuiltinESMExports(); }
+}
+
+function format() {
+  const db = new DatabaseSync(':memory:');
+  try {
+    quietly(() => layOut(db, { fresh: true }));
+    const ztrack = source('ztrack.mjs'), opens = ztrack.indexOf('const BOARD_TABLES = `');
+    if (opens < 0) throw new Error('ztrack.mjs has no BOARD_TABLES');
+    db.exec(ztrack.slice(ztrack.indexOf('`', opens) + 1, ztrack.indexOf('`;', opens)));
+    const layout = db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY type, name, tbl_name").all()
+      .map(({ type, name, tbl_name: table, sql }) => [type, name, table, sql]);
+    const modules = MODULES.map((file) => [file, code((READS[file] ?? []).reduce(without, source(file)))]);
+    return createHash('sha256').update(JSON.stringify({ layout, modules })).digest('hex');
+  } finally { db.close(); }
+}
+
+export function storageContract() {
+  const storage = createHash('sha256');
+  for (const file of MODULES) storage.update(file).update(readFileSync(new URL(file, import.meta.url)));
+  let formatDigest = null;
+  try { formatDigest = format(); } catch (error) { process.stderr.write(`board storage contract: no format digest (${error.message}); the owner compares storage\n`); }
+  return { storage: storage.digest('hex'), format: formatDigest };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.223",
+  "version": "0.5.225",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -36,7 +36,7 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.380",
+    "@volter/supercode-teams": "^0.3.382",
     "@volter/supercode-terminal": "^0.3.12",
     "@volter/supercode-harness-sdk": "^0.3.106",
     "@volter/teams": "0.2.106",