Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

feat(land): the landing merge numbers new engines in order [B3,R3]

Corey Olsonc7e7b705a478
diff --git a/docs/formats.md b/docs/formats.md
index 4a6e5173..db72aaa5 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -116,6 +116,8 @@ The board file is in the repository's Git common directory at `.git/pullboard/bo
| `move engine` | `80` | `ENGINE_VERSION` in `src/machine.js`, carried as `engine` in every sealed executable move | Bump when a move's meaning changes, independently of the event log and sealed envelope. A newer engine is refused with `ENGINE_VERSION`, naming both versions and asking you to upgrade Pullboard. |
<!-- format-versions:end -->
+A builder never picks an engine number (#1101). An item that adds a board move adds its own `src/<name>-engine.js` leaf as `export const NAME_ENGINE = unassignedEngine();` (importing `unassignedEngine` from `./engine-next.js`); on its branch the leaf reads as one above the highest landed engine. The landing merge writes the next number into the leaf, in landing order, inside that item's merge commit, and sets the `move engine` row above to the highest landed number. A landed number never changes, so recorded moves replay as they were written.
+
Relay transport capability `apiVersion: 2` is independent of these versions and
of the unchanged `version: 1` HTTP envelope and seal envelope. API2 uses
`pullboard-paged-snapshot/1` inside encrypted directory pages, with a current-state
diff --git a/src/engine-next.js b/src/engine-next.js
new file mode 100644
index 00000000..7f2fa4f4
--- /dev/null
+++ b/src/engine-next.js
@@ -0,0 +1,15 @@
+/** The engine number an unlanded leaf reads as on its branch: one above the highest landed engine (#1101). */
+import { fileURLToPath } from 'node:url';
+import {
+ nextEngineNumber,
+ readEngineLeaves,
+} from './engine-numbers.js';
+
+/**
+ * One above the highest landed engine among this directory's leaves; the landing merge writes the real number.
+ *
+ * @returns {number}
+ */
+export function unassignedEngine() {
+ return nextEngineNumber(readEngineLeaves(fileURLToPath(new URL('./', import.meta.url))));
+}
diff --git a/src/engine-numbers.js b/src/engine-numbers.js
new file mode 100644
index 00000000..5cee8940
--- /dev/null
+++ b/src/engine-numbers.js
@@ -0,0 +1,85 @@
+/**
+ * Engine numbers are given at landing, never picked by a builder (#1101).
+ *
+ * An item that adds a board move adds its own src/<name>-engine.js leaf as `export const NAME_ENGINE =
+ * unassignedEngine();`. On its branch the leaf reads as the trunk's highest engine plus one, so its tests run; the
+ * landing merge then writes the next number into the leaf, in landing order, inside the item's merge commit. Two
+ * items can never take the same number and none waits on a stale one; a landed number never changes, so moves
+ * recorded under it replay as they were written.
+ */
+import {
+ existsSync,
+ readFileSync,
+ readdirSync,
+ writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import {
+ ENGINE_CANDIDATE,
+ ENGINE_FILE,
+ discovered,
+} from './discovery.js';
+
+/** The one declaration a leaf holds: a landed number, or the placeholder a branch carries until it lands. */
+export const ENGINE_LINE = /^export const ([A-Z][A-Z0-9_]*_ENGINE) = (?:(\d+)|unassignedEngine\(\));$/u;
+/** The import a placeholder leaf needs, removed when the leaf gets its number. */
+export const UNASSIGNED_IMPORT = "import { unassignedEngine } from './engine-next.js';";
+
+/**
+ * Read every engine leaf in a directory.
+ *
+ * @param {string} directory
+ * @returns {{ file: string, name: string, number: number | null }[]} By file name; `number` is null until it lands.
+ */
+export function readEngineLeaves(directory) {
+ return discovered(readdirSync(directory), ENGINE_CANDIDATE, ENGINE_FILE, 'feature engine').map((file) => {
+ const lines = readFileSync(join(directory, file), 'utf8').split('\n').filter((line) => /^export const /u.test(line));
+ const match = lines.length === 1 ? ENGINE_LINE.exec(lines[0]) : null;
+ if (!match) throw new Error(`${file} must declare exactly one line \`export const NAME_ENGINE = <number>;\`, or \`= unassignedEngine();\` until it lands, so ENGINE_VERSION can read it`);
+ return { file, name: match[1], number: match[2] === undefined ? null : Number(match[2]) };
+ });
+}
+
+/**
+ * The number an unlanded leaf reads as: one above the highest landed number.
+ *
+ * @param {{ number: number | null }[]} leaves
+ * @returns {number}
+ */
+export function nextEngineNumber(leaves) {
+ return Math.max(0, ...leaves.map((leaf) => leaf.number ?? 0)) + 1;
+}
+
+/**
+ * Give each unlanded leaf under `root`/src its number, next above the landed ones in file-name order, and keep the
+ * documented move engine in docs/formats.md equal to the result. A tree with no unlanded leaf is left untouched.
+ *
+ * @param {string} root
+ * @returns {{ files: string[], assigned: { name: string, number: number }[] }} The changed paths, relative to root.
+ */
+export function assignEngineNumbers(root) {
+ const directory = join(root, 'src');
+ if (!existsSync(directory)) return { files: [], assigned: [] };
+ const leaves = readEngineLeaves(directory);
+ const unlanded = leaves.filter((leaf) => leaf.number === null);
+ if (!unlanded.length) return { files: [], assigned: [] };
+ let next = nextEngineNumber(leaves) - 1;
+ const files = [];
+ const assigned = [];
+ for (const leaf of unlanded) {
+ next += 1;
+ const path = join(directory, leaf.file);
+ const text = readFileSync(path, 'utf8').split('\n').filter((line) => line !== UNASSIGNED_IMPORT).join('\n')
+ .replace(/= unassignedEngine\(\);$/mu, `= ${next};`);
+ writeFileSync(path, text);
+ files.push(`src/${leaf.file}`);
+ assigned.push({ name: leaf.name, number: next });
+ }
+ const formats = join(root, 'docs', 'formats.md');
+ if (existsSync(formats)) {
+ const text = readFileSync(formats, 'utf8');
+ const updated = text.replace(/^(\| `move engine` \| `)\d+(` \|)/mu, `$1${next}$2`);
+ if (updated !== text) { writeFileSync(formats, updated); files.push('docs/formats.md'); }
+ }
+ return { files, assigned };
+}
diff --git a/src/land.js b/src/land.js
index 6dac5a5c..4db64c66 100644
--- a/src/land.js
+++ b/src/land.js
@@ -1,4 +1,5 @@
/** Coordinator landing batches retain exact Git and gate receipts across interruptions [B3,R3]. */
+import { assignEngineNumbers } from './engine-numbers.js';
import {
createHash,
randomUUID,
@@ -206,6 +207,13 @@ async function mergeGroup(state, items) {
state.say(`conflict #${item.item_id}: ${files.join(', ')}`);
continue;
}
+ // An engine the item added without a number gets the next one now, in landing order, inside its own merge (#1101).
+ const engines = assignEngineNumbers(batch.root);
+ if (engines.files.length) {
+ git(batch.root, ['add', '--', ...engines.files]);
+ git(batch.root, ['commit', '--amend', '--no-edit']);
+ for (const engine of engines.assigned) state.say(`engine ${engine.name}: ${engine.number} for #${item.item_id}`);
+ }
const first = git(batch.root, ['rev-list', '--first-parent', '--reverse', 'HEAD']).split('\n')
.find((commit) => tryGit(batch.root, ['merge-base', '--is-ancestor', checked, commit]).status === 0);
merged.push({ id: item.item_id, commit: item.item_commit, ...(checked !== item.item_commit ? { reviewedCommit: checked } : {}), merge: first });
diff --git a/src/machine.js b/src/machine.js
index e8f4c714..fee01697 100644
--- a/src/machine.js
+++ b/src/machine.js
@@ -9,15 +9,11 @@
* broken copy, and checks the declaration against the refusals board.js and cli.js raise today.
*/
+import { fileURLToPath } from 'node:url';
import {
- ENGINE_CANDIDATE,
- ENGINE_FILE,
- discovered,
-} from './discovery.js';
-import {
- readdirSync,
- readFileSync,
-} from 'node:fs';
+ nextEngineNumber,
+ readEngineLeaves,
+} from './engine-numbers.js';
export { AUTO_ESCALATE_ENGINE } from './auto-escalate-engine.js';
export { ROW_DRAFT_ENGINE } from './row-draft-engine.js';
@@ -28,20 +24,17 @@ export { WITHDRAW_MILESTONE_ENGINE } from './withdraw-milestone-engine.js';
/**
* Find every feature engine: each src/*-engine.js leaf declares exactly one `export const NAME_ENGINE = n;` line.
* A feature that raises the engine adds its own new file and no line of any shared one, so two items adding
- * different engines never conflict [C7,V4]. The value is read as text because machine.js needs it synchronously.
+ * different engines never conflict [C7,V4]. An unlanded leaf says `= unassignedEngine();` and reads as one above
+ * the landed engines until the landing merge gives it its number (#1101). The value is read as text because
+ * machine.js needs it synchronously.
*
* @param {URL} directory the folder holding the *-engine.js leaves
* @returns {Record<string, number>} engine number by file name, in name order
*/
export function discoverEngines(directory = new URL('./', import.meta.url)) {
- const found = {};
- for (const file of discovered(readdirSync(directory), ENGINE_CANDIDATE, ENGINE_FILE, 'feature engine')) {
- const lines = readFileSync(new URL(file, directory), 'utf8').split('\n').filter((line) => /^export const /u.test(line));
- const match = lines.length === 1 ? /^export const [A-Z][A-Z0-9_]*_ENGINE = (\d+);$/u.exec(lines[0]) : null;
- if (!match) throw new Error(`${file} must declare exactly one line \`export const NAME_ENGINE = <number>;\` so ENGINE_VERSION can read it`);
- found[file.slice(0, -'-engine.js'.length)] = Number(match[1]);
- }
- return found;
+ const leaves = readEngineLeaves(fileURLToPath(directory));
+ const unlanded = nextEngineNumber(leaves);
+ return Object.fromEntries(leaves.map((leaf) => [leaf.file.slice(0, -'-engine.js'.length), leaf.number ?? unlanded]));
}
export { REOPEN_FIRST_REFUSAL_ENGINE } from './reopen-first-refusal-engine.js';
diff --git a/test/land-engine-fixture.js b/test/land-engine-fixture.js
new file mode 100644
index 00000000..bee75f22
--- /dev/null
+++ b/test/land-engine-fixture.js
@@ -0,0 +1,65 @@
+/** Two items that each add an unnumbered engine land in either order and take the next numbers in that order [B3,R3]. */
+import assert from 'node:assert/strict';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as store from '../src/board.js';
+import { exportBoard, importBoard } from '../src/exchange.js';
+
+/** An unlanded engine leaf, as an item adds one under #1101. */
+function unlandedLeaf(name) {
+ return `/** The ${name} feature's engine. */\nimport { unassignedEngine } from './engine-next.js';\nexport const ${name.toUpperCase()}_ENGINE = unassignedEngine();\n`;
+}
+
+/** The engine number a leaf holds at a commit, or null when the leaf is not there or not yet numbered. */
+function numberAt(box, commit, name) {
+ const shown = box.tryGit(box.repo, 'show', `${commit}:src/${name}-engine.js`);
+ return shown.status === 0 ? Number(/= (\d+);/u.exec(shown.stdout)?.[1] ?? NaN) : null;
+}
+
+/**
+ * Land two engine-adding items, accepted in `order`, and check each took the next number in landing order inside its
+ * own merge, that the documented move engine follows, and that the landed board still replays.
+ *
+ * @param {object} helpers - land.test.js's own project, item, verdict and output helpers.
+ * @param {number[]} order - The verdict order, which is the landing order.
+ */
+export function landEnginesInOrder({ landProject, itemWorktree, submitItem, acceptItem, json, onBoard }, order) {
+ const box = landProject();
+ // The trunk already has one landed engine, and its documented move engine; the fixture lane owns src/ too.
+ const config = JSON.parse(readFileSync(join(box.repo, 'pullboard.json'), 'utf8'));
+ config.lanes.web.owns = [...new Set([...config.lanes.web.owns, 'src/', 'docs/'])];
+ writeFileSync(join(box.repo, 'pullboard.json'), `${JSON.stringify(config, null, 2)}\n`);
+ mkdirSync(join(box.repo, 'src'), { recursive: true });
+ mkdirSync(join(box.repo, 'docs'), { recursive: true });
+ writeFileSync(join(box.repo, 'src', 'base-engine.js'), '/** The landed base engine. */\nexport const BASE_ENGINE = 80;\n');
+ writeFileSync(join(box.repo, 'docs', 'formats.md'), '| Format | Version |\n| --- | --- |\n| `move engine` | `80` | the fixture |\n');
+ box.git(box.repo, 'add', '-A');
+ box.git(box.repo, 'commit', '-q', '-m', 'chore: a landed engine and its documented number');
+ const names = ['alpha', 'beta'];
+ const entries = names.map((name, index) => {
+ const entry = itemWorktree(box, index + 1);
+ writeFileSync(join(entry.path, 'src', `${name}-engine.js`), unlandedLeaf(name));
+ return submitItem(box, entry);
+ });
+ for (const index of order) acceptItem(box, entries[index]);
+ const base = box.git(box.repo, 'rev-parse', 'main');
+ const result = json(box, box.repo, 'land', '--max', '2');
+ assert.deepEqual(result.landed, order.map((index) => entries[index].item), 'the train lands in verdict order');
+ for (const [position, index] of order.entries()) {
+ const merge = json(box, box.repo, 'show', String(entries[index].item)).item_merged_commit;
+ assert.equal(numberAt(box, merge, names[index]), 81 + position, `${names[index]} took ${81 + position}, its place in landing order, inside its own merge`);
+ assert.equal(box.git(box.repo, 'rev-list', '--parents', '-n', '1', merge).split(' ').length, 3, 'the numbered leaf is part of the merge commit itself');
+ const other = names[order[1 - position]];
+ if (position === 0) assert.equal(numberAt(box, merge, other), null, `${other} had not landed yet at the first merge`);
+ }
+ assert.match(box.git(box.repo, 'show', `${result.batch.tip}:docs/formats.md`), /\| `move engine` \| `82` \|/u, 'the documented move engine follows the highest landed number');
+ assert.ok(!box.git(box.repo, 'show', `${result.batch.tip}:src/alpha-engine.js`).includes('unassignedEngine'), 'a landed leaf names its number, not the placeholder');
+ assert.notEqual(box.git(box.repo, 'rev-parse', 'main'), base);
+ // The landed board replays: its events import into a fresh board unchanged.
+ const document = onBoard(box, (board) => exportBoard(board));
+ const replayed = store.openBoard(join(box.dir, 'replayed.sqlite'));
+ try {
+ importBoard(replayed, document);
+ assert.deepEqual(exportBoard(replayed).tables.event.map((event) => event.event_id), document.tables.event.map((event) => event.event_id));
+ } finally { store.closeBoard(replayed); }
+}
diff --git a/test/land.test.js b/test/land.test.js
index 4fd74516..d08b3ef2 100644
--- a/test/land.test.js
+++ b/test/land.test.js
@@ -16,6 +16,7 @@ import { assertLandingDoctrineCounts } from './land-doctrine-fixture.js';
import { onBoard, events, calls } from './land-board-fixture.js';
import { landingTimeoutFixture } from './landing-timeout-fixture.js';
+import { landEnginesInOrder } from './land-engine-fixture.js';
const e2e = createE2eHelpers();
after(e2e.cleanup);
const { sandbox, project, commitFile, waitFor, BIN } = e2e;
@@ -1487,3 +1488,7 @@ test('a publish gate run is recorded and a red and green pair it sees files the
assert.equal(calls(box).length - before, 3, 'each receipt represents one actual full publish gate');
});
test('a landing gate past its timeout stops cleanly [E27,E29]', () => landingTimeoutFixture({ landProject, itemWorktree, submitItem, acceptItem, onBoard, json }));
+
+test('the landing merge assigns engine numbers in landing order, either order, and the board replays [B3,R3,H16]', () => {
+ for (const order of [[0, 1], [1, 0]]) landEnginesInOrder({ landProject, itemWorktree, submitItem, acceptItem, json, onBoard }, order);
+});