@codedology/code-forge 0.1.0

package/src/state/block.mjs

@@ -0,0 +1,289 @@
+/**
+ * Block state verbs (plan §4.9): `open`, `attempt`, `rebase`, `claim`, `scope`, `close`, `stop`,
+ * and the brief pointer. Every mutation runs under the run lock and writes its SIGNED ledger row
+ * through the `writeRow` parameter BEFORE saving the registry in the authoritative run record
+ * (a failed ledger write leaves the registry unchanged). `closeBlock` reads the pin and the rows
+ * outside the lock and re-checks status and orphans inside it before closing.
+ *
+ * `closeBlock` is B8's share of the block gate (§4.6): the worker pin (row 9/§4.8), the MAC of
+ * every gate-relevant row (row 10), and the orphan rule (row 1). The other rows (reviews, gates,
+ * acceptance, proof, forecast) arrive as `extraChecks` from the blocks that own them (B5, B10,
+ * B12) — this module never imports them (C17).
+ */
+
+import { createHash } from 'node:crypto';
+import os from 'node:os';
+import { exec } from '../util/exec.mjs';
+import { isAncestorArgv, revParseArgv } from '../util/git.mjs';
+import { StateError } from './paths.mjs';
+import { assertOwned, findOverlap, scopeGate } from './registry.mjs';
+import { checkWorkerPin, readRun, saveRun, withRunLock, writeSigned } from './run.mjs';
+import { verifyRow, loadKey } from './signer.mjs';
+
+/** @typedef {import('./run.mjs').WriteRow} WriteRow */
+
+export const BRIEF_POINTER_MAX_BYTES = 200;
+
+/** Ledger events the block gate requires to carry a valid MAC (§4.6 row 10). */
+export const GATE_EVENTS = Object.freeze(['dispatch', 'block.attempt', 'block.rebase', 'block.claim', 'review.approved', 'proof']);
+
+const BLOCK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+const LEVEL = /^L[0-3]$/;
+
+/** `process.env` minus every inherited `GIT_*` (hooks export GIT_DIR…), with no system/global config. */
+function gitEnv() {
+  /** @type {NodeJS.ProcessEnv} */
+  const env = { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: os.devNull };
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith('GIT_')) env[key] = value;
+  }
+  return env;
+}
+
+/** @param {string[]} argv @param {string} cwd @param {number[]} [okExitCodes] */
+async function git(argv, cwd, okExitCodes) {
+  const res = await exec(argv, { cwd, env: gitEnv(), okExitCodes, timeoutMs: 30000 });
+  if (res.result !== 'ok') throw new StateError('git-failed', `${argv.slice(0, 2).join(' ')} failed (exit ${res.code})`);
+  return res;
+}
+
+/** @param {string} ref @param {string} cwd @returns {Promise<string>} the full commit sha */
+async function resolveCommit(ref, cwd) {
+  if (typeof ref !== 'string' || ref.length === 0 || ref.startsWith('-')) {
+    throw new StateError('bad-ref', `a git ref must be non-empty and not start with "-" (got ${JSON.stringify(ref)})`);
+  }
+  const res = await git(revParseArgv(`${ref}^{commit}`), cwd);
+  return res.stdout.trim();
+}
+
+/**
+ * `BRIEF <path> lines=<n> sha=<sha8> <<<EOM>>>` — `sha8` is the first 8 hex of the brief's
+ * SHA-256, `lines` counts `\n` (plus a final unterminated line). The coder answers
+ * `ACK <sha8> lines=<n>` (§5.3, parsed by B4).
+ * @param {string} relPath @param {Buffer | string} content
+ * @returns {string}
+ * @throws {StateError} `pointer-too-long` over 200 bytes, `bad-brief-path` on whitespace.
+ */
+export function briefPointer(relPath, content) {
+  if (typeof relPath !== 'string' || relPath.length === 0 || /\s/.test(relPath)) {
+    throw new StateError('bad-brief-path', 'brief path must be non-empty and contain no whitespace');
+  }
+  const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+  const sha8 = createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+  let lines = 0;
+  for (const byte of bytes) if (byte === 0x0a) lines += 1;
+  if (bytes.length > 0 && bytes[bytes.length - 1] !== 0x0a) lines += 1;
+  const pointer = `BRIEF ${relPath} lines=${lines} sha=${sha8} <<<EOM>>>`;
+  const size = Buffer.byteLength(pointer, 'utf8');
+  if (size > BRIEF_POINTER_MAX_BYTES) {
+    throw new StateError('pointer-too-long', `brief pointer is ${size} bytes (max ${BRIEF_POINTER_MAX_BYTES}); use a shorter brief path`);
+  }
+  return pointer;
+}
+
+/**
+ * @param {unknown} clauses
+ * @returns {{clause: string, tests: string[]}[]}
+ */
+function assertAcceptance(clauses) {
+  const ok =
+    Array.isArray(clauses) &&
+    clauses.length > 0 &&
+    clauses.every(
+      (c) => typeof c?.clause === 'string' && c.clause.length > 0 && Array.isArray(c.tests) && c.tests.length > 0 && c.tests.every((t) => typeof t === 'string' && t.length > 0),
+    );
+  if (!ok) throw new StateError('bad-acceptance', 'acceptance: a non-empty list of {clause, tests: [test ids…]} is required');
+  return clauses;
+}
+
+/**
+ * Under the run lock: load the run, check it is active and (when `id` is given) that the block
+ * is open, run `mutate`, write its signed `rows` through the ledger writer, THEN save the record —
+ * a ledger write that fails leaves the registry unchanged.
+ * @template T
+ * @param {string} runId @param {string | null} id @param {WriteRow} writeRow
+ * @param {(record: Record<string, any>, block: Record<string, any> | undefined) => Promise<{result: T, rows?: Record<string, any>[]}> | {result: T, rows?: Record<string, any>[]}} mutate
+ * @returns {Promise<T>}
+ */
+async function mutateRun(runId, id, writeRow, mutate) {
+  return withRunLock(runId, async () => {
+    const record = await readRun(runId);
+    if (record.status !== 'active') throw new StateError('run-ended', `run ${runId} has ended`);
+    const block = id === null ? undefined : record.blocks[id];
+    if (id !== null && block?.status !== 'open') throw new StateError('no-block', `block ${id} is not open in run ${runId}`);
+    const { result, rows = [] } = await mutate(record, block);
+    for (const row of rows) await writeSigned(runId, writeRow, row);
+    await saveRun(record);
+    return result;
+  });
+}
+
+/** @param {Record<string, any>} record @returns {Record<string, any>} the open blocks only */
+function activeBlocks(record) {
+  return Object.fromEntries(Object.entries(record.blocks).filter(([, b]) => b.status === 'open'));
+}
+
+/**
+ * `block open` — refuses a second open of the same id and any owned set that overlaps another
+ * ACTIVE block's; records base, owned files, level, attempt, acceptance, line forecast.
+ * @param {{
+ *   runId: string, id: string, level: string, owned: string[], acceptance: unknown,
+ *   attempt?: number, base?: string, lines?: number, brief?: {path: string, content: Buffer | string},
+ *   writeRow: WriteRow, now?: Date,
+ * }} opts
+ * @returns {Promise<{block: Record<string, any>, pointer: string | null}>}
+ */
+export async function openBlock(opts) {
+  const { runId, id, level, attempt = 1, lines = null, writeRow, now = new Date() } = opts;
+  if (typeof id !== 'string' || !BLOCK_ID.test(id)) throw new StateError('bad-block-id', `block id must match ${BLOCK_ID}`);
+  if (typeof level !== 'string' || !LEVEL.test(level)) throw new StateError('bad-level', 'level must be L0..L3');
+  if (!Number.isInteger(attempt) || attempt < 1) throw new StateError('bad-attempt', 'attempt must be an integer >= 1');
+  if (lines !== null && !(Number.isInteger(lines) && lines > 0)) throw new StateError('bad-lines', 'lines forecast must be a positive integer');
+  const owned = assertOwned(opts.owned);
+  const acceptance = assertAcceptance(opts.acceptance);
+  const pointer = opts.brief ? briefPointer(opts.brief.path, opts.brief.content) : null;
+
+  const block = await mutateRun(runId, null, writeRow, async (record) => {
+    if (record.blocks[id]?.status === 'open') throw new StateError('already-open', `block ${id} is already open`);
+    for (const [otherId, other] of Object.entries(activeBlocks(record))) {
+      const pair = findOverlap(owned, other.owned_files);
+      if (pair) throw new StateError('overlap', `block ${id} owns ${pair[0]}, which overlaps ${pair[1]} owned by open block ${otherId}`);
+    }
+    const baseSha = await resolveCommit(opts.base ?? 'HEAD', record.workspace);
+    const entry = { block: id, base_sha: baseSha, owned_files: [...owned], level, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open' };
+    record.blocks[id] = entry;
+    return {
+      result: entry,
+      rows: [{ event: 'dispatch', block: id, level, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines }],
+    };
+  });
+  return { block, pointer };
+}
+
+/** @param {{runId: string, id: string, writeRow: WriteRow}} opts */
+export async function attemptBlock({ runId, id, writeRow }) {
+  return mutateRun(runId, id, writeRow, (_record, block) => {
+    block.attempt += 1;
+    return { result: block.attempt, rows: [{ event: 'block.attempt', block: id, attempt: block.attempt }] };
+  });
+}
+
+/**
+ * `block rebase` — move the base to `head` only when the old base is its ancestor and no commit
+ * in between touched a file this block owns (that is a conflict ⇒ stop). Rename detection is OFF
+ * (`--no-renames`): a rename lists both its old and its new path, so moving an owned file away
+ * is a conflict too. Never silent.
+ * @param {{runId: string, id: string, head?: string, writeRow: WriteRow}} opts
+ * @returns {Promise<{old_base: string, new_base: string}>}
+ */
+export async function rebaseBlock({ runId, id, head = 'HEAD', writeRow }) {
+  return mutateRun(runId, id, writeRow, async (record, block) => {
+    const cwd = record.workspace;
+    const newBase = await resolveCommit(head, cwd);
+    const ancestor = await git(isAncestorArgv(block.base_sha, newBase), cwd, [0, 1]);
+    if (ancestor.code !== 0) throw new StateError('base-not-ancestor', `block ${id}: base ${block.base_sha.slice(0, 12)} is not an ancestor of ${head}`);
+    const diff = await git(['git', 'diff', '--no-renames', '--name-only', block.base_sha, newBase], cwd);
+    const conflicts = diff.stdout.split('\n').filter((file) => file.length > 0 && findOverlap(block.owned_files, [file]) !== null);
+    if (conflicts.length > 0) throw new StateError('owned-conflict', `block ${id}: commits since its base changed owned files: ${conflicts.join(', ')}`);
+    const moved = { old_base: block.base_sha, new_base: newBase };
+    block.base_sha = newBase;
+    return { result: moved, rows: [{ event: 'block.rebase', block: id, ...moved }] };
+  });
+}
+
+/**
+ * `block claim` — assign one EXACT path (an orphan, or any unowned path) to `id`; refused for a
+ * glob, and when another open block owns it.
+ * @param {{runId: string, id: string, file: string, writeRow: WriteRow}} opts
+ */
+export async function claimPath({ runId, id, file, writeRow }) {
+  assertOwned([file]);
+  if (/[*?{]/.test(file)) throw new StateError('bad-owned', `block claim takes one exact path, not a glob (${JSON.stringify(file)})`);
+  await mutateRun(runId, id, writeRow, (record, block) => {
+    for (const [otherId, other] of Object.entries(activeBlocks(record))) {
+      if (otherId !== id && findOverlap([file], other.owned_files)) throw new StateError('overlap', `${file} is owned by open block ${otherId}`);
+    }
+    if (!block.owned_files.includes(file)) block.owned_files.push(file);
+    record.orphans = record.orphans.filter((/** @type {string} */ o) => o !== file);
+    return { result: undefined, rows: [{ event: 'block.claim', block: id, path: file }] };
+  });
+}
+
+/**
+ * The scope row for `id` against the tree's file set; NEW orphans are written to the registry
+ * and the ledger (`block.orphan`), so every active gate sees them.
+ * @param {{runId: string, id: string, files: string[], writeRow: WriteRow}} opts
+ * @returns {Promise<{ok: boolean, scope: string[], orphans: string[]}>}
+ */
+export async function checkScope({ runId, id, files, writeRow }) {
+  return mutateRun(runId, id, writeRow, (record) => {
+    const gate = scopeGate(activeBlocks(record), id, files);
+    const fresh = gate.orphans.filter((o) => !record.orphans.includes(o));
+    record.orphans = [...record.orphans, ...fresh];
+    return { result: gate, rows: fresh.map((orphan) => ({ event: 'block.orphan', path: orphan })) };
+  });
+}
+
+/** @param {{runId: string, id: string, reason: string, writeRow: WriteRow, event?: string}} opts */
+export async function stopBlock({ runId, id, reason, writeRow, event = 'block.stop' }) {
+  await mutateRun(runId, id, writeRow, (_record, block) => {
+    block.status = 'stopped';
+    block.stop_reason = reason;
+    return { result: undefined, rows: [{ event, block: id, reason }] };
+  });
+}
+
+/**
+ * B8's rows of the block gate, in order: worker pin ⇒ `worker.replaced`/`worker.down` (block
+ * stopped); the block's signed `dispatch` row must exist and verify, and every other
+ * gate-relevant row of the block must verify ⇒ else `ledger.tamper` (block stopped); then
+ * `extraChecks`; finally, UNDER the run lock, orphans in the registry ⇒ refused (block stays
+ * open), else closed.
+ * @param {{
+ *   runId: string, id: string, rows: Record<string, any>[], writeRow: WriteRow,
+ *   livePid?: number, probe?: import('./run.mjs').StartTimeProbe,
+ *   extraChecks?: Array<() => Promise<{ok: boolean, reason?: string}>>,
+ * }} opts
+ * @returns {Promise<{ok: boolean, status: 'closed' | 'stopped' | 'open', reason?: string, event?: string}>}
+ */
+export async function closeBlock({ runId, id, rows, writeRow, livePid, probe, extraChecks = [] }) {
+  const record = await readRun(runId);
+  if (record.blocks[id]?.status !== 'open') throw new StateError('no-block', `block ${id} is not open in run ${runId}`);
+
+  const pin = await checkWorkerPin(record, { livePid, probe });
+  if (!pin.ok) {
+    await stopBlock({ runId, id, reason: pin.reason, writeRow, event: pin.event });
+    return { ok: false, status: 'stopped', event: pin.event, reason: pin.reason };
+  }
+
+  const key = await loadKey(runId);
+  const relevant = rows.filter((row) => row.block === id && GATE_EVENTS.includes(row.event) && (row.run === undefined || row.run === runId));
+  const checked = relevant.map((row) => ({ row, result: verifyRow(row, key) }));
+  const bad = checked.filter((x) => !x.result.ok);
+  const dispatchOk = checked.some((x) => x.row.event === 'dispatch' && x.result.ok);
+  if (bad.length > 0 || !dispatchOk) {
+    const reasons = bad.map((x) => `${x.row.event}: ${x.result.reason}`);
+    if (!dispatchOk) reasons.push('no verified dispatch row');
+    const reason = reasons.join('; ');
+    await stopBlock({ runId, id, reason, writeRow, event: 'ledger.tamper' });
+    return { ok: false, status: 'stopped', event: 'ledger.tamper', reason };
+  }
+
+  for (const check of extraChecks) {
+    const result = await check();
+    if (!result.ok) return { ok: false, status: 'open', reason: result.reason ?? 'check failed' };
+  }
+
+  /** @typedef {{ok: boolean, status: 'closed' | 'stopped' | 'open', reason?: string, event?: string}} CloseResult */
+  return mutateRun(runId, id, writeRow, (current, block) => {
+    if (current.orphans.length > 0) {
+      /** @type {CloseResult} */
+      const refused = { ok: false, status: 'open', reason: `orphans: ${current.orphans.join(', ')}` };
+      return { result: refused, rows: [] };
+    }
+    block.status = 'closed';
+    /** @type {CloseResult} */
+    const closed = { ok: true, status: 'closed' };
+    return { result: closed, rows: [{ event: 'block.close', block: id, status: 'complete' }] };
+  });
+}

package/src/state/cli-args.mjs

@@ -0,0 +1,67 @@
+/**
+ * Flag parsing shared by the `run` and `block` verbs. Strict: every flag must be declared in the
+ * spec — `values` (`--flag value` / `--flag=value`, once), `booleans` (no value), or `multi`
+ * (every following token up to the next `--flag`, seeded by an inline `--flag=value`). An unknown
+ * flag, a bare `--`, a repeated single-value flag, or a value on a boolean is a usage error, so a
+ * typo never swallows the next token silently. Positionals are what is left.
+ */
+
+import { StateError } from './paths.mjs';
+
+/**
+ * @param {string[]} args
+ * @param {{values?: string[], booleans?: string[], multi?: string[]}} [spec]
+ * @returns {{flags: Record<string, string | string[] | true>, positionals: string[]}}
+ * @throws {StateError} `usage`
+ */
+export function parseFlags(args, { values = [], booleans = [], multi = [] } = {}) {
+  /** @type {Record<string, string | string[] | true>} */
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf('=');
+    const name = arg.slice(2, eq < 0 ? undefined : eq);
+    const inline = eq < 0 ? undefined : arg.slice(eq + 1);
+    if (!booleans.includes(name) && !multi.includes(name) && !values.includes(name)) {
+      throw new StateError('usage', `unknown flag ${JSON.stringify(arg)}`);
+    }
+    if (Object.hasOwn(flags, name) && !multi.includes(name)) throw new StateError('usage', `--${name} given more than once`);
+    if (booleans.includes(name)) {
+      if (inline !== undefined) throw new StateError('usage', `--${name} takes no value`);
+      flags[name] = true;
+    } else if (multi.includes(name)) {
+      const collected = Array.isArray(flags[name]) ? /** @type {string[]} */ (flags[name]) : [];
+      if (inline !== undefined && inline.length > 0) collected.push(inline);
+      while (i + 1 < args.length && !args[i + 1].startsWith('--')) collected.push(args[(i += 1)]);
+      if (collected.length === 0) throw new StateError('usage', `--${name} needs at least one value`);
+      flags[name] = collected;
+    } else if (inline !== undefined) {
+      if (inline.length === 0) throw new StateError('usage', `--${name} needs a value`);
+      flags[name] = inline;
+    } else {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('--')) throw new StateError('usage', `--${name} needs a value`);
+      flags[name] = next;
+      i += 1;
+    }
+  }
+  return { flags, positionals };
+}
+
+/**
+ * A strictly positive safe integer written without sign or leading zeros.
+ * @param {string | string[] | true | undefined} raw @param {string} name
+ * @returns {number | undefined}
+ * @throws {StateError} `usage`
+ */
+export function intFlag(raw, name) {
+  if (raw === undefined) return undefined;
+  const value = typeof raw === 'string' && /^[1-9]\d*$/.test(raw) ? Number(raw) : Number.NaN;
+  if (!Number.isSafeInteger(value)) throw new StateError('usage', `--${name} must be a positive integer`);
+  return value;
+}

package/src/state/paths.mjs

@@ -0,0 +1,92 @@
+/**
+ * Where run state lives (plan §1.2, §4.9, §8.6) and the one error type the state verbs throw.
+ *
+ *  - `~/.code-forge/runs/<run>.json` — the AUTHORITATIVE run record (registry + worker pin),
+ *    outside every workspace; `~/.code-forge/runs/<run>.key` — the per-run HMAC key, mode 0600.
+ *  - `<workspace>/.code-forge/runs/<run>.json` — an informational mirror, minus the worker pin.
+ *
+ * `os.homedir()` re-reads `$HOME` on every call (POSIX), so a test that points `HOME` at a temp
+ * dir never touches a real `~/.code-forge/`.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** A refusal with a stable machine-readable `code` (the CLI prints the message, exits 1). */
+export class StateError extends Error {
+  /** @param {string} code @param {string} message */
+  constructor(code, message) {
+    super(message);
+    this.name = 'StateError';
+    this.code = code;
+  }
+}
+
+const RUN_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/**
+ * @param {unknown} runId
+ * @returns {string}
+ * @throws {StateError} `bad-run-id` — a run id must never resolve outside the runs directory.
+ */
+export function assertRunId(runId) {
+  if (typeof runId !== 'string' || !RUN_ID_PATTERN.test(runId)) {
+    throw new StateError('bad-run-id', `run id must match ${RUN_ID_PATTERN}`);
+  }
+  return runId;
+}
+
+/** @param {Date} [now] @returns {string} e.g. `r-20260924-201500-3fa9c1` */
+export function newRunId(now = new Date()) {
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);
+  return `r-${stamp}-${randomBytes(3).toString('hex')}`;
+}
+
+/** @returns {string} */
+export function runsDir() {
+  return path.join(os.homedir(), '.code-forge', 'runs');
+}
+
+/** @param {string} runId @returns {string} */
+export function runRecordPath(runId) {
+  return path.join(runsDir(), `${assertRunId(runId)}.json`);
+}
+
+/** @param {string} runId @returns {string} */
+export function runKeyPath(runId) {
+  return path.join(runsDir(), `${assertRunId(runId)}.key`);
+}
+
+/** @param {string} p @returns {string} the real path when it exists, else the resolved one */
+function canonical(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * The run record must live OUTSIDE the workspace (C4). A workspace that is `$HOME` or one of its
+ * ancestors would hold `~/.code-forge/runs/` inside it — and with workspace === `$HOME` the
+ * mirror would overwrite the authoritative record (dropping the worker pin).
+ * @param {string} workspace
+ * @returns {string} the canonical workspace path
+ * @throws {StateError} `workspace-contains-runs-dir`
+ */
+export function assertWorkspaceOutsideRuns(workspace) {
+  const ws = canonical(workspace);
+  const rel = path.relative(ws, path.join(canonical(os.homedir()), '.code-forge', 'runs'));
+  if (!rel.startsWith('..') && !path.isAbsolute(rel)) {
+    throw new StateError('workspace-contains-runs-dir', `the workspace ${ws} contains ${runsDir()} — run code-forge from a project directory, not $HOME or above`);
+  }
+  return ws;
+}
+
+/** @param {string} workspace @param {string} runId @returns {string} */
+export function mirrorPath(workspace, runId) {
+  assertWorkspaceOutsideRuns(workspace);
+  return path.join(workspace, '.code-forge', 'runs', `${assertRunId(runId)}.json`);
+}

package/src/state/registry.mjs

@@ -0,0 +1,189 @@
+/**
+ * Shared-tree scope maths for parallel blocks in one working tree (plan §4.7, O2). Pure — the
+ * run record (`run.mjs`) stores the registry, the caller supplies the file set (B5 computes it:
+ * tracked changes ∪ untracked).
+ *
+ * Owned entries are exact paths or globs in a deliberately SMALL syntax, repo-relative, POSIX:
+ * `*` (any run of characters inside one segment), `?` (one character inside a segment), `**` (a
+ * whole segment matching zero or more segments) and `{a,b}` (expanded before anything else).
+ * Inside a GLOB, character classes and extglobs (`[` `]` `(` `)` `!` `+` `@`) are REFUSED by
+ * `assertOwned`, so no two readers can disagree on what an entry covers; in an EXACT path
+ * (no `*`, `?`, `{`) they are ordinary characters (`pages/[id].vue`) matched literally. The matcher is this module's own
+ * (`globMatch`), not `path.matchesGlob`, which Node still marks experimental. Dot-files are
+ * matched like any other name (fail closed for overlap).
+ *
+ * Overlap between two GLOBS cannot be decided in general, so it FAILS CLOSED: two globs are
+ * treated as overlapping when one's static directory prefix (the segments before the first glob
+ * character) is a segment-prefix of the other's — `test/fixtures/repos/two-blocks/**` and
+ * `test/fixtures/repos/node/**` are disjoint, `src/**` and `src/cli/*.mjs` overlap, and so do
+ * `src/*.mjs` and `src/cli/*.mjs` (they cannot share a path, but overlap is not ruled out by
+ * the prefix rule — the owner resolves it by naming exact paths).
+ */
+
+import { StateError } from './paths.mjs';
+
+const GLOB_CHARS = /[*?]/;
+/** Glob syntax this matcher does NOT implement — refused inside a glob entry only. */
+const UNSUPPORTED_GLOB_CHARS = /[[\]()!+@]/;
+
+/** @param {string} segment @returns {RegExp} */
+function segmentRegExp(segment) {
+  const body = segment
+    .split('')
+    .map((c) => (c === '*' ? '[^/]*' : c === '?' ? '[^/]' : c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+    .join('');
+  return new RegExp(`^${body}$`);
+}
+
+/**
+ * Does repo-relative `file` match brace-free `pattern` (`*`, `?`, `**` — see the module doc)?
+ * @param {string} file @param {string} pattern
+ * @returns {boolean}
+ */
+export function globMatch(file, pattern) {
+  const f = file.split('/');
+  const p = pattern.split('/');
+  /** @type {(i: number, j: number) => boolean} */
+  const match = (i, j) => {
+    if (j === p.length) return i === f.length;
+    if (p[j] === '**') {
+      for (let k = i; k <= f.length; k += 1) if (match(k, j + 1)) return true;
+      return false;
+    }
+    return i < f.length && segmentRegExp(p[j]).test(f[i]) && match(i + 1, j + 1);
+  };
+  return match(0, 0);
+}
+
+/**
+ * @param {string} pattern
+ * @returns {string[]} every alternative of every `{a,b}` group (nested groups included).
+ */
+export function expandBraces(pattern) {
+  const open = pattern.indexOf('{');
+  if (open < 0) return [pattern];
+  let depth = 0;
+  let close = -1;
+  const commas = [];
+  for (let i = open; i < pattern.length; i += 1) {
+    if (pattern[i] === '{') depth += 1;
+    else if (pattern[i] === '}' && --depth === 0) {
+      close = i;
+      break;
+    } else if (pattern[i] === ',' && depth === 1) commas.push(i);
+  }
+  if (close < 0) return [pattern];
+  const bounds = [open, ...commas, close];
+  const head = pattern.slice(0, open);
+  const tail = pattern.slice(close + 1);
+  return bounds.slice(0, -1).flatMap((start, i) => expandBraces(head + pattern.slice(start + 1, bounds[i + 1]) + tail));
+}
+
+/**
+ * @param {unknown} owned
+ * @returns {string[]}
+ * An EXACT entry (no `*`, `?` or `{`) may contain `[ ] ( ) ! + @ }` — real routes such as
+ * `pages/[id].vue`, `app/(group)/page.tsx`, `@types/x.d.ts` — and is matched literally by
+ * string equality. A GLOB entry may not: there those characters would be character-class or
+ * extglob syntax this matcher does not implement, so it is refused with that reason rather than
+ * silently read one way by us and another way by git or a shell.
+ * @throws {StateError} `bad-owned` — empty, absolute, `.`/`..`/empty segments (checked on every
+ *   brace alternative), backslashes, unbalanced braces, or unsupported glob syntax in a glob.
+ */
+export function assertOwned(owned) {
+  if (!Array.isArray(owned) || owned.length === 0) throw new StateError('bad-owned', 'owned files: at least one path is required');
+  for (const entry of owned) {
+    /** @param {string} why */
+    const refuse = (why) => {
+      throw new StateError('bad-owned', `owned files: invalid path ${JSON.stringify(entry)}: ${why}`);
+    };
+    if (typeof entry !== 'string' || entry.length === 0) refuse('must be a non-empty string');
+    if (entry.includes('\\')) refuse('backslashes are not allowed (POSIX paths only)');
+    const isGlob = /[*?{]/.test(entry);
+    if (isGlob && UNSUPPORTED_GLOB_CHARS.test(entry)) {
+      refuse('a glob may not contain [ ] ( ) ! + @ — character classes and extglobs are not supported; name the files exactly or use only *, ?, ** and {a,b}');
+    }
+    for (const alt of expandBraces(entry)) {
+      if (alt.startsWith('/')) refuse('must be repo-relative, not absolute');
+      if (isGlob && /[{}]/.test(alt)) refuse('unbalanced braces');
+      if (alt.split('/').some((segment) => segment === '..' || segment === '.' || segment === '')) refuse('no ".", ".." or empty segments');
+    }
+  }
+  return owned;
+}
+
+/** @param {string} p @returns {string[]} segments before the first glob character */
+function staticSegments(p) {
+  const segments = p.split('/');
+  const firstGlob = segments.findIndex((s) => GLOB_CHARS.test(s));
+  return firstGlob < 0 ? segments : segments.slice(0, firstGlob);
+}
+
+/** @param {string[]} a @param {string[]} b */
+const segmentPrefix = (a, b) => a.length <= b.length && a.every((s, i) => s === b[i]);
+
+/**
+ * @param {string} a @param {string} b - brace-free patterns
+ * @returns {boolean}
+ */
+function patternsOverlap(a, b) {
+  const aGlob = GLOB_CHARS.test(a);
+  const bGlob = GLOB_CHARS.test(b);
+  if (!aGlob && !bGlob) return a === b;
+  if (!aGlob) return globMatch(a, b);
+  if (!bGlob) return globMatch(b, a);
+  const sa = staticSegments(a);
+  const sb = staticSegments(b);
+  return segmentPrefix(sa, sb) || segmentPrefix(sb, sa);
+}
+
+/**
+ * @param {ReadonlyArray<string>} ownedA @param {ReadonlyArray<string>} ownedB
+ * @returns {[string, string] | null} the first overlapping pair (original spellings), or null.
+ */
+export function findOverlap(ownedA, ownedB) {
+  for (const a of ownedA) {
+    for (const b of ownedB) {
+      if (expandBraces(a).some((x) => expandBraces(b).some((y) => patternsOverlap(x, y)))) return [a, b];
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {ReadonlyArray<string>} owned @param {string} file
+ * @returns {boolean}
+ */
+export function ownsFile(owned, file) {
+  return owned.some((entry) => expandBraces(entry).some((p) => p === file || (GLOB_CHARS.test(p) && globMatch(file, p))));
+}
+
+/**
+ * @typedef {{owned_files: string[], status?: string}} RegistryBlock
+ * @param {Record<string, RegistryBlock>} blocks - the ACTIVE blocks only (status `open`)
+ * @param {ReadonlyArray<string>} files - the shared tree's changed + untracked files
+ * @returns {{scopes: Record<string, string[]>, orphans: string[]}}
+ */
+export function computeScopes(blocks, files) {
+  /** @type {Record<string, string[]>} */
+  const scopes = Object.fromEntries(Object.keys(blocks).map((id) => [id, []]));
+  const orphans = [];
+  for (const file of [...new Set(files)].sort()) {
+    const owners = Object.keys(blocks).filter((id) => ownsFile(blocks[id].owned_files, file));
+    if (owners.length === 0) orphans.push(file);
+    for (const id of owners) scopes[id].push(file);
+  }
+  return { scopes, orphans };
+}
+
+/**
+ * The scope row of block `blockId`'s gate: its files are what it owns; ANY orphan in the tree
+ * refuses EVERY active block's gate until it is claimed (`block claim`) or deleted.
+ * @param {Record<string, RegistryBlock>} blocks @param {string} blockId @param {ReadonlyArray<string>} files
+ * @returns {{ok: boolean, scope: string[], orphans: string[]}}
+ */
+export function scopeGate(blocks, blockId, files) {
+  if (!blocks[blockId]) throw new StateError('no-block', `block ${blockId} is not active`);
+  const { scopes, orphans } = computeScopes(blocks, files);
+  return { ok: orphans.length === 0, scope: scopes[blockId], orphans };
+}