feature-factory 0.7.0

package/core/effective-push.js

@@ -0,0 +1,88 @@
+import { spawnSync } from "node:child_process";
+
+const ARITY_ERROR = "factory effective-push: expected exactly three positional arguments: <bootstrap|check> <operator-repository> <sandbox-repository>";
+const EMPTY_ERROR = "factory effective-push: positional arguments must be non-empty";
+const OPERATION_ERROR = "factory effective-push: operation must be bootstrap or check";
+
+function failure(message) {
+  return new Error(message);
+}
+
+function execute(run, args) {
+  // No `encoding`: stdout stays a Buffer. Decoding to utf8 replaces every distinct
+  // invalid byte sequence with the same U+FFFD, so two unequal targets could compare
+  // equal here while `git push` used the original raw bytes. A local-path remote on
+  // Unix may legitimately hold non-UTF-8 bytes, so this is reachable, not theoretical.
+  return run("git", args, {
+    shell: false,
+    env: { ...process.env, LC_ALL: "C" },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function capture(run, repository) {
+  let result;
+  try {
+    result = execute(run, ["-C", repository, "remote", "get-url", "--push", "origin"]);
+  } catch {
+    return null;
+  }
+  if (!result || result.error || result.signal !== null && result.signal !== undefined
+    || result.status !== 0 || result.stdout === null || result.stdout === undefined) return null;
+  // A test double may still hand back a string; normalise to bytes either way.
+  const raw = Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(String(result.stdout), "utf8");
+  // Exactly one LF, because git contributes exactly one record terminator. Stripping every
+  // trailing LF would make a target that itself ends in LF indistinguishable from one that
+  // does not: operator bytes `path\n` are emitted as `path\n\n` and sandbox bytes `path` as
+  // `path\n`, and a greedy strip reduces both to `path` and accepts two unequal targets.
+  // Absent terminator means this is not the output shape being parsed, so fail closed.
+  if (raw.length === 0 || raw[raw.length - 1] !== 0x0a) return null;
+  const target = raw.subarray(0, raw.length - 1);
+  return target.length > 0 ? Buffer.from(target) : null;
+}
+
+// argv is bytes-as-string, so a target that does not survive a utf8 round trip cannot be
+// placed there without silently altering it. Refuse instead of configuring something other
+// than what was captured.
+function argvSafe(target) {
+  return Buffer.from(target.toString("utf8"), "utf8").equals(target);
+}
+
+function configure(run, repository, target) {
+  try {
+    return execute(run, ["-C", repository, "config", "--replace-all", "remote.origin.pushurl", target])?.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function enforceEffectivePushTarget(positionals, { spawnSync: run = spawnSync } = {}) {
+  if (!Array.isArray(positionals) || positionals.length !== 3) throw failure(ARITY_ERROR);
+  if (positionals.some((value) => typeof value !== "string" || value.length === 0)) throw failure(EMPTY_ERROR);
+  const [operation, operatorRepository, sandboxRepository] = positionals;
+  if (operation !== "bootstrap" && operation !== "check") throw failure(OPERATION_ERROR);
+
+  let operatorTarget = capture(run, operatorRepository);
+  if (operatorTarget === null) {
+    throw failure(`factory sandbox: operator effective push target unavailable; sandbox retained at ${sandboxRepository}`);
+  }
+  if (operation === "bootstrap") {
+    if (!argvSafe(operatorTarget)) {
+      throw failure(`factory sandbox: operator effective push target is not representable for configuration; sandbox retained at ${sandboxRepository}`);
+    }
+    if (!configure(run, sandboxRepository, operatorTarget.toString("utf8"))) {
+      throw failure(`factory sandbox: sandbox effective push target unavailable at ${sandboxRepository}`);
+    }
+    operatorTarget = capture(run, operatorRepository);
+    if (operatorTarget === null) {
+      throw failure(`factory sandbox: operator effective push target unavailable; sandbox retained at ${sandboxRepository}`);
+    }
+  }
+  const sandboxTarget = capture(run, sandboxRepository);
+  if (sandboxTarget === null) {
+    throw failure(`factory sandbox: sandbox effective push target unavailable at ${sandboxRepository}`);
+  }
+  if (!sandboxTarget.equals(operatorTarget)) {
+    throw failure(`factory sandbox: sandbox effective push target does not match operator target; sandbox retained at ${sandboxRepository}`);
+  }
+}

package/core/executable.js

@@ -0,0 +1,29 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { posix } from "node:path";
+
+// Resolves argv[0] the way observe's shell-free spawn does, so a passing seed check cannot be followed by a
+// spawn that fails for the same reason. POSIX only, and that boundary is enforced here rather than inferred:
+// a first version approximated Windows lookup and did not match it, and simply deleting the branch was worse
+// -- `observe` spawns cross-platform, nothing declares this package POSIX-only, so on Windows the check would
+// have split `PATH` on `:` and disagreed with the spawn it exists to predict. A guard that cannot establish
+// its claim must refuse, not guess.
+export function resolveSpawnExecutable(argv0, options = {}) {
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") return { ok: false, reason: "unsupported-platform", platform };
+  const cwd = options.cwd ?? process.cwd(), env = options.env ?? process.env;
+  const stat = options.stat ?? statSync, access = options.access ?? accessSync;
+  const defaultPath = options.posixDefaultPath ?? "/usr/bin:/bin", direct = argv0.includes("/");
+  const searchPath = Object.hasOwn(env, "PATH") ? env.PATH : null;
+  const source = searchPath === null ? `the POSIX default search path ${defaultPath}` : "POSIX PATH";
+  // An empty PATH entry means the current directory, which is why `entry || "."` is not a no-op.
+  const candidates = direct ? [posix.isAbsolute(argv0) ? argv0 : posix.resolve(cwd, argv0)]
+    : (searchPath ?? defaultPath).split(":").map((entry) => posix.join(posix.resolve(cwd, entry || "."), argv0));
+  for (const candidate of candidates) {
+    try {
+      if (!stat(candidate).isFile()) continue;
+      access(candidate, constants.X_OK);
+      return { ok: true, path: candidate, source: direct ? "its direct path" : source };
+    } catch {}
+  }
+  return { ok: false, reason: "not-executable", source: direct ? "its direct path" : source };
+}

package/core/run-lock.js

@@ -0,0 +1,269 @@
+// Ported unchanged from src/run-state.js:120-485 (the run-json lock cluster).
+// The 0c spike reused this lock as-is, which is why it is lifted rather than
+// rewritten: hand-rolling lock reclaim and steal logic is where subtle crash bugs
+// live. Only the imports and the extracted constants below are new.
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
+const DEFAULT_LOCK_TIMEOUT_MS = 1000;
+const DEFAULT_LOCK_RETRY_DELAY_MS = 10;
+const DEFAULT_STALE_LOCK_MS = 60000;
+const DEFAULT_MISSING_OWNER_STEAL_MS = 5000;
+const LOCK_DIR = "run-json.lock";
+const LOCK_OWNER_FILE = "owner.json";
+
+export async function withRunJsonLock(runDir, fn, options = {}) {
+  if (typeof fn !== "function") throw new Error("withRunJsonLock requires a callback");
+  const { onBeforeSteal } = options;
+  if (onBeforeSteal !== undefined && typeof onBeforeSteal !== "function") {
+    throw new Error("onBeforeSteal must be a function");
+  }
+  const timeoutMs = normalizePositiveInteger(options.timeoutMs, DEFAULT_LOCK_TIMEOUT_MS);
+  normalizePositiveInteger(options.staleLockMs, DEFAULT_STALE_LOCK_MS);
+  normalizePositiveInteger(options.missingOwnerStealMs, DEFAULT_MISSING_OWNER_STEAL_MS);
+  const lockDir = join(runDir, LOCK_DIR);
+  const ownerPath = join(lockDir, LOCK_OWNER_FILE);
+  const deadline = Date.now() + timeoutMs;
+  let stealAttempted = false;
+  let createdIdentity = null;
+  let owner = null;
+  let ownerPublished = false;
+  let publishedEvidence = null;
+
+  while (true) {
+    try {
+      await mkdir(lockDir);
+      createdIdentity = await lockDirectoryIdentity(lockDir);
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      if (!stealAttempted) {
+        const observedIdentity = await lockDirectoryIdentity(lockDir);
+        const observedEvidence = await readLockOwnerEvidence(ownerPath);
+        if (canStealRunJsonLock(observedEvidence?.owner, options)) {
+          stealAttempted = true;
+          if (observedIdentity && await stealByRename(runDir, lockDir, observedIdentity, observedEvidence, onBeforeSteal)) continue;
+        } else if (!observedEvidence && await ownerlessLockIsReclaimable(lockDir, ownerPath, options)) {
+          stealAttempted = true;
+          if (observedIdentity && await stealByRename(runDir, lockDir, observedIdentity, null, onBeforeSteal)) continue;
+        }
+      }
+      if (Date.now() >= deadline) throw new Error(`timed out waiting for run.json lock at ${lockDir}`);
+      await delay(Math.min(DEFAULT_LOCK_RETRY_DELAY_MS, Math.max(1, deadline - Date.now())));
+    }
+  }
+
+  owner = { pid: process.pid, hostname: hostname(), acquired_at: new Date().toISOString(), nonce: randomUUID() };
+
+  try {
+    if (!sameLockDirectoryIdentity(createdIdentity, await lockDirectoryIdentity(lockDir))) {
+      throw new Error(`run.json lock ownership changed before owner publication at ${lockDir}`);
+    }
+    await writeFile(ownerPath, `${JSON.stringify(owner, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+    publishedEvidence = await readLockOwnerEvidence(ownerPath);
+    if (!sameLockOwner(owner, publishedEvidence?.owner)) throw new Error(`run.json lock owner publication failed at ${lockDir}`);
+    ownerPublished = true;
+    return await fn({ lock_dir: lockDir, owner });
+  } finally {
+    if (ownerPublished) {
+      await releaseOwnedRunJsonLock(runDir, lockDir, createdIdentity, publishedEvidence);
+    } else if (!ownerPublished && !(await lockOwnerEntryExists(ownerPath))) {
+      await quarantineAndRemoveOwnedLock(runDir, lockDir, createdIdentity);
+    }
+  }
+}
+
+function canStealRunJsonLock(owner, options = {}) {
+  return isDurableLockOwner(owner) && inspectLockOwnerLiveness(owner, options) === "dead";
+}
+
+async function readLockOwnerEvidence(ownerPath) {
+  let handle;
+  try {
+    handle = await open(ownerPath, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const parsed = JSON.parse(await handle.readFile("utf8"));
+    if (!isDurableLockOwner(parsed)) return null;
+    const value = await handle.stat();
+    return { owner: parsed, identity: { dev: value.dev, ino: value.ino } };
+  } catch {
+    return null;
+  } finally {
+    await handle?.close();
+  }
+}
+
+// Stealing a stale lock is one atomic rename.
+//
+// A nonce-keyed reclaim-claim protocol used to guard this, re-verifying a claim
+// file four times across the steal. It was unnecessary: `rename` is atomic, so of
+// two racers exactly one succeeds and the loser gets ENOENT and retries the
+// acquire loop. More importantly the lock is not the correctness boundary - the
+// write core re-reads run.json and deep-compares it immediately before its own
+// rename, so even a wrongly stolen lock cannot produce a lost update. The
+// ceremony was protecting the lock as though the lock were the invariant.
+//
+// The identity check still earns its place: it refuses to rename away a lock that
+// is no longer the one we judged stale, which is the case where another process
+// already stole and re-acquired.
+async function stealByRename(runDir, lockDir, observedIdentity, observedEvidence, onBeforeSteal) {
+  if (onBeforeSteal) await onBeforeSteal({ runDir, lockDir, owner: observedEvidence?.owner ?? null });
+  // The owner must still be the one we judged stale, and the directory's dev/ino cannot establish
+  // that: Linux reuses inode numbers, so a lock deleted and recreated here presents the identity we
+  // recorded and the post-rename check sees nothing wrong while a live lock is renamed away. The
+  // nonce is the discriminator. The note that once stood here — a pre-check is undetectable — was
+  // falsified only on APFS, which does not reuse the inode; CI failed on Linux and passed on macOS.
+  // The post-rename check stays, the two together are narrower, and the write core is still the
+  // real boundary, so the residual check-then-act window cannot produce a lost update.
+  if (observedEvidence
+    && !sameLockOwnerEvidence(observedEvidence, await readLockOwnerEvidence(join(lockDir, LOCK_OWNER_FILE)))) {
+    return false;
+  }
+  let quarantine;
+  try {
+    quarantine = await renameOwnedLockToQuarantine(runDir, lockDir, observedIdentity);
+  } catch (error) {
+    // Losing the race is a retry, not a failure: ENOENT is the rename losing the path, ELOCKIDENTITY
+    // is noticing the winner before renaming. Only ENOENT was handled, so the second case failed the
+    // whole run — rare until the owner pre-check widened that window, and then CI hit it.
+    if (error?.code === "ENOENT" || error?.code === "ELOCKIDENTITY") return false;
+    throw error;
+  }
+  await rm(quarantine, { recursive: true, force: true });
+  return true;
+}
+
+async function releaseOwnedRunJsonLock(runDir, lockDir, expectedIdentity, expectedEvidence) {
+  if (!sameLockDirectoryIdentity(expectedIdentity, await lockDirectoryIdentity(lockDir))) return;
+  if (!sameLockOwnerEvidence(expectedEvidence, await readLockOwnerEvidence(join(lockDir, LOCK_OWNER_FILE)))) return;
+  const quarantine = await renameOwnedLockToQuarantine(runDir, lockDir, expectedIdentity);
+  if (!sameLockOwnerEvidence(expectedEvidence, await readLockOwnerEvidence(join(quarantine, LOCK_OWNER_FILE)))) {
+    throw new Error(`run.json lock cleanup identity changed at ${quarantine}`);
+  }
+  if (!sameLockDirectoryIdentity(expectedIdentity, await lockDirectoryIdentity(quarantine))
+    || !sameLockOwnerEvidence(expectedEvidence, await readLockOwnerEvidence(join(quarantine, LOCK_OWNER_FILE)))) return;
+  await rm(quarantine, { recursive: true, force: true });
+}
+
+async function quarantineAndRemoveOwnedLock(runDir, lockDir, expectedIdentity) {
+  if (!sameLockDirectoryIdentity(expectedIdentity, await lockDirectoryIdentity(lockDir))) return;
+  const quarantine = await renameOwnedLockToQuarantine(runDir, lockDir, expectedIdentity);
+  if (!sameLockDirectoryIdentity(expectedIdentity, await lockDirectoryIdentity(quarantine))) return;
+  await rm(quarantine, { recursive: true, force: true });
+}
+
+async function renameOwnedLockToQuarantine(runDir, lockDir, expectedIdentity) {
+  if (!sameLockDirectoryIdentity(expectedIdentity, await lockDirectoryIdentity(lockDir))) {
+    // Coded so a *steal* can treat it as losing a race and retry. Release and cleanup check identity
+    // first, so for them it stays the error it is.
+    throw Object.assign(new Error(`run.json lock directory identity changed at ${lockDir}`), { code: "ELOCKIDENTITY" });
+  }
+  const quarantine = join(runDir, `.run-json.lock-quarantine-${randomUUID()}`);
+  await rename(lockDir, quarantine);
+  if (!sameLockDirectoryIdentity(expectedIdentity, await lockDirectoryIdentity(quarantine))) {
+    throw new Error(`run.json lock quarantine identity changed at ${quarantine}`);
+  }
+  return quarantine;
+}
+
+// Staleness is decided by TTL on `acquired_at`, not process identity: this lock spans
+// one transition, so exceeding the TTL means its holder is gone. Immediate dead-owner
+// probing adds complexity for convenience rather than correctness in a single-operator tool.
+function inspectLockOwnerLiveness(owner, options = {}) {
+  if (!isDurableLockOwner(owner)) return "indeterminate";
+  // A lock taken on another host cannot be adjudicated from here at all.
+  if (owner.hostname !== hostname()) return "indeterminate";
+  const staleAfterMs = normalizePositiveInteger(options.staleLockMs, DEFAULT_STALE_LOCK_MS);
+  const heldForMs = Date.now() - Date.parse(owner.acquired_at);
+  if (!Number.isFinite(heldForMs)) return "indeterminate";
+  // A future `acquired_at` yields a negative age, which is never greater than the
+  // TTL, so clock skew already fails closed here. An explicit `heldForMs < 0`
+  // branch was removed after its falsification showed removing it changed nothing.
+  return heldForMs > staleAfterMs ? "dead" : "alive";
+}
+
+async function lockOwnerEntryExists(ownerPath) {
+  try {
+    await lstat(ownerPath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    return true;
+  }
+}
+
+function isDurableLockOwner(owner) {
+  return isRecord(owner)
+    && Number.isInteger(owner.pid)
+    && owner.pid > 0
+    && stringValue(owner.hostname)
+    && Number.isFinite(Date.parse(owner.acquired_at || ""))
+    && typeof owner.nonce === "string"
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(owner.nonce);
+}
+
+function sameLockOwner(left, right) {
+  return isDurableLockOwner(left) && isDurableLockOwner(right) && left.nonce === right.nonce;
+}
+
+function sameLockOwnerEvidence(left, right) {
+  return Boolean(left && right
+    && sameLockOwner(left.owner, right.owner)
+    && left.identity.dev === right.identity.dev
+    && left.identity.ino === right.identity.ino);
+}
+
+async function lockDirectoryIdentity(lockDir) {
+  try {
+    const value = await lstat(lockDir);
+    if (!value.isDirectory() || value.isSymbolicLink()) return null;
+    return { dev: value.dev, ino: value.ino, mtimeMs: value.mtimeMs };
+  } catch {
+    return null;
+  }
+}
+
+function sameLockDirectoryIdentity(left, right) {
+  return Boolean(left && right && left.dev === right.dev && left.ino === right.ino);
+}
+
+function normalizePositiveInteger(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  if (!Number.isInteger(value) || value <= 0) throw new Error("lock timing options must be positive integers");
+  return value;
+}
+
+// Small local helpers, lifted with the cluster.
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// An ownerless lock is a directory with no valid owner record: a crash between the
+// mkdir and publishing owner.json. It is only reclaimable after a grace window,
+// because that gap is microseconds wide in the normal case and stealing inside it
+// would take a lock from a process that is about to publish.
+//
+// This replaces a canReclaimOwnerlessRunJsonLock that was deleted during the reclaim
+// simplification while its call site remained — a live ReferenceError on the
+// ownerless path, found by opencode.
+async function ownerlessLockIsReclaimable(lockDir, ownerPath, options = {}) {
+  if (await lockOwnerEntryExists(ownerPath)) return false;
+  const graceMs = normalizePositiveInteger(options.missingOwnerStealMs, DEFAULT_MISSING_OWNER_STEAL_MS);
+  try {
+    const observed = await stat(lockDir);
+    const ageMs = Date.now() - observed.mtimeMs;
+    return Number.isFinite(ageMs) && ageMs > graceMs;
+  } catch {
+    return false;
+  }
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}

package/core/write-core.js

@@ -0,0 +1,146 @@
+import { readFile, rename } from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
+import { join } from "node:path";
+import { writeProtectedJsonAtomic } from "./atomic-write.js";
+import { withRunJsonLock } from "./run-lock.js";
+
+const RUN_FILE = "run.json";
+
+export async function coordinateRunJsonTransition(runDir, options) {
+  const {
+    contracts,
+    descriptor,
+    validateRun,
+    reobservers = new Map(),
+    atomicWriteHooks,
+    finalGuard,
+  } = options ?? {};
+  const registry = contractRegistry(contracts);
+  const participants = participantRegistry(descriptor, registry);
+  if (typeof validateRun !== "function") throw new Error("validateRun must be a function");
+  if (!(reobservers instanceof Map)) throw new Error("reobservers must be a Map");
+
+  return withRunJsonLock(runDir, async () => {
+    const initial = deepFreeze(await readRunState(runDir, validateRun));
+    const before = projectAll(registry, initial);
+    const applied = descriptor.apply(structuredClone(initial));
+    if (!applied || typeof applied !== "object" || Array.isArray(applied)) {
+      throw new Error("transition apply must return a state object");
+    }
+    validateRun(applied);
+    const candidate = deepFreeze(applied);
+    const after = projectAll(registry, candidate);
+
+    for (const [familyId, contract] of registry) {
+      contract.validateTransition({
+        mode: participants.get(familyId),
+        before: before.get(familyId),
+        after: after.get(familyId),
+        current: initial,
+        candidate,
+      });
+    }
+
+    await writeProtectedJsonAtomic(runDir, RUN_FILE, candidate, {
+      hooks: atomicWriteHooks,
+      fsOps: {
+        rename: async (source, destination) => {
+
+          // First comparison: gives the reobservers a state to reason about that is
+          // known current as of this moment.
+          const observed = deepFreeze(await readRunState(runDir, validateRun));
+          assertUnchanged(observed, initial);
+
+          const observedProjections = projectAll(registry, observed);
+          for (const [familyId, contract] of registry) {
+            await contract.reobserve({
+              mode: participants.get(familyId),
+              current: observedProjections.get(familyId),
+              candidate: after.get(familyId),
+              observe: reobservers.get(familyId),
+              state: observed,
+              nextState: candidate,
+            });
+          }
+
+          // Second comparison, immediately before the rename and after anything the
+          // reobservers did. Comparing only once left a window: a reobserver - or a
+          // concurrent writer running while one awaited - could commit a valid
+          // record after the check, and this rename would silently overwrite it.
+          // Only the synchronous final guard may run between this line and the rename.
+          const finalObserved = deepFreeze(await readRunState(runDir, validateRun));
+          assertUnchanged(finalObserved, initial);
+          if (typeof finalGuard === "function") {
+            const guarded = finalGuard({ state: finalObserved, candidate });
+            if (guarded && typeof guarded.then === "function") throw new Error("final commit guard must be synchronous");
+          }
+          await rename(source, destination);
+        },
+      },
+    });
+    return candidate;
+  });
+}
+
+function assertUnchanged(observed, initial) {
+  if (!isDeepStrictEqual(observed, initial)) {
+    throw new Error("run state changed before protected replacement");
+  }
+}
+
+async function readRunState(runDir, validateRun) {
+  const state = JSON.parse(await readFile(join(runDir, RUN_FILE), "utf8"));
+  return validateRun(state);
+}
+
+function contractRegistry(contracts) {
+  if (!Array.isArray(contracts) || !Object.isFrozen(contracts)) {
+    throw new Error("contracts must be a frozen array");
+  }
+  const registry = new Map();
+  for (const contract of contracts) {
+    if (!contract || !Object.isFrozen(contract) || typeof contract.id !== "string" || !contract.id) {
+      throw new Error("each contract must be frozen and have an id");
+    }
+    for (const method of ["project", "validateProjection", "validateTransition", "reobserve"]) {
+      if (typeof contract[method] !== "function") throw new Error(`contract '${contract.id}' is missing ${method}`);
+    }
+    if (registry.has(contract.id)) throw new Error(`duplicate contract '${contract.id}'`);
+    registry.set(contract.id, contract);
+  }
+  return registry;
+}
+
+function participantRegistry(descriptor, contracts) {
+  if (!descriptor || !Object.isFrozen(descriptor) || typeof descriptor.apply !== "function"
+    || !Array.isArray(descriptor.participants) || !Object.isFrozen(descriptor.participants)) {
+    throw new Error("descriptor and participants must be frozen");
+  }
+  const participants = new Map();
+  for (const participant of descriptor.participants) {
+    if (!participant || !Object.isFrozen(participant) || typeof participant.familyId !== "string"
+      || !participant.familyId || typeof participant.mode !== "string" || !participant.mode) {
+      throw new Error("each participant must be frozen and declare familyId and mode");
+    }
+    if (!contracts.has(participant.familyId)) throw new Error(`unknown contract '${participant.familyId}'`);
+    if (participants.has(participant.familyId)) throw new Error(`duplicate participant '${participant.familyId}'`);
+    participants.set(participant.familyId, participant.mode);
+  }
+  return participants;
+}
+
+function projectAll(contracts, state) {
+  const projections = new Map();
+  for (const [familyId, contract] of contracts) {
+    const projection = contract.project(state);
+    contract.validateProjection(projection);
+    projections.set(familyId, projection);
+  }
+  return projections;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const nested of Object.values(value)) deepFreeze(nested);
+  return Object.freeze(value);
+}