@volter/supercode-orchestrator 0.5.20 → 0.5.21

package/board/dispatch.mjs

@@ -15,7 +15,7 @@
 // Every side effect follows a committed transition: a card is claimed before its session is launched, and a
 // subscriber's cursor moves only after its notice was delivered, so two dispatchers over one board never both
 // launch and a crash between the two steps is answered by the next tick.
-import { monitorsRuns, failedObservation, surfaceIncident, auditEndedRuns } from './incidents.mjs';
+import { monitorsRuns, failedObservation, surfaceIncident, auditEndedRuns, originOf } from './incidents.mjs';
 import { readEventFleet } from './event-fleet.mjs';
 let eventFleetRoot = null;
 import { inspectCompletionEvidence, noCodeChange, openReviewPullRequests, reviewDue, withCompletionEvidence, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
@@ -616,7 +616,7 @@ function startCards(board, fleet, lanes, settings, report, entry, effects, { onl
       }
     } catch (error) {
       if (error.launchPending) { report.queued.push([task.id, error.message]); continue; }
-      const payload = { error: String(error.message).slice(-500), ...(error.resumeFailed ? { resume_failed: true, ...error.resumeFailed } : {}) };
+      const payload = { error: String(error.message).slice(-500), origin: originOf(error), ...(error.resumeFailed ? { resume_failed: true, ...error.resumeFailed } : {}) };
       try { const r = tx(board, db => monitorsRuns(entry) ? (surfaceIncident(db,board,entry,task.id,'spawn_failed',payload), {effects:[]}) : fire(db, board, entry, task.id, 'spawn_failed', { roles: ['platform'], payload })); effects.push(...r.effects); } catch { /* no transition for it */ }
       report.failed.push([task.id, String(error.message).slice(-300)]);
     }
@@ -741,7 +741,7 @@ export async function startCard(board, id, { roles = ['manager'], lanes, setting
   if (!lane) return null;
   try { return launchRun(board,entry,id,lane,fleet,settings); }
   catch (error) {
-    if (monitorsRuns(entry) && !error.launchPending) tx(board,db=>surfaceIncident(db,board,entry,id,'spawn_failed',{error:error.message}));
+    if (monitorsRuns(entry) && !error.launchPending) tx(board,db=>surfaceIncident(db,board,entry,id,'spawn_failed',{error:error.message,origin:originOf(error)}));
     throw error;
   }
 }
@@ -1205,7 +1205,7 @@ function reconcileLaunches(board, fleet, report, entry, effects, settings, lanes
       if(session)report.started.push([id,session.address??session.session_id,session.mode]);
     }catch(error){
       if(error.launchPending){report.queued.push([id,error.message]);continue;}
-      const moved=tx(board,db=>monitorsRuns(entry)?(surfaceIncident(db,board,entry,id,'spawn_failed',{error:error.message}),{effects:[]}):fire(db,board,entry,id,'spawn_failed',{roles:['platform'],payload:{error:error.message}}));effects.push(...moved.effects);
+      const moved=tx(board,db=>monitorsRuns(entry)?(surfaceIncident(db,board,entry,id,'spawn_failed',{error:error.message,origin:originOf(error)}),{effects:[]}):fire(db,board,entry,id,'spawn_failed',{roles:['platform'],payload:{error:error.message}}));effects.push(...moved.effects);
       report.failed.push([id,error.message]);
     }
   }

package/board/engine.mjs

@@ -12,7 +12,7 @@ import { existsSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspace } from './workspace.mjs';
 import { DatabaseSync } from 'node:sqlite';
-import { view, actorOf, principalOf, claimer, event, json, newTaskId, now, tx } from './store.mjs';
+import { view, actorOf, principalOf, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
 import { completionPhase, inspectCompletionEvidence, observeCompletionEvidence, withCompletionEvidence } from './ci.mjs';
 import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 
@@ -148,8 +148,9 @@ function projectOf(root, idOrSlug) {
   if (!existsSync(file)) return null;
   const db = new DatabaseSync(file, { readOnly: true });
   try {
-    return db.prepare('SELECT id, slug, name, primary_path FROM projects WHERE id = ?').get(idOrSlug)
-      ?? db.prepare('SELECT id, slug, name, primary_path FROM projects WHERE slug = ?').get(String(idOrSlug).toLowerCase()) ?? null;
+    // another process writing the registry is waited out, never read as "no such project"
+    return retryContention(() => db.prepare('SELECT id, slug, name, primary_path FROM projects WHERE id = ?').get(idOrSlug)
+      ?? db.prepare('SELECT id, slug, name, primary_path FROM projects WHERE slug = ?').get(String(idOrSlug).toLowerCase()) ?? null);
   } catch { return null; } finally { db.close(); }
 }
 
@@ -511,15 +512,20 @@ function stopWorker(board, runId) {
  */
 export function recomputeReady(board, effects = [], errors = []) {
   const entry = workflowFor(board.root);
-  return tx(board, (db) => {
+  // what the moves ask for is handed on only once the write commits: a retried write starts its lists again
+  const { moved, asked, failed } = tx(board, (db) => {
+    const asked = [], failed = [];
     let moved = 0;
     for (const { id } of all(db, "SELECT id FROM tasks WHERE status NOT IN ('done', 'archived')")) {
       const before = statusOf(db, getTask(db, id));
-      try { settle(db, board, entry, id, effects); } catch (error) { errors.push([id, String(error.message).slice(-300)]); continue; }
+      // another writer's commit is the whole write's to retry, never one card's failure
+      try { settle(db, board, entry, id, asked); } catch (error) { if (contention(error)) throw error; failed.push([id, String(error.message).slice(-300)]); continue; }
       if (statusOf(db, getTask(db, id)) !== before) moved += 1;
     }
-    return moved;
+    return { moved, asked, failed };
   });
+  effects.push(...asked); errors.push(...failed);
+  return moved;
 }
 
 // Hermes's invalidate_descendants_for_parent_reopen: every descendant that moved on because of the reopened card

package/board/event-stream.mjs

@@ -47,7 +47,7 @@ export async function* followBoardPublications({root,after,signal}) {
       const paths=backingPaths(root,slug);
       file(paths.sqlite);file(`${paths.sqlite}-wal`);file(paths.ztrack);stores.push(paths.sqlite,`${paths.sqlite}-wal`);
       directory(paths.files,name=>name.endsWith('.json'));
-      try {const cfg=JSON.parse(readFileSync(paths.ztrack,'utf8'));const document=resolve(dirname(paths.ztrack),cfg.document);file(document);file(`${document}.archive.md`);}catch{/* other backing */}
+      try {const cfg=JSON.parse(readFileSync(paths.ztrack,'utf8'));const document=resolve(dirname(paths.ztrack),cfg.document);file(document);const own=basename(document);directory(dirname(document),name=>name===`${own}.archive.md`||(name.startsWith(`${own}.archive-`)&&name.endsWith('.md')));}catch{/* other backing */}
     }
   };
   const aborted=()=>wake?.();signal?.addEventListener('abort',aborted);

package/board/incidents.mjs

@@ -3,6 +3,10 @@ import { event, json, now } from './store.mjs';
 import { statusOf, creatorOf } from './workflow.mjs';
 
 export const monitorsRuns = entry => entry?.params?.run_failure_policy !== 'retry';
+// Where a thrown failure came from: its first frames, with paths from the package root, kept as the incident's
+// evidence so a bare message ("database is locked") still names the statement's caller.
+export const originOf = (error) => String(error?.stack ?? '').split('\n').filter((line) => /^\s+at /.test(line)).slice(0, 5)
+  .map((line) => line.trim().replace(/\((?:file:\/\/)?[^()]*\/(orchestrator\/|teams\/|volter-teams\/)/, '($1'));
 export const failedObservation = name => ['exited', 'session_closed', 'session_lost', 'spawn_failed', 'orphaned', 'timed_out', 'stale'].includes(name);
 
 export function surfaceIncident(db, board, entry, id, name, evidence = {}, runId = null) {

package/board/store.mjs

@@ -189,7 +189,7 @@ export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing
       break;
     } catch (error) {
       try { db.exec('ROLLBACK'); } catch {}
-      if (!/locked|busy/i.test(error.message)) throw error;
+      if (!contention(error)) throw error;
     }
   }
   return { db, root, slug, path, backing: use, tx: (fn) => sqliteTx(db, fn), close: () => db.close() };
@@ -204,18 +204,25 @@ export const tx = (board, fn) => {
   signalBoardWrite(board.root, actor);
   return result;
 };
-// A read that meets another process's write is retried as a write is (sqliteTx): a dispatcher service and a CLI share
-// the board, and a lost read must not become a launch failure. Inside a transaction its retry is the transaction's.
+// SQLite's own contention (BUSY, LOCKED, and their extended codes) and nothing else: a refusal whose words happen to
+// say "blocked" or "busy" reaches its caller at once instead of being retried forever.
+export const contention = (error) => [5, 6].includes(Number(error?.errcode) & 255)
+  || ['SQLITE_BUSY', 'SQLITE_LOCKED'].includes(error?.code)
+  || /^database (?:table |schema )?is locked$/i.test(error?.message ?? '');
 const pause = new Int32Array(new SharedArrayBuffer(4));
-export const view = (board, fn) => {
-  for (;;) {
-    try { return fn(board.db); }
+/** Run `fn` until it answers without meeting another process's write (a short, randomized wait between tries). */
+export function retryContention(fn) {
+  for (let attempt = 0; ; attempt++) {
+    try { return fn(); }
     catch (error) {
-      if (inTx.has(board.db) || !/locked|busy/i.test(error.message)) throw error;
-      Atomics.wait(pause, 0, 0, 10);
+      if (!contention(error)) throw error;
+      Atomics.wait(pause, 0, 0, Math.min(40, 2 ** Math.min(attempt, 5)) * (0.5 + Math.random()));
     }
   }
-};
+}
+// A read that meets another process's write is retried as a write is (sqliteTx): a dispatcher service and a CLI share
+// the board, and a lost read must not become a launch failure. Inside a transaction its retry is the transaction's.
+export const view = (board, fn) => inTx.has(board.db) ? fn(board.db) : retryContention(() => fn(board.db));
 
 // A deferred native transaction, with the whole operation retried on an optimistic conflict.
 // There is no separate application writer lock or contention timeout. A write inside one is part of it.
@@ -231,7 +238,8 @@ function sqliteTx(db, fn) {
       return out;
     } catch(error) {
       try {db.exec('ROLLBACK');} catch {}
-      if (!/locked|busy/i.test(error.message))throw error;
+      if (!contention(error))throw error;
+      Atomics.wait(pause, 0, 0, 1 + Math.random() * 20);
     } finally { inTx.delete(db); }
   }
 }

package/board/wake.mjs

@@ -74,7 +74,9 @@ export function watchBoard({ root, binary, env, log = () => {} }) {
         const config = JSON.parse(readFileSync(join(dir, 'ztrack.json'), 'utf8'));
         const document = resolve(dir, config.document);
         file(document, `document:${document}`);
-        file(`${document}.archive.md`, `document:${document}.archive.md`);
+        // the current archive and each rotated one (`<document>.archive-<date>.md`)
+        const own = basename(document);
+        directory(dirname(document), `document:${document}.archive`, name => name === `${own}.archive.md` || (name.startsWith(`${own}.archive-`) && name.endsWith('.md')));
       } catch { /* other backing or not yet created */ }
     }
     const config = env.SUPERCODE_HOME || (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, 'supercode') : join(env.HOME ?? '', '.config', 'supercode'));

package/board/ztrack.mjs

@@ -12,7 +12,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, linkSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { actorOf, event, json, now, principalOf, setActor } from './store.mjs';
+import { actorOf, contention, event, json, now, principalOf, retryContention, setActor } from './store.mjs';
 import { GitDocument } from './git-document.mjs';
 import { noteStep, recordSlow } from '@volter/supercode-harness-sdk/slow-log';
 
@@ -39,12 +39,13 @@ const atomic = (path, text) => { const tmp = `${path}.${process.pid}.tmp`; write
 const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 const backoff = (attempt) => sleep(Math.min(40, 2 ** Math.min(attempt, 5)) * (0.5 + Math.random()));
 
-// Only SQLite's actual contention codes retry (BUSY, BUSY_SNAPSHOT, LOCKED). Rule refusals can
-// contain words such as "blocked" or "busy" and must reach the caller unchanged.
-const sqliteContention = error => [5, 6].includes(Number(error?.errcode) & 255)
-  || ['SQLITE_BUSY', 'SQLITE_LOCKED'].includes(error?.code)
-  || /^database (?:table |schema )?is locked$/i.test(error?.message ?? '');
+// Only SQLite's actual contention codes retry (store.mjs `contention`). Rule refusals can contain words such as
+// "blocked" or "busy" and must reach the caller unchanged.
+const sqliteContention = (error) => contention(error); // resolved at call time: store.mjs and this module import each other
 const RETRY = new Error('board changed while this operation read it; retry');
+// The current archive's size before it rotates, unless the board declares its own (`archive.max_lines`).
+const ARCHIVE_LINES = 2000;
+const isArchive = (role) => role === 'archived' || String(role ?? '').startsWith('archived:');
 
 const BOARD_TABLES = `
 CREATE TABLE IF NOT EXISTS board_state (key TEXT PRIMARY KEY, value TEXT NOT NULL);
@@ -75,16 +76,20 @@ export function openZtrackBoard(marker, { create = false, document = null, seed
 const behindSaid = new Set();
 
 class ZtrackBoard {
-  constructor({ document, seed, marker, init, root, slug, compatPath, commit = false, manager = null }) {
+  constructor({ document, seed, marker, init, root, slug, compatPath, commit = false, manager = null, archive = {} }) {
     this.path = resolve(dirname(marker), document);
     this.archive = `${this.path}.archive.md`;
-    this.docs = [{ role: 'open', path: this.path }, { role: 'archived', path: this.archive }];
+    this.baseDocs = [{ role: 'open', path: this.path }, { role: 'archived', path: this.archive }];
+    // The current archive rotates (`"archive": {"max_lines": N, "period": "month"}` in the board's ztrack.json): past
+    // its size, or once its period has turned, its whole text moves into `<document>.archive-<date>.md`, which stays a
+    // document of the board. Retention: rotated archives are kept, checked in beside the board.
+    this.rotation = { lines: Number(archive.max_lines) > 0 ? Number(archive.max_lines) : ARCHIVE_LINES, period: archive.period === 'month' ? 'month' : null };
     // `"commit": true` in the board's ztrack.json: the documents live in a git checkout, and each write is committed as
     // its doer and pushed, after taking what was pushed (git-document.mjs; company RFC 0025 decision 3).
     // `"manager"`: the board's manager (its principal or session address), whose writes it commits itself as part of its
     // own work; the backing commits only the writes the manager does not make.
     this.manager = manager;
-    this.git = commit ? new GitDocument([this.path, this.archive], (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
+    this.git = commit ? new GitDocument(this.baseDocs.map((doc) => doc.path), (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
     // A publish that is behind is said once per process, on whichever workflow verb opened the board: a refused push
     // surfaces on the next call instead of only in the dispatcher's report, and stops being said once the push lands.
     if (this.git && !behindSaid.has(this.path)) {
@@ -115,14 +120,22 @@ class ZtrackBoard {
           get: (...args) => self.read(() => self.statement(sql).get(...args)),
           all: (...args) => self.read(() => self.statement(sql).all(...args)),
           iterate: (...args) => self.read(() => self.statement(sql).all(...args))[Symbol.iterator](),
-          run: (...args) => self.active ? self.statement(sql).run(...args) : self.tx(() => self.statement(sql).run(...args)),
+          run: (...args) => self.active ? self.noting(() => self.statement(sql).run(...args)) : self.tx(() => self.statement(sql).run(...args)),
         };
       },
-      exec(sql) { return self.active ? self.conn.exec(sql) : self.tx(() => self.conn.exec(sql)); },
+      exec(sql) { return self.active ? self.noting(() => self.conn.exec(sql)) : self.tx(() => self.conn.exec(sql)); },
       close() { self.close(); },
     };
     if (seed) this.tx(() => {});
   }
+  // The board's documents: the open one, the current archive, and each rotated archive (recorded in the board's own
+  // state, so a rotation committed but not yet written is still a document of the board).
+  get docs() {
+    let rotated = [];
+    try { rotated = this.conn ? this.get('archives', []) : []; } catch { rotated = []; }
+    // recorded by file name, beside the document, so a board moved with its documents still finds them
+    return [...this.baseDocs, ...rotated.map(({ role, name }) => ({ role, path: resolve(dirname(this.path), name) }))];
+  }
   get codec() { return this._codec ??= require('@volter/ztrack/board-document'); }
   get preset() { return this._preset ??= require('@volter/ztrack/kanban-preset'); }
   board() { return { root: this.root, slug: this.slug, label: this.slug, db: this.db }; }
@@ -295,8 +308,14 @@ class ZtrackBoard {
 
   // ------------------------------------------------------------------ reads
 
+  // A statement inside a write that meets another writer marks the write: whatever the body does with the error (a
+  // per-card catch that reports it and moves on), the write retries whole instead of committing what is left.
+  noting(fn) {
+    try { return fn(); } catch (error) { if (sqliteContention(error)) this.contended = true; throw error; }
+  }
+
   read(fn) {
-    if (this.active) return fn();
+    if (this.active) return this.noting(fn);
     this.observeForRead();
     for (let attempt = 0; ; attempt++) {
       try { return fn(); } catch (error) { if (!sqliteContention(error)) throw error; backoff(attempt); }
@@ -350,16 +369,18 @@ class ZtrackBoard {
     // A write inside a write is part of it: the pull below happened once, for the outermost one.
     if (this.active) return fn(this.db);
     // A pull request merged on the remote (a page edited in Git Notes) is in the document before this write reads it.
+    if (this.git) this.git.paths = this.docs.map((doc) => doc.path);
     try { timedStep('board git pull', () => this.git?.pull()); } catch (error) { process.stderr.write(`board: ${error.message}\n`); }
     let txStarted = 0;
     for (let attempt = 0; ; attempt++) {
-      const hermes = this.seed ? null : this.prepareHermes();
-      this.dropOverlay();
-      let outcome;
+      let outcome, hermes = null;
       try {
         txStarted = performance.now();
+        // Reading Hermes's export meets its writer (another process exporting) as contention, retried with the write.
+        hermes = this.seed ? null : this.prepareHermes();
+        this.dropOverlay();
         this.conn.exec('BEGIN');
-        this.active = true;
+        this.active = true; this.contended = false;
         this.conn.exec('DELETE FROM temp.board_dirty; DELETE FROM temp.board_touched');
         this.refused = new Set();
         this.loadErrors();
@@ -373,6 +394,7 @@ class ZtrackBoard {
         if (this.seed) this.seedRows(); else this.lift(hermes);
         this.snapshotHeld();
         const result = fn(this.db);
+        if (this.contended) throw RETRY;
         const files = this.render();
         this.statement('INSERT INTO main.board_export (name, key) SELECT DISTINCT name, key FROM temp.board_dirty WHERE true ON CONFLICT(name, key) DO UPDATE SET rev = rev + 1').run();
         const intent = files.length ? randomBytes(16).toString('hex') : null;
@@ -398,6 +420,7 @@ class ZtrackBoard {
         this.publish(outcome);
         // Committed as the session (or person) whose act this write was, and pushed.
         const byManager = this.manager !== null && (actorOf() === this.manager || principalOf() === this.manager);
+        if (this.git) this.git.paths = this.docs.map((doc) => doc.path);
         if (!byManager) try { timedStep('board git commit and push', () => this.git?.commit(actorOf(), `board: ${outcome.files.map((file) => basename(file.path)).join(', ')} written for ${actorOf() ?? 'the board'}`)); }
         catch (error) { process.stderr.write(`board: ${error.message}\n`); }
       }
@@ -773,10 +796,11 @@ class ZtrackBoard {
     const held = [...parents].filter((id) => !this.refused.has(id) && heldBy(id));
     if (held.length) { this.applyPlan(this.observe([], held), { overlay: false }); parents = cardsTouched(); }
     if (this.seedIds) for (const id of this.seedIds) parents.add(id);
-    const layout = { open: this.entries('open'), archived: this.entries('archived') };
+    const roles = this.docs.map((doc) => doc.role);
+    const layout = Object.fromEntries(roles.map((role) => [role, this.entries(role)]));
     const where = new Map();
-    for (const role of ['open', 'archived']) layout[role].forEach((entry, index) => { if (entry.id) where.set(nativeId(entry.id), { role, index, entry }); });
-    const edits = { open: [], archived: [] };
+    for (const role of roles) layout[role].forEach((entry, index) => { if (entry.id) where.set(nativeId(entry.id), { role, index, entry }); });
+    const edits = Object.fromEntries(roles.map((role) => [role, []]));
     for (const id of parents) {
       if (heldBy(id)) continue;
       const task = this.one('SELECT * FROM main.tasks WHERE id = ?', id);
@@ -784,7 +808,9 @@ class ZtrackBoard {
       if (task && state.subtask_of) continue;
       const at = where.get(id);
       if (!task) { if (at) edits[at.role].push({ index: at.index, remove: true }); continue; }
-      const role = state.archived || ['done', 'cancelled'].includes(state.stage ?? task.status) ? 'archived' : 'open';
+      // An ended card stays in the archive that holds it (a rotated one included); one that newly ends goes to the current.
+      const ended = state.archived || ['done', 'cancelled'].includes(state.stage ?? task.status);
+      const role = !ended ? 'open' : isArchive(at?.role) ? at.role : 'archived';
       // Its ended subtasks: each its own entry in the archive document while the card is open (the open document lists
       // only what is still to do); back in the card's own text once the card has ended.
       for (const sub of this.statement('SELECT t.* FROM main.tasks t JOIN main.supercode_cards s ON s.task_id = t.id WHERE s.subtask_of = ?').all(id)) {
@@ -793,12 +819,13 @@ class ZtrackBoard {
         if (role !== 'open' || !ENDED.has(subState.stage ?? sub.status)) { if (subAt) edits[subAt.role].push({ index: subAt.index, remove: true }); continue; }
         const subRecord = this.subtaskRecord(sub.id, sub, subState, id, where);
         const subRec = hash(JSON.stringify(subRecord));
-        if (subAt?.role === 'archived' && subAt.entry.rec === subRec) continue;
+        const kept = isArchive(subAt?.role);
+        if (kept && subAt.entry.rec === subRec) continue;
         let subText;
-        try { subText = this.codec.renderBoardCard(subRecord, subAt?.role === 'archived' ? subAt.entry.level : 2, this.docOf('archived').path); }
+        try { subText = this.codec.renderBoardCard(subRecord, kept ? subAt.entry.level : 2, this.docOf(kept ? subAt.role : 'archived').path); }
         catch (error) { this.errors.set(sub.id, error.message); continue; }
-        const subEntry = { cid: null, id: subRecord.id, level: subAt?.role === 'archived' ? subAt.entry.level : 2, len: subText.length, rec: subRec, text: subText };
-        if (subAt?.role === 'archived') edits.archived.push({ index: subAt.index, entry: subEntry });
+        const subEntry = { cid: null, id: subRecord.id, level: kept ? subAt.entry.level : 2, len: subText.length, rec: subRec, text: subText };
+        if (kept) edits[subAt.role].push({ index: subAt.index, entry: subEntry });
         else { if (subAt) edits[subAt.role].push({ index: subAt.index, remove: true }); edits.archived.push({ entry: subEntry }); }
       }
       const record = this.recordOf(id, task, state, where);
@@ -818,7 +845,7 @@ class ZtrackBoard {
     }
     const files = [];
     const published = this.get('published', {});
-    for (const role of ['open', 'archived']) {
+    for (const role of roles) {
       if (!edits[role].length) continue;
       const doc = this.docOf(role);
       const current = this.fileHash(doc.path);
@@ -854,10 +881,38 @@ class ZtrackBoard {
       files.push({ role, path: doc.path, before: current.hash, after: hash(text), base: lf(current.raw), text });
       published[role] = hash(text);
     }
-    if (files.length) this.put('published', published);
+    if (files.length) { this.rotate(files, published); this.put('published', published); }
     return files;
   }
 
+  // Past its declared size, or once its period has turned, the current archive's whole text and index move into a new
+  // dated archive document, and the current one starts empty. Part of the same write: retried, rolled back or
+  // recovered with it.
+  rotate(files, published) {
+    const current = files.find((file) => file.role === 'archived');
+    const text = current ? current.text : lf(this.fileHash(this.archive).raw);
+    const entries = this.entries('archived');
+    const started = this.get('archive_started', null);
+    const at = new Date();
+    if (started === null) this.put('archive_started', Math.floor(at.getTime() / 1000));
+    const turned = this.rotation.period === 'month' && started !== null && new Date(started * 1000).toISOString().slice(0, 7) !== at.toISOString().slice(0, 7);
+    if (!entries.length || !text || (text.split('\n').length <= this.rotation.lines && !turned)) return;
+    const archives = this.get('archives', []);
+    const day = at.toISOString().slice(0, 10);
+    let suffix = day;
+    for (let n = 2; archives.some((doc) => doc.role === `archived:${suffix}`) || existsSync(`${this.path}.archive-${suffix}.md`); n++) suffix = `${day}-${n}`;
+    const role = `archived:${suffix}`, path = `${this.path}.archive-${suffix}.md`;
+    this.put(`chunks:${role}`, entries);
+    this.put('chunks:archived', []);
+    this.put('archives', [...archives, { role, name: basename(path) }]);
+    this.put('archive_started', Math.floor(at.getTime() / 1000));
+    files.push({ role, path, before: hash(''), after: hash(text), base: '', text });
+    if (current) Object.assign(current, { after: hash(''), text: '' });
+    else { const was = this.fileHash(this.archive); files.push({ role: 'archived', path: this.archive, before: was.hash, after: hash(''), base: lf(was.raw), text: '' }); }
+    published[role] = hash(text);
+    published.archived = hash('');
+  }
+
   // The document record of card `id`, from its rows and its subtasks' rows.
   recordOf(id, row, c, where) {
     const fileId = (x) => where.get(x)?.entry.id ?? x;
@@ -1064,7 +1119,8 @@ class ZtrackBoard {
     let compat;
     try {
       compat = new DatabaseSync(this.compatPath, { readOnly: true });
-      return compat.prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name IN ('tasks', 'task_events')").get().n === 2;
+      // a moment of another process's export is not an absent export
+      return retryContention(() => compat.prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name IN ('tasks', 'task_events')").get().n) === 2;
     } catch { return false; } finally { compat?.close(); }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.20",
+  "version": "0.5.21",
   "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": {