@gate-forge/pack-playwright 0.7.1 → 0.9.0

package/dist/discovery/prepare-barrier.js

@@ -0,0 +1,739 @@
+/**
+ * The GLOBAL native preparation freeze barrier (contract: "ONE native
+ * process, ONE GLOBAL prepared snapshot").
+ *
+ * Why this exists. A Playwright config's prerequisite (`setup`) projects
+ * produce their artifacts — the saved `playwright/.auth/user.json` of the
+ * standard auth pattern above all — WHILE the behavioral projects are
+ * already scheduled to run. Gateforge's candidate freeze, on the other
+ * hand, is taken BEFORE the runner starts, so a run whose setup writes
+ * generated bytes into the workspace always ends with a candidate tree
+ * that no longer equals the frozen one, and no receipt is ever sealed.
+ * That is the honest failure this module removes — not by excluding the
+ * generated bytes (that would weaken every binding), but by taking ONE
+ * prepared snapshot AFTER the whole prerequisite stage and BEFORE any
+ * body project, and then demanding the workspace stay exactly that.
+ *
+ * The shape of the barrier, and why each part exists:
+ *
+ * - ONE controller project. The engine adds a project of its own that
+ *   depends on the FULL upstream prerequisite closure of the planned
+ *   graph, and gives every non-prerequisite planned project that
+ *   controller as its FIRST dependency (its own captured edges follow,
+ *   unchanged, in their emitted order). Prerequisites keep their edges
+ *   exactly as captured. The runner's own phase scheduler then orders
+ *   prerequisite → controller → body inside ONE process, with the
+ *   runner's real dependency semantics — not a second process, not a flag.
+ * - The controller is a real Playwright test, because the environment
+ *   leak it has to undo happens in WORKERS: the native scheduler unions
+ *   every dependency worker's produced environment into its dependents
+ *   (`runner/tasks.js`), so merely emitting an empty controller project
+ *   would hand each body the whole preparation environment.
+ * - A REQUEST/RELEASE handshake. The controller writes a request naming
+ *   the exact run, invocation and per-invocation nonce; the trusted CLI
+ *   — the only process holding supervisor credentials — validates every
+ *   prerequisite identity against the authenticated witness execution
+ *   trace, freezes, and answers with a SIGNED release. A request that
+ *   never comes, an unsigned release, a release for another
+ *   run/invocation/nonce, and a release whose bound controller spec
+ *   bytes no longer hash to what the CLI pinned are all refusals, and a
+ *   controller that never receives a valid release fails its own bounded
+ *   wait instead of letting the bodies run unfrozen.
+ * - An ephemeral Ed25519 signature. A release is a file, and a file at
+ *   this boundary is forgeable by any code running as the same user. The
+ *   private key is minted per invocation and never leaves the CLI
+ *   process — never a child environment, never a file; the controller
+ *   receives only the public key. Same-UID modify/restore or in-process
+ *   tampering stays OUTSIDE this boundary (this is not a filesystem
+ *   sandbox); what the signature closes is an ordinary control-file
+ *   forgery and any replay of an older or different release.
+ *
+ * Honesty boundary (repeated on purpose): this is a CONTROL barrier, not
+ * a physical one. It orders one native process, proves the prerequisites
+ * really passed under supervision, and proves the workspace did not move
+ * between the freeze and the seal. It does not make the source read-only.
+ */
+import { createHash, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+/** The engine-owned controller project name (never a candidate project). */
+export const FREEZE_CONTROLLER_PROJECT = 'gateforge-freeze';
+/**
+ * Directory (inside the excluded run-state dir) holding the barrier's
+ * handshake DOCUMENTS — the controller's request, the CLI's signed
+ * release and its refusal document. They are evidence about the run,
+ * not test-shaped files, so they stay where the CLI pins and seals
+ * them.
+ *
+ * The generated controller SPEC is deliberately NOT here: a `.mjs` spec
+ * file inside the repository is a file a consumer's own Playwright
+ * configuration can collect (see {@link FREEZE_CONTROL_SPEC_FILE}).
+ */
+export const FREEZE_CONTROL_DIR = 'native-freeze';
+/**
+ * The generated controller spec: the ONE worker that performs the handshake.
+ *
+ * Plain ESM JavaScript under an `.mjs` name, deliberately. The runner
+ * decides a file's module kind from its extension first and only then from
+ * the nearest `package.json` `type`, and a consumer repository may sit
+ * under EITHER: a CommonJS/default root would have this spec `require`d,
+ * which turns its ESM imports into `require()` of a `file:` URL and fails
+ * to load at all. `.mjs` fixes the module kind on the file itself, so the
+ * controller's imports resolve as real ESM imports whatever the
+ * consumer's root package says — no manifest inspection, no install
+ * restriction, and no candidate module ever loaded by the CLI. The
+ * consequence is that the generated bytes must stay plain JavaScript:
+ * nothing TypeScript-only may reappear in the template below.
+ *
+ * WHERE the file is written follows from what it IS: a parseable test
+ * file. Inside the repository it is a candidate the consumer's own
+ * runner collects — a config at the repo root with no restricting
+ * `testDir` enumerates every parseable file below it, so an engine spec
+ * parked in the run-state subtree was still enumerated as a consumer
+ * case, by the engine's own `--list` and by the owner's `npx playwright
+ * test` alike. It is therefore written into a private per-run directory
+ * OUTSIDE the repository ({@link FreezeControl.specDir}) and removed
+ * once the run no longer reads it.
+ */
+export const FREEZE_CONTROL_SPEC_FILE = 'freeze-controller.spec.mjs';
+/** The controller's request document (written by the controller worker). */
+export const FREEZE_REQUEST_FILE = 'freeze-request.json';
+/** The CLI's signed release document (read by the controller worker). */
+export const FREEZE_RELEASE_FILE = 'freeze-release.json';
+/**
+ * The trusted CLI's REFUSAL document (read by the controller worker).
+ *
+ * The handshake needs a failure channel as well as a success one, or a
+ * permanent refusal turns into a bounded-but-slow timeout: the trusted
+ * side answers "your prerequisite sealed as failed", and the controller
+ * should stop waiting the moment it hears that, not poll to its own long
+ * bound. This file is FAILURE ONLY. Nothing here can ever unblock a body
+ * project — only a correctly signed `FREEZE_RELEASE_FILE` does — so a
+ * controller that trusts this document can only ever fail earlier, never
+ * proceed. A forged refusal therefore costs a run its barrier, which the
+ * signing already guarantees; a missing one costs nothing.
+ */
+export const FREEZE_REFUSAL_FILE = 'freeze-refusal.json';
+/**
+ * Environment names the runner itself owns in every worker process, and
+ * which the projection must therefore never touch.
+ *
+ * The reason is structural, read from the runner itself:
+ * `worker/workerMain.js` assigns `TEST_WORKER_INDEX` and
+ * `TEST_PARALLEL_INDEX` AFTER the process booted, and
+ * `runner/workerHost.js` spreads `FORCE_COLOR` and `DEBUG_COLORS` into
+ * every worker's environment at spawn. `lib/common/process.js` computes
+ * the produced-environment diff against the worker's OWN boot
+ * environment, so all four names appear in a produced diff without any
+ * prerequisite having written them — a subtraction reset that touched
+ * them would report a deletion the bodies then inherit.
+ *
+ * The reset set is otherwise derived BY SUBTRACTION — every key in the
+ * controller's environment or in the trusted baseline, minus these four.
+ * That is equivalent to a positively-owned namespace ONLY under the
+ * invariant below, and the invariant is the real risk: nothing in the
+ * run pins it, so a future change that starts injecting environment into
+ * workers beyond these names would be silently projected away rather
+ * than reported.
+ *
+ * Gateforge injects nothing into worker environment beyond the runner
+ * child's own baseline: `buildRunnerChildEnv` refuses run-state paths
+ * and signing material, and the freeze control reaches the controller
+ * inlined in its generated spec rather than through the environment.
+ * Under that invariant the worker's environment is the baseline, plus
+ * preparation-written keys, plus these four names — so the reset set is
+ * exactly the baseline keys a prerequisite overrode (restored) and the
+ * keys a prerequisite introduced (deleted), whatever they are named.
+ */
+export const FREEZE_ENV_EXEMPT = [
+    'TEST_WORKER_INDEX',
+    'TEST_PARALLEL_INDEX',
+    'FORCE_COLOR',
+    'DEBUG_COLORS',
+];
+/**
+ * Deterministic canonical JSON: object keys sorted, no insignificant
+ * whitespace. The CLI signs exactly these bytes and the controller
+ * verifies exactly these bytes, so neither side may depend on a property
+ * order or a serializer default.
+ *
+ * @param value: any JSON-compatible value.
+ *
+ * @returns
+ *   string: the canonical form.
+ */
+export function canonicalFreezeJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((entry) => canonicalFreezeJson(entry)).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalFreezeJson(record[key])}`)
+        .join(',')}}`;
+}
+/**
+ * Mints one ephemeral Ed25519 key pair for the release signature. The
+ * private key is returned to the CLI and NEVER written anywhere: not the
+ * trusted config, not the run state, not a child environment.
+ *
+ * @returns
+ *   FreezeSigningKeyPair: the pair, with the public key already
+ *   base64-encoded as raw SPKI.
+ */
+export function mintFreezeSigningKeyPair() {
+    const pair = generateKeyPairSync('ed25519');
+    const spki = pair.publicKey.export({ format: 'der', type: 'spki' });
+    return {
+        publicKey: pair.publicKey,
+        publicKeyBase64: spki.toString('base64'),
+        privateKey: pair.privateKey,
+    };
+}
+/**
+ * Signs one release payload with the invocation's ephemeral private key.
+ *
+ * @param privateKey: the ephemeral key (CLI memory only).
+ * @param payload: the payload to sign.
+ *
+ * @returns
+ *   FreezeReleaseDocument: the document the controller verifies.
+ */
+export function signFreezeRelease(privateKey, payload) {
+    const signature = sign(null, Buffer.from(canonicalFreezeJson(payload), 'utf8'), privateKey);
+    return { schemaVersion: 1, payload, signature: signature.toString('base64') };
+}
+/**
+ * Verifies one release document against the pinned public key and the
+ * exact identities the controller itself was armed with.
+ *
+ * A release passes only when ALL of these hold: the document shape, the
+ * Ed25519 signature under the pinned key, the controller project name, the
+ * run, the invocation, the per-invocation nonce, and the sha256 of the
+ * controller's OWN current spec bytes. The last check is what makes a
+ * replaced control file detectable rather than trusted.
+ *
+ * @param document: the parsed release document.
+ * @param publicKeyBase64: the pinned base64 raw SPKI public key.
+ * @param expected: the identities and spec digest the controller was armed with.
+ *
+ * @returns
+ *   {ok: true, payload} | {ok: false, reason}: the verified payload, or the
+ *   single plain reason the release was refused.
+ */
+export function verifyFreezeRelease(document, publicKeyBase64, expected) {
+    if (typeof document !== 'object' || document === null) {
+        return { ok: false, reason: 'the freeze release is not an object' };
+    }
+    const row = document;
+    if (row['schemaVersion'] !== 1 || typeof row['signature'] !== 'string') {
+        return { ok: false, reason: 'the freeze release is missing its signature' };
+    }
+    const payload = row['payload'];
+    if (typeof payload !== 'object' || payload === null) {
+        return { ok: false, reason: 'the freeze release carries no payload' };
+    }
+    const fields = payload;
+    if (fields['schemaVersion'] !== 1) {
+        return { ok: false, reason: 'the freeze release payload has an unknown schema version' };
+    }
+    for (const key of ['project', 'runId', 'invocationId', 'nonce', 'preparedTreeId', 'specDigest', 'sealedAt']) {
+        if (typeof fields[key] !== 'string' || fields[key].length === 0) {
+            return { ok: false, reason: `the freeze release payload has no ${key}` };
+        }
+    }
+    let signatureOk = false;
+    try {
+        signatureOk = verify(null, Buffer.from(canonicalFreezeJson(fields), 'utf8'), createPublicKey({ key: Buffer.from(publicKeyBase64, 'base64'), format: 'der', type: 'spki' }), Buffer.from(row['signature'], 'base64'));
+    }
+    catch {
+        signatureOk = false;
+    }
+    if (!signatureOk) {
+        return { ok: false, reason: 'the freeze release is unsigned or signed by another key' };
+    }
+    if (fields['project'] !== expected.project) {
+        return { ok: false, reason: 'the freeze release names another controller project' };
+    }
+    if (fields['runId'] !== expected.runId || fields['invocationId'] !== expected.invocationId) {
+        return { ok: false, reason: 'the freeze release belongs to another run or invocation' };
+    }
+    if (fields['nonce'] !== expected.nonce) {
+        return { ok: false, reason: 'the freeze release was minted for another nonce (a replayed release)' };
+    }
+    if (fields['specDigest'] !== expected.specDigest) {
+        return { ok: false, reason: 'the controller control spec no longer matches the bytes the run pinned' };
+    }
+    return { ok: true, payload: fields };
+}
+/**
+ * Projects one worker environment back to the trusted baseline the runner
+ * child started with.
+ *
+ * The native scheduler unions every dependency worker's produced
+ * environment into its dependents, so a body worker inherits whatever a
+ * prerequisite worker assigned — including a deleted key, which the
+ * scheduler carries as `undefined` and Node then simply omits from the
+ * child. This restores exactly that difference: every name the trusted
+ * baseline OWNS goes back to its own value, and every name the baseline
+ * never owned is removed. The keys Playwright's own worker bootstrap
+ * writes ({@link FREEZE_ENV_EXEMPT}) are left alone — they are the
+ * runner's, not a prerequisite's.
+ *
+ * Both sides are read by OWN membership, never through an inherited
+ * lookup, because the names at stake are ordinary environment names the
+ * runner itself spawns workers with: `constructor`, `toString` and
+ * `__proto__` are each a property every plain object inherits, so a
+ * baseline read as `base[key]` reports those as owned values of `Object`,
+ * `Object.prototype.toString` and `Object.prototype` itself and hands
+ * the body worker that instead of deleting what a prerequisite
+ * introduced. No prefix restriction avoids that, and none is acceptable.
+ *
+ * The restore side is therefore a `defineProperty`, not an assignment:
+ * on an ordinary object an assignment to `__proto__` does not create an
+ * own key at all — the inherited accessor swallows it — so a baseline
+ * name a prerequisite deleted could never be put back.
+ *
+ * @param current: the controller worker's own environment (mutated in place).
+ * @param base: the trusted runner child's baseline environment.
+ * @param exempt: names the projection must not touch.
+ *
+ * @returns
+ *   BaselineEnvProjection: what the projection changed, sorted, for the
+ *   controller's own diagnostic.
+ */
+export function projectBaselineEnv(current, base, exempt = FREEZE_ENV_EXEMPT) {
+    const skip = new Set(exempt);
+    const restored = [];
+    const deleted = [];
+    // One value descriptor for the whole projection, allocated on the first
+    // restoration and reused: every name needs the same configurable,
+    // writable, enumerable shape, and one descriptor avoids a per-key
+    // allocation in the one worker that runs on this path.
+    let descriptor;
+    for (const key of Object.keys(base)) {
+        if (skip.has(key))
+            continue;
+        const want = base[key];
+        if (Object.hasOwn(current, key) && current[key] === want)
+            continue;
+        if (descriptor === undefined) {
+            descriptor = { value: want, writable: true, enumerable: true, configurable: true };
+        }
+        else {
+            descriptor.value = want;
+        }
+        Object.defineProperty(current, key, descriptor);
+        restored.push(key);
+    }
+    // `Object.keys` is own-only, so a name the baseline never owned is an
+    // OWN entry a prerequisite introduced, whatever its value: an own entry
+    // the scheduler carries as `undefined` is still an entry no baseline
+    // ever had, and the worker must not keep it. A name that is only
+    // inherited is not an entry and is never reached here.
+    for (const key of Object.keys(current)) {
+        if (skip.has(key) || Object.hasOwn(base, key))
+            continue;
+        delete current[key];
+        deleted.push(key);
+    }
+    restored.sort();
+    deleted.sort();
+    return { restored, deleted };
+}
+/**
+ * Resolves the engine barrier module the generated controller imports.
+ * Absolute and pack-relative for the same reason the trusted reporter
+ * entry is: a generated worker spec must load an ENGINE file by absolute
+ * path, never a candidate-relative one. Resolves from both the `src/` and
+ * the `dist/` layout.
+ *
+ * @param fromModule: module URL to resolve the pack from (default: this file).
+ *
+ * @returns
+ *   string: absolute `<pack>/dist|src/discovery/prepare-barrier.js` path.
+ */
+export function barrierModulePath(fromModule = import.meta.url) {
+    return fileURLToPath(new URL('./prepare-barrier.js', fromModule));
+}
+/**
+ * The controller worker's own bytes.
+ *
+ * The generated spec imports the ENGINE barrier module by absolute path so
+ * the canonical payload form, the signature verification and the
+ * environment projection are ONE implementation on both sides — never a
+ * second copy that can drift from the one the CLI signed.
+ *
+ * The armed control reaches the worker as a JSON document bound through
+ * `JSON.parse`, never as an object literal inlined in these bytes: the
+ * baseline is a map of ordinary environment NAMES, so a name like
+ * `__proto__` has to arrive as an own key, and a value has to arrive
+ * escaped. `JSON.parse` is the one binding that gives both — it creates
+ * data properties — while a literal would be re-read by the JavaScript
+ * parser: a backtick or a `${` in a value would end the literal, and
+ * `__proto__:` in a literal is a PROTOTYPE assignment, not a key.
+ *
+ * @param control: the armed control (paths and pinned identities).
+ *
+ * @returns
+ *   string: the generated plain-ESM JavaScript source of the controller spec.
+ */
+export function freezeControllerSpecSource(control) {
+    const armed = {
+        project: control.project,
+        runId: control.runId,
+        invocationId: control.invocationId,
+        nonce: control.nonce,
+        requestPath: control.requestPath,
+        refusalPath: control.refusalPath,
+        releasePath: control.releasePath,
+        specPath: control.specPath,
+        releasePublicKey: control.releasePublicKey,
+        timeoutMs: control.timeoutMs,
+        baseEnv: control.baseEnv,
+        exemptEnv: control.exemptEnv,
+    };
+    return `// GENERATED by gateforge trusted supervision — the GLOBAL native
+// preparation freeze controller. Never edit: the CLI pinned these exact
+// bytes before the run and the signed release binds their sha256.
+//
+// Plain ESM JavaScript, loaded as an ES module by the runner's own
+// extension rule. The imports below are therefore real ESM imports and
+// must never be written as require() calls or as TypeScript-only syntax.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import nativeRunner from ${JSON.stringify(pathToFileURL(control.testModulePath).href)};
+import {
+  canonicalFreezeJson,
+  projectBaselineEnv,
+  verifyFreezeRelease,
+} from ${JSON.stringify(control.barrierModulePath)};
+
+// The runner's own playwright/test module is CommonJS, and it assembles
+// its exports at RUN time, so Node's static named-export detection finds
+// none of them and a named import cannot LOAD the file at all. The
+// ordinary ESM binding for a CommonJS module is its default export,
+// which is that module object itself: the runner and its assertions as
+// members. It is the same file, from the same install, that every body
+// in this run executes against — no second module, no other version.
+const { test, expect } = nativeRunner;
+
+const ARMED = JSON.parse(${JSON.stringify(JSON.stringify(armed))});
+
+test('gateforge global preparation freeze', async () => {
+  test.setTimeout(ARMED.timeoutMs + 60000);
+  writeFileSync(
+    ARMED.requestPath,
+    canonicalFreezeJson({
+      schemaVersion: 1,
+      project: ARMED.project,
+      runId: ARMED.runId,
+      invocationId: ARMED.invocationId,
+      nonce: ARMED.nonce,
+      requestedAt: new Date().toISOString(),
+    }) + '\\n',
+    'utf8',
+  );
+  // Wait for EITHER outcome. A refusal is failure-only: it can end this
+  // wait early but never unblock it, so a permanent refusal (a
+  // prerequisite that sealed failed, skipped, retried or duplicated)
+  // fails the controller within the poll interval instead of running out
+  // the whole bound. A forged refusal costs the run its barrier, which
+  // the signed release already guarantees; a missing one costs nothing.
+  await expect
+    .poll(
+      () => (existsSync(ARMED.releasePath) ? 'released' : existsSync(ARMED.refusalPath) ? 'refused' : 'waiting'),
+      { timeout: ARMED.timeoutMs, intervals: [25] },
+    )
+    .not.toBe('waiting');
+  // A release document that EXISTS is always read and verified, even when
+  // a refusal document sits beside it. The signature is the only thing
+  // that can unblock a body, so a present release must produce its OWN
+  // verdict — an unsigned document, one signed by another key and a
+  // replayed document from an earlier invocation each have a distinct,
+  // precise reason, and consulting the refusal first would mask all three
+  // behind the refusal's wording. The refusal is read only when there is
+  // no release at all, which is the ordinary refusal path.
+  if (existsSync(ARMED.releasePath)) {
+    let release = null;
+    try {
+      release = JSON.parse(readFileSync(ARMED.releasePath, 'utf8'));
+    } catch (error) {
+      expect(false, 'the freeze release is not readable JSON: ' + String(error)).toBe(true);
+    }
+    const verified = verifyFreezeRelease(release, ARMED.releasePublicKey, {
+      project: ARMED.project,
+      runId: ARMED.runId,
+      invocationId: ARMED.invocationId,
+      nonce: ARMED.nonce,
+      specDigest: createHash('sha256').update(readFileSync(ARMED.specPath)).digest('hex'),
+    });
+    expect(verified.ok, verified.ok ? '' : verified.reason).toBe(true);
+  } else {
+    const refusal = JSON.parse(readFileSync(ARMED.refusalPath, 'utf8'));
+    throw new Error(
+      'the trusted side refused the prepared candidate: ' +
+        (typeof refusal.reason === 'string' ? refusal.reason : 'no reason given'),
+    );
+  }
+  // The environment projection is the whole reason this worker exists:
+  // the native scheduler unions every dependency worker's produced
+  // environment into its dependents, so a prerequisite's assignment
+  // would otherwise reach every body. Assert the RESULT, not that the
+  // projection ran — after it, every non-exempt name must carry exactly
+  // the baseline value and nothing the baseline never had may remain.
+  // OWN membership and OWN value on both sides: a name only one side owns
+  // is a difference whatever an inherited lookup would return for it, and
+  // an inherited property is never a baseline value.
+  projectBaselineEnv(process.env, ARMED.baseEnv, ARMED.exemptEnv);
+  const exempt = new Set(ARMED.exemptEnv);
+  const drifted = [...new Set([...Object.keys(process.env), ...Object.keys(ARMED.baseEnv)])]
+    .filter((key) => !exempt.has(key))
+    .filter(
+      (key) =>
+        Object.hasOwn(process.env, key) !== Object.hasOwn(ARMED.baseEnv, key) ||
+        process.env[key] !== ARMED.baseEnv[key],
+    )
+    .sort();
+  expect(drifted, 'the worker environment still differs from the trusted baseline: ' + drifted.join(', ')).toEqual([]);
+});
+`;
+}
+/**
+ * Writes the controller spec and returns the armed barrier plus the sha256
+ * of the exact bytes written. The spec is GENERATED engine code and the
+ * only worker that performs the handshake, and its bytes are pinned in
+ * CLI memory for the whole run; because it is a parseable test file it is
+ * written OUTSIDE the repository, into a private per-run directory
+ * ({@link FreezeControl.specDir}), while the handshake documents stay in
+ * the excluded run-state subtree.
+ *
+ * @param input: the identities, paths, public key and baseline environment.
+ *
+ * @returns
+ *   ArmedFreezeControl: the control (with absolute paths) and its spec digest.
+ */
+export function armFreezeControl(input) {
+    const controlDir = join(input.stateDir, FREEZE_CONTROL_DIR);
+    mkdirSync(controlDir, { recursive: true, mode: 0o700 });
+    // Owner-only. The control directory holds the pinned public key, the
+    // controller's request, the CLI's signed release and the refusal
+    // document; nothing else on this host has a reason to read them, and
+    // the default 0o755/0o644 would publish the baseline allowlisted
+    // variables the generated spec embeds. The private signing key is
+    // NEVER written here — it stays in the CLI process's memory.
+    chmodSync(controlDir, 0o700);
+    // The spec is a TEST file, so it cannot live inside the repository: a
+    // consumer configuration whose `testDir` covers the repo root collects
+    // every parseable file below it, and would enumerate the engine's own
+    // controller as a candidate case — through the engine's `--list` as
+    // well as through the owner's own `npx playwright test`. A fresh
+    // `mkdtemp` directory under the host temporary directory keeps it out
+    // of the candidate entirely and gives every invocation its own, so
+    // one run can never read another's spec.
+    //
+    // Resolved through `realpath` because a temporary directory is
+    // commonly a symlink (`/tmp` → `/private/tmp`): the runner reports
+    // the spec under the `testDir` it was handed, and both the reporter's
+    // exclusion and the CLI's own digest checks compare resolved paths.
+    const specDir = realpathSync(mkdtempSync(join(tmpdir(), 'gateforge-freeze-')));
+    // `mkdtempSync` already creates the directory 0700; the mode is
+    // asserted rather than assumed, so the guarantee does not rest on a
+    // default this module does not control.
+    chmodSync(specDir, 0o700);
+    const control = {
+        project: FREEZE_CONTROLLER_PROJECT,
+        runId: input.runId,
+        invocationId: input.invocationId,
+        nonce: input.nonce,
+        controlDir,
+        specDir,
+        specPath: join(specDir, FREEZE_CONTROL_SPEC_FILE),
+        requestPath: join(controlDir, FREEZE_REQUEST_FILE),
+        releasePath: join(controlDir, FREEZE_RELEASE_FILE),
+        refusalPath: join(controlDir, FREEZE_REFUSAL_FILE),
+        testModulePath: input.testModulePath,
+        barrierModulePath: barrierModulePath(),
+        releasePublicKey: input.releasePublicKey,
+        timeoutMs: input.timeoutMs,
+        baseEnv: { ...input.baseEnv },
+        exemptEnv: [...FREEZE_ENV_EXEMPT],
+    };
+    // A previous invocation's handshake must not be visible to this one: a
+    // stale request would be served before this run's controller ever asks,
+    // and a stale release or refusal would be read by a controller that
+    // never asked. The spec has no such history — it was just generated
+    // into a directory this invocation created.
+    for (const path of [control.requestPath, control.releasePath, control.refusalPath]) {
+        rmSync(path, { force: true });
+    }
+    const source = freezeControllerSpecSource(control);
+    try {
+        writeFileSync(control.specPath, source, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch (error) {
+        // An armed barrier that never got its spec is not a barrier: leave
+        // no directory behind for a run that is about to fail anyway.
+        rmSync(specDir, { recursive: true, force: true });
+        throw error;
+    }
+    return {
+        control,
+        specDigest: createHash('sha256').update(source).digest('hex'),
+    };
+}
+/**
+ * Removes the private per-run directory holding the generated controller
+ * spec, and with it the generated engine file itself.
+ *
+ * The CLI calls this once the spec has been read for the LAST time — the
+ * final pinned-digest check — and on every path that never reaches that
+ * check, so no generated spec outlives the run that produced it and no
+ * consumer enumeration can ever see one. Idempotent: a second call, or a
+ * call for a directory something else already removed, removes nothing.
+ *
+ * @param control: the armed control.
+ */
+export function removeFreezeSpecDir(control) {
+    rmSync(control.specDir, { recursive: true, force: true });
+}
+/**
+ * Writes the trusted side's REFUSAL document for one handshake. It is
+ * failure-only by construction: no code path in the controller treats
+ * its presence as permission to continue, so a refusal can only shorten a
+ * wait, never satisfy one.
+ *
+ * @param control: the armed control.
+ * @param reason: the plain refusal text the controller surfaces.
+ */
+export function writeFreezeRefusal(control, reason) {
+    writeFileSync(control.refusalPath, `${canonicalFreezeJson({
+        schemaVersion: 1,
+        project: control.project,
+        runId: control.runId,
+        invocationId: control.invocationId,
+        nonce: control.nonce,
+        reason,
+    })}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+/**
+ * Reads the controller's request document, or null when it is absent or
+ * unusable. An absent request is ordinary (the controller has not asked
+ * yet); a MALFORMED one is a refusal the trusted side reports.
+ *
+ * @param path: absolute request document path.
+ *
+ * @returns
+ *   FreezeRequest | null: the parsed request, or null.
+ */
+export function readFreezeRequest(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const row = parsed;
+    if (row['schemaVersion'] !== 1)
+        return null;
+    // Every identity is NARROWED, not asserted: a document the controller
+    // wrote (or anything else sharing its writable path) is untrusted input,
+    // so a missing or non-string identity makes the whole request unusable
+    // rather than a field of `unknown` slipping into the frozen handshake.
+    const identity = (key) => {
+        const value = row[key];
+        return typeof value === 'string' && value.length > 0 ? value : null;
+    };
+    const project = identity('project');
+    const runId = identity('runId');
+    const invocationId = identity('invocationId');
+    const nonce = identity('nonce');
+    if (project === null || runId === null || invocationId === null || nonce === null)
+        return null;
+    return {
+        schemaVersion: 1,
+        project,
+        runId,
+        invocationId,
+        nonce,
+        requestedAt: typeof row['requestedAt'] === 'string' ? row['requestedAt'] : '',
+    };
+}
+/**
+ * Rewrites the planned project scopes into the freeze-aware shape the
+ * synthesized config emits.
+ *
+ * The rules, in the order they matter:
+ *
+ * - The engine's controller project is appended as one more scope. It
+   collects its generated spec from its OWN `testDir` — the private
+   per-run directory outside the repository the spec was written into,
+   which the consumer's own configuration can never collect — and
+   depends on the FULL upstream prerequisite closure the trusted CLI
+   classified, so the runner's own scheduler runs every prerequisite,
+   then the controller, then any body.
+ * - A PREREQUISITE keeps its captured edges exactly as they were. Its
+   rows are the native cases that must execute genuinely and exactly
+   once, and re-ordering them would change what the run proves.
+ * - Every other project gets the controller as its FIRST dependency,
+   followed by its own captured edges in their original emitted order.
+   Placement is not an ordering statement — the runner's phase scheduler
+   is topological (`runner/tasks.js`: a project joins the earliest phase
+   in which every dependency is already processed), so a body runs after
+   the controller either way. Placement IS an environment-merge
+   statement: a project's extra environment is the union over
+   `project.deps` in emitted order (`tasks.js:341-347`), later entries
+   winning, so where the controller lands decides what a body starts
+   with. FIRST is the contract's placement, emitted explicitly rather
+   than by inserting into a sorted array (a sort would move the
+   controller behind any prerequisite that sorts before it);
+   `trusted-config.ts` re-asserts it when it emits the final list. Whether
+   FIRST or LAST is what the environment projection actually needs is
+   under live measurement by the native environment probe; this is the
+   contract's ordering until that measurement says otherwise.
+ * @param control: the armed controller (its project name, dir and spec).
+ * @param scopes: the planned project scopes, unchanged in every other way.
+ * @param prerequisiteProjects: the CLI's upstream-closure classification.
+ *
+ * @returns
+ *   ProjectScope[]: the scopes to synthesize — the planned scopes in
+ *   place, plus the controller appended.
+ */
+export function freezeProjectScopes(control, scopes, prerequisiteProjects) {
+    const defined = new Set(scopes.map((scope) => scope.name));
+    const prerequisites = new Set(prerequisiteProjects.filter((name) => defined.has(name) && name !== control.project));
+    return [
+        ...scopes.map((scope) => prerequisites.has(scope.name) || scope.name === control.project
+            ? scope
+            : {
+                ...scope,
+                dependencies: [
+                    control.project,
+                    ...(scope.dependencies ?? []).filter((name) => name !== control.project),
+                ],
+            }),
+        {
+            name: control.project,
+            files: [FREEZE_CONTROL_SPEC_FILE],
+            // The controller collects from the private directory the spec was
+            // written into — never from the state directory, which no longer
+            // holds it, and never from the repository root.
+            testDir: control.specDir,
+            dependencies: [...prerequisites].sort(),
+        },
+    ];
+}
+//# sourceMappingURL=prepare-barrier.js.map