gentle-pi 2.1.2 → 2.2.0

package/runtime/review-relay-contract.mjs

@@ -0,0 +1,17 @@
+// Generated by scripts/build-git-commit-transaction-runner.mjs. Do not edit.
+// gentle-pi.review-relay/v1 — the Pi host relay handshake (gentle-pi#311 P4,
+// provider side gentle-ai#3249/#3254).
+//
+// gentle-ai admits `pi` as a host-mediated runtime identity only when the
+// launcher that relays the invocation declares this exact contract through
+// this exact environment variable. Any other value (or none) keeps Pi
+// fail-closed at admission, before any repository, target, or authority work.
+// That refusal is correct provider behavior and is never worked around here;
+// the single central gentle-ai process runner injects this declaration on
+// every invocation the extension makes.
+//
+// Both values are compiled constants: the contract identity is versioned by
+// release, never by configuration.
+
+export const GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV = "GENTLE_PI_REVIEW_RELAY_CONTRACT";
+export const GENTLE_PI_REVIEW_RELAY_CONTRACT = "gentle-pi.review-relay/v1";

package/scripts/build-git-commit-transaction-runner.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 const root = fileURLToPath(new URL("..", import.meta.url));
 const sources = [
 	"gentle-ai-binary",
+	"review-relay-contract",
 	"review-integration-v2",
 	"native-review-cli",
 	"git-commit-transaction",

package/scripts/check-provider-contract.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// Offline drift check for the mirrored gentle-ai provider contract bundle
+// (gentle-pi#311 P2).
+//
+// Fails when the mirror, the lock record, the schemas, the vectors, or the
+// generated consumer baselines disagree in any direction. Runs completely
+// offline against `contracts/review-provider-contract-mirror/` and never
+// touches the network or the Gentle AI release pin.
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+	generateProviderContractBaselines,
+	piRuntimeRegistration,
+	verifyProviderContractBundleTree,
+} from "../lib/provider-contract-bundle.ts";
+import {
+	PROVIDER_CONTRACT_ACQUISITION,
+	PROVIDER_CONTRACT_LOCK_FILE,
+	PROVIDER_CONTRACT_LOCK_SCHEMA,
+	PROVIDER_CONTRACT_MIRROR_ROOT,
+} from "./mirror-provider-contract.mjs";
+
+function sha256Hex(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function recordEquals(problems, label, expected, actual) {
+	const expectedKeys = Object.keys(expected).sort();
+	const actualKeys = Object.keys(actual).sort();
+	for (const key of expectedKeys) {
+		if (!(key in actual)) problems.push(`${label}: ${key} is recorded in the lock but absent from the mirror`);
+		else if (actual[key] !== expected[key]) problems.push(`${label}: ${key} drifted (lock ${expected[key]}, mirror ${actual[key]})`);
+	}
+	for (const key of actualKeys) {
+		if (!(key in expected)) problems.push(`${label}: ${key} exists in the mirror but is not recorded in the lock`);
+	}
+}
+
+// Returns a list of drift problems; an empty list means the mirror, lock,
+// schemas, vectors, and generated baselines all agree.
+export function checkProviderContractMirror(packageRoot) {
+	const problems = [];
+	const mirrorRoot = join(packageRoot, ...PROVIDER_CONTRACT_MIRROR_ROOT.split("/"));
+	const lockPath = join(mirrorRoot, PROVIDER_CONTRACT_LOCK_FILE);
+	if (!existsSync(lockPath)) {
+		return [`${PROVIDER_CONTRACT_MIRROR_ROOT}/${PROVIDER_CONTRACT_LOCK_FILE} is missing; run scripts/mirror-provider-contract.mjs against a verified local bundle`];
+	}
+
+	let lock;
+	try {
+		lock = JSON.parse(readFileSync(lockPath, "utf8"));
+	} catch (error) {
+		return [`lock record is not valid JSON: ${error instanceof Error ? error.message : String(error)}`];
+	}
+	if (lock === null || typeof lock !== "object" || Array.isArray(lock)) return ["lock record is not a JSON object"];
+	if (lock.schema !== PROVIDER_CONTRACT_LOCK_SCHEMA) problems.push(`lock schema is ${JSON.stringify(lock.schema)}; expected ${JSON.stringify(PROVIDER_CONTRACT_LOCK_SCHEMA)}`);
+	if (lock.acquisition !== PROVIDER_CONTRACT_ACQUISITION) problems.push(`lock acquisition is ${JSON.stringify(lock.acquisition)}; expected ${JSON.stringify(PROVIDER_CONTRACT_ACQUISITION)}`);
+	if (typeof lock.contract_semver !== "string") return [...problems, "lock contract_semver is not a string"];
+	if (lock.pi_registered !== true) problems.push("lock does not record pi as a registered runtime identity");
+
+	// The mirror directory must contain exactly the lock and the locked version.
+	const expectedVersionDirectory = `v${lock.contract_semver}`;
+	for (const entry of readdirSync(mirrorRoot)) {
+		if (entry !== PROVIDER_CONTRACT_LOCK_FILE && entry !== expectedVersionDirectory) {
+			problems.push(`mirror has unexpected entry ${JSON.stringify(entry)}; only ${PROVIDER_CONTRACT_LOCK_FILE} and ${expectedVersionDirectory} belong there`);
+		}
+	}
+
+	const versionRoot = join(mirrorRoot, expectedVersionDirectory);
+	let bundle;
+	try {
+		bundle = verifyProviderContractBundleTree(join(versionRoot, "bundle"));
+	} catch (error) {
+		return [...problems, `mirrored bundle failed verification: ${error instanceof Error ? error.message : String(error)}`];
+	}
+
+	if (bundle.contractSemver !== lock.contract_semver) {
+		problems.push(`mirrored bundle declares contract ${bundle.contractSemver}; lock records ${lock.contract_semver}`);
+	}
+	if (bundle.treeSha256 !== lock.tree_sha256) {
+		problems.push(`mirrored bundle tree digest ${bundle.treeSha256} does not match lock tree_sha256 ${lock.tree_sha256}`);
+	}
+	recordEquals(problems, "bundle entries", lock.entries ?? {}, Object.fromEntries(bundle.entrySha256));
+	const lockRuntimes = Array.isArray(lock.runtimes) ? lock.runtimes : [];
+	const bundleRuntimes = [...(bundle.runtimes ?? [])];
+	if (JSON.stringify(lockRuntimes) !== JSON.stringify(bundleRuntimes)) {
+		problems.push(`lock runtimes ${JSON.stringify(lockRuntimes)} do not match mirrored manifest runtimes ${JSON.stringify(bundleRuntimes)}`);
+	}
+	if (!piRuntimeRegistration(bundle).registered) {
+		problems.push("mirrored bundle does not register the pi runtime identity");
+	}
+
+	// Regenerate the consumer contract surface from the verified mirror and
+	// require byte-identical generated files plus matching lock digests.
+	const baselines = generateProviderContractBaselines(bundle);
+	const generatedRoot = join(versionRoot, "generated");
+	const onDisk = existsSync(generatedRoot) ? readdirSync(generatedRoot).sort() : [];
+	const expectedGenerated = [...baselines.keys()].sort();
+	for (const name of onDisk) {
+		if (!baselines.has(name)) problems.push(`generated/${name} exists on disk but is not a generated provider baseline`);
+	}
+	const actualGeneratedSha256 = {};
+	for (const name of expectedGenerated) {
+		const path = join(generatedRoot, name);
+		if (!existsSync(path)) {
+			problems.push(`generated/${name} is missing from the mirror`);
+			continue;
+		}
+		const actual = readFileSync(path);
+		const expected = Buffer.from(baselines.get(name), "utf8");
+		if (!actual.equals(expected)) problems.push(`generated/${name} is not byte-identical to the baseline derived from the verified mirror`);
+		actualGeneratedSha256[`generated/${name}`] = sha256Hex(actual);
+	}
+	recordEquals(problems, "generated baselines", lock.generated ?? {}, actualGeneratedSha256);
+
+	return problems;
+}
+
+async function main() {
+	const packageRoot = join(fileURLToPath(new URL("..", import.meta.url)));
+	const problems = checkProviderContractMirror(packageRoot);
+	if (problems.length > 0) {
+		console.error("gentle-pi provider contract mirror has drifted:");
+		for (const problem of problems) console.error(`- ${problem}`);
+		console.error("\nRe-run scripts/mirror-provider-contract.mjs against a verified local bundle, or restore the mirrored bytes.");
+		process.exit(1);
+	}
+	const lock = JSON.parse(readFileSync(join(packageRoot, ...PROVIDER_CONTRACT_MIRROR_ROOT.split("/"), PROVIDER_CONTRACT_LOCK_FILE), "utf8"));
+	console.log(`gentle-pi provider contract mirror check passed (contract ${lock.contract_semver}, ${Object.keys(lock.entries).length} bundle entries, ${Object.keys(lock.generated).length} generated baselines, acquisition ${lock.acquisition}).`);
+}
+
+const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+	await main();
+}

package/scripts/gentle-ai-installer.mjs

@@ -19,24 +19,32 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
-const RELEASE_BASE_URL = "https://github.com/Gentleman-Programming/gentle-ai/releases/download/v2.2.2/";
 const MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
 const MAX_REDIRECTS = 3;
 const DOWNLOAD_TIMEOUTS = { headers: 10_000, body: 30_000, attempts: 2, retryDelay: 100 };
 const GO_COMMAND_TIMEOUT_MS = 120_000;
 const GO_COMMAND_MAX_BUFFER = 1024 * 1024;
 const WINDOWS_SYSTEM_ROOT = "C:\\Windows";
-export const INSTALLER_VERSION = "2.2.2";
+// The one authoritative pinned Gentle AI version. Every other location in this
+// module (the release download URL, the Windows source tag, and the reported
+// version check below) derives from this constant instead of repeating the
+// literal, so a pin bump cannot leave a stale copy behind. See
+// scripts/install-gentle-ai.mjs for the incident that motivated this.
+export const INSTALLER_VERSION = "2.4.0";
+export const RELEASE_BASE_URL = `https://github.com/Gentleman-Programming/gentle-ai/releases/download/v${INSTALLER_VERSION}/`;
 export const GENTLE_AI_INSTALL_METHOD = Object.freeze({
 	SIGNED_RELEASE_ASSET: "signed-release-asset",
 	GO_SUMDB_SOURCE_BUILD: "go-sumdb-source-build",
 });
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH = "github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai";
 export const GENTLE_AI_WINDOWS_SOURCE_MODULE = "github.com/gentleman-programming/gentle-ai/v2";
-export const GENTLE_AI_WINDOWS_SOURCE_TAG = "v2.2.2";
-// `go mod download -json github.com/gentleman-programming/gentle-ai/v2@v2.2.2`
-// with GOSUMDB=sum.golang.org reports this exact module SumDB checksum.
-export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:YZcI5dRvoHm82I2CULvgBkB2M3UQQGarYO/u/Nt5LSc=";
+export const GENTLE_AI_WINDOWS_SOURCE_TAG = `v${INSTALLER_VERSION}`;
+// `go mod download -json github.com/gentleman-programming/gentle-ai/v2@v2.4.0`
+// with GOSUMDB=sum.golang.org reports this exact module SumDB checksum. The
+// same response resolves the tag to commit 301fb2ad, which is also the
+// `vcs_revision` the published v2.4.0 binary self-reports in its capabilities
+// envelope -- the two independent provenance paths agree.
+export const GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:XKkcy+t76cyUKQnRwL1UnqHbhh8o416I8HQ1UsdvWSI=";
 export const GENTLE_AI_WINDOWS_SOURCE_PACKAGE = `${GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH}@${GENTLE_AI_WINDOWS_SOURCE_TAG}`;
 export const GENTLE_AI_WINDOWS_MINIMUM_GO_VERSION = "1.25.10";
 export const GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE_CODE = "GENTLE_AI_GO_TOOLCHAIN_UNAVAILABLE";
@@ -55,7 +63,7 @@ export class GentleAiInstallerError extends Error {
 // Sentinel used while a re-pinned gentle-ai release is not yet published. A
 // sentinel digest can never match a real SHA-256, so installation fails closed,
 // and verify-package-files.mjs refuses to pack/publish while any digest below
-// still holds it. The v2.2.2 digests are pinned from the published release:
+// still holds it. The v2.4.0 digests are pinned from the published release:
 // archive sha256 values verified against the minisign-signed checksums.txt and
 // freshly computed hashes; binary sha256 values computed from the extracted
 // executables.
@@ -66,15 +74,15 @@ function asset(name, sha256, binarySha256, executable) {
 }
 
 // Windows is absent from signed release archives on purpose. gentle-ai stopped
-// distributing unsigned Windows builds in c4b764d0, so v2.2.2 publishes signed
+// distributing unsigned Windows builds in c4b764d0, so v2.4.0 publishes signed
 // Darwin/Linux archives only. Windows x64/arm64 uses the separately verified
 // exact-tag Go SumDB source-build path below; restore archive rows only when
 // upstream ships signed Windows assets.
 export const GENTLE_AI_RELEASE_ASSETS = Object.freeze({
-	"darwin/amd64": asset("gentle-ai_2.2.2_darwin_amd64.tar.gz", "5ca67829903bf4c6b14665664f80f9d8216c84b10c8e50870d297f452cefb9dc", "9b239423450562d026384f482bbd2f1e3f2820431a84f0921743ac3df9d632de", "gentle-ai"),
-	"darwin/arm64": asset("gentle-ai_2.2.2_darwin_arm64.tar.gz", "0193e1a284444dccee2863d31b8dbb76a982e8f9111955908d6a9131c1a5490e", "149b97248552c5e03ebc4d991f86b1360fb847a40fc315555a8aa256f95baca0", "gentle-ai"),
-	"linux/amd64": asset("gentle-ai_2.2.2_linux_amd64.tar.gz", "b85bbb20eb2236de97b261df16cfc8d8394dfd07a137e885c4889b62d0c20fa1", "00d5732e8dd3945956800217a4f60213c2d9ca63351092a2cb7f4e5f9ece54f9", "gentle-ai"),
-	"linux/arm64": asset("gentle-ai_2.2.2_linux_arm64.tar.gz", "61e7077342448273f0c43af49ce4d182594bab5e4f86f812975af2fbe69e3b0b", "a92685aa7dbea0cc4297d016569b3defe9bb30a7374a620021e245b74f50eb68", "gentle-ai"),
+	"darwin/amd64": asset("gentle-ai_2.4.0_darwin_amd64.tar.gz", "c3f5a4251e927c41864e7a9a5670ac3fce97c6282755ec8e9b2e7e064067f750", "c4d25b98bae0d06b33baa23ba997cb64ab63c2e93e97983bcb9c239139bceaba", "gentle-ai"),
+	"darwin/arm64": asset("gentle-ai_2.4.0_darwin_arm64.tar.gz", "2240ae797119dd1dc5a0dd2fd2711077ce6712e66ab0b67461344c983478f7f4", "54a8a5957ce4f10f36b46ef818c888f484a3e213a71faca6b7783af6c029eb77", "gentle-ai"),
+	"linux/amd64": asset("gentle-ai_2.4.0_linux_amd64.tar.gz", "517eb8420cf966b74be1413a7ea1036119a5ccbb376e0778aa9f4d4d283e2e9a", "0be446737f8f1a9458fd2891d488beb2d72786578afead9bbf2d6ddddc9ec113", "gentle-ai"),
+	"linux/arm64": asset("gentle-ai_2.4.0_linux_arm64.tar.gz", "1badec9cad1f2bbeb22b5c6804c3a88c601d844abae231264e416e8095f2a15f", "cdd8fa43c3417e844cc11d2e436d4667edb0a54f086e0eb1d6cd3f7493bfee5a", "gentle-ai"),
 });
 
 function upstreamArchitecture(architecture) {
@@ -330,11 +338,13 @@ async function verifyGoBuildMetadata(execute, goPath, binaryPath, environment, c
 	catch (error) { if (error instanceof GentleAiInstallerError) throw error; throw new GentleAiInstallerError(GENTLE_AI_GO_INSTALL_FAILED_CODE, "Gentle AI source build metadata could not be verified.", error); }
 }
 
+function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
+
 async function assertExactGentleAiVersion(execute, binaryPath, environment, cwd) {
 	let result;
 	try { result = await runCommand(execute, binaryPath, ["version"], commandOptions(environment, cwd)); }
 	catch (error) { throw new GentleAiInstallerError(GENTLE_AI_VERSION_MISMATCH_CODE, `Gentle AI source build at ${binaryPath} could not report its version.`, error); }
-	if (!/^gentle-ai 2\.2\.2\r?\n?$/.test(commandOutput(result))) throw new GentleAiInstallerError(GENTLE_AI_VERSION_MISMATCH_CODE, `Gentle AI source build reported ${JSON.stringify(commandOutput(result).trim())}; expected gentle-ai ${INSTALLER_VERSION}.`);
+	if (!new RegExp(`^gentle-ai ${escapeRegExp(INSTALLER_VERSION)}\\r?\\n?$`).test(commandOutput(result))) throw new GentleAiInstallerError(GENTLE_AI_VERSION_MISMATCH_CODE, `Gentle AI source build reported ${JSON.stringify(commandOutput(result).trim())}; expected gentle-ai ${INSTALLER_VERSION}.`);
 }
 
 function sameFile(before, after) { return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs; }

package/scripts/maintainer/provider-relay-matrix.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// Maintainer provider-relay matrix (gentle-pi#311, first direct work unit).
+//
+// Read-only maintainer harness driving the REAL Pi host relay
+// (lib/review-host-relay.ts#runReviewHostRelaySlot) through explicit
+// maintainer runtime descriptors. Validates an EXACT descriptor shape, uses
+// ONLY declared executables (never re-resolves the production binary), and
+// emits one machine-readable NDJSON verdict per case. Not a production path:
+// `pnpm test` never imports it; `pnpm run test:maintainer` runs the tests;
+// the CLI is the entry point the separate verifier uses for the real organic
+// positive journey after a user-visible forecast.
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { REVIEW_HOST_RELAY_FAILURE, ReviewHostRelayError, resolveReviewHostRelaySubmission, runReviewHostRelaySlot } from "../../lib/review-host-relay.ts";
+export const DESCRIPTOR_SCHEMA = "gentle-pi.maintainer.provider-relay-descriptor/v1";
+export const CASE_KINDS = Object.freeze(["relay-unavailable", "positive-lens"]);
+// The positive lens runs only when explicitly armed: the organic journey
+// needs a real capable binary, a real pi, and a real review session. Without
+// the arm the runner blocks the positive leg before materialize.
+export const ARM_POSITIVE_ENV = "GENTLE_PI_MAINTAINER_ARM_POSITIVE";
+export const POSITIVE_JOURNEY_COMMAND =
+	"GENTLE_PI_MAINTAINER_ARM_POSITIVE=1 node --experimental-strip-types scripts/maintainer/provider-relay-matrix.mjs --descriptor <descriptor.json>  # needs a real capable gentle-ai binary + real pi on PATH + real binding tokens from a live review session (gentle-ai review status --next-transition)";
+export class DescriptorValidationError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DescriptorValidationError";
+	}
+}
+const isObj = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isStr = (value) => typeof value === "string" && value.length > 0;
+const isStrArr = (value) => Array.isArray(value) && value.length > 0 && value.every(isStr);
+const fail = (message) => {
+	throw new DescriptorValidationError(message);
+};
+// Reject any key outside an exact allowed set; keeps the descriptor shape
+// strict so a maintainer cannot smuggle production overrides through it.
+const exactKeys = (obj, allowed, label) => {
+	for (const key of Object.keys(obj)) {
+		if (!allowed.has(key)) fail(`${label}.${key} is not allowed; exact shape is {${[...allowed].join(",")}}`);
+	}
+};
+// Strict, exact-shape descriptor validation: no defaults, no production
+// resolution. The submission is validated through the REAL relay resolver so
+// the completing form is provably bindable before any process launches.
+export function validateDescriptor(value) {
+	if (!isObj(value)) fail("descriptor must be a JSON object");
+	exactKeys(value, new Set(["schema", "gentleAiExecutable", "piExecutable", "cases"]), "descriptor");
+	if (value.schema !== DESCRIPTOR_SCHEMA) fail(`descriptor.schema must be exactly "${DESCRIPTOR_SCHEMA}"`);
+	if (!isStr(value.gentleAiExecutable) || !isAbsolute(value.gentleAiExecutable)) fail("descriptor.gentleAiExecutable must be a non-empty absolute path; the runner never re-resolves the production binary");
+	if (!isStr(value.piExecutable)) fail("descriptor.piExecutable must be a non-empty string");
+	if (!Array.isArray(value.cases) || value.cases.length === 0) fail("descriptor.cases must be a non-empty array");
+	const seen = new Set();
+	return { schema: value.schema, gentleAiExecutable: value.gentleAiExecutable, piExecutable: value.piExecutable, cases: value.cases.map((entry, index) => {
+			if (!isObj(entry)) fail(`descriptor.cases[${index}] must be an object`);
+			exactKeys(entry, new Set(["name", "kind", "captureArgumentTokens", "submission"]), `descriptor.cases[${index}]`);
+			if (!isStr(entry.name)) fail(`descriptor.cases[${index}].name must be a non-empty string`);
+			if (seen.has(entry.name)) fail(`descriptor.cases[${index}].name "${entry.name}" is duplicated`);
+			seen.add(entry.name);
+			if (!CASE_KINDS.includes(entry.kind)) fail(`descriptor.cases[${index}].kind must be one of ${JSON.stringify([...CASE_KINDS])}`);
+			if (!isStrArr(entry.captureArgumentTokens)) fail(`descriptor.cases[${index}].captureArgumentTokens must be a non-empty array of non-empty strings`);
+			// A real host-relay materialize slot is the provider-issued
+			// --agent=pi --materialize=true pair; the descriptor must declare
+			// exactly that so the negative control exercises the unknown-flag
+			// refusal and the positive leg exercises the real surface.
+			for (const required of ["--agent=pi", "--materialize=true"]) {
+				if (!entry.captureArgumentTokens.includes(required)) fail(`descriptor.cases[${index}].captureArgumentTokens must include the provider-issued "${required}" token`);
+			}
+			const submission = entry.submission;
+			if (!isObj(submission)) fail(`descriptor.cases[${index}].submission must be an object; a materialize slot without a provider submission is a contract mismatch, never synthesized`);
+			exactKeys(submission, new Set(["operationToken", "argumentTokens", "values"]), `descriptor.cases[${index}].submission`);
+			if (!isStr(submission.operationToken)) fail(`descriptor.cases[${index}].submission.operationToken must be a non-empty string`);
+			if (!isStrArr(submission.argumentTokens)) fail(`descriptor.cases[${index}].submission.argumentTokens must be a non-empty array of non-empty strings`);
+			if (!Array.isArray(submission.values) || submission.values.length === 0 || !submission.values.every(isObj)) {
+				fail(`descriptor.cases[${index}].submission.values must be a non-empty array of objects`);
+			}
+			for (const [vi, ve] of submission.values.entries()) {
+				exactKeys(ve, new Set(["slot", "domain", "substitutionLocation"]), `descriptor.cases[${index}].submission.values[${vi}]`);
+				if (!isStr(ve.slot) || !isStr(ve.domain)) fail(`descriptor.cases[${index}].submission.values[${vi}] must have non-empty string slot and domain`);
+			}
+			// Delegate binding semantics (count, substitution location, the
+			// {{value}} slot) to the REAL relay resolver so they never drift.
+			try {
+				resolveReviewHostRelaySubmission({
+					operationToken: submission.operationToken,
+					argumentTokens: submission.argumentTokens,
+					values: submission.values.map((ve) => ({ slot: ve.slot, domain: ve.domain, substitutionLocation: ve.substitutionLocation })),
+				});
+			} catch (error) {
+				fail(`descriptor.cases[${index}].submission is not a bindable provider form: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			return { name: entry.name, kind: entry.kind, captureArgumentTokens: [...entry.captureArgumentTokens], submission: { operationToken: submission.operationToken, argumentTokens: [...submission.argumentTokens], values: submission.values.map((ve) => ({ ...ve })) } };
+		}),
+	};
+}
+export function loadDescriptor(path) {
+	if (!isStr(path)) fail("a descriptor path is required");
+	let raw, parsed;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		fail(`could not read descriptor at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		fail(`descriptor at ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return validateDescriptor(parsed);
+}
+// Resolves a declared executable without a shell: absolute path checked
+// verbatim, bare name searched on PATH. Never re-resolves production.
+export function resolveDeclaredExecutable(executable) {
+	if (isAbsolute(executable)) return existsSync(executable) && statSync(executable).isFile() ? executable : null;
+	for (const directory of (process.env.PATH ?? "").split(process.platform === "win32" ? ";" : ":")) {
+		if (!directory) continue;
+		const candidate = join(directory, executable);
+		if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+	}
+	return null;
+}
+const missingReason = (executable, label) => `${label} "${executable}" is not an existing executable; arm the descriptor with a real binary, or set GENTLE_PI_REQUIRE_MAINTAINER=1 to fail instead of block.`;
+// A guaranteed-nonexistent pi path inside a fresh private directory. mkdtemp
+// picks an unpredictable name and 0700 keeps it ours, so nothing can race a
+// file into the slot between the mkdtemp and the spawn.
+function unlaunchablePi() {
+	const directory = mkdtempSync(join(tmpdir(), "gentle-pi-maintainer-no-pi-"));
+	chmodSync(directory, 0o700);
+	return { directory, executable: join(directory, "pi-must-never-launch") };
+}
+// Runs the matrix against the REAL relay. A case that cannot run honestly is
+// `blocked` (never `pass`); `fail` is an armed case whose outcome mismatched.
+export async function runMatrix(descriptor, options = {}) {
+	const positiveArmed = options.armPositive ?? (process.env[ARM_POSITIVE_ENV] === "1");
+	const verdicts = [];
+	for (const caseEntry of descriptor.cases) {
+		const gentleAiPath = resolveDeclaredExecutable(descriptor.gentleAiExecutable);
+		if (gentleAiPath === null) {
+			verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", reason: missingReason(descriptor.gentleAiExecutable, "gentleAiExecutable") });
+			continue;
+		}
+		// The positive lens needs a real pi AND an explicit arm; the negative
+		// control never launches pi (fails closed at materialize).
+		if (caseEntry.kind === "positive-lens") {
+			if (resolveDeclaredExecutable(descriptor.piExecutable) === null) {
+				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", reason: missingReason(descriptor.piExecutable, "piExecutable"), command: POSITIVE_JOURNEY_COMMAND });
+				continue;
+			}
+			if (!positiveArmed) {
+				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", reason: `positive-lens case is not explicitly armed; set ${ARM_POSITIVE_ENV}=1 with a real capable gentle-ai binary, a real pi, and a real review session (real binding tokens from \`gentle-ai review status --next-transition\`) to run the organic journey. The runner never synthesizes a provider result.`, command: POSITIVE_JOURNEY_COMMAND });
+				continue;
+			}
+		}
+		// `relay-unavailable` is a NEGATIVE CONTROL: it must never launch pi and
+		// never submit. The maintainer-declared `kind` is not evidence that the
+		// declared binary is actually incapable, so the arm gate cannot key off
+		// the declaration alone. Pointed at a mis-declared CAPABLE binary, a
+		// declaration-only gate materializes, runs a REAL pi model, and executes
+		// a REAL `capture-result --input=...` submission, and only then reports
+		// `fail` — the mutation already happened. So give the negative control a
+		// pi that cannot exist: an incapable binary still classifies
+		// relay-unavailable at materialize (the control stays genuine, since it
+		// never reached pi anyway), while a capable one fails closed at the pi
+		// stage as kind=pi-launch-failed stage=pi mutationOutcome=none, with
+		// zero pi launch and zero submission.
+		const negativeControl = caseEntry.kind === "relay-unavailable" ? unlaunchablePi() : null;
+		const request = { captureArgumentTokens: caseEntry.captureArgumentTokens, submission: caseEntry.submission, gentleAiExecutable: gentleAiPath, piExecutable: negativeControl === null ? descriptor.piExecutable : negativeControl.executable, ...(options.signal === undefined ? {} : { signal: options.signal }) };
+		try {
+			const result = await runReviewHostRelaySlot(request);
+			if (caseEntry.kind === "relay-unavailable") {
+				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: "expected relay-unavailable (runtime without --materialize) but the relay succeeded; the descriptor's binary is unexpectedly capable" });
+			} else {
+				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "pass", promptByteLength: result.promptByteLength, resultByteLength: result.resultByteLength, submissionByteLength: result.submission.length });
+			}
+		} catch (error) {
+			if (error instanceof ReviewHostRelayError) {
+				if (caseEntry.kind === "relay-unavailable") {
+					if (error.kind === REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE && error.stage === "materialize" && error.mutationOutcome === "none") {
+						verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "pass", stage: error.stage, mutationOutcome: error.mutationOutcome, reason: REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE });
+					} else {
+						verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: `expected relay-unavailable at materialize with zero mutation, got kind=${error.kind} stage=${error.stage} mutationOutcome=${error.mutationOutcome}`, stderr: error.stderr });
+					}
+				} else if (error.kind === REVIEW_HOST_RELAY_FAILURE.RELAY_UNAVAILABLE) {
+					verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "blocked", stage: error.stage, reason: `the declared gentle-ai binary lacks the pi host relay surface: ${error.message}`, command: POSITIVE_JOURNEY_COMMAND });
+				} else {
+					verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: `relay error kind=${error.kind} stage=${error.stage} mutationOutcome=${error.mutationOutcome}: ${error.message}`, stderr: error.stderr });
+				}
+			} else {
+				verdicts.push({ name: caseEntry.name, kind: caseEntry.kind, verdict: "fail", reason: `unexpected non-relay error: ${error instanceof Error ? error.message : String(error)}` });
+			}
+		} finally {
+			if (negativeControl !== null) rmSync(negativeControl.directory, { recursive: true, force: true });
+		}
+	}
+	return verdicts;
+}
+async function main() {
+	const argv = process.argv.slice(2);
+	const index = argv.indexOf("--descriptor");
+	if (index === -1 || argv[index + 1] === undefined) {
+		process.stderr.write("usage: provider-relay-matrix.mjs --descriptor <path.json>\n");
+		process.exitCode = 2;
+		return;
+	}
+	let descriptor;
+	try {
+		descriptor = loadDescriptor(argv[index + 1]);
+	} catch (error) {
+		process.stderr.write(`descriptor validation failed: ${error instanceof Error ? error.message : String(error)}\n`);
+		process.exitCode = 2;
+		return;
+	}
+	const verdicts = await runMatrix(descriptor, { armPositive: process.env[ARM_POSITIVE_ENV] === "1" });
+	for (const verdict of verdicts) {
+		process.stdout.write(`${JSON.stringify(verdict)}\n`);
+		if (verdict.verdict !== "pass") process.exitCode = 1;
+	}
+}
+if (process.argv[1]?.endsWith("provider-relay-matrix.mjs")) await main();

package/scripts/mirror-provider-contract.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Field-test acquisition of the gentle-ai provider contract bundle
+// (gentle-pi#311 P1/P2).
+//
+// This script NEVER fetches anything from the network and NEVER touches the
+// Gentle AI release pin (scripts/gentle-ai-installer.mjs INSTALLER_VERSION).
+// RC and main-built bundles are field-test input only: you pass an explicit
+// LOCAL path to a `gentle-ai-review-provider-contract-<semver>.tar.gz` archive
+// or to an already-extracted bundle tree, the bundle is strictly verified,
+// and only then is the verified mirror written under
+// `contracts/review-provider-contract-mirror/` together with a lock record
+// (contract semver, archive digest when mirroring an archive, tree digest,
+// per-entry digests, generated baseline digests, runtime registry).
+//
+// Usage:
+//   node scripts/mirror-provider-contract.mjs --bundle <local archive or tree> [--root <package root>]
+
+import { lstatSync, mkdirSync, rmSync, writeFileSync, chmodSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+	generateProviderContractBaselines,
+	piRuntimeRegistration,
+	verifyProviderContractBundleArchive,
+	verifyProviderContractBundleTree,
+} from "../lib/provider-contract-bundle.ts";
+
+export const PROVIDER_CONTRACT_MIRROR_ROOT = "contracts/review-provider-contract-mirror";
+export const PROVIDER_CONTRACT_LOCK_FILE = "provider-contract.lock.json";
+export const PROVIDER_CONTRACT_LOCK_SCHEMA = "gentle-pi.review-provider-contract-mirror-lock/v1";
+// This script exists for field-test consumption only; the lock says so
+// explicitly so nothing downstream mistakes it for a release pin.
+export const PROVIDER_CONTRACT_ACQUISITION = "field-test-local";
+
+function sha256Hex(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function parseArguments(argv) {
+	const values = { bundle: undefined, root: undefined };
+	for (let index = 0; index < argv.length; index += 2) {
+		const flag = argv[index];
+		const value = argv[index + 1];
+		if ((flag !== "--bundle" && flag !== "--root") || value === undefined) {
+			throw new Error("usage: node scripts/mirror-provider-contract.mjs --bundle <local archive or tree> [--root <package root>]");
+		}
+		if (values[flag.slice(2)] !== undefined) throw new Error(`duplicate ${flag} argument`);
+		values[flag.slice(2)] = value;
+	}
+	if (values.bundle === undefined) {
+		throw new Error("usage: node scripts/mirror-provider-contract.mjs --bundle <local archive or tree> [--root <package root>]");
+	}
+	return values;
+}
+
+function verifyLocalBundle(bundlePath) {
+	const details = lstatSync(bundlePath);
+	if (details.isDirectory()) {
+		return { bundle: verifyProviderContractBundleTree(bundlePath), source: { kind: "tree" } };
+	}
+	const { bundle, archiveSha256 } = verifyProviderContractBundleArchive(bundlePath);
+	return { bundle, source: { kind: "archive", archive_sha256: archiveSha256 } };
+}
+
+function sortedRecord(map) {
+	return Object.fromEntries([...map.entries()].sort(([left], [right]) => (left < right ? -1 : 1)));
+}
+
+export function buildLockRecord(bundle, source, generatedSha256) {
+	return {
+		schema: PROVIDER_CONTRACT_LOCK_SCHEMA,
+		acquisition: PROVIDER_CONTRACT_ACQUISITION,
+		contract_semver: bundle.contractSemver,
+		source,
+		tree_sha256: bundle.treeSha256,
+		entries: sortedRecord(bundle.entrySha256),
+		generated: sortedRecord(generatedSha256),
+		runtimes: [...(bundle.runtimes ?? [])],
+		pi_registered: piRuntimeRegistration(bundle).registered,
+	};
+}
+
+export function mirrorProviderContractBundle(bundlePath, packageRoot) {
+	const { bundle, source } = verifyLocalBundle(bundlePath);
+	const registration = piRuntimeRegistration(bundle);
+	if (!registration.registered) {
+		throw new Error(
+			`refusing to mirror provider contract ${bundle.contractSemver}: ${registration.reason ?? "the pi runtime identity is not registered"}`,
+		);
+	}
+
+	const mirrorRoot = join(resolve(packageRoot), ...PROVIDER_CONTRACT_MIRROR_ROOT.split("/"));
+	const versionRoot = join(mirrorRoot, `v${bundle.contractSemver}`);
+	const bundleRoot = join(versionRoot, "bundle");
+	const generatedRoot = join(versionRoot, "generated");
+
+	// Single locked version policy: the mirror directory holds exactly one
+	// verified bundle plus its lock, so rebuild it from scratch every time.
+	rmSync(mirrorRoot, { recursive: true, force: true });
+
+	// Confined materialization: entries come exclusively from the verified
+	// in-memory inventory whose paths already passed canonical-path checks, so
+	// no archive metadata ever steers a write location or a file mode.
+	for (const [name, payload] of bundle.entries) {
+		const destination = join(bundleRoot, ...name.split("/"));
+		mkdirSync(dirname(destination), { recursive: true });
+		writeFileSync(destination, payload, { flag: "wx" });
+		chmodSync(destination, 0o644);
+	}
+
+	const baselines = generateProviderContractBaselines(bundle);
+	const generatedSha256 = new Map();
+	for (const [name, payload] of baselines) {
+		const destination = join(generatedRoot, name);
+		mkdirSync(generatedRoot, { recursive: true });
+		writeFileSync(destination, payload, { flag: "wx" });
+		chmodSync(destination, 0o644);
+		generatedSha256.set(`generated/${name}`, sha256Hex(Buffer.from(payload, "utf8")));
+	}
+
+	const lock = buildLockRecord(bundle, source, generatedSha256);
+	const lockPath = join(mirrorRoot, PROVIDER_CONTRACT_LOCK_FILE);
+	writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, { flag: "wx" });
+	chmodSync(lockPath, 0o644);
+
+	return { bundle, source, lock, mirrorRoot };
+}
+
+async function main() {
+	const packageRoot = join(fileURLToPath(new URL("..", import.meta.url)));
+	const { bundle: bundlePath, root } = parseArguments(process.argv.slice(2));
+	const { bundle, source, mirrorRoot } = mirrorProviderContractBundle(resolve(bundlePath), root ?? packageRoot);
+	console.log(
+		`Mirrored provider contract ${bundle.contractSemver} (${source.kind}${source.kind === "archive" ? ` ${source.archive_sha256}` : ""}) into ${mirrorRoot}`,
+	);
+	console.log(`tree ${bundle.treeSha256}; runtimes ${(bundle.runtimes ?? []).join(", ")}; acquisition ${PROVIDER_CONTRACT_ACQUISITION}`);
+}
+
+const isMainModule = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+	await main();
+}