@volter/supercode-orchestrator 0.5.224 → 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/files.mjs

@@ -12,7 +12,7 @@ import { fillReadableIds } from './readable-id.mjs';
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { fenced } from './fence.mjs';
 import { markRemovedHeads } from './published.mjs';
-import { CARD_NUMBERS, unnumberTasks } from './store.mjs';
+import { CARD_NUMBERS } from './store.mjs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
@@ -133,9 +133,6 @@ class FilesBoard {
     cards.sort((a, b) => madeAt(a) - madeAt(b) || (String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0));
     for (const card of cards) for (const [table, rows] of Object.entries(card.tables ?? {})) if (table !== CARD_NUMBERS) insert(table, rows);
     for (const [table, rows] of Object.entries(state?.tables ?? {})) insert(table, rows);
-    // A task whose file names no number keeps none: only cards are numbered.
-    unnumberTasks(mem, new Set(cards.filter((card) => card.tables?.[CARD_NUMBERS]?.length).map((card) => card.id)),
-      (state?.sequence ?? []).find((row) => row.name === CARD_NUMBERS)?.seq ?? 0);
     // Loading inserts every card, which marks every card changed (published.mjs). The first load of this projection keeps
     // those marks: its next write compares each card with its published head once (a named limit: each projection opened
     // compares every card once, as each load already reads every card's file). A reload keeps the marks not yet

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/board/store.mjs

@@ -370,18 +370,6 @@ function layOutNumbers(db) {
   } catch (error) { db.exec('ROLLBACK TO supercode_card_numbering; RELEASE supercode_card_numbering'); throw error; }
 }
 
-/** Only cards are numbered (VO-3578 row 22): a task's row (supercode_cards.subtask_of) is numbered by the insert trigger
- *  like any row, so a load gives each task's number back unless its source named it (`named`, task ids). The sequence
- *  returns to the highest number held, never below `floor` (what the source had already handed out). */
-export function unnumberTasks(db, named = new Set(), floor = 0) {
-  const taken = db.prepare(`SELECT n.task_id FROM ${CARD_NUMBERS} n JOIN supercode_cards c ON c.task_id = n.task_id WHERE c.subtask_of IS NOT NULL`).all()
-    .filter((row) => !named.has(row.task_id));
-  if (!taken.length) return;
-  const drop = db.prepare(`DELETE FROM ${CARD_NUMBERS} WHERE task_id = ?`);
-  for (const row of taken) drop.run(row.task_id);
-  db.prepare(`UPDATE sqlite_sequence SET seq = MAX(?, (SELECT COALESCE(MAX(number), 0) FROM ${CARD_NUMBERS})) WHERE name = ?`).run(Number(floor) || 0, CARD_NUMBERS);
-}
-
 /** Raise the numbers' high-water mark to the highest number held, and to `floor`: AUTOINCREMENT hands out only numbers
  *  above it. For a store whose numbers were given or copied explicitly. */
 export function raiseCardNumbers(db, floor = 0) {

package/board/ztrack.mjs

@@ -19,7 +19,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { actorOf, boardKey, CARD_NUMBERS, contention, raiseCardNumbers, unnumberTasks, event, json, now, principalOf, storageFault, STORAGE_TRIES, unreadable } from './store.mjs';
+import { actorOf, boardKey, CARD_NUMBERS, contention, raiseCardNumbers, event, json, now, principalOf, storageFault, STORAGE_TRIES, unreadable } from './store.mjs';
 import { GitDocument } from './git-document.mjs';
 import { unimported } from './legacy-store.mjs';
 import { noteStep, recordSlow } from '@volter/supercode-harness-sdk/slow-log';
@@ -462,14 +462,13 @@ class ZtrackBoard {
       put(`chunks:${role}`, entries);
     }
     put('published', published);
-    // The earlier store held no numbers: its cards take the numbers their documents' headings give them, and the other
-    // cards are numbered in the order they were made, after every number the documents name (documentNumbers); a task is not.
+    // The earlier store held no numbers: its cards take the numbers their documents' headings give them, and the rest
+    // are numbered in the order they were made, after every number the documents name (documentNumbers).
     db.exec(`DELETE FROM ${CARD_NUMBERS}; DELETE FROM sqlite_sequence WHERE name = '${CARD_NUMBERS}'`);
     const named = this.documentNumbers();
     this.numberFromHeadings([...named.headings].filter(([id]) => db.prepare('SELECT 1 FROM tasks WHERE id = ?').get(id)), db);
     raiseCardNumbers(db, named.highest);
-    db.exec(`INSERT INTO ${CARD_NUMBERS} (task_id) SELECT id FROM tasks WHERE id NOT IN (SELECT task_id FROM ${CARD_NUMBERS})
-      AND id NOT IN (SELECT task_id FROM supercode_cards WHERE subtask_of IS NOT NULL) ORDER BY created_at, id`);
+    db.exec(`INSERT INTO ${CARD_NUMBERS} (task_id) SELECT id FROM tasks WHERE id NOT IN (SELECT task_id FROM ${CARD_NUMBERS}) ORDER BY created_at, id`);
     db.exec('COMMIT');
   }
 
@@ -922,10 +921,6 @@ class ZtrackBoard {
       this.numberFromHeadings([...plan.numbers].filter(([id]) => plan.rows.has(id)));
       raiseCardNumbers(this.conn, this.documentNumbers().highest);
     }
-    // What is numbered before the cards load: a task the document or the store had numbered keeps it, and a task row the
-    // load inserts gives back the number the insert trigger hands it (only cards are numbered).
-    const numbered = overlay ? null : new Set(this.statement(`SELECT task_id FROM main.${CARD_NUMBERS}`).all().map((row) => row.task_id));
-    const handedOut = overlay ? 0 : this.one(`SELECT seq FROM main.sqlite_sequence WHERE name = '${CARD_NUMBERS}'`)?.seq ?? 0;
     for (const [id, rows] of plan.rows) {
       const before = fingerprintOf(id);
       const oldTask = this.one(`SELECT * FROM ${schema}.tasks WHERE id = ?`, id) ?? {};
@@ -944,7 +939,6 @@ class ZtrackBoard {
         events.push({ id, kind, payload: { by, source: 'document', status: after.status, assignee: after.assignee, author: by }, before, after });
       }
     }
-    if (!overlay) unnumberTasks(this.conn, numbered, handedOut);
     for (const id of plan.checked) this.errors.delete(id);
     for (const [id, reason] of plan.errors) this.errors.set(id, reason);
     // A read overlays new document cards before the owner commits them. Give that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.224",
+  "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.381",
+    "@volter/supercode-teams": "^0.3.382",
     "@volter/supercode-terminal": "^0.3.12",
     "@volter/supercode-harness-sdk": "^0.3.106",
     "@volter/teams": "0.2.106",