spexcode 0.6.7 → 0.7.0-next.0

package/node_modules/@spexcode/session-topology/dist/index.js

@@ -0,0 +1,173 @@
+import { randomBytes } from 'node:crypto';
+import { applyComponentMigrations } from '@spexcode/session-protocol';
+import { failTopology, TopologyError } from './errors.js';
+import { TOPOLOGY_MIGRATIONS } from './schema.js';
+const EDGE_ID = /^[0-9a-f]{32}$/;
+const RELATION_TYPE = /^[0-9A-Za-z._:-]{1,64}$/;
+const SESSION_ID = /^(?!-)[0-9A-Za-z_-]{1,256}$/;
+const EDGE_COLUMNS = `edge_id, from_session_id, to_session_id, relation_type, created_at_ms, removed_at_ms`;
+export function openTopology(protocol) {
+    applyComponentMigrations(protocol, 'session-topology', TOPOLOGY_MIGRATIONS);
+    const requireTransaction = (tx) => {
+        if (!tx
+            || typeof tx.exec !== 'function'
+            || typeof tx.query !== 'function'
+            || typeof tx.enqueue !== 'function') {
+            failTopology('TOPOLOGY_TRANSACTION_INVALID', 'a live protocol transaction context is required');
+        }
+        return tx;
+    };
+    const requireSessionId = (sessionId) => {
+        if (typeof sessionId !== 'string' || !SESSION_ID.test(sessionId)) {
+            failTopology('TOPOLOGY_SESSION_ID_INVALID', 'session id must match the protocol address grammar');
+        }
+    };
+    const requireRelationType = (relationType) => {
+        if (typeof relationType !== 'string' || !RELATION_TYPE.test(relationType)) {
+            failTopology('TOPOLOGY_RELATION_TYPE_INVALID', 'relation type must match [0-9A-Za-z._:-]{1,64}');
+        }
+    };
+    const requireEdgeId = (edgeId) => {
+        if (typeof edgeId !== 'string' || !EDGE_ID.test(edgeId)) {
+            failTopology('TOPOLOGY_EDGE_ID_INVALID', 'edge id must be 32 lowercase hexadecimal characters');
+        }
+    };
+    const toEdge = (row) => ({
+        edgeId: String(row.edge_id),
+        fromSessionId: String(row.from_session_id),
+        toSessionId: String(row.to_session_id),
+        relationType: String(row.relation_type),
+        createdAtMs: Number(row.created_at_ms),
+        removedAtMs: row.removed_at_ms === null ? null : Number(row.removed_at_ms),
+    });
+    const asEdgeRows = (rows) => rows;
+    const requireAddresses = (tx, fromSessionId, toSessionId) => {
+        const rows = tx.query('SELECT session_id FROM protocol_sessions WHERE session_id IN (?,?) ORDER BY session_id', fromSessionId, toSessionId);
+        const found = new Set(rows.map(row => String(row.session_id)));
+        if (!found.has(fromSessionId) || !found.has(toSessionId)) {
+            failTopology('TOPOLOGY_SESSION_UNKNOWN', 'one or more topology session addresses are unknown');
+        }
+    };
+    const cycleExists = (tx, fromSessionId, toSessionId, relationType) => tx.query(`WITH RECURSIVE reachable(session_id) AS (
+       VALUES (?)
+       UNION
+       SELECT edge.to_session_id
+       FROM topology_edges AS edge INDEXED BY topology_active_edge
+       JOIN reachable ON edge.from_session_id=reachable.session_id
+       WHERE edge.relation_type=? AND edge.removed_at_ms IS NULL
+     )
+     SELECT 1 AS present FROM reachable WHERE session_id=? LIMIT 1`, toSessionId, relationType, fromSessionId).length > 0;
+    const validateNewEdge = (tx, fromSessionId, toSessionId, relationType) => {
+        requireTransaction(tx);
+        requireSessionId(fromSessionId);
+        requireSessionId(toSessionId);
+        requireRelationType(relationType);
+        if (fromSessionId === toSessionId) {
+            failTopology('TOPOLOGY_SELF_EDGE', 'an edge cannot point from a session to itself');
+        }
+        requireAddresses(tx, fromSessionId, toSessionId);
+        if (cycleExists(tx, fromSessionId, toSessionId, relationType)) {
+            failTopology('TOPOLOGY_CYCLE_REFUSED', 'the edge would create a relation cycle');
+        }
+    };
+    const activeEdge = (tx, fromSessionId, toSessionId, relationType) => asEdgeRows(tx.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges INDEXED BY topology_active_edge
+     WHERE from_session_id=? AND to_session_id=? AND relation_type=? AND removed_at_ms IS NULL`, fromSessionId, toSessionId, relationType))[0];
+    const insertEdge = (tx, fromSessionId, toSessionId, relationType) => {
+        const edgeId = randomBytes(16).toString('hex');
+        const createdAtMs = Date.now();
+        try {
+            tx.exec(`INSERT INTO topology_edges
+         (edge_id, from_session_id, to_session_id, relation_type, created_at_ms, removed_at_ms)
+         VALUES (?,?,?,?,?,NULL)`, edgeId, fromSessionId, toSessionId, relationType, createdAtMs);
+        }
+        catch (error) {
+            const code = String(error?.code ?? '');
+            if (code.includes('UNIQUE') || code.includes('PRIMARYKEY')) {
+                failTopology('TOPOLOGY_EDGE_EXISTS', 'the active topology edge already exists', error);
+            }
+            if (code.includes('FOREIGNKEY')) {
+                failTopology('TOPOLOGY_SESSION_UNKNOWN', 'one or more topology session addresses are unknown', error);
+            }
+            failTopology('TOPOLOGY_STORAGE_ERROR', 'the topology edge could not be stored', error);
+        }
+        return { edgeId, fromSessionId, toSessionId, relationType, createdAtMs, removedAtMs: null };
+    };
+    const attach = (tx, fromSessionId, toSessionId, relationType) => {
+        validateNewEdge(tx, fromSessionId, toSessionId, relationType);
+        if (activeEdge(tx, fromSessionId, toSessionId, relationType)) {
+            failTopology('TOPOLOGY_EDGE_EXISTS', 'the active topology edge already exists');
+        }
+        return insertEdge(tx, fromSessionId, toSessionId, relationType);
+    };
+    const detach = (tx, edgeId) => {
+        requireTransaction(tx);
+        requireEdgeId(edgeId);
+        const row = asEdgeRows(tx.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges WHERE edge_id=? AND removed_at_ms IS NULL`, edgeId))[0];
+        if (!row)
+            failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+        const removedAtMs = Date.now();
+        const result = tx.exec('UPDATE topology_edges SET removed_at_ms=? WHERE edge_id=? AND removed_at_ms IS NULL', removedAtMs, edgeId);
+        if (result.changes !== 1) {
+            failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+        }
+        return { ...toEdge(row), removedAtMs };
+    };
+    const withRead = (tx, query) => {
+        if (tx !== undefined)
+            return query(requireTransaction(tx));
+        return protocol.withTransaction(query);
+    };
+    const queryEdges = (sessionId, relationType, tx, direction) => {
+        requireSessionId(sessionId);
+        if (relationType !== undefined)
+            requireRelationType(relationType);
+        return withRead(tx, active => {
+            const index = direction === 'from' ? 'topology_active_edge' : 'topology_active_to';
+            const column = direction === 'from' ? 'from_session_id' : 'to_session_id';
+            const relation = relationType === undefined ? '' : ' AND relation_type=?';
+            const params = relationType === undefined ? [sessionId] : [sessionId, relationType];
+            return asEdgeRows(active.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges INDEXED BY ${index}
+         WHERE ${column}=? AND removed_at_ms IS NULL${relation}
+         ORDER BY relation_type, from_session_id, to_session_id, created_at_ms, edge_id`, ...params)).map(toEdge);
+        });
+    };
+    return {
+        attach,
+        detach,
+        reparent(tx, subjectSessionId, nextFromSessionId, relationType) {
+            validateNewEdge(tx, nextFromSessionId, subjectSessionId, relationType);
+            const removedAtMs = Date.now();
+            tx.exec(`UPDATE topology_edges SET removed_at_ms=?
+         WHERE to_session_id=? AND relation_type=? AND removed_at_ms IS NULL`, removedAtMs, subjectSessionId, relationType);
+            return insertEdge(tx, nextFromSessionId, subjectSessionId, relationType);
+        },
+        subscribe(tx, watcherSessionId, subjectSessionId, channel) {
+            return attach(tx, watcherSessionId, subjectSessionId, channel);
+        },
+        unsubscribe(tx, watcherSessionId, subjectSessionId, channel) {
+            requireTransaction(tx);
+            requireSessionId(watcherSessionId);
+            requireSessionId(subjectSessionId);
+            requireRelationType(channel);
+            const row = activeEdge(tx, watcherSessionId, subjectSessionId, channel);
+            if (!row)
+                failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+            return detach(tx, String(row.edge_id));
+        },
+        parents(sessionId, relationType, tx) {
+            return queryEdges(sessionId, relationType, tx, 'to');
+        },
+        children(sessionId, relationType, tx) {
+            return queryEdges(sessionId, relationType, tx, 'from');
+        },
+        subscriptions(sessionId, tx) {
+            return queryEdges(sessionId, undefined, tx, 'from');
+        },
+        recipients(subjectSessionId, tx) {
+            requireSessionId(subjectSessionId);
+            return withRead(tx, active => active.query(`SELECT DISTINCT from_session_id FROM topology_edges INDEXED BY topology_active_to
+         WHERE to_session_id=? AND removed_at_ms IS NULL ORDER BY from_session_id`, subjectSessionId).map(row => String(row.from_session_id)));
+        },
+    };
+}
+export { TopologyError };

package/node_modules/@spexcode/session-topology/dist/schema.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentMigration } from '@spexcode/session-protocol';
+export declare const TOPOLOGY_MIGRATION_SQL = "\nCREATE TABLE topology_edges (\n  edge_id          TEXT    NOT NULL PRIMARY KEY,\n  from_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),\n  to_session_id    TEXT    NOT NULL REFERENCES protocol_sessions(session_id),\n  relation_type    TEXT    NOT NULL,\n  created_at_ms    INTEGER NOT NULL,\n  removed_at_ms    INTEGER,\n  CHECK (length(edge_id) = 32 AND edge_id NOT GLOB '*[^0-9a-f]*'),\n  CHECK (from_session_id <> to_session_id),\n  CHECK (length(relation_type) BETWEEN 1 AND 64),\n  CHECK (relation_type NOT GLOB '*[^0-9A-Za-z._:-]*'),\n  CHECK (created_at_ms >= 0),\n  CHECK (removed_at_ms IS NULL OR removed_at_ms >= 0)\n) STRICT;\n\nCREATE UNIQUE INDEX topology_active_edge\n  ON topology_edges (from_session_id, to_session_id, relation_type)\n  WHERE removed_at_ms IS NULL;\n\nCREATE INDEX topology_active_to\n  ON topology_edges (to_session_id, relation_type, from_session_id)\n  WHERE removed_at_ms IS NULL;\n";
+export declare const TOPOLOGY_MIGRATIONS: readonly ComponentMigration[];

package/node_modules/@spexcode/session-topology/dist/schema.js

@@ -0,0 +1,27 @@
+export const TOPOLOGY_MIGRATION_SQL = `
+CREATE TABLE topology_edges (
+  edge_id          TEXT    NOT NULL PRIMARY KEY,
+  from_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  to_session_id    TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  relation_type    TEXT    NOT NULL,
+  created_at_ms    INTEGER NOT NULL,
+  removed_at_ms    INTEGER,
+  CHECK (length(edge_id) = 32 AND edge_id NOT GLOB '*[^0-9a-f]*'),
+  CHECK (from_session_id <> to_session_id),
+  CHECK (length(relation_type) BETWEEN 1 AND 64),
+  CHECK (relation_type NOT GLOB '*[^0-9A-Za-z._:-]*'),
+  CHECK (created_at_ms >= 0),
+  CHECK (removed_at_ms IS NULL OR removed_at_ms >= 0)
+) STRICT;
+
+CREATE UNIQUE INDEX topology_active_edge
+  ON topology_edges (from_session_id, to_session_id, relation_type)
+  WHERE removed_at_ms IS NULL;
+
+CREATE INDEX topology_active_to
+  ON topology_edges (to_session_id, relation_type, from_session_id)
+  WHERE removed_at_ms IS NULL;
+`;
+export const TOPOLOGY_MIGRATIONS = [
+    { version: 1, sql: TOPOLOGY_MIGRATION_SQL },
+];

package/node_modules/@spexcode/session-topology/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@spexcode/session-topology",
+  "version": "0.7.0-next.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "A neutral SQLite relation model for session addresses.",
+  "files": ["dist"],
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": { "@spexcode/session-protocol": "0.7.0-next.0" },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/node_modules/@spexcode/spec-cli/bin/spex.mjs

@@ -2,7 +2,8 @@
 // @@@ spex launcher ([[release-launcher]]) - package installs execute the package's compiled CLI directly;
 // tsx remains a development tool and never enters an adopter's runtime closure.
 import { spawn, spawnSync } from 'node:child_process'
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 
@@ -16,7 +17,19 @@ const workspace = join(pkg, '..')
 // carry unresolved conflict markers, so hooks keep the retryable exit-75 contract during a merge.
 const sourceRoot = join(pkg, 'src')
 if (existsSync(sourceRoot)) {
-  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'packages', 'session-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
+  const buildTargets = [
+    ['packages/session-protocol', 'dist/index.js'],
+    ['packages/session-topology', 'dist/index.js'],
+    ['packages/session-runtime', 'dist/index.js'],
+    ['packages/session-events', 'dist/index.js'],
+    ['packages/session-application', 'dist/index.js'],
+    ['packages/session-selflaunch', 'dist/index.js'],
+    ['packages/spec-core', 'dist/index.js'],
+    ['spec-eval', 'dist/index.js'],
+    ['spec-forge', 'dist/index.js'],
+    ['spec-cli', 'dist/cli.js'],
+  ]
+  const srcRoots = buildTargets.map(([packagePath]) => join(pkg, '..', packagePath, 'src'))
   const conflicted = srcRoots.flatMap((root) => {
     if (!existsSync(root)) return []
     return readdirSync(root, { recursive: true })
@@ -34,33 +47,174 @@ if (existsSync(sourceRoot)) {
   }
 
   // @@@ source-workspace build ([[release-launcher]]) - the git hooks invoke this launcher straight from a
-  // checkout, where dist is intentionally untracked. Rebuild the complete runtime closure before linting
-  // candidate source; an installed package has no src tree and stays a pure Node -> dist execution path.
+  // checkout, where dist is intentionally untracked. Import main's fresh closure and rebuild only changed
+  // packages plus dependents before linting candidate source; an untrusted baseline falls back to the complete
+  // ordered driver. Every package still publishes its dist atomically. An installed package has no src tree
+  // and stays a pure Node -> dist execution path.
   const runtimeEntries = [
     cli,
     join(workspace, 'packages', 'spec-core', 'dist', 'index.js'),
-    join(workspace, 'packages', 'session-core', 'dist', 'index.js'),
     join(workspace, 'spec-eval', 'dist', 'index.js'),
     join(workspace, 'spec-forge', 'dist', 'index.js'),
   ]
-  const newestSource = srcRoots.reduce((newest, root) => {
-    if (!existsSync(root)) return newest
-    for (const entry of readdirSync(root, { recursive: true })) {
-      const path = join(root, String(entry))
-      try {
-        if (/\.(ts|tsx|js|mjs)$/.test(path)) newest = Math.max(newest, statSync(path).mtimeMs)
-      } catch { /* a concurrent source edit can only make the next invocation rebuild again */ }
+  // Tests and declaration files are typecheck inputs, not runtime build inputs. Counting them here makes a
+  // harmless test edit look like a stale CLI and rebuilds every workspace on the next hook invocation.
+  const isRuntimeSource = (path) => {
+    return /\.(ts|tsx|js|mjs)$/.test(path)
+      && !/\.d\.ts$/.test(path)
+      && !/(^|[./])[^/]+\.test\.(ts|tsx|js|mjs)$/.test(path)
+  }
+  const newestRuntimeSource = (root) => {
+    const roots = buildTargets.map(([packagePath]) => join(root, packagePath, 'src'))
+    return roots.reduce((newest, root) => {
+      if (!existsSync(root)) return newest
+      for (const entry of readdirSync(root, { recursive: true })) {
+        const path = join(root, String(entry))
+        try {
+          if (isRuntimeSource(path)) newest = Math.max(newest, statSync(path).mtimeMs)
+        } catch { /* a concurrent source edit can only make the next invocation rebuild again */ }
+      }
+      return newest
+    }, 0)
+  }
+  const newestPackageSource = (root, packagePath) => {
+    const source = join(root, packagePath, 'src')
+    if (!existsSync(source)) return 0
+    let newest = 0
+    const visit = (dir) => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name)
+        if (entry.isDirectory()) visit(path)
+        else if (isRuntimeSource(path)) {
+          try { newest = Math.max(newest, statSync(path).mtimeMs) } catch { /* retry on the next launch */ }
+        }
+      }
     }
+    visit(source)
     return newest
-  }, 0)
-  const rebuild = runtimeEntries.some((entry) => {
-    try { return statSync(entry).mtimeMs < newestSource } catch { return true }
-  })
-  if (rebuild) {
-    const build = spawnSync('npm', ['run', 'build'], { cwd: workspace, stdio: 'inherit' })
-    if (build.error || build.status !== 0 || !existsSync(cli)) {
-      console.error('spex: source workspace build failed; fix it, then retry.')
-      process.exit(build.status ?? 1)
+  }
+  const entriesAreFresh = (root) => {
+    const newestSource = newestRuntimeSource(root)
+    return buildTargets.every(([packagePath, entry]) => {
+      try { return statSync(join(root, packagePath, entry)).mtimeMs >= newestSource } catch { return false }
+    })
+  }
+  const packageFingerprint = (root, packagePath) => {
+    const hash = createHash('sha256')
+    const packageRoot = join(root, packagePath)
+    const files = ['package.json', 'tsconfig.build.json'].map((name) => join(packageRoot, name)).filter(existsSync)
+    const visit = (dir, relative = '') => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name)
+        const child = relative ? `${relative}/${entry.name}` : entry.name
+        if (entry.isDirectory()) visit(path, child)
+        else if (isRuntimeSource(path)) files.push(path)
+      }
+    }
+    const source = join(packageRoot, 'src')
+    if (existsSync(source)) visit(source)
+    files.sort()
+    for (const path of files) hash.update(path.slice(packageRoot.length)).update('\0').update(readFileSync(path)).update('\0')
+    return hash.digest('hex')
+  }
+  const packageDependents = {
+    'packages/session-protocol': ['packages/session-topology', 'packages/session-runtime', 'packages/session-events', 'packages/session-application', 'packages/session-selflaunch', 'spec-cli'],
+    'packages/session-topology': ['packages/session-application', 'spec-cli'],
+    'packages/session-runtime': ['packages/session-application', 'packages/session-selflaunch', 'spec-cli'],
+    'packages/session-events': ['packages/session-application', 'spec-cli'],
+    'packages/session-application': ['spec-cli'],
+    'packages/session-selflaunch': ['spec-cli'],
+    'packages/spec-core': ['spec-eval', 'spec-forge', 'spec-cli'],
+    'spec-eval': ['spec-cli'],
+    'spec-forge': ['spec-cli'],
+    'spec-cli': [],
+  }
+  const changedBuildPackages = (root) => {
+    const changed = new Set(buildTargets
+      .map(([packagePath]) => packagePath)
+      .filter((packagePath) => packageFingerprint(workspace, packagePath) !== packageFingerprint(root, packagePath)))
+    for (const [packagePath, entry] of buildTargets) {
+      try {
+        if (statSync(join(root, packagePath, entry)).mtimeMs < newestPackageSource(workspace, packagePath)) changed.add(packagePath)
+      } catch { changed.add(packagePath) }
+    }
+    for (const packagePath of [...changed]) for (const dependent of packageDependents[packagePath]) changed.add(dependent)
+    return buildTargets.map(([packagePath]) => packagePath).filter((packagePath) => changed.has(packagePath))
+  }
+  const mainRoot = (() => {
+    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: workspace, encoding: 'utf8' })
+    if (result.status !== 0) return null
+    const commonDir = result.stdout.trim()
+    return commonDir ? dirname(commonDir) : null
+  })()
+  const reusableMainBuild = () => mainRoot && mainRoot !== workspace && entriesAreFresh(mainRoot)
+  const importMainBuild = () => {
+    for (const [packagePath] of buildTargets) {
+      const source = join(mainRoot, packagePath, 'dist')
+      const target = join(workspace, packagePath, 'dist')
+      const temporary = `${target}.from-main-${process.pid}`
+      const previous = `${target}.from-main-previous-${process.pid}`
+      rmSync(temporary, { recursive: true, force: true })
+      rmSync(previous, { recursive: true, force: true })
+      cpSync(source, temporary, { recursive: true })
+      if (existsSync(target)) renameSync(target, previous)
+      renameSync(temporary, target)
+      rmSync(previous, { recursive: true, force: true })
+    }
+  }
+  const sourceIsStale = () => {
+    const newestSource = newestRuntimeSource(workspace)
+    return runtimeEntries.some((entry) => {
+      try { return statSync(entry).mtimeMs < newestSource } catch { return true }
+    })
+  }
+  if (sourceIsStale()) {
+    // A hook, poller, and human shell can all invoke spex at once. The lock is deliberately at the
+    // launcher boundary: only one process pays the full workspace build, and waiters re-check freshness
+    // after the owner exits. A dead owner is recoverable; a live build gets two minutes before it is stale.
+    const buildLock = join(workspace, '.spex-build.lock')
+    const wait = new Int32Array(new SharedArrayBuffer(4))
+    const deadline = Date.now() + 120_000
+    let owner = false
+    while (!owner) {
+      try {
+        mkdirSync(buildLock)
+        owner = true
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error
+        try {
+          if (Date.now() - statSync(buildLock).mtimeMs > 120_000) rmSync(buildLock, { recursive: true, force: true })
+        } catch { /* the owner may have completed between the stat and the next check */ }
+        if (Date.now() >= deadline) {
+          console.error('spex: source workspace build lock did not clear; remove .spex-build.lock after confirming no build is running.')
+          process.exit(75)
+        }
+        Atomics.wait(wait, 0, 0, 100)
+      }
+    }
+    try {
+      if (sourceIsStale()) {
+        if (reusableMainBuild()) {
+          const changed = changedBuildPackages(mainRoot)
+          console.error(`spex: importing fresh runtime closure from main; rebuilding ${changed.length} package(s)`)
+          importMainBuild()
+          if (changed.length) {
+            const build = spawnSync(process.execPath, [join(workspace, 'scripts', 'build-workspaces.mjs'), ...changed], { cwd: workspace, stdio: 'inherit' })
+            if (build.error || build.status !== 0 || !existsSync(cli)) {
+              console.error('spex: source workspace selective build failed; fix it, then retry.')
+              process.exit(build.status ?? 1)
+            }
+          }
+        } else {
+          const build = spawnSync('npm', ['run', 'build'], { cwd: workspace, stdio: 'inherit' })
+          if (build.error || build.status !== 0 || !existsSync(cli)) {
+            console.error('spex: source workspace build failed; fix it, then retry.')
+            process.exit(build.status ?? 1)
+          }
+        }
+      }
+    } finally {
+      rmSync(buildLock, { recursive: true, force: true })
     }
   }
 }