forge-workflow 0.1.0-beta.6 → 0.1.0-beta.8

package/lib/test-workflow.js

@@ -0,0 +1,389 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { secureExecFileSync } = require('./shell-utils');
+const {
+	createProtectedStateAuditRecord,
+	recordProtectedStateAuditEvent,
+	removeProtectedFile,
+	writeProtectedFile,
+} = require('./protected-state-surfaces');
+const {
+	issueTestWorkflowAuthorization,
+	completeTestWorkflowAuthorization,
+} = require('./protected-state-authority');
+const {
+	readIndexedPackageManifest,
+	readPinnedBunVersion,
+	readSourcePackageManifest,
+	resolveCurrentHead,
+} = require('./bun-workflow-pins');
+
+const TEST_WORKFLOW_PATH = '.github/workflows/test.yml';
+const TEST_WORKFLOW_TEMPLATE_PATH = 'lib/workflow-templates/test.yml';
+const BUN_VERSION_PLACEHOLDER = '__BUN_VERSION__';
+const BUN_VERSION_PLACEHOLDER_COUNT = 8;
+
+/**
+ * Renders the canonical test workflow as exact bytes for one stable Bun version.
+ * The template must contain exactly eight version placeholders so every substitution is deterministic.
+ *
+ * @param {Buffer|string} template canonical workflow template bytes
+ * @param {string} bunVersion exact stable Bun version
+ * @returns {Buffer} rendered workflow bytes
+ * @throws {Error} when the version is not exact or the template placeholder count is not eight
+ */
+function renderTestWorkflow(template, bunVersion) {
+	if (!/^\d+\.\d+\.\d+$/.test(bunVersion)) {
+		throw new Error('Test workflow requires an exact stable Bun version.');
+	}
+	const source = Buffer.from(template).toString('utf8');
+	const count = source.split(BUN_VERSION_PLACEHOLDER).length - 1;
+	if (count !== BUN_VERSION_PLACEHOLDER_COUNT) {
+		throw new Error(`Test workflow template must contain exactly ${BUN_VERSION_PLACEHOLDER_COUNT} ${BUN_VERSION_PLACEHOLDER} placeholders; found ${count}.`);
+	}
+	return Buffer.from(source.replaceAll(BUN_VERSION_PLACEHOLDER, bunVersion));
+}
+
+function readGitFile(projectRoot, revision, filePath, execGit = secureExecFileSync) {
+	const indexed = revision === ':';
+	const options = {
+		cwd: projectRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+		windowsHide: true,
+	};
+	const entry = execGit('git', indexed
+		? ['ls-files', '--stage', '--', filePath]
+		: ['ls-tree', revision, '--', filePath], options).trim();
+	const suffix = filePath.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+	const expected = indexed
+		? new RegExp(String.raw`^100(?:644|755) [0-9a-f]+ 0\t${suffix}$`)
+		: new RegExp(String.raw`^100(?:644|755) blob [0-9a-f]+\t${suffix}$`);
+	if (!expected.test(entry)) {
+		const location = indexed ? 'in the Git index' : `at ${revision}`;
+		throw new Error(`${filePath} is not one regular file ${location}.`);
+	}
+	return Buffer.from(execGit('git', ['show', `${revision}${indexed ? '' : ':'}${filePath}`], {
+		...options,
+		encoding: 'buffer',
+	}));
+}
+
+function projectionObjectId(raw, filePath, indexed, sourceHead) {
+	const suffix = filePath.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+	const matching = raw.trim().split(/\r?\n/).filter(line => line.endsWith(`\t${filePath}`));
+	if (matching.length === 0) return null;
+	const pattern = indexed
+		? new RegExp(String.raw`^100(?:644|755) ([0-9a-f]+) 0\t${suffix}$`)
+		: new RegExp(String.raw`^100(?:644|755) blob ([0-9a-f]+)\t${suffix}$`);
+	if (matching.length !== 1 || !pattern.test(matching[0])) {
+		const location = indexed ? 'in the Git index' : `at ${sourceHead}`;
+		throw new Error(`${filePath} is not one regular file ${location}.`);
+	}
+	return pattern.exec(matching[0])[1];
+}
+
+/**
+ * Captures the committed package/template and stage-0 package/template/target by Git blob ID.
+ * A missing template remains null for legacy/bootstrap handling; nonregular or conflicted entries fail closed.
+ *
+ * @param {string} projectRoot repository root
+ * @param {string} sourceHead immutable source commit
+ * @param {Function} execGit Git execution seam
+ * @returns {{sourcePackage: Buffer, indexedPackage: Buffer, sourceTemplate: Buffer|null, indexedTemplate: Buffer|null, indexedWorkflow: Buffer|null}}
+ * @throws {Error} when required package blobs or present workflow entries are not one regular file
+ */
+function readTestWorkflowProjection(projectRoot, sourceHead, execGit = secureExecFileSync) {
+	const options = {
+		cwd: projectRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+		windowsHide: true,
+	};
+	const sourceEntries = execGit('git', [
+		'ls-tree', sourceHead, '--', 'package.json', TEST_WORKFLOW_TEMPLATE_PATH,
+	], options);
+	const indexedEntries = execGit('git', [
+		'ls-files', '--stage', '--', 'package.json', TEST_WORKFLOW_TEMPLATE_PATH, TEST_WORKFLOW_PATH,
+	], options);
+	const sourcePackageId = projectionObjectId(sourceEntries, 'package.json', false, sourceHead);
+	const indexedPackageId = projectionObjectId(indexedEntries, 'package.json', true, sourceHead);
+	if (sourcePackageId === null) throw new Error(`package.json is not a regular file at ${sourceHead}.`);
+	if (indexedPackageId === null) throw new Error('package.json is not one regular file in the Git index.');
+	const readObject = objectId => Buffer.from(execGit('git', ['cat-file', 'blob', objectId], {
+		...options,
+		encoding: 'buffer',
+	}));
+	const readOptionalObject = objectId => objectId === null ? null : readObject(objectId);
+	const sourceTemplateId = projectionObjectId(sourceEntries, TEST_WORKFLOW_TEMPLATE_PATH, false, sourceHead);
+	const indexedTemplateId = projectionObjectId(indexedEntries, TEST_WORKFLOW_TEMPLATE_PATH, true, sourceHead);
+	return {
+		sourcePackage: readObject(sourcePackageId),
+		indexedPackage: readObject(indexedPackageId),
+		sourceTemplate: readOptionalObject(sourceTemplateId),
+		indexedTemplate: readOptionalObject(indexedTemplateId),
+		indexedWorkflow: sourceTemplateId === null && indexedTemplateId === null
+			? null
+			: readOptionalObject(projectionObjectId(indexedEntries, TEST_WORKFLOW_PATH, true, sourceHead)),
+	};
+}
+
+function readRegularFile(projectRoot, filePath) {
+	const fullPath = path.join(projectRoot, filePath);
+	const stat = fs.lstatSync(fullPath);
+	if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${filePath} must be a regular file.`);
+	return fs.readFileSync(fullPath);
+}
+
+function snapshotWorkflow(projectRoot) {
+	const fullPath = path.join(projectRoot, TEST_WORKFLOW_PATH);
+	try {
+		const stat = fs.lstatSync(fullPath);
+		if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${TEST_WORKFLOW_PATH} must be a regular file.`);
+		return { existed: true, content: fs.readFileSync(fullPath) };
+	} catch (error) {
+		if (error.code === 'ENOENT') return { existed: false, content: null };
+		throw error;
+	}
+}
+
+function sameSnapshot(left, right) {
+	return left?.existed === right?.existed
+		&& (!left?.existed || (Buffer.isBuffer(left.content) && left.content.equals(right.content)));
+}
+
+/**
+ * Resolves one exact workflow update after checking HEAD, source baseline, index, and working-tree consistency.
+ * The result includes exact new bytes and the compare-and-swap snapshot used for recovery.
+ *
+ * @param {string} projectRoot repository root
+ * @param {string} sourceHead immutable source commit
+ * @param {object} options dependency seams and staged-state readers
+ * @returns {object} validated update, compare-and-swap snapshot, and exact output bytes
+ * @throws {Error} when the source baseline is noncanonical or staged/working bytes have drifted
+ */
+function resolveTestWorkflowUpdate(projectRoot, sourceHead, options = {}) {
+	const currentHead = (options.resolveHead || resolveCurrentHead)(projectRoot, options.execGit);
+	if (currentHead !== sourceHead) {
+		throw new Error(`Protected test workflow source HEAD changed from ${sourceHead} to ${currentHead}.`);
+	}
+
+	const sourcePackage = Buffer.from((options.readSourcePackageManifest || readSourcePackageManifest)(
+		projectRoot,
+		sourceHead,
+		options.execGit,
+	));
+	const indexedPackage = Buffer.from((options.readIndexedPackageManifest || readIndexedPackageManifest)(
+		projectRoot,
+		options.execGit,
+	));
+	const workingPackage = readRegularFile(projectRoot, 'package.json');
+	if (!workingPackage.equals(indexedPackage)) {
+		throw new Error('package.json differs from the Git index; stage the intended manifest before generating test.yml.');
+	}
+
+	const sourceTemplate = Buffer.from((options.readSourceTemplate || readGitFile)(
+		projectRoot,
+		sourceHead,
+		TEST_WORKFLOW_TEMPLATE_PATH,
+		options.execGit,
+	));
+	const indexedTemplate = Buffer.from((options.readIndexedTemplate || readGitFile)(
+		projectRoot,
+		':',
+		TEST_WORKFLOW_TEMPLATE_PATH,
+		options.execGit,
+	));
+	const workingTemplate = readRegularFile(projectRoot, TEST_WORKFLOW_TEMPLATE_PATH);
+	if (!workingTemplate.equals(indexedTemplate)) {
+		throw new Error(`${TEST_WORKFLOW_TEMPLATE_PATH} differs from the Git index; stage the intended template before generating test.yml.`);
+	}
+
+	const sourceWorkflow = Buffer.from((options.readSourceWorkflow || readGitFile)(
+		projectRoot,
+		sourceHead,
+		TEST_WORKFLOW_PATH,
+		options.execGit,
+	));
+	const sourceVersion = readPinnedBunVersion(sourcePackage);
+	const baseline = renderTestWorkflow(sourceTemplate, sourceVersion);
+	if (!sourceWorkflow.equals(baseline)) {
+		throw new Error(`${TEST_WORKFLOW_PATH} at ${sourceHead} differs from its canonical template output.`);
+	}
+
+	const version = readPinnedBunVersion(indexedPackage);
+	const content = renderTestWorkflow(indexedTemplate, version);
+	const snapshot = snapshotWorkflow(projectRoot);
+	if (!snapshot.existed || (!snapshot.content.equals(baseline) && !snapshot.content.equals(content))) {
+		throw new Error(`${TEST_WORKFLOW_PATH} has unrelated local edits; restore or commit them before generation.`);
+	}
+	const indexedWorkflow = Buffer.from((options.readIndexedWorkflow || readGitFile)(
+		projectRoot,
+		':',
+		TEST_WORKFLOW_PATH,
+		options.execGit,
+	));
+	if (!indexedWorkflow.equals(baseline) && !indexedWorkflow.equals(content)) {
+		throw new Error(`${TEST_WORKFLOW_PATH} has unrelated staged edits; restore or commit them before generation.`);
+	}
+
+	return { path: TEST_WORKFLOW_PATH, sourceHead, version, baseline, content, indexedWorkflow, snapshot };
+}
+
+function recoverWorkflow(snapshot, projectRoot, generatedContent, protectedWriter, protectedRemover, writeOptions) {
+	const recoveryOptions = {
+		...writeOptions,
+		operation: 'recover_test_workflow',
+		expectedContent: generatedContent,
+	};
+	return snapshot.existed
+		? protectedWriter(projectRoot, TEST_WORKFLOW_PATH, snapshot.content, recoveryOptions)
+		: protectedRemover(projectRoot, TEST_WORKFLOW_PATH, recoveryOptions);
+}
+
+function attemptRecovery(snapshot, projectRoot, generatedContent, protectedWriter, protectedRemover, writeOptions) {
+	try {
+		return recoverWorkflow(snapshot, projectRoot, generatedContent, protectedWriter, protectedRemover, writeOptions);
+	} catch (error) {
+		return { allowed: false, reason: error.message };
+	}
+}
+
+function matchesExpectedUpdate(expectedUpdate, update) {
+	if (!expectedUpdate) return true;
+	try {
+		return expectedUpdate.version === update.version
+			&& Buffer.from(expectedUpdate.content).equals(update.content);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Generates test.yml by validating HEAD/preflight bindings, authorizing exact bytes, writing atomically,
+ * auditing, and recording completion. Audit or completion failures conditionally restore the prior snapshot.
+ *
+ * @param {string} projectRoot repository root
+ * @param {object} options expected HEAD, actor, staged-state seams, and protected writer dependencies
+ * @returns {Promise<object>} success evidence or a handled failure with recovery evidence when applicable
+ * @throws {Error} when snapshot inspection itself cannot read the target filesystem state
+ */
+async function generateTestWorkflow(projectRoot, options = {}) {
+	const { verifyExpectedHead } = require('./npm-publish-workflow');
+	const head = verifyExpectedHead(projectRoot, options.expectedHead, options.resolveHead);
+	if (!head.success) return head;
+	const sourceHead = head.sourceHead;
+	if (options.expectedSnapshot && !sameSnapshot(options.expectedSnapshot, snapshotWorkflow(projectRoot))) {
+		return { success: false, error: `${TEST_WORKFLOW_PATH} changed after Bun pin batch preflight.` };
+	}
+	let update;
+	try {
+		update = resolveTestWorkflowUpdate(projectRoot, sourceHead, options);
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+	if (!matchesExpectedUpdate(options.expectedUpdate, update)) {
+		return { success: false, error: `${TEST_WORKFLOW_PATH} changed after Bun pin batch preflight.` };
+	}
+
+	const env = options.env || process.env;
+	const actor = options.actor || env.FORGE_PROTECTED_STATE_ACTOR || env.FORGE_ACTOR || env.USER || env.USERNAME || 'unknown';
+	const capabilityId = (options.createCapabilityId || randomUUID)();
+	const issueAuthorization = options.issueAuthorization || issueTestWorkflowAuthorization;
+	const completeAuthorization = options.completeAuthorization || completeTestWorkflowAuthorization;
+	const protectedWriter = options.writeProtectedFile || writeProtectedFile;
+	const protectedRemover = options.removeProtectedFile || removeProtectedFile;
+	const auditWriter = options.recordProtectedStateAuditEvent || recordProtectedStateAuditEvent;
+	let authorization;
+	try {
+		authorization = await issueAuthorization(projectRoot, {
+			actor,
+			sourceHead,
+			targetBunVersion: update.version,
+		}, { deps: options.kernelDeps, capabilityId });
+	} catch (error) {
+		authorization = { success: false, error: error.message };
+	}
+	if (!authorization.success || authorization.capabilityId !== capabilityId) {
+		return { success: false, error: `Could not authorize ${TEST_WORKFLOW_PATH}: ${authorization.error || 'authority returned a different capability id.'}` };
+	}
+
+	const writeOptions = {
+		actor,
+		operation: 'generate_test_workflow',
+		viaForgeApi: true,
+		surface: 'workflows',
+		expectedContent: update.snapshot.content,
+		...(options.beforeAtomicCommit ? { beforeAtomicCommit: options.beforeAtomicCommit } : {}),
+	};
+	let write;
+	try {
+		write = protectedWriter(projectRoot, TEST_WORKFLOW_PATH, update.content, writeOptions);
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+	if (!write.allowed) return { success: false, error: write.reason, write };
+
+	const audit = (() => {
+		try {
+			return auditWriter(createProtectedStateAuditRecord({
+				actor,
+				surface: 'workflows',
+				path: TEST_WORKFLOW_PATH,
+				content: update.content,
+				operation: 'generate_test_workflow',
+				viaForgeApi: true,
+				sourceHead,
+			}), { cwd: projectRoot });
+		} catch (error) {
+			return { success: false, error: error.message };
+		}
+	})();
+	if (!audit.success) {
+		const recovery = attemptRecovery(update.snapshot, projectRoot, update.content, protectedWriter, protectedRemover, writeOptions);
+		return { success: false, error: `Could not record ${TEST_WORKFLOW_PATH}: ${audit.error}`, audit, recovery };
+	}
+
+	let completion;
+	try {
+		completion = await completeAuthorization(projectRoot, {
+			actor,
+			sourceHead,
+			capabilityId,
+			targetBunVersion: update.version,
+		}, { deps: options.kernelDeps });
+	} catch (error) {
+		completion = { success: false, error: error.message };
+	}
+	if (!completion.success) {
+		const recovery = attemptRecovery(update.snapshot, projectRoot, update.content, protectedWriter, protectedRemover, writeOptions);
+		return { success: false, error: `Could not complete ${TEST_WORKFLOW_PATH}: ${completion.error}`, audit, completion, recovery };
+	}
+
+	return {
+		success: true,
+		path: TEST_WORKFLOW_PATH,
+		sourceHead,
+		bunVersion: update.version,
+		contentHash: write.contentHash,
+		write,
+		audit,
+		authorization,
+		completion,
+	};
+}
+
+module.exports = {
+	BUN_VERSION_PLACEHOLDER,
+	// Preserve the existing deep-import name while canonical callers use template terminology.
+	BUN_VERSION_TOKEN: BUN_VERSION_PLACEHOLDER,
+	TEST_WORKFLOW_PATH,
+	TEST_WORKFLOW_TEMPLATE_PATH,
+	renderTestWorkflow,
+	readTestWorkflowProjection,
+	resolveTestWorkflowUpdate,
+	generateTestWorkflow,
+};

package/lib/validation-receipt.js

@@ -0,0 +1,305 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { resolveWorktreeScope } = require('./protected-state-authority');
+const { QUICK_LANE_ENV_VAR, QUICK_LANE_VALUE } = require('../scripts/test');
+
+const SCHEMA_VERSION = 1;
+const RECEIPT_TTL_MS = 60 * 60 * 1000;
+const FUTURE_SKEW_MS = 60 * 1000;
+const RUNNER_ID = 'forge-full-suite-v1';
+const PUSH_PROOF_SCHEMA_VERSION = 1;
+const PUSH_MODES = Object.freeze({
+	full: Object.freeze(['branch-protection', 'lint', 'tests']),
+	quick: Object.freeze(['branch-protection', 'lint']),
+});
+
+function git(projectRoot, args, deps = {}) {
+	return (deps.execFileSync || execFileSync)('git', args, {
+		cwd: projectRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+	}).trim();
+}
+
+function resolveGitRoot(projectRoot, deps = {}) {
+	return path.resolve(git(projectRoot, ['rev-parse', '--show-toplevel'], deps));
+}
+
+function resolveReceiptPath(projectRoot, deps = {}) {
+	const root = resolveGitRoot(projectRoot, deps);
+	const gitPath = git(root, ['rev-parse', '--git-path', 'forge/validation-receipt.json'], deps);
+	return path.resolve(root, gitPath);
+}
+
+function resolveKeyPath(deps = {}) {
+	return path.join(deps.homeDir || os.homedir(), '.forge', 'validation-receipt.key');
+}
+
+function runtimeIdentity(deps = {}) {
+	return deps.runtimeIdentity
+		|| [process.platform, process.arch, process.versions.node, process.versions.bun || 'node'].join(':');
+}
+
+function commandIdentity(command, projectRoot, env, run, options = {}) {
+	let version;
+	try {
+		version = run(command, ['--version'], {
+			cwd: projectRoot,
+			encoding: 'utf8',
+			env,
+			stdio: ['ignore', 'pipe', 'pipe'],
+		}).trim();
+	} catch (error) {
+		if (options.missingIdentity && error?.code === 'ENOENT') return options.missingIdentity;
+		throw error;
+	}
+	const located = path.isAbsolute(command)
+		? fs.realpathSync.native(command)
+		: run(process.platform === 'win32' ? 'where.exe' : 'which', [command], {
+			encoding: 'utf8',
+			env,
+			stdio: ['ignore', 'pipe', 'pipe'],
+		}).trim().split(/\r?\n/)[0];
+	return `${process.platform === 'win32' ? located.toLowerCase() : located}:${version}`;
+}
+
+function testRuntimeIdentity(projectRoot, deps = {}, options = {}) {
+	if (deps.testRuntimeIdentity) return deps.testRuntimeIdentity;
+	const env = deps.env || process.env;
+	const run = deps.runtimeExecFileSync || execFileSync;
+	const bunCommand = env.BUN_EXE || 'bun';
+	return [
+		commandIdentity(bunCommand, projectRoot, env, run, {
+			missingIdentity: options.allowMissingDefaultBun && !env.BUN_EXE
+				? 'missing:default-bun'
+				: null,
+		}),
+		commandIdentity('node', projectRoot, env, run),
+	].join('|');
+}
+
+function captureState(projectRoot, deps = {}) {
+	const root = resolveGitRoot(projectRoot, deps);
+	return {
+		worktree: resolveWorktreeScope(root, deps),
+		head: git(root, ['rev-parse', 'HEAD'], deps),
+		clean: git(root, ['status', '--porcelain=v1', '--untracked-files=all'], deps) === '',
+		runtime: runtimeIdentity(deps),
+		testRuntime: testRuntimeIdentity(root, deps),
+		runner: RUNNER_ID,
+	};
+}
+
+function sameState(left, right) {
+	return left?.clean === true
+		&& right?.clean === true
+		&& left.worktree === right.worktree
+		&& left.head === right.head
+		&& left.runtime === right.runtime
+		&& left.testRuntime === right.testRuntime
+		&& left.runner === right.runner;
+}
+
+function capturePushState(projectRoot, deps = {}) {
+	if (deps.capturePushState) return deps.capturePushState(projectRoot);
+	const root = resolveGitRoot(projectRoot, deps);
+	const state = captureState(root, {
+		...deps,
+		testRuntimeIdentity: testRuntimeIdentity(root, deps, { allowMissingDefaultBun: true }),
+	});
+	delete state.runtime;
+	return {
+		...state,
+		branch: git(root, ['symbolic-ref', '--quiet', 'HEAD'], deps),
+	};
+}
+
+function samePushState(left, right) {
+	return left?.clean === true
+		&& right?.clean === true
+		&& left.worktree === right.worktree
+		&& left.head === right.head
+		&& left.testRuntime === right.testRuntime
+		&& left.runner === right.runner
+		&& left.branch === right.branch;
+}
+
+function hasExactGates(mode, gates) {
+	if (mode !== 'full' && mode !== 'quick') return false;
+	const expected = PUSH_MODES[mode];
+	return Boolean(expected)
+		&& Array.isArray(gates)
+		&& gates.length === expected.length
+		&& gates.every((gate, index) => gate === expected[index]);
+}
+
+function beginPushProof(projectRoot, deps = {}) {
+	try {
+		const state = capturePushState(projectRoot, deps);
+		return state.clean ? state : null;
+	} catch {
+		return null;
+	}
+}
+
+function createPushProof(projectRoot, snapshot, claims, deps = {}) {
+	if (!snapshot) throw new Error('push proof requires a clean pre-gate snapshot');
+	if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(claims?.nonce || '')) {
+		throw new Error('push proof requires a valid nonce');
+	}
+	if (!hasExactGates(claims?.mode, claims?.gates)) throw new Error('push proof gates do not match mode');
+	if (!Number.isInteger(claims?.owner?.pid) || claims.owner.pid <= 0 || typeof claims.owner.identity !== 'string' || !claims.owner.identity) {
+		throw new Error('push proof requires an exact process owner');
+	}
+	if (claims.mode === 'full' && (typeof claims.receiptIdentity !== 'string' || !claims.receiptIdentity)) {
+		throw new Error('full push proof requires test evidence identity');
+	}
+	const current = capturePushState(projectRoot, deps);
+	if (!samePushState(snapshot, current)) throw new Error('push proof state changed during gates');
+	const payload = {
+		schemaVersion: PUSH_PROOF_SCHEMA_VERSION,
+		type: 'forge-push-invocation',
+		nonce: claims.nonce,
+		state: current,
+		mode: claims.mode,
+		gates: [...claims.gates],
+		owner: { ...claims.owner },
+		receiptIdentity: claims.receiptIdentity || null,
+	};
+	return { payload, signature: sign(payload, deps) };
+}
+
+function verifyPushProof(projectRoot, proof, expected, deps = {}) {
+	try {
+		const payload = proof?.payload;
+		if (payload?.schemaVersion !== PUSH_PROOF_SCHEMA_VERSION || payload.type !== 'forge-push-invocation') {
+			return { valid: false, reason: 'schema' };
+		}
+		if (payload.nonce !== expected?.nonce) return { valid: false, reason: 'nonce' };
+		if (!signatureMatches(payload, proof.signature, deps)) return { valid: false, reason: 'signature' };
+		if (!hasExactGates(payload.mode, payload.gates)) return { valid: false, reason: 'gates' };
+		const quickLane = expected?.env?.[QUICK_LANE_ENV_VAR] === QUICK_LANE_VALUE;
+		if ((payload.mode === 'quick') !== quickLane) return { valid: false, reason: 'mode' };
+		if (payload.mode === 'full' && (typeof payload.receiptIdentity !== 'string' || !payload.receiptIdentity)) {
+			return { valid: false, reason: 'test-evidence' };
+		}
+		if (!samePushState(payload.state, capturePushState(projectRoot, deps))) {
+			return { valid: false, reason: 'state' };
+		}
+		return { valid: true, payload };
+	} catch {
+		return { valid: false, reason: 'missing-or-invalid' };
+	}
+}
+
+function validationIsComplete(result) {
+	const checks = result?.checks || {};
+	const tests = checks.tests || {};
+	return result?.success === true
+		&& checks.conflictMarkers?.success === true
+		&& checks.typeCheck?.success === true
+		&& (checks.typeCheck.skipped !== true || checks.typeCheck.notConfigured === true)
+		&& checks.lint?.success === true && checks.lint?.skipped !== true
+		&& checks.security?.success === true && checks.security?.skipped !== true
+		&& tests.success === true && tests.skipped !== true
+		&& tests.fullSuite === true && tests.testsFound === true
+		&& tests.total > 0 && tests.failed === 0;
+}
+
+function readOrCreateKey(deps = {}) {
+	const keyPath = resolveKeyPath(deps);
+	fs.mkdirSync(path.dirname(keyPath), { recursive: true });
+	try {
+		fs.writeFileSync(keyPath, crypto.randomBytes(32), { flag: 'wx', mode: 0o600 });
+	} catch (error) {
+		if (error.code !== 'EEXIST') throw error;
+	}
+	return fs.readFileSync(keyPath);
+}
+
+function sign(payload, deps = {}) {
+	return crypto.createHmac('sha256', readOrCreateKey(deps))
+		.update(JSON.stringify(payload))
+		.digest('hex');
+}
+
+function signatureMatches(payload, signature, deps = {}) {
+	if (!/^[a-f0-9]{64}$/.test(signature || '')) return false;
+	const expected = Buffer.from(sign(payload, deps), 'hex');
+	const actual = Buffer.from(signature, 'hex');
+	return actual.length === expected.length && crypto.timingSafeEqual(actual, expected);
+}
+
+function writeAtomic(filePath, content) {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	try {
+		fs.writeFileSync(temporary, content, { flag: 'wx', mode: 0o600 });
+		fs.renameSync(temporary, filePath);
+	} finally {
+		fs.rmSync(temporary, { force: true });
+	}
+}
+
+function beginValidation(projectRoot, deps = {}) {
+	try {
+		fs.rmSync(resolveReceiptPath(projectRoot, deps), { force: true });
+		const state = captureState(projectRoot, deps);
+		return state.clean ? state : null;
+	} catch {
+		return null;
+	}
+}
+
+function completeValidation(projectRoot, snapshot, result, deps = {}) {
+	try {
+		if (!snapshot || !validationIsComplete(result)) return false;
+		const current = captureState(projectRoot, deps);
+		if (!sameState(snapshot, current)) return false;
+		const issuedAt = (deps.now || Date.now)();
+		const payload = {
+			schemaVersion: SCHEMA_VERSION,
+			...current,
+			issuedAt,
+			expiresAt: issuedAt + RECEIPT_TTL_MS,
+			gates: ['conflictMarkers', 'typeCheck', 'lint', 'security', 'tests'],
+		};
+		writeAtomic(resolveReceiptPath(projectRoot, deps), JSON.stringify({ payload, signature: sign(payload, deps) }));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function verifyValidationReceipt(projectRoot, deps = {}) {
+	try {
+		const receipt = JSON.parse(fs.readFileSync(resolveReceiptPath(projectRoot, deps), 'utf8'));
+		if (receipt?.payload?.schemaVersion !== SCHEMA_VERSION) return { valid: false, reason: 'schema' };
+		if (!signatureMatches(receipt.payload, receipt.signature, deps)) return { valid: false, reason: 'signature' };
+		const now = (deps.now || Date.now)();
+		if (receipt.payload.issuedAt > now + FUTURE_SKEW_MS) return { valid: false, reason: 'future' };
+		if (receipt.payload.expiresAt < now) return { valid: false, reason: 'expired' };
+		if (!sameState(receipt.payload, captureState(projectRoot, deps))) return { valid: false, reason: 'state' };
+		return { valid: true, head: receipt.payload.head, identity: receipt.signature };
+	} catch {
+		return { valid: false, reason: 'missing-or-invalid' };
+	}
+}
+
+module.exports = {
+	beginValidation,
+	completeValidation,
+	resolveReceiptPath,
+	validationIsComplete,
+	verifyValidationReceipt,
+	_pushProof: {
+		begin: beginPushProof,
+		create: createPushProof,
+		verify: verifyPushProof,
+	},
+};