import { spawn } from "node:child_process";
import { createHash, randomUUID } from "node:crypto";
import {
	chmodSync,
	closeSync,
	existsSync,
	fsyncSync,
	mkdirSync,
	openSync,
	readFileSync,
	realpathSync,
	renameSync,
	rmSync,
	statSync,
	unlinkSync,
	writeFileSync,
} from "node:fs";
import { hostname } from "node:os";
import { dirname, isAbsolute, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { execFileSync } from "node:child_process";
import {
	createNativeReviewCli,
	type NativeReviewCli,
	type NativeValidateResult,
} from "./native-review-cli.ts";

const TRANSACTION_SCHEMA = "gentle-pi.git-commit-transaction/v1";
const INVOCATION_SCHEMA = "gentle-pi.git-commit-transaction-invocation/v1";
const INDEX_ASSERTION_SCHEMA = "gentle-pi.git-commit-index-assertion/v1";
const COMMIT_CAPTURE_SCHEMA = "gentle-pi.git-commit-capture/v1";
const GIT_TIMEOUT_MS = 10_000;

export const COMMIT_TRANSACTION_STATE = {
	PREPARED: "prepared",
	HOOK_RUNNING: "hook-running",
	AWAITING_NATIVE: "awaiting-native",
	AWAITING_REVIEW: "awaiting-review",
	VALIDATION_FAILED: "validation-failed",
	VALIDATED: "validated",
	COMMIT_RUNNING: "commit-running",
	COMMIT_FAILED: "commit-failed",
	COMMITTED: "committed",
	HOOK_FAILED: "hook-failed",
	INTERRUPTED: "interrupted",
	INCIDENT: "incident",
	ABANDONED: "abandoned",
} as const;

export type CommitTransactionState =
	(typeof COMMIT_TRANSACTION_STATE)[keyof typeof COMMIT_TRANSACTION_STATE];

export interface CommitTransactionAuthorization {
	lineageId: string;
	storeRevision: string;
	fingerprint: string;
	intendedTree: string;
}

export interface CommitTransactionInvocation {
	schema: typeof INVOCATION_SCHEMA;
	transactionId: string;
	command: string;
	commandHash: string;
	cwd: string;
	arguments: readonly string[];
	authorization: CommitTransactionAuthorization;
}

interface CommitTransactionRecordBody {
	schema: typeof TRANSACTION_SCHEMA;
	transaction_id: string;
	repository_id: string;
	repository_root: string;
	common_directory: string;
	git_directory: string;
	command: string;
	command_hash: string;
	arguments: readonly string[];
	original_head?: string;
	original_head_tree?: string;
	original_index_tree: string;
	original_index_hash: string;
	authorized_pre_hook_tree: string;
	state: CommitTransactionState;
	created_at: string;
	updated_at: string;
	hook_runs: number;
	invocation_ids: readonly string[];
	lineage_history: readonly string[];
	post_hook_tree?: string;
	post_hook_index_hash?: string;
	authorized_tree?: string;
	authority_revision?: string;
	gate_context_hash?: string;
	committed_head?: string;
	committed_tree?: string;
	git_created_head?: string;
	git_created_tree?: string;
	error?: string;
	native_result?: Record<string, unknown>;
}

export interface CommitTransactionRecord extends CommitTransactionRecordBody {
	record_hash: string;
}

export interface CommitTransactionInspection {
	status: "clean" | "active" | "corrupted";
	record?: CommitTransactionRecord;
	reason?: string;
}

export interface CommitTransactionResult {
	transactionId: string;
	status: "committed" | "recovered";
	head: string;
	tree: string;
}

export interface CommitTransactionDependencies {
	nativeReviewCli?: NativeReviewCli;
	runnerPath?: string;
	now?: () => Date;
	signal?: AbortSignal;
	failpoint?: "after-commit-before-proof";
}

interface RepositoryBinding {
	root: string;
	commonDir: string;
	gitDir: string;
	repositoryId: string;
	stateDir: string;
	activePath: string;
	lockPath: string;
	historyDir: string;
}

interface LockBody {
	schema: "gentle-pi.git-commit-transaction-lock/v1";
	pid: number;
	host: string;
	transaction_id: string;
	created_at: string;
}

interface ProcessResult {
	code: number;
	signal: NodeJS.Signals | null;
}

function sha256(value: string | Buffer): string {
	return `sha256:${createHash("sha256").update(value).digest("hex")}`;
}

function canonicalJson(value: unknown): string {
	if (value === null || typeof value !== "object") return JSON.stringify(value);
	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
	const object = value as Record<string, unknown>;
	return `{${Object.keys(object).filter((key) => object[key] !== undefined).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
}

function recordHash(body: CommitTransactionRecordBody): string {
	return sha256(canonicalJson(body));
}

function git(cwd: string, args: readonly string[]): string {
	return execFileSync("git", args, {
		cwd,
		encoding: "utf8",
		stdio: ["ignore", "pipe", "pipe"],
		timeout: GIT_TIMEOUT_MS,
		windowsHide: true,
	}).trim();
}

function absoluteGitPath(cwd: string, name: string): string {
	const value = git(cwd, ["rev-parse", "--path-format=absolute", "--git-path", name]);
	return isAbsolute(value) ? value : resolve(cwd, value);
}

// Runs a probe that may exit nonzero as an expected signal (absent ref, unborn
// HEAD). Returns the exit status and trimmed stdout. Timeout and I/O failures
// propagate instead of being masked as a status, so callers fail closed.
function probeGit(cwd: string, args: readonly string[]): { status: number; stdout: string } {
	try {
		const stdout = execFileSync("git", args, {
			cwd,
			encoding: "utf8",
			stdio: ["ignore", "pipe", "pipe"],
			timeout: GIT_TIMEOUT_MS,
			windowsHide: true,
		});
		return { status: 0, stdout: stdout.trim() };
	} catch (error) {
		const detail = error as NodeJS.ErrnoException & { killed?: boolean; status?: number; stdout?: string | Buffer };
		if (detail.code === "ETIMEDOUT" || detail.killed === true) throw error;
		if (typeof detail.status === "number") return { status: detail.status, stdout: typeof detail.stdout === "string" ? detail.stdout.trim() : "" };
		throw error;
	}
}

// Resolves HEAD to a commit SHA, or undefined only for a valid unborn symbolic
// HEAD (symbolic HEAD pointing at a branch with no commits). Timeout, I/O,
// corruption, and all other failures propagate (fail closed on uncertain HEAD
// state). Classification uses status-based probes, not localized stderr text.
function resolveHead(cwd: string): string | undefined {
	try {
		return git(cwd, ["rev-parse", "--verify", "HEAD"]);
	} catch (error) {
		const detail = error as NodeJS.ErrnoException & { killed?: boolean };
		if (detail.code === "ETIMEDOUT" || detail.killed === true) throw error;
		if (typeof detail.status !== "number") throw error;
		const symbolic = probeGit(cwd, ["symbolic-ref", "--quiet", "HEAD"]);
		if (symbolic.status !== 0) throw error;
		// show-ref --verify --quiet distinguishes: status 1 = ref absent (valid
		// unborn), status 0 = ref exists and valid (rethrow original HEAD error),
		// any other status (128, etc.) = corruption/missing object (fail closed).
		const refProbe = probeGit(cwd, ["show-ref", "--verify", "--quiet", symbolic.stdout]);
		if (refProbe.status === 1) return undefined;
		throw error;
	}
}

function repositoryBinding(cwd: string): RepositoryBinding {
	const root = realpathSync(git(cwd, ["rev-parse", "--show-toplevel"]));
	const commonDirValue = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
	const gitDirValue = git(root, ["rev-parse", "--path-format=absolute", "--git-dir"]);
	const commonDir = realpathSync(commonDirValue);
	const gitDir = realpathSync(gitDirValue);
	// Preserve the durable repository identity across the unborn-handling
	// upgrade: a born repository keeps the byte-for-byte previous formula
	// `sha256(canonicalJson({ common_directory: commonDir, roots }))` with
	// `roots` the sorted root commits reachable from HEAD. An unborn
	// repository has no HEAD, so `rev-list HEAD` cannot run; resolveHead
	// already classifies HEAD state and propagates timeout/corruption/I/O
	// failures rather than masking them, so the unborn branch gets a
	// deterministic safe roots representation (the empty set) without
	// hiding real errors.
	const head = resolveHead(root);
	const roots = head === undefined
		? []
		: git(root, ["rev-list", "--max-parents=0", "HEAD"]).split(/\r?\n/).filter(Boolean).sort();
	const repositoryId = sha256(canonicalJson({ common_directory: commonDir, roots }));
	const worktreeKey = sha256(gitDir).slice("sha256:".length, "sha256:".length + 24);
	const stateDir = join(commonDir, "gentle-pi", "commit-transactions", worktreeKey);
	return {
		root,
		commonDir,
		gitDir,
		repositoryId,
		stateDir,
		activePath: join(stateDir, "active.json"),
		lockPath: join(stateDir, "lock.json"),
		historyDir: join(stateDir, "history"),
	};
}

function ensureStateDirectories(binding: RepositoryBinding): void {
	mkdirSync(binding.historyDir, { recursive: true, mode: 0o700 });
	chmodSync(dirname(binding.stateDir), 0o700);
	chmodSync(binding.stateDir, 0o700);
	chmodSync(binding.historyDir, 0o700);
}

function atomicWrite(path: string, value: string): void {
	const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
	const descriptor = openSync(temporary, "wx", 0o600);
	try {
		writeFileSync(descriptor, value, "utf8");
		fsyncSync(descriptor);
	} finally {
		closeSync(descriptor);
	}
	renameSync(temporary, path);
	if (process.platform !== "win32") {
		const directory = openSync(dirname(path), "r");
		try { fsyncSync(directory); } finally { closeSync(directory); }
	}
}

function writeRecord(path: string, body: CommitTransactionRecordBody): CommitTransactionRecord {
	const record: CommitTransactionRecord = { ...body, record_hash: recordHash(body) };
	atomicWrite(path, `${canonicalJson(record)}\n`);
	return record;
}

function isStringArray(value: unknown): value is string[] {
	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
}

function decodeRecord(value: unknown): CommitTransactionRecord {
	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("commit transaction record is not an object");
	const record = value as Record<string, unknown>;
	if (record.schema !== TRANSACTION_SCHEMA) throw new Error("commit transaction record schema is incompatible");
	for (const field of [
		"transaction_id", "repository_id", "repository_root", "common_directory", "git_directory",
		"command", "command_hash", "original_index_tree",
		"original_index_hash", "authorized_pre_hook_tree", "state", "created_at", "updated_at", "record_hash",
	]) if (typeof record[field] !== "string" || (record[field] as string).length === 0) throw new Error(`commit transaction record ${field} is invalid`);
	if (!isStringArray(record.arguments) || !isStringArray(record.invocation_ids) || !isStringArray(record.lineage_history)) throw new Error("commit transaction record arrays are invalid");
	for (const field of ["original_head", "original_head_tree", "post_hook_tree", "post_hook_index_hash", "authorized_tree", "authority_revision", "gate_context_hash", "committed_head", "committed_tree", "git_created_head", "git_created_tree", "error"] as const) {
		if (record[field] !== undefined && typeof record[field] !== "string") throw new Error(`commit transaction record ${field} is invalid`);
	}
	if (!Number.isSafeInteger(record.hook_runs) || (record.hook_runs as number) < 0) throw new Error("commit transaction hook count is invalid");
	if (!(Object.values(COMMIT_TRANSACTION_STATE) as readonly unknown[]).includes(record.state)) throw new Error("commit transaction state is invalid");
	const { record_hash: hash, ...body } = record;
	if (recordHash(body as unknown as CommitTransactionRecordBody) !== hash) throw new Error("commit transaction record integrity check failed");
	return record as unknown as CommitTransactionRecord;
}

function readRecord(path: string): CommitTransactionRecord | undefined {
	if (!existsSync(path)) return undefined;
	return decodeRecord(JSON.parse(readFileSync(path, "utf8")));
}

function bodyOf(record: CommitTransactionRecord): CommitTransactionRecordBody {
	const { record_hash: _hash, ...body } = record;
	return body;
}

function transition(
	binding: RepositoryBinding,
	record: CommitTransactionRecord,
	state: CommitTransactionState,
	patch: Partial<CommitTransactionRecordBody> = {},
	now: () => Date = () => new Date(),
): CommitTransactionRecord {
	return writeRecord(binding.activePath, {
		...bodyOf(record),
		...patch,
		state,
		updated_at: now().toISOString(),
	});
}

function archive(binding: RepositoryBinding, record: CommitTransactionRecord): CommitTransactionRecord {
	const archived = writeRecord(join(binding.historyDir, `${record.transaction_id}.json`), bodyOf(record));
	if (existsSync(binding.activePath)) unlinkSync(binding.activePath);
	return archived;
}

function processIsAlive(pid: number): boolean {
	try { process.kill(pid, 0); return true; } catch (error) {
		return (error as NodeJS.ErrnoException).code !== "ESRCH";
	}
}

function acquireLock(binding: RepositoryBinding, transactionId: string, now: () => Date): () => void {
	ensureStateDirectories(binding);
	const body: LockBody = {
		schema: "gentle-pi.git-commit-transaction-lock/v1",
		pid: process.pid,
		host: hostname(),
		transaction_id: transactionId,
		created_at: now().toISOString(),
	};
	for (let attempt = 0; attempt < 2; attempt += 1) {
		try {
			const descriptor = openSync(binding.lockPath, "wx", 0o600);
			try { writeFileSync(descriptor, `${canonicalJson(body)}\n`, "utf8"); fsyncSync(descriptor); }
			finally { closeSync(descriptor); }
			return () => { try { unlinkSync(binding.lockPath); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } };
		} catch (error) {
			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
			let existing: Partial<LockBody> = {};
			try { existing = JSON.parse(readFileSync(binding.lockPath, "utf8")) as Partial<LockBody>; } catch { /* fail closed below */ }
			if (existing.host === hostname() && typeof existing.pid === "number" && !processIsAlive(existing.pid)) {
				unlinkSync(binding.lockPath);
				continue;
			}
			throw new Error(`commit transaction lock is active${typeof existing.transaction_id === "string" ? ` for ${existing.transaction_id}` : ""}`);
		}
	}
	throw new Error("commit transaction stale lock could not be reconciled");
}

function indexFingerprint(cwd: string): string {
	const indexPath = absoluteGitPath(cwd, "index");
	if (!existsSync(indexPath)) return sha256("missing-index");
	const before = statSync(indexPath);
	const bytes = readFileSync(indexPath);
	const after = statSync(indexPath);
	if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
		throw new Error("Git index changed while its transaction fingerprint was captured");
	}
	return sha256(bytes);
}

function assertSafeCommitArguments(arguments_: readonly string[]): void {
	const booleanOptions = new Set([
		"--allow-empty", "--allow-empty-message", "--amend", "--edit", "--no-edit", "--no-gpg-sign",
		"--no-post-rewrite", "--no-signoff", "--no-status", "--no-verify", "--quiet", "--short",
		"--signoff", "--status", "--verbose",
	]);
	const valueOptions = new Set([
		"--author", "--cleanup", "--date", "--file", "--fixup", "--message", "--reedit-message",
		"--reuse-message", "--squash", "-C", "-F", "-c", "-m",
	]);
	const unsupportedTreeOptions = /^(?:--all|--include|--interactive|--only|--patch|--pathspec-from-file|--pathspec-file-nul|-a|-i|-o|-p)$/;
	for (let index = 0; index < arguments_.length; index += 1) {
		const argument = arguments_[index]!;
		if (argument === "--") {
			if (index !== arguments_.length - 1) throw new Error("commit pathspecs are unsupported by the transaction runner");
			continue;
		}
		if (argument === "--dry-run") throw new Error("commit --dry-run does not create a transaction");
		if (unsupportedTreeOptions.test(argument) || unsupportedTreeOptions.test(argument.split("=")[0]!)) throw new Error(`unsupported commit tree semantics: ${argument}`);
		if (argument === "-S" || argument === "--gpg-sign") continue;
		if (/^-S.+/.test(argument) || argument.startsWith("--gpg-sign=")) continue;
		if (/^-[^-]+$/.test(argument) && argument.length > 2) {
			const flags = argument.slice(1);
			if (/[^emnsqv]/.test(flags)) throw new Error(`unsupported combined commit option: ${argument}`);
			if (flags.includes("m")) {
				index += 1;
				if (arguments_[index] === undefined) throw new Error("commit message option is missing its value");
			}
			continue;
		}
		if (booleanOptions.has(argument)) continue;
		if ([...valueOptions].some((option) => argument.startsWith(`${option}=`))) continue;
		if (valueOptions.has(argument)) {
			index += 1;
			if (arguments_[index] === undefined) throw new Error(`commit option ${argument} is missing its value`);
			continue;
		}
		if (!argument.startsWith("-")) throw new Error("commit pathspecs are unsupported by the transaction runner");
		throw new Error(`unsupported commit option: ${argument}`);
	}
}

function shellQuote(value: string): string {
	if (process.platform === "win32") return `\"${value.replaceAll("\"", "\\\"")}\"`;
	return `'${value.replaceAll("'", `'\\''`)}'`;
}

function invocationBody(invocation: CommitTransactionInvocation): Record<string, unknown> {
	return {
		schema: invocation.schema,
		transaction_id: invocation.transactionId,
		command: invocation.command,
		command_hash: invocation.commandHash,
		cwd: invocation.cwd,
		arguments: invocation.arguments,
		authorization: {
			lineage_id: invocation.authorization.lineageId,
			store_revision: invocation.authorization.storeRevision,
			fingerprint: invocation.authorization.fingerprint,
			intended_tree: invocation.authorization.intendedTree,
		},
	};
}

export function encodeCommitTransactionInvocation(invocation: CommitTransactionInvocation): string {
	return Buffer.from(canonicalJson(invocationBody(invocation)), "utf8").toString("base64url");
}

export function decodeCommitTransactionInvocation(encoded: string): CommitTransactionInvocation {
	let value: unknown;
	try { value = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")); }
	catch { throw new Error("commit transaction invocation is malformed"); }
	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("commit transaction invocation is invalid");
	const body = value as Record<string, unknown>;
	const authorization = body.authorization;
	if (body.schema !== INVOCATION_SCHEMA || typeof body.transaction_id !== "string" || typeof body.command !== "string" || typeof body.command_hash !== "string" || typeof body.cwd !== "string" || !isStringArray(body.arguments) || typeof authorization !== "object" || authorization === null || Array.isArray(authorization)) throw new Error("commit transaction invocation is incompatible");
	const native = authorization as Record<string, unknown>;
	for (const field of ["lineage_id", "store_revision", "fingerprint", "intended_tree"]) if (typeof native[field] !== "string" || (native[field] as string).length === 0) throw new Error(`commit transaction authorization ${field} is invalid`);
	if (sha256(body.command) !== body.command_hash) throw new Error("commit transaction command hash is invalid");
	assertSafeCommitArguments(body.arguments);
	return {
		schema: INVOCATION_SCHEMA,
		transactionId: body.transaction_id,
		command: body.command,
		commandHash: body.command_hash,
		cwd: body.cwd,
		arguments: body.arguments,
		authorization: {
			lineageId: native.lineage_id as string,
			storeRevision: native.store_revision as string,
			fingerprint: native.fingerprint as string,
			intendedTree: native.intended_tree as string,
		},
	};
}

export function prepareCommitTransactionInvocation(input: {
	command: string;
	cwd: string;
	arguments: readonly string[];
	authorization: CommitTransactionAuthorization;
}): CommitTransactionInvocation {
	assertSafeCommitArguments(input.arguments);
	const binding = repositoryBinding(input.cwd);
	const head = resolveHead(binding.root);
	const currentTree = git(binding.root, ["write-tree"]);
	if (currentTree !== input.authorization.intendedTree) throw new Error("commit transaction pre-hook index no longer matches its controller authorization");
	let transactionId = randomUUID();
	const active = readRecord(binding.activePath);
	const commandHash = sha256(input.command);
	if (active !== undefined && active.command_hash === commandHash && active.original_head === head) transactionId = active.transaction_id;
	return {
		schema: INVOCATION_SCHEMA,
		transactionId,
		command: input.command,
		commandHash,
		cwd: binding.root,
		arguments: [...input.arguments],
		authorization: { ...input.authorization },
	};
}

export function commitTransactionRunnerPath(): string {
	return fileURLToPath(new URL("../scripts/run-git-commit-transaction.mjs", import.meta.url));
}

export function buildCommitTransactionShellCommand(invocation: CommitTransactionInvocation): string {
	return [
		shellQuote(process.execPath),
		shellQuote(commitTransactionRunnerPath()),
		"run",
		shellQuote(encodeCommitTransactionInvocation(invocation)),
	].join(" ");
}

function runProcess(file: string, arguments_: readonly string[], cwd: string, signal?: AbortSignal): Promise<ProcessResult> {
	return new Promise((resolvePromise, reject) => {
		const child = spawn(file, [...arguments_], { cwd, env: process.env, stdio: "inherit", windowsHide: true, signal });
		child.once("error", reject);
		child.once("close", (code, processSignal) => resolvePromise({ code: code ?? 1, signal: processSignal }));
	});
}

function assertionPayload(binding: RepositoryBinding, record: CommitTransactionRecord): string {
	return Buffer.from(canonicalJson({
		schema: INDEX_ASSERTION_SCHEMA,
		cwd: binding.root,
		transaction_id: record.transaction_id,
		authorized_tree: record.authorized_tree,
	}), "utf8").toString("base64url");
}

function capturePayload(binding: RepositoryBinding, record: CommitTransactionRecord): string {
	return Buffer.from(canonicalJson({
		schema: COMMIT_CAPTURE_SCHEMA,
		cwd: binding.root,
		transaction_id: record.transaction_id,
		authorized_tree: record.authorized_tree,
	}), "utf8").toString("base64url");
}

function writeHook(path: string, lines: readonly string[]): void {
	writeFileSync(path, `#!/bin/sh\nset -eu\n${lines.join("\n")}\n`, { encoding: "utf8", mode: 0o700 });
	chmodSync(path, 0o700);
}

function createHookProxy(binding: RepositoryBinding, record: CommitTransactionRecord, runnerPath: string): string {
	if (record.authorized_tree === undefined) throw new Error("commit transaction cannot create hooks before native authorization");
	const originalHooks = absoluteGitPath(binding.root, "hooks");
	const proxy = join(binding.stateDir, `hooks-${record.transaction_id}`);
	rmSync(proxy, { recursive: true, force: true });
	mkdirSync(proxy, { recursive: true, mode: 0o700 });
	const assertion = `${shellQuote(process.execPath)} ${shellQuote(runnerPath)} assert-index ${shellQuote(assertionPayload(binding, record))}`;
	const capture = `${shellQuote(process.execPath)} ${shellQuote(runnerPath)} capture-commit ${shellQuote(capturePayload(binding, record))}`;
	writeHook(join(proxy, "pre-commit"), [`exec ${assertion}`]);
	for (const name of ["prepare-commit-msg", "commit-msg"]) {
		const original = join(originalHooks, name);
		const lines = existsSync(original) && (statSync(original).mode & 0o111) !== 0
			? [`${shellQuote(original)} \"$@\"`, `exec ${assertion}`]
			: [`exec ${assertion}`];
		writeHook(join(proxy, name), lines);
	}
	const postCommit = join(originalHooks, "post-commit");
	writeHook(join(proxy, "post-commit"), [capture, ...(existsSync(postCommit) && (statSync(postCommit).mode & 0o111) !== 0 ? [`exec ${shellQuote(postCommit)} \"$@\"`] : [])]);
	const postRewrite = join(originalHooks, "post-rewrite");
	if (existsSync(postRewrite) && (statSync(postRewrite).mode & 0o111) !== 0) writeHook(join(proxy, "post-rewrite"), [`exec ${shellQuote(postRewrite)} \"$@\"`]);
	return proxy;
}

function nativeResultDocument(result: NativeValidateResult): Record<string, unknown> {
	return {
		allowed: result.allowed,
		result: result.result,
		action: result.action,
		reason: result.reason,
		context: result.gateContext.raw,
	};
}

function validateNativeTree(result: NativeValidateResult, lineageId: string, tree: string): void {
	if (!result.allowed || result.result !== "allow") throw new Error(`native pre-commit validation denied the post-hook tree: ${result.result}; ${result.action}; ${result.reason}`);
	if (result.gateContext.lineageId !== lineageId) throw new Error("native pre-commit validation returned a different lineage");
	if (result.gateContext.raw.gate !== "pre-commit") throw new Error("native pre-commit validation returned a different gate");
	if (result.gateContext.raw.candidate_tree !== tree) throw new Error("native pre-commit validation did not authorize the exact post-hook tree");
}

function createRecord(binding: RepositoryBinding, invocation: CommitTransactionInvocation, now: () => Date): CommitTransactionRecord {
	const head = resolveHead(binding.root);
	const tree = git(binding.root, ["write-tree"]);
	if (tree !== invocation.authorization.intendedTree) throw new Error("commit transaction index changed after controller authorization");
	const timestamp = now().toISOString();
	return writeRecord(binding.activePath, {
		schema: TRANSACTION_SCHEMA,
		transaction_id: invocation.transactionId,
		repository_id: binding.repositoryId,
		repository_root: binding.root,
		common_directory: binding.commonDir,
		git_directory: binding.gitDir,
		command: invocation.command,
		command_hash: invocation.commandHash,
		arguments: [...invocation.arguments],
		original_head: head,
		original_head_tree: head === undefined ? undefined : git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]),
		original_index_tree: tree,
		original_index_hash: indexFingerprint(binding.root),
		authorized_pre_hook_tree: invocation.authorization.intendedTree,
		state: COMMIT_TRANSACTION_STATE.PREPARED,
		created_at: timestamp,
		updated_at: timestamp,
		hook_runs: 0,
		invocation_ids: [invocation.transactionId],
		lineage_history: [invocation.authorization.lineageId],
	});
}

function assertInvocationMatches(binding: RepositoryBinding, record: CommitTransactionRecord, invocation: CommitTransactionInvocation): void {
	if (record.repository_id !== binding.repositoryId || record.repository_root !== binding.root || record.common_directory !== binding.commonDir || record.git_directory !== binding.gitDir) throw new Error("commit transaction repository identity changed");
	if (record.transaction_id !== invocation.transactionId || record.command_hash !== invocation.commandHash || record.command !== invocation.command || canonicalJson(record.arguments) !== canonicalJson(invocation.arguments)) throw new Error("commit transaction exact retry does not match the durable command intent");
	if (resolveHead(binding.root) !== record.original_head) throw new Error("commit transaction HEAD changed before reconciliation");
}

function recoverCompletedCommit(binding: RepositoryBinding, record: CommitTransactionRecord, now: () => Date): CommitTransactionResult | undefined {
	if (record.state !== COMMIT_TRANSACTION_STATE.COMMIT_RUNNING && record.state !== COMMIT_TRANSACTION_STATE.COMMITTED) return undefined;
	const head = resolveHead(binding.root);
	if (head === record.original_head) return undefined;
	if (head === undefined) {
		transition(binding, record, COMMIT_TRANSACTION_STATE.INCIDENT, { error: "HEAD disappeared during commit transaction" }, now);
		throw new Error("commit transaction incident: HEAD disappeared during commit; publication remains blocked");
	}
	const tree = git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]);
	if (record.git_created_head === undefined || record.git_created_tree === undefined || head !== record.git_created_head || tree !== record.git_created_tree || tree !== record.authorized_tree) {
		transition(binding, record, COMMIT_TRANSACTION_STATE.INCIDENT, { committed_head: head, committed_tree: tree, error: "HEAD identity differs from the exact Git-created authorized commit" }, now);
		throw new Error("commit transaction incident: HEAD identity differs from the exact Git-created authorized commit; push, PR, and release remain blocked");
	}
	const committed = transition(binding, record, COMMIT_TRANSACTION_STATE.COMMITTED, { committed_head: head, committed_tree: tree }, now);
	archive(binding, committed);
	return { transactionId: record.transaction_id, status: "recovered", head, tree };
}

function appendInvocation(record: CommitTransactionRecord, invocation: CommitTransactionInvocation): Partial<CommitTransactionRecordBody> {
	return {
		invocation_ids: [...new Set([...record.invocation_ids, invocation.transactionId])],
		lineage_history: [...new Set([...record.lineage_history, invocation.authorization.lineageId])],
	};
}

export async function runGitCommitTransaction(
	invocation: CommitTransactionInvocation,
	dependencies: CommitTransactionDependencies = {},
): Promise<CommitTransactionResult> {
	assertSafeCommitArguments(invocation.arguments);
	if (sha256(invocation.command) !== invocation.commandHash) throw new Error("commit transaction command identity is invalid");
	const now = dependencies.now ?? (() => new Date());
	const binding = repositoryBinding(invocation.cwd);
	const releaseLock = acquireLock(binding, invocation.transactionId, now);
	let record: CommitTransactionRecord | undefined;
	try {
		record = readRecord(binding.activePath);
		if (record !== undefined) {
			assertInvocationMatches(binding, record, invocation);
			const recovered = recoverCompletedCommit(binding, record, now);
			if (recovered !== undefined) return recovered;
			if ([COMMIT_TRANSACTION_STATE.HOOK_FAILED, COMMIT_TRANSACTION_STATE.VALIDATION_FAILED, COMMIT_TRANSACTION_STATE.COMMIT_FAILED, COMMIT_TRANSACTION_STATE.INTERRUPTED, COMMIT_TRANSACTION_STATE.INCIDENT, COMMIT_TRANSACTION_STATE.HOOK_RUNNING, COMMIT_TRANSACTION_STATE.COMMIT_RUNNING].includes(record.state as never)) {
				throw new Error(`commit transaction ${record.transaction_id} requires explicit recovery from state ${record.state}; no Git state was rolled back`);
			}
			if (record.state !== COMMIT_TRANSACTION_STATE.AWAITING_REVIEW && record.state !== COMMIT_TRANSACTION_STATE.AWAITING_NATIVE && record.state !== COMMIT_TRANSACTION_STATE.VALIDATED && record.state !== COMMIT_TRANSACTION_STATE.PREPARED) throw new Error(`commit transaction cannot resume from ${record.state}`);
			record = transition(binding, record, record.state, appendInvocation(record, invocation), now);
		} else {
			record = createRecord(binding, invocation, now);
		}

		const noVerify = invocation.arguments.includes("--no-verify") || invocation.arguments.some((argument) => /^-[^-]*n/.test(argument));
		if (record.state === COMMIT_TRANSACTION_STATE.PREPARED) {
			if (!noVerify) {
				record = transition(binding, record, COMMIT_TRANSACTION_STATE.HOOK_RUNNING, { hook_runs: record.hook_runs + 1 }, now);
				const hook = await runProcess("git", ["hook", "run", "--ignore-missing", "pre-commit"], binding.root, dependencies.signal);
				if (hook.code !== 0 || hook.signal !== null) {
					record = transition(binding, record, COMMIT_TRANSACTION_STATE.HOOK_FAILED, { error: `pre-commit hook failed with ${hook.signal ?? `exit ${hook.code}`}` }, now);
					throw new Error(`pre-commit hook failed; transaction ${record.transaction_id} created no commit and requires explicit recovery`);
				}
			}
			const postHookTree = git(binding.root, ["write-tree"]);
			record = transition(binding, record, COMMIT_TRANSACTION_STATE.AWAITING_NATIVE, {
				post_hook_tree: postHookTree,
				post_hook_index_hash: indexFingerprint(binding.root),
			}, now);
		}

		if (record.state === COMMIT_TRANSACTION_STATE.AWAITING_REVIEW) {
			const tree = git(binding.root, ["write-tree"]);
			if (tree !== record.post_hook_tree || indexFingerprint(binding.root) !== record.post_hook_index_hash) throw new Error("post-hook index changed while the commit transaction awaited review");
		}

		if (record.state === COMMIT_TRANSACTION_STATE.AWAITING_NATIVE || record.state === COMMIT_TRANSACTION_STATE.AWAITING_REVIEW || record.state === COMMIT_TRANSACTION_STATE.VALIDATED) {
			const currentTree = git(binding.root, ["write-tree"]);
			if (record.post_hook_tree !== currentTree) throw new Error("commit transaction post-hook tree changed before native validation");
			if (currentTree !== invocation.authorization.intendedTree) {
				const mutation = `pre-commit hook mutated the staged candidate: post-hook tree ${currentTree} is not the authorized tree ${invocation.authorization.intendedTree}; the content-bound receipt no longer covers this index; normalize sources and re-run review explicitly, or make the hook convergent, then retry the exact command; transaction ${record.transaction_id} created no commit`;
				record = transition(binding, record, COMMIT_TRANSACTION_STATE.AWAITING_REVIEW, { error: mutation }, now);
				throw new Error(mutation);
			}
			const nativeReviewCli = dependencies.nativeReviewCli ?? createNativeReviewCli();
			let nativeResult: NativeValidateResult;
			try {
				nativeResult = await nativeReviewCli.validate({ cwd: binding.root, gate: "pre-commit", lineageId: invocation.authorization.lineageId, ...(dependencies.signal === undefined ? {} : { signal: dependencies.signal }) });
			} catch (error) {
				record = transition(binding, record, COMMIT_TRANSACTION_STATE.VALIDATION_FAILED, { error: error instanceof Error ? error.message : String(error) }, now);
				throw error;
			}
			if (!nativeResult.allowed || nativeResult.result !== "allow") {
				const state = nativeResult.result === "scope-changed" ? COMMIT_TRANSACTION_STATE.AWAITING_REVIEW : COMMIT_TRANSACTION_STATE.VALIDATION_FAILED;
				record = transition(binding, record, state, { native_result: nativeResultDocument(nativeResult), error: nativeResult.reason }, now);
				throw new Error(`native pre-commit validation denied the post-hook tree: ${nativeResult.result}; ${nativeResult.action}; ${nativeResult.reason}`);
			}
			try { validateNativeTree(nativeResult, invocation.authorization.lineageId, currentTree); }
			catch (error) {
				record = transition(binding, record, COMMIT_TRANSACTION_STATE.INCIDENT, { native_result: nativeResultDocument(nativeResult), error: error instanceof Error ? error.message : String(error) }, now);
				throw error;
			}
			record = transition(binding, record, COMMIT_TRANSACTION_STATE.VALIDATED, {
				authorized_tree: currentTree,
				authority_revision: nativeResult.gateContext.storeRevision,
				gate_context_hash: sha256(canonicalJson(nativeResult.gateContext.raw)),
				native_result: nativeResultDocument(nativeResult),
				error: undefined,
			}, now);
		}

		const runnerPath = dependencies.runnerPath ?? commitTransactionRunnerPath();
		const proxy = createHookProxy(binding, record, runnerPath);
		dependencies.signal?.throwIfAborted();
		record = transition(binding, record, COMMIT_TRANSACTION_STATE.COMMIT_RUNNING, {}, now);
		const commit = await runProcess("git", ["-c", `core.hooksPath=${proxy}`, "commit", ...invocation.arguments], binding.root);
		if (dependencies.failpoint === "after-commit-before-proof") throw new Error("commit transaction test interruption after Git returned");
		record = readRecord(binding.activePath) ?? record;
		const head = resolveHead(binding.root);
		const headTree = head === undefined ? undefined : git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]);
		const headChanged = head !== record.original_head;
		if (headChanged && head === record.git_created_head && headTree === record.git_created_tree && headTree === record.authorized_tree) {
			const committed = transition(binding, record, COMMIT_TRANSACTION_STATE.COMMITTED, { committed_head: head, committed_tree: headTree, ...(commit.code === 0 && commit.signal === null ? {} : { error: `Git returned ${commit.signal ?? `exit ${commit.code}`} after creating the authorized commit` }) }, now);
			archive(binding, committed);
			return { transactionId: record.transaction_id, status: "committed", head: head!, tree: headTree! };
		}
		if (headChanged) {
			transition(binding, record, COMMIT_TRANSACTION_STATE.INCIDENT, { committed_head: head, committed_tree: headTree, error: "HEAD identity differs from the exact Git-created authorized commit" }, now);
			throw new Error("commit transaction incident: HEAD identity changed after Git created the authorized commit; publication remains blocked");
		}
		record = transition(binding, record, COMMIT_TRANSACTION_STATE.COMMIT_FAILED, { error: `Git commit failed with ${commit.signal ?? `exit ${commit.code}`}` }, now);
		throw new Error(`Git commit failed; transaction ${record.transaction_id} created no commit and requires explicit recovery`);
	} catch (error) {
		if (record !== undefined && dependencies.signal?.aborted === true && existsSync(binding.activePath)) {
			try {
				const active = readRecord(binding.activePath) ?? record;
				if (resolveHead(binding.root) === active.original_head) transition(binding, active, COMMIT_TRANSACTION_STATE.INTERRUPTED, { error: "commit transaction was cancelled" }, now);
			} catch { /* retain the earlier durable state */ }
		}
		throw error;
	} finally {
		releaseLock();
	}
}

export function assertCommitTransactionIndex(encoded: string): void {
	let value: unknown;
	try { value = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")); }
	catch { throw new Error("commit transaction index assertion is malformed"); }
	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("commit transaction index assertion is invalid");
	const body = value as Record<string, unknown>;
	if (body.schema !== INDEX_ASSERTION_SCHEMA || typeof body.cwd !== "string" || typeof body.transaction_id !== "string" || typeof body.authorized_tree !== "string") throw new Error("commit transaction index assertion is incompatible");
	const binding = repositoryBinding(body.cwd);
	const record = readRecord(binding.activePath);
	if (record === undefined || record.transaction_id !== body.transaction_id || record.state !== COMMIT_TRANSACTION_STATE.COMMIT_RUNNING || record.authorized_tree !== body.authorized_tree) throw new Error("commit transaction index assertion has no matching active authorization");
	if (git(binding.root, ["write-tree"]) !== body.authorized_tree) throw new Error("Git hook changed the index after native pre-commit authorization");
}

export function captureCommitTransactionHead(encoded: string): void {
	let value: unknown;
	try { value = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")); }
	catch { throw new Error("commit transaction capture is malformed"); }
	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("commit transaction capture is invalid");
	const body = value as Record<string, unknown>;
	if (body.schema !== COMMIT_CAPTURE_SCHEMA || typeof body.cwd !== "string" || typeof body.transaction_id !== "string" || typeof body.authorized_tree !== "string") throw new Error("commit transaction capture is incompatible");
	const binding = repositoryBinding(body.cwd);
	const record = readRecord(binding.activePath);
	if (record === undefined || record.transaction_id !== body.transaction_id || record.state !== COMMIT_TRANSACTION_STATE.COMMIT_RUNNING || record.authorized_tree !== body.authorized_tree) throw new Error("commit transaction capture has no matching active authorization");
	const head = git(binding.root, ["rev-parse", "--verify", "HEAD"]);
	const tree = git(binding.root, ["rev-parse", "--verify", "HEAD^{tree}"]);
	if (head === record.original_head || tree !== record.authorized_tree) throw new Error("commit transaction capture does not match a new authorized commit");
	if (record.git_created_head !== undefined && (record.git_created_head !== head || record.git_created_tree !== tree)) throw new Error("commit transaction capture conflicts with the recorded Git commit");
	transition(binding, record, COMMIT_TRANSACTION_STATE.COMMIT_RUNNING, { git_created_head: head, git_created_tree: tree });
}

export function inspectCommitTransaction(cwd: string): CommitTransactionInspection {
	let binding: RepositoryBinding;
	try { binding = repositoryBinding(cwd); }
	catch (error) { return { status: "corrupted", reason: error instanceof Error ? error.message : String(error) }; }
	try {
		const record = readRecord(binding.activePath);
		return record === undefined ? { status: "clean" } : { status: "active", record };
	} catch (error) {
		return { status: "corrupted", reason: error instanceof Error ? error.message : String(error) };
	}
}

export function reconcileCommitTransaction(cwd: string): CommitTransactionInspection {
	const binding = repositoryBinding(cwd);
	const active = readRecord(binding.activePath);
	if (active === undefined) return { status: "clean" };
	const now = () => new Date();
	const releaseLock = acquireLock(binding, active.transaction_id, now);
	try {
		const record = readRecord(binding.activePath);
		if (record === undefined) return { status: "clean" };
		const recovered = recoverCompletedCommit(binding, record, now);
		return recovered === undefined ? { status: "active", record } : { status: "clean" };
	} finally { releaseLock(); }
}

export function assertNoUnresolvedCommitTransaction(cwd: string): void {
	const inspection = inspectCommitTransaction(cwd);
	if (inspection.status === "clean") return;
	if (inspection.status === "corrupted") throw new Error(`commit transaction recovery state is corrupted: ${inspection.reason}`);
	throw new Error(`commit transaction ${inspection.record!.transaction_id} is unresolved in state ${inspection.record!.state}; publication is blocked until deterministic recovery completes`);
}

export function abandonCommitTransaction(cwd: string): CommitTransactionRecord {
	const binding = repositoryBinding(cwd);
	const now = () => new Date();
	const active = readRecord(binding.activePath);
	if (active === undefined) throw new Error("no active commit transaction exists");
	const releaseLock = acquireLock(binding, active.transaction_id, now);
	try {
		const record = readRecord(binding.activePath);
		if (record === undefined) throw new Error("active commit transaction disappeared during recovery");
		if (resolveHead(binding.root) !== record.original_head) throw new Error("cannot abandon a commit transaction after HEAD changed; reconcile the committed tree instead");
		const abandoned = transition(binding, record, COMMIT_TRANSACTION_STATE.ABANDONED, { error: "explicitly abandoned without changing HEAD or index" }, now);
		return archive(binding, abandoned);
	} finally { releaseLock(); }
}

export function verifyCommitTransactionResult(cwd: string, transactionId: string): CommitTransactionResult {
	const binding = repositoryBinding(cwd);
	const active = readRecord(binding.activePath);
	if (active?.transaction_id === transactionId) throw new Error(`commit transaction ${transactionId} remains unresolved in state ${active.state}`);
	const history = readRecord(join(binding.historyDir, `${transactionId}.json`));
	if (history === undefined || history.state !== COMMIT_TRANSACTION_STATE.COMMITTED || history.committed_head === undefined || history.committed_tree === undefined || history.git_created_head !== history.committed_head || history.git_created_tree !== history.committed_tree || history.authorized_tree !== history.committed_tree) throw new Error(`commit transaction ${transactionId} has no durable verified commit result`);
	const head = git(binding.root, ["rev-parse", "--verify", "HEAD"]);
	const tree = git(binding.root, ["rev-parse", "--verify", `${history.committed_head}^{tree}`]);
	if (head !== history.committed_head || tree !== history.committed_tree) throw new Error(`commit transaction ${transactionId} HEAD proof changed before tool_result reconciliation`);
	return { transactionId, status: "committed", head, tree };
}