@volter/supercode-orchestrator 0.4.154 → 0.4.156

package/board/ci.mjs

@@ -180,6 +180,31 @@ export function openReviewPullRequests(board, id) {
   return { pr: prs.map((p) => p.url), pr_head: prs.map((p) => p.head), branch };
 }
 
+/** An arc that changed no code (a disposition, such as closing a PR with its reason): its work branch holds no commit
+ *  beyond its repository's default branch, locally or on origin, its checkout holds no uncommitted work, no PR was
+ *  ever opened from it, and it registered no other branch. Answers what its review reads instead of a diff, or null when the arc carries (or may carry) code. */
+export function noCodeChange(board, id) {
+  const own = repositoryWorkspace(board, id);
+  if (!own) return null;
+  try {
+    const repository = originOf(own);
+    const task = board.db.prepare('SELECT branch_name FROM tasks WHERE id=?').get(id);
+    const branch = task?.branch_name ?? (run('git', ['branch', '--show-current'], own) || null);
+    const base = run('git', ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], own);
+    if (!repository || !branch || !base || branch === base.replace(/^origin\//, '')) return null;
+    if (registeredBranches(board, id).some((r) => r.repository !== repository || r.branch !== branch)) return null;
+    // Uncommitted work in the checkout is code not yet committed: a dirty worktree is never no-code.
+    if (run('git', ['status', '--porcelain', '--untracked-files=normal'], own)) return null;
+    // An unknown local or remote commit is code this checkout cannot see: run() throws and the arc waits.
+    if (run('git', ['for-each-ref', '--format=%(refname)', `refs/heads/${branch}`], own)) run('git', ['merge-base', '--is-ancestor', `refs/heads/${branch}`, base], own);
+    const remote = run('git', ['ls-remote', 'origin', `refs/heads/${branch}`], own).split(/\s+/)[0];
+    if (remote) run('git', ['merge-base', '--is-ancestor', remote, base], own);
+    const owner = repository.split('/')[0];
+    if (github(`/repos/${repository}/pulls?state=all&head=${encodeURIComponent(`${owner}:${branch}`)}&per_page=1`).length) return null;
+    return { pr: [], pr_head: [], branch, no_code: { repository, branch, base, branch_head: remote || null } };
+  } catch { return null; }
+}
+
 /** The repositories this machine keeps a checkout of. */
 function knownRepositories() {
   try { return [...new Set(branchCheckouts(null, '*').map((row) => row.repository))]; } catch { return []; }

package/board/cli.mjs

@@ -756,8 +756,11 @@ export async function runWorkflow(argv) {
       const params = { ...(args['failure-limit'] ? { failure_limit: Number(args['failure-limit']) } : {}), ...(args.max ? { max_spawn: Number(args.max) } : {}) };
       if (args['dry-run']) {
         // planned through the workflow's own dispatch (its start event, eligible, order and limits), writing nothing
-        const would = (await plan({ root, lanes, settings, params, slugs: [slug] })).flatMap((r) => r.would);
-        say(args, would.length ? would.map((w) => `would start ${w.id} (${w.status}${w.role ? `, its ${w.role}` : ''}) as ${w.surface} for ${w.assignee}${w.machine ? ` on ${w.machine}` : ''}`).join('\n') : 'nothing would start', would);
+        const reports = await plan({ root, lanes, settings, params, slugs: [slug] });
+        const would = reports.flatMap((r) => r.would), reviews = reports.flatMap((r) => r.would_review ?? []);
+        const lines = [...reviews.map((r) => `would request review of ${r.id}: ${r.no_code ? `no code changed (${r.no_code.repository} ${r.no_code.branch} holds no commit beyond ${r.no_code.base}, no PR from it)` : r.prs.map((url, i) => `${url} at ${r.heads[i]}`).join(', ')}`),
+          ...would.map((w) => `would start ${w.id} (${w.status}${w.role ? `, its ${w.role}` : ''}) as ${w.surface} for ${w.assignee}${w.machine ? ` on ${w.machine}` : ''}`)];
+        say(args, lines.length ? lines.join('\n') : 'nothing would start', args.json ? { would, would_review: reviews } : would);
         return 0;
       }
       const reports = await tick({ root, lanes, settings, params });

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 { inspectCompletionEvidence, openReviewPullRequests, reviewDue, withCompletionEvidence, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
+import { inspectCompletionEvidence, noCodeChange, openReviewPullRequests, reviewDue, withCompletionEvidence, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
 import { createRequire } from 'node:module';
 import { spawn as spawnChild, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -1848,15 +1848,30 @@ export async function plan({ root, lanes, settings, slugs = null, params = {} })
   for (const slug of slugs ?? listBoards(root)) {
     const report = { board: slug, would: [], queued: [], unassigned: [], nonspawnable: [] };
     const board = openBoard(root, slug);
-    try { board.label = boardLabel(root, slug); startCards(board, fleet, lanes, settings, report, entry, [], { dry: true }); } finally { board.close(); }
+    try {
+      board.label = boardLabel(root, slug);
+      await activatePullRequestReviews(board, entry, report, [], { dry: true });
+      startCards(board, fleet, lanes, settings, report, entry, [], { dry: true });
+    } finally { board.close(); }
     out.push(report);
   }
   return out;
 }
 
+/** Whether an arc with no open PR may be one that changed no code and is due its review: it filed and closed tasks
+ *  (a fresh arc with none has not started), and no review of it is pending or passed (after changes are requested,
+ *  closing the tasks that own the findings makes it due again). */
+function noCodeReviewDue(board, id) {
+  return view(board, (db) => {
+    if (!db.prepare('SELECT 1 FROM supercode_cards WHERE subtask_of = ? LIMIT 1').get(id)) return false;
+    const last = db.prepare("SELECT kind FROM task_events WHERE task_id = ? AND kind IN ('review_requested', 'changes_requested', 'review_pass') ORDER BY id DESC LIMIT 1").get(id);
+    return !last || last.kind === 'changes_requested';
+  });
+}
+
 /** An opened PR asks for the declared review transition once the arc's tasks are closed. */
 // A task written in the card's own Tasks section that did not become a subtask holds its review too.
-async function activatePullRequestReviews(board, entry, report, effects, { only = null } = {}) {
+async function activatePullRequestReviews(board, entry, report, effects, { only = null, dry = false } = {}) {
   const candidates = view(board, db => db.prepare(`SELECT t.id FROM tasks t JOIN supercode_cards c ON c.task_id=t.id
     WHERE c.subtask_of IS NULL AND c.every IS NULL
     AND t.workspace_kind!='scratch' ${only ? 'AND t.id=?' : ''}`).all(...(only ? [only] : [])));
@@ -1879,20 +1894,26 @@ async function activatePullRequestReviews(board, entry, report, effects, { only
       payload = openReviewPullRequests(board, id);
       // The arc's open PRs ask for one review only while some head has no verdict: after changes are
       // requested the next run is the implementer's, until a new head is pushed.
+      // An arc that closed its tasks having changed no code gets its one review of the act itself (ADR 0003).
+      if (!payload && noCodeReviewDue(board, id)) payload = noCodeChange(board, id);
       if (!payload) { report.queued.push([id, 'review waits: no open PR on its branch, a wt/<card> branch or a registered checkout']); continue; }
       if (payload.waits) { report.queued.push([id, `review waits: ${payload.waits}`]); payload = null; continue; }
-      if (!reviewDue(board, id, payload.pr.map((url, index) => ({ url, head: payload.pr_head[index] })))) {
+      if (!payload.no_code && !reviewDue(board, id, payload.pr.map((url, index) => ({ url, head: payload.pr_head[index] })))) {
         report.queued.push([id, `review waits: every open PR head (${payload.pr.join(', ')}) has a verdict or predates the last one; push a commit that answers it`]);
         continue;
       }
-      const evidence = inspectCompletionEvidence(board, id, entry, payload, 'request_review');
+      const evidence = payload.no_code ? { required: false, ready: true, reason: null, phase: 'source', no_code: payload.no_code } : inspectCompletionEvidence(board, id, entry, payload, 'request_review');
       if (!evidence.ready) throw new Error(evidence.reason);
+      // a dry run names the review a tick would request and writes nothing
+      if (dry) { (report.would_review ??= []).push({ id, prs: payload.pr, heads: payload.pr_head, no_code: payload.no_code ?? null }); continue; }
       refreshCardInputs(board, id, { commits: true });
       const moved = tx(board, db => {
         const task = getTask(db, id);
         if (eligible(db) !== true) return null;
         return withCompletionEvidence(board, id, evidence, () => fire(db, board, entry, id, 'request_review', {
-          roles: ['platform'], payload: { ...payload, run_id: task.current_run_id, summary: `Opened ${payload.pr.map((url, index) => `${url} at ${payload.pr_head[index]}`).join(', ')}`, ci: evidence }
+          roles: ['platform'], payload: { ...payload, run_id: task.current_run_id, ci: evidence, summary: payload.no_code
+            ? `No code changed: ${payload.no_code.repository} ${payload.branch} holds no commit beyond ${payload.no_code.base} and no PR was opened from it. Review the arc's act from the card: its comments, its tasks' results and what they point at.`
+            : `Opened ${payload.pr.map((url, index) => `${url} at ${payload.pr_head[index]}`).join(', ')}` }
         }));
       });
       if (moved) {

package/board/ztrack.mjs

@@ -78,7 +78,7 @@ class ZtrackBoard {
     this.conn = new DatabaseSync(this.file);
     this.refuseUnimported(legacy);
     this.errors = new Map(); this.statements = new Map(); this.hashes = new Map();
-    this.active = false; this.overlay = false; this.seen = null;
+    this.active = false; this.overlay = false; this.seen = null; this.refused = new Set();
     this.prepareConnection();
     this.loadErrors();
     const self = this;
@@ -330,6 +330,7 @@ class ZtrackBoard {
         this.conn.exec('BEGIN');
         this.active = true;
         this.conn.exec('DELETE FROM temp.board_dirty; DELETE FROM temp.board_touched');
+        this.refused = new Set();
         this.loadErrors();
         this.recover();
         if (this.seed) this.indexForSeed();
@@ -339,6 +340,7 @@ class ZtrackBoard {
         }
         if (hermes && hermes.cursor !== this.get('hermes_cursor', 0)) throw RETRY;
         if (this.seed) this.seedRows(); else this.lift(hermes);
+        this.snapshotHeld();
         const result = fn(this.db);
         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();
@@ -417,8 +419,9 @@ class ZtrackBoard {
 
   // What the edited documents now say, as a plan of rows; applied to the tables by a write, to
   // connection-local copies by a read. Only the spans the edit touched are parsed.
-  observe(stale) {
-    const plan = { layout: new Map(), dropped: [], published: {}, cards: new Map(), rows: new Map(), subtasks: new Map(), tasks: new Map(), remove: new Set(), errors: new Map(), checked: new Set() };
+  // `held` names cards read again from their indexed span with no edit (see render).
+  observe(stale, held = []) {
+    const plan = { layout: new Map(), dropped: [], published: {}, cards: new Map(), rows: new Map(), subtasks: new Map(), tasks: new Map(), remove: new Set(), errors: new Map(), checked: new Set(), before: new Map() };
     const changed = new Set();
     for (const doc of this.docs) {
       const entries = this.entries(doc.role);
@@ -436,9 +439,11 @@ class ZtrackBoard {
       plan.dropped.push(...replaced.map((e) => e.cid));
       plan.published[doc.role] = edit.hash;
       for (const c of [...added, ...replaced]) if (c.id) changed.add(nativeId(c.id));
+      for (const c of replaced) if (c.id) plan.before.set(nativeId(c.id), { role: doc.role, entry: c });
     }
     const places = new Map();
     for (const [role, entries] of plan.layout) for (const entry of entries) if (entry.id) places.set(nativeId(entry.id), [...(places.get(nativeId(entry.id)) ?? []), { role, entry }]);
+    for (const id of held) { changed.add(id); const at = places.get(id); if (at?.length === 1) plan.before.set(id, at[0]); }
     for (const id of changed) {
       plan.checked.add(id);
       const at = places.get(id) ?? [];
@@ -469,7 +474,8 @@ class ZtrackBoard {
     const keyed = new Map([...plan.tasks].map(([tid, { key }]) => [key, tid]));
     const resolveRef = (ref) => keyed.get(ref) ?? this.one('SELECT id FROM main.board_tasks WHERE key = ?', ref)?.id ?? ref;
     for (const rows of plan.rows.values()) rows.state.blocked_by = JSON.stringify(json(rows.state.blocked_by, []).map((b) => ({ ...b, id: resolveRef(b.id) })));
-    this.checkControls(plan);
+    if (held.length) this.keepMoved(plan);
+    this.checkControls(plan, resolveRef);
     // A refused task line refuses its card's edit: the hand text stays in the document with the reason, never
     // re-rendered without the line.
     for (const [id, subtasks] of plan.subtasks) {
@@ -485,6 +491,35 @@ class ZtrackBoard {
     return plan;
   }
 
+  // The rows of every card held by a recorded refusal (with its subtasks) before this write's verb runs, so a held
+  // card read again after it keeps what the verb moved (keepMoved).
+  snapshotHeld() {
+    this.heldRows = new Map();
+    const cards = new Set();
+    for (const id of this.errors.keys()) cards.add(this.one('SELECT subtask_of FROM main.supercode_cards WHERE task_id = ?', id)?.subtask_of ?? id);
+    for (const card of cards) {
+      for (const { task_id: id } of [{ task_id: card }, ...this.statement('SELECT task_id FROM main.supercode_cards WHERE subtask_of = ?').all(card)]) {
+        this.heldRows.set(id, { task: this.one('SELECT * FROM main.tasks WHERE id = ?', id) ?? null, state: this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', id) ?? null });
+      }
+    }
+  }
+
+  // A held card's span is older than this write: every column the write's verb moved keeps the store's value
+  // (title, body, assignee, status, ...); the span's text lands only where the store did not move.
+  keepMoved(plan) {
+    const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+    for (const [id, rows] of plan.rows) {
+      const task = this.one('SELECT * FROM main.tasks WHERE id = ?', id), state = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', id);
+      if (!task) continue;
+      const was = this.heldRows?.get(id);
+      for (const [side, now, then] of [['task', task, was?.task], ['state', state, was?.state]]) {
+        if (!now) continue;
+        // A row the write created has nothing held to keep: all of it is the store's.
+        for (const key of Object.keys(now)) if (!then || !same(now[key], then[key])) rows[side][key] = now[key];
+      }
+    }
+  }
+
   planRemoval(plan, id) {
     const task = this.one('SELECT current_run_id FROM main.tasks WHERE id = ?', id);
     if (!task) return;
@@ -495,7 +530,10 @@ class ZtrackBoard {
 
   // A raw edit cannot authenticate its author: the workflow's controlled fields change only through
   // role-checked verbs. The first import of a document has nothing to compare with.
-  checkControls(plan) {
+  // A controlled value the edit left as the replaced span said it is no edit but a stale line (the store moved
+  // while its card was not rendered, as under a recorded refusal): it takes the store's value, and the card's
+  // render writes that back into its lines (t_f3f102db).
+  checkControls(plan, resolveRef) {
     if (!this.one('SELECT 1 FROM main.tasks LIMIT 1')) return;
     let fields = [];
     try { fields = workflowFor(this.root).params.document_control_fields ?? []; } catch { /* no home policy */ }
@@ -504,13 +542,46 @@ class ZtrackBoard {
       : field === 'blocked_by' ? json(state?.blocked_by, []).map((b) => [b.kind, b.id]).sort()
       : field === 'paused' ? json(state?.paused, null)
       : field === 'archived' ? Boolean(state?.archived) : task?.[field] ?? null;
+    const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+    // The rows a card's span read as before this edit, with its subtasks', parsed only when a field differs.
+    const before = new Map();
+    const rowsBefore = (card) => {
+      if (before.has(card)) return before.get(card);
+      const rows = new Map(); before.set(card, rows);
+      const at = plan.before.get(card);
+      if (!at) return rows;
+      try {
+        const { records, errors } = this.codec.inspectBoardDocument(this.texts([at.entry])[0].text, this.docOf(at.role).path);
+        if (errors.length || records.length !== 1 || nativeId(records[0].id) !== card) return rows;
+        const parsed = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([records[0]])).issues[0];
+        rows.set(card, this.cardRows(card, parsed, null));
+        for (const [tid, taskCard] of this.taskCards(card, parsed)) rows.set(tid, this.cardRows(tid, taskCard, card));
+        for (const r of rows.values()) r.state.blocked_by = JSON.stringify(json(r.state.blocked_by, []).map((b) => ({ ...b, id: resolveRef(b.id) })));
+      } catch { rows.clear(); } // an unreadable span says nothing of what the lines said
+      return rows;
+    };
+    const adopt = (rows, task, state, field) => {
+      if (field === 'status') { rows.task.status = task.status; rows.state.stage = state?.stage ?? null; }
+      else if (field === 'blocked_by') rows.state.blocked_by = state?.blocked_by ?? '[]';
+      else if (field === 'paused') rows.state.paused = state?.paused ?? null;
+      else if (field === 'archived') rows.state.archived = state?.archived ?? 0;
+      else rows.task[field] = task[field] ?? null;
+    };
     for (const [id, rows] of plan.rows) {
       const task = this.one('SELECT * FROM main.tasks WHERE id = ?', id), state = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', id);
       // A new display author is not an authenticated creator.
-      const forbidden = fields.filter((field) => (task || field !== 'created_by') && JSON.stringify(value(rows.task, rows.state, field)) !== JSON.stringify(value(task, state, field)));
+      const differ = fields.filter((field) => (task || field !== 'created_by') && !same(value(rows.task, rows.state, field), value(task, state, field)));
+      const prior = task && differ.length ? rowsBefore(rows.state.subtask_of ?? id).get(id) : null;
+      const stale = prior ? differ.filter((field) => same(value(prior.task, prior.state, field), value(rows.task, rows.state, field))) : [];
+      for (const field of stale) adopt(rows, task, state, field);
+      const forbidden = differ.filter((field) => !stale.includes(field));
       if (forbidden.length) plan.errors.set(id, `Document edit cannot change ${forbidden.join(', ')}; use this card's role-checked workflow verbs or request-state.`);
     }
     for (const id of plan.remove) {
+      // A task line already absent from the replaced span was not removed by this edit: the store keeps it.
+      const parent = this.one('SELECT subtask_of FROM main.supercode_cards WHERE task_id = ?', id)?.subtask_of;
+      const prior = parent && !plan.remove.has(parent) ? rowsBefore(parent) : null;
+      if (prior?.size && !prior.has(id)) { plan.remove.delete(id); plan.checked.add(id); continue; }
       plan.errors.set(id, "Document edit cannot change card removal; use this card's role-checked workflow verbs or request-state.");
     }
     for (const id of plan.errors.keys()) plan.remove.delete(id);
@@ -553,6 +624,7 @@ class ZtrackBoard {
     for (const id of plan.checked) this.errors.delete(id);
     for (const [id, reason] of plan.errors) this.errors.set(id, reason);
     if (overlay) return;
+    for (const id of plan.errors.keys()) this.refused.add(this.one('SELECT subtask_of FROM main.supercode_cards WHERE task_id = ?', id)?.subtask_of ?? id);
     for (const [tid, { key, sources }] of plan.tasks) this.statement('INSERT OR REPLACE INTO main.board_tasks (id, key, sources) VALUES (?, ?, ?)').run(tid, key, sources?.length ? JSON.stringify(sources) : null);
     for (const id of [...plan.checked, ...plan.rows.keys()]) if (!plan.errors.has(id)) this.statement('DELETE FROM main.board_errors WHERE id = ?').run(id);
     for (const [id, reason] of plan.errors) this.statement('INSERT OR REPLACE INTO main.board_errors VALUES (?, ?)').run(id, reason);
@@ -629,21 +701,30 @@ class ZtrackBoard {
   // into their documents; a card whose record is unchanged keeps its exact bytes. Answers the
   // documents to publish.
   render() {
-    const touched = new Set(this.statement('SELECT DISTINCT id FROM temp.board_touched WHERE id IS NOT NULL').all().map((r) => r.id));
-    if (!touched.size) return [];
+    const cardsTouched = () => {
+      const parents = new Set();
+      for (const { id } of this.statement('SELECT DISTINCT id FROM temp.board_touched WHERE id IS NOT NULL').all()) {
+        const parent = this.one('SELECT subtask_of FROM main.supercode_cards WHERE task_id = ?', id)?.subtask_of;
+        const key = parent ? null : this.one('SELECT key FROM main.board_tasks WHERE id = ?', id)?.key;
+        parents.add(parent ?? (key && !this.one('SELECT 1 FROM main.tasks WHERE id = ?', id) ? key.slice(0, key.lastIndexOf(':')) : id));
+      }
+      return parents;
+    };
+    let parents = cardsTouched();
+    if (!parents.size) return [];
+    const heldBy = (id) => this.errors.has(id) || this.one('SELECT 1 FROM main.supercode_cards WHERE subtask_of = ? AND task_id IN (SELECT id FROM main.board_errors)', id);
+    // A card held by a recorded refusal is not rendered, so the store's verbs move its tasks past its lines. When
+    // the store moves it, its span is read again: what the store moved past is stale and takes the store's value
+    // (checkControls), and the card renders. A card refused by this write's own edit stays as it was written.
+    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 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 parents = new Set();
-    for (const id of touched) {
-      const parent = this.one('SELECT subtask_of FROM main.supercode_cards WHERE task_id = ?', id)?.subtask_of;
-      const key = parent ? null : this.one('SELECT key FROM main.board_tasks WHERE id = ?', id)?.key;
-      parents.add(parent ?? (key && !this.one('SELECT 1 FROM main.tasks WHERE id = ?', id) ? key.slice(0, key.lastIndexOf(':')) : id));
-    }
-    if (this.seedIds) for (const id of this.seedIds) parents.add(id);
     const edits = { open: [], archived: [] };
     for (const id of parents) {
-      if (this.errors.has(id) || this.one('SELECT 1 FROM main.supercode_cards WHERE subtask_of = ? AND task_id IN (SELECT id FROM main.board_errors)', id)) continue;
+      if (heldBy(id)) continue;
       const task = this.one('SELECT * FROM main.tasks WHERE id = ?', id);
       const state = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', id) ?? {};
       if (task && state.subtask_of) continue;

package/package.json

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