@gajae-code/coding-agent 0.12.21 → 0.13.0

package/src/sdk/elevation/grant-ledger.ts

@@ -0,0 +1,1142 @@
+import { randomUUID } from "node:crypto";
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { withFileLock } from "../../config/file-lock";
+import { assertSupportedStateVersion, SDK_STATE_VERSION } from "../broker/state-version";
+import { ElevationAudit, type ElevationAuditEntry } from "./audit";
+import {
+	ELEVATION_OPERATION_KINDS,
+	type ElevationOperation,
+	elevationRequestDigest,
+	isKnownElevationOperation,
+} from "./digest";
+import {
+	claimReceipt,
+	dispatchReceipt,
+	type ElevationAnswerAuthority,
+	type ElevationClaimIdentity,
+	type ElevationDispatchOutcome,
+	type ElevationDispatchReceipt,
+	isElevationAnswerAuthority,
+	isElevationClaimIdentity,
+	isElevationDispatchOutcome,
+	isElevationDispatchReceipt,
+	isElevationRequestId,
+	receiptClaimMatches,
+	uncertainReceipt,
+} from "./dispatch-receipt";
+import {
+	type BrokerOwnerPrincipal,
+	classifyProcessIncarnationLiveness,
+	isBrokerOwnerPrincipal,
+	sameBrokerOwnerPrincipal,
+} from "./owner";
+
+/**
+ * Broker-owned elevation grant ledger.
+ *
+ * Durable state machine (per elevation request):
+ * `requested -> granted -> claimed -> dispatched(outcome)`; terminal
+ * `denied`/`expired`/`misused`/`target_unavailable`; crash truth
+ * `consumed` (claimed but outcome unknown). Grants are single-use: the claim
+ * CAS consumes the grant before dispatch, and a crash between consume and
+ * dispatch is replayed truthfully as `consumed` with outcome `unknown`
+ * (retry requires a new grant — fail closed).
+ *
+ * All mutations and reads serialize on one elevation-local
+ * `withFileLock` transaction covering grants (`grants.jsonl`), dispatch
+ * receipts (`receipts.jsonl`), the issue index (`index.json`), and the
+ * audit trail (`audit.jsonl`), so a claim, its receipt, and the issue
+ * sequence commit together.
+ *
+ * The answer boundary is internal operator-only: there is no public
+ * `elevation.answer` operation; answers are admitted only from the internal
+ * operator attestation, so requester self-approval is impossible by
+ * construction.
+ */
+export type ElevationGrantState =
+	| "requested"
+	| "granted"
+	| "claimed"
+	| "dispatched"
+	| "consumed"
+	| "denied"
+	| "expired"
+	| "misused"
+	| "target_unavailable";
+
+export interface ElevationSessionIdentity {
+	sessionId: string;
+	/** Exact endpoint state root bound at issue time; never the repo root. */
+	endpointStateRoot: string;
+	endpointGeneration: number;
+	endpointIncarnation: string;
+}
+
+/** Audit-only requester binding; never an identity claim. */
+export interface ElevationRequester {
+	source: "broker_connection";
+	connectionId: string;
+}
+
+export interface ElevationGrantRecord {
+	version: typeof SDK_STATE_VERSION;
+	/** Durable correlation ID; UUID, path-safe. */
+	elevationRequestId: string;
+	/** Monotonic path-safe issue sequence, allocated under the ledger lock. */
+	issueIndex: number;
+	state: ElevationGrantState;
+	operation: ElevationOperation;
+	requestDigest: string;
+	sessionIdentity: ElevationSessionIdentity;
+	principal: BrokerOwnerPrincipal;
+	requester: ElevationRequester;
+	requestedAt: number;
+	expiresAt: number;
+	outcome?: ElevationDispatchOutcome;
+	ts: number;
+}
+
+export type ElevationErrorCode =
+	| "not_found"
+	| "invalid_input"
+	| "idempotency_conflict"
+	| "grant_spent"
+	| "elevation_claim_in_progress"
+	| "elevation_required"
+	| "elevation_unavailable"
+	| "elevation_not_required"
+	| "endpoint_stale"
+	| "target_unavailable"
+	| "expired"
+	| "misused"
+	| "duplicate_answer"
+	| "terminal_uncertain"
+	| (string & {});
+
+export type ElevationResult<T> =
+	| { ok: true; value: T }
+	| { ok: false; error: { code: ElevationErrorCode; message: string } };
+
+export interface ElevationIssueParams {
+	/** Optional caller-supplied correlation ID for idempotent retry; the broker generates a UUID otherwise. */
+	elevationRequestId?: string;
+	operation: ElevationOperation;
+	input: Record<string, unknown>;
+	sessionIdentity: ElevationSessionIdentity;
+	principal: BrokerOwnerPrincipal;
+	requester: ElevationRequester;
+	expiresInMs?: number;
+}
+
+export interface ElevationIssueValue {
+	replay: boolean;
+	elevationRequestId: string;
+	issueIndex: number;
+	requestDigest: string;
+	state: ElevationGrantState;
+	requestedAt: number;
+	expiresAt: number;
+	grant: ElevationGrantRecord;
+}
+
+export interface ElevationAnswerParams {
+	elevationRequestId: string;
+	answer: "approve" | "deny";
+	/** Digest the answering surface presented from the gate payload. */
+	presentedDigest: string;
+	/** Broker-owner principal attesting the answer authority. */
+	principal: BrokerOwnerPrincipal;
+	answerer: ElevationAnswerAuthority;
+	/** Current broker-resolved target identity; undefined means the session is unreachable. */
+	currentSessionIdentity?: ElevationSessionIdentity;
+}
+
+export type ElevationAnswerOutcome =
+	| "granted"
+	| "denied"
+	| "expired"
+	| "misused"
+	| "target_unavailable"
+	| "duplicate_answer";
+
+export interface ElevationAnswerValue {
+	outcome: ElevationAnswerOutcome;
+	grant: ElevationGrantRecord;
+}
+
+export interface ElevationClaimParams {
+	elevationRequestId: string;
+	claimIdentity: ElevationClaimIdentity;
+	/** Current broker-resolved target identity; undefined means the session is unreachable. */
+	currentSessionIdentity?: ElevationSessionIdentity;
+}
+
+export interface ElevationClaimValue {
+	grant: ElevationGrantRecord;
+	receipt: ElevationDispatchReceipt;
+}
+
+export interface ElevationDispatchParams {
+	elevationRequestId: string;
+	dispatchIdentity: ElevationClaimIdentity;
+	outcome: ElevationDispatchOutcome;
+}
+
+export interface ElevationDispatchValue {
+	grant: ElevationGrantRecord;
+	receipt: ElevationDispatchReceipt;
+}
+
+export interface ElevationReadValue {
+	grant: ElevationGrantRecord;
+	receipt?: ElevationDispatchReceipt;
+}
+
+export interface ElevationListValue {
+	grants: ElevationReadValue[];
+}
+
+export interface ElevationLedgerOptions {
+	/** Defaults to the GJC_SDK_ELEVATION_ENABLED environment flag. */
+	enabled?: boolean;
+	/** Request lifetime before the grant expires. */
+	ttlMs?: number;
+	/** Injectable clock. */
+	now?: () => number;
+	/**
+	 * Injectable tri-state process-incarnation liveness classifier (defaults to
+	 * `classifyProcessIncarnationLiveness`). Test seam for crash-state replay:
+	 * "unknown" must always fail closed as `elevation_claim_in_progress`.
+	 */
+	classifyLiveness?: typeof classifyProcessIncarnationLiveness;
+}
+
+const ELEVATION_DIR_NAME = "elevation";
+const MAX_ELEVATION_FILE_BYTES = 64 * 1024 * 1024;
+const MAX_ELEVATION_LINE_BYTES = 8 * 1024 * 1024;
+const ELEVATION_REQUEST_TTL_MS = 60_000;
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+const CANONICAL_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const ELEVATION_GRANT_STATES = [
+	"requested",
+	"granted",
+	"claimed",
+	"dispatched",
+	"consumed",
+	"denied",
+	"expired",
+	"misused",
+	"target_unavailable",
+] as const;
+
+const elevationUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+function parseElevationJson(bytes: Uint8Array): unknown {
+	return JSON.parse(elevationUtf8Decoder.decode(bytes));
+}
+
+function elevationEnabledByDefault(): boolean {
+	const raw = (process.env.GJC_SDK_ELEVATION_ENABLED ?? "").trim().toLowerCase();
+	return raw === "1" || raw === "true";
+}
+
+function elevationFailure<T>(code: ElevationErrorCode, message: string): ElevationResult<T> {
+	return { ok: false, error: { code, message } };
+}
+
+function isElevationOperation(value: unknown): value is ElevationOperation {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const operation = value as { kind?: unknown; sdkId?: unknown };
+	return (
+		typeof operation.kind === "string" &&
+		(ELEVATION_OPERATION_KINDS as readonly string[]).includes(operation.kind) &&
+		typeof operation.sdkId === "string" &&
+		operation.sdkId.length > 0 &&
+		operation.sdkId.length <= 128 &&
+		isKnownElevationOperation(operation.kind, operation.sdkId)
+	);
+}
+
+function isElevationGrantState(value: unknown): value is ElevationGrantState {
+	return typeof value === "string" && (ELEVATION_GRANT_STATES as readonly string[]).includes(value);
+}
+
+function isElevationSessionIdentity(value: unknown): value is ElevationSessionIdentity {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const identity = value as {
+		sessionId?: unknown;
+		endpointStateRoot?: unknown;
+		endpointGeneration?: unknown;
+		endpointIncarnation?: unknown;
+	};
+	return (
+		typeof identity.sessionId === "string" &&
+		CANONICAL_SESSION_ID.test(identity.sessionId) &&
+		typeof identity.endpointStateRoot === "string" &&
+		identity.endpointStateRoot.length > 0 &&
+		Number.isSafeInteger(identity.endpointGeneration) &&
+		(identity.endpointGeneration as number) > 0 &&
+		typeof identity.endpointIncarnation === "string" &&
+		SHA256_HEX.test(identity.endpointIncarnation)
+	);
+}
+
+function isElevationRequester(value: unknown): value is ElevationRequester {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const requester = value as { source?: unknown; connectionId?: unknown };
+	return (
+		requester.source === "broker_connection" &&
+		typeof requester.connectionId === "string" &&
+		requester.connectionId.length > 0
+	);
+}
+
+function isElevationGrantRecord(value: unknown): value is ElevationGrantRecord {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value as Partial<ElevationGrantRecord>;
+	if (
+		record.version !== SDK_STATE_VERSION ||
+		!isElevationRequestId(record.elevationRequestId) ||
+		!Number.isSafeInteger(record.issueIndex) ||
+		(record.issueIndex as number) <= 0 ||
+		!isElevationGrantState(record.state) ||
+		!isElevationOperation(record.operation) ||
+		typeof record.requestDigest !== "string" ||
+		!SHA256_HEX.test(record.requestDigest) ||
+		!isElevationSessionIdentity(record.sessionIdentity) ||
+		!isBrokerOwnerPrincipal(record.principal) ||
+		!isElevationRequester(record.requester) ||
+		!Number.isSafeInteger(record.requestedAt) ||
+		(record.requestedAt as number) <= 0 ||
+		!Number.isSafeInteger(record.expiresAt) ||
+		(record.expiresAt as number) <= 0 ||
+		!Number.isSafeInteger(record.ts) ||
+		(record.ts as number) <= 0
+	)
+		return false;
+	const outcome = record.outcome;
+	if (record.state === "dispatched") return isElevationDispatchOutcome(outcome) && outcome.status !== "unknown";
+	if (record.state === "consumed") return isElevationDispatchOutcome(outcome) && outcome.status === "unknown";
+	return outcome === undefined;
+}
+
+function sameSessionIdentity(left: ElevationSessionIdentity, right: ElevationSessionIdentity): boolean {
+	return (
+		left.sessionId === right.sessionId &&
+		path.resolve(left.endpointStateRoot) === path.resolve(right.endpointStateRoot) &&
+		left.endpointGeneration === right.endpointGeneration &&
+		left.endpointIncarnation === right.endpointIncarnation
+	);
+}
+
+type ReconcileOutcome = "ok" | "expired" | "uncertain" | "in_progress";
+export class ElevationLedger {
+	#dir: string;
+	#agentDir: string;
+	#grantsFile: string;
+	#receiptsFile: string;
+	#indexFile: string;
+	#audit: ElevationAudit;
+	#enabled: boolean;
+	#ttlMs: number;
+	#now: () => number;
+	#grants: ElevationGrantRecord[] = [];
+	#receipts: ElevationDispatchReceipt[] = [];
+	#byRequestId = new Map<string, ElevationGrantRecord>();
+	#byReceiptRequestId = new Map<string, ElevationDispatchReceipt>();
+	#nextIssueIndex = 1;
+	#warnings: string[] = [];
+	#classifyLiveness: typeof classifyProcessIncarnationLiveness;
+
+	constructor(agentDir: string, options: ElevationLedgerOptions = {}) {
+		this.#agentDir = agentDir;
+		this.#dir = path.join(agentDir, "sdk", ELEVATION_DIR_NAME);
+		this.#grantsFile = path.join(this.#dir, "grants.jsonl");
+		this.#receiptsFile = path.join(this.#dir, "receipts.jsonl");
+		this.#indexFile = path.join(this.#dir, "index.json");
+		this.#audit = new ElevationAudit(agentDir, { now: options.now, classifyLiveness: options.classifyLiveness });
+		this.#enabled = options.enabled ?? elevationEnabledByDefault();
+		this.#ttlMs = options.ttlMs ?? ELEVATION_REQUEST_TTL_MS;
+		this.#now = options.now ?? Date.now;
+		this.#classifyLiveness = options.classifyLiveness ?? classifyProcessIncarnationLiveness;
+	}
+
+	get warnings(): readonly string[] {
+		return this.#warnings;
+	}
+
+	/**
+	 * One elevation-local lock serializes grants, receipts, and the issue
+	 * index: the same transaction covers every file the ledger owns.
+	 */
+	async #mutate<T>(operation: () => Promise<T>): Promise<T> {
+		return withFileLock(this.#grantsFile, operation);
+	}
+
+	async open(): Promise<this> {
+		await this.#mutate(async () => this.#openUnderLock());
+		return this;
+	}
+
+	async #openUnderLock(): Promise<void> {
+		await fs.mkdir(this.#dir, { recursive: true, mode: 0o700 });
+		this.#audit = await new ElevationAudit(this.#agentDir, {
+			now: this.#now,
+			classifyLiveness: this.#classifyLiveness,
+		}).open();
+		this.#grants = [];
+		this.#receipts = [];
+		this.#byRequestId.clear();
+		this.#byReceiptRequestId.clear();
+		this.#warnings = [];
+		this.#warnings.push(...this.#audit.warnings);
+		let nextIssueIndex = 1;
+		const indexRaw = await this.#readIndex();
+		if (indexRaw !== undefined) {
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(indexRaw);
+			} catch {
+				throw new Error("Invalid elevation issue index");
+			}
+			assertSupportedStateVersion(this.#indexFile, parsed);
+			const index = parsed as { nextIssueIndex?: unknown };
+			if (!Number.isSafeInteger(index.nextIssueIndex) || (index.nextIssueIndex as number) < 1)
+				throw new Error("Invalid elevation issue index");
+			nextIssueIndex = index.nextIssueIndex as number;
+		}
+		const grantSource = await this.#readBoundedSource(this.#grantsFile);
+		let maxIssueIndex = 0;
+		if (grantSource) maxIssueIndex = await this.#loadGrantRows(grantSource);
+		const receiptSource = await this.#readBoundedSource(this.#receiptsFile);
+		if (receiptSource) await this.#loadReceiptRows(receiptSource);
+		// Grants are the source of truth for issued indexes: a crash between
+		// appending a grant row and rewriting index.json must never reuse it.
+		const healed = Math.max(nextIssueIndex, maxIssueIndex + 1);
+		if (healed !== nextIssueIndex) await this.#writeIndex(healed);
+		this.#nextIssueIndex = healed;
+	}
+
+	async assertSupportedStateVersions(): Promise<void> {
+		for (const file of [this.#grantsFile, this.#receiptsFile]) {
+			const source = await this.#readBoundedSource(file);
+			if (!source) continue;
+			let lineStart = 0;
+			for (let offset = 0; offset <= source.length; offset += 1) {
+				if (offset !== source.length && source[offset] !== 0x0a) continue;
+				const line = source.subarray(lineStart, offset);
+				lineStart = offset + 1;
+				if (line.length === 0 || line.length > MAX_ELEVATION_LINE_BYTES) continue;
+				try {
+					assertSupportedStateVersion(file, parseElevationJson(line));
+				} catch (error) {
+					if (error instanceof Error && "code" in error && error.code === "unsupported_state_version") throw error;
+				}
+			}
+		}
+	}
+
+	async #readIndex(): Promise<string | undefined> {
+		let handle: fs.FileHandle | undefined;
+		try {
+			handle = await fs.open(this.#indexFile, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW);
+			const stat = await handle.stat();
+			if (!stat.isFile()) throw new Error("Elevation issue index is not a regular file");
+			if (stat.size > MAX_ELEVATION_LINE_BYTES)
+				throw new Error("Elevation issue index exceeds the maximum byte length");
+			const bytes = Buffer.alloc(stat.size + 1);
+			const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+			return elevationUtf8Decoder.decode(bytes.subarray(0, bytesRead));
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+			throw error;
+		} finally {
+			if (handle) await handle.close();
+		}
+	}
+
+	async #readBoundedSource(file: string): Promise<Buffer | undefined> {
+		let handle: fs.FileHandle | undefined;
+		try {
+			handle = await fs.open(file, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW);
+			const stat = await handle.stat({ bigint: true });
+			if (!stat.isFile()) throw new Error(`Elevation ledger target is not a regular file: ${file}`);
+			if (stat.size > BigInt(MAX_ELEVATION_FILE_BYTES))
+				throw new Error(`Elevation ledger file exceeds the maximum byte length: ${file}`);
+			const bytes = Buffer.alloc(Number(stat.size) + 1);
+			const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+			return bytes.subarray(0, bytesRead);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+			throw error;
+		} finally {
+			if (handle) await handle.close();
+		}
+	}
+
+	async #loadGrantRows(source: Buffer): Promise<number> {
+		let maxIssueIndex = 0;
+		const tornTail = source.length > 0 && source.at(-1) !== 0x0a;
+		let lineStart = 0;
+		for (let offset = 0; offset <= source.length; offset += 1) {
+			if (offset !== source.length && source[offset] !== 0x0a) continue;
+			const line = source.subarray(lineStart, offset);
+			lineStart = offset + 1;
+			if (line.length === 0) continue;
+			if (line.length > MAX_ELEVATION_LINE_BYTES)
+				throw new Error("Elevation grant row exceeds the maximum byte length");
+			try {
+				const value = parseElevationJson(line);
+				assertSupportedStateVersion(this.#grantsFile, value);
+				if (!isElevationGrantRecord(value)) throw new Error("invalid elevation grant record");
+				this.#grants.push(value);
+				this.#byRequestId.set(value.elevationRequestId, value);
+				if (value.issueIndex > maxIssueIndex) maxIssueIndex = value.issueIndex;
+			} catch (error) {
+				if (error instanceof Error && "code" in error && error.code === "unsupported_state_version") throw error;
+				await this.#quarantine(this.#grantsFile, line);
+			}
+		}
+		if (tornTail) await this.#sealTornTail(this.#grantsFile);
+		return maxIssueIndex;
+	}
+
+	async #loadReceiptRows(source: Buffer): Promise<void> {
+		const tornTail = source.length > 0 && source.at(-1) !== 0x0a;
+		let lineStart = 0;
+		for (let offset = 0; offset <= source.length; offset += 1) {
+			if (offset !== source.length && source[offset] !== 0x0a) continue;
+			const line = source.subarray(lineStart, offset);
+			lineStart = offset + 1;
+			if (line.length === 0) continue;
+			if (line.length > MAX_ELEVATION_LINE_BYTES)
+				throw new Error("Elevation receipt row exceeds the maximum byte length");
+			try {
+				const value = parseElevationJson(line);
+				assertSupportedStateVersion(this.#receiptsFile, value);
+				if (!isElevationDispatchReceipt(value)) throw new Error("invalid elevation dispatch receipt");
+				this.#receipts.push(value);
+				this.#byReceiptRequestId.set(value.elevationRequestId, value);
+			} catch (error) {
+				if (error instanceof Error && "code" in error && error.code === "unsupported_state_version") throw error;
+				await this.#quarantine(this.#receiptsFile, line);
+			}
+		}
+		if (tornTail) await this.#sealTornTail(this.#receiptsFile);
+	}
+
+	async #openAppendRegular(file: string): Promise<fs.FileHandle> {
+		const handle = await fs.open(
+			file,
+			fsSync.constants.O_WRONLY | fsSync.constants.O_APPEND | fsSync.constants.O_CREAT | fsSync.constants.O_NOFOLLOW,
+			0o600,
+		);
+		try {
+			if (!(await handle.stat()).isFile()) throw new Error("Elevation ledger write target is not a regular file.");
+			return handle;
+		} catch (error) {
+			await handle.close();
+			throw error;
+		}
+	}
+
+	async #sealTornTail(file: string): Promise<void> {
+		const h = await this.#openAppendRegular(file);
+		try {
+			await h.writeFile("\n");
+			await h.sync();
+		} finally {
+			await h.close();
+		}
+	}
+
+	async #quarantine(file: string, line: Uint8Array): Promise<void> {
+		const h = await this.#openAppendRegular(`${file}.corrupt`);
+		try {
+			await h.writeFile(line);
+			await h.writeFile("\n");
+			await h.sync();
+		} finally {
+			await h.close();
+		}
+		this.#warnings.push("Malformed elevation ledger entry quarantined");
+	}
+
+	async #syncDirectory(): Promise<void> {
+		const directory = await fs.open(this.#dir, fsSync.constants.O_RDONLY);
+		try {
+			await directory.sync();
+		} finally {
+			await directory.close();
+		}
+	}
+
+	async #writeIndex(nextIssueIndex: number): Promise<void> {
+		const contents = Buffer.from(`${JSON.stringify({ version: SDK_STATE_VERSION, nextIssueIndex })}\n`);
+		const temporary = path.join(
+			this.#dir,
+			`.index.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`,
+		);
+		let renamed = false;
+		try {
+			const h = await fs.open(
+				temporary,
+				fsSync.constants.O_WRONLY |
+					fsSync.constants.O_CREAT |
+					fsSync.constants.O_EXCL |
+					fsSync.constants.O_NOFOLLOW,
+				0o600,
+			);
+			try {
+				await h.writeFile(contents);
+				await h.sync();
+			} finally {
+				await h.close();
+			}
+			await fs.rename(temporary, this.#indexFile);
+			renamed = true;
+			await this.#syncDirectory();
+		} finally {
+			if (!renamed) await fs.unlink(temporary).catch(() => {});
+		}
+	}
+
+	async #appendGrant(record: ElevationGrantRecord): Promise<void> {
+		const line = Buffer.from(`${JSON.stringify(record)}\n`);
+		if (line.length - 1 > MAX_ELEVATION_LINE_BYTES)
+			throw new Error("Elevation grant row exceeds the maximum byte length");
+		const h = await this.#openAppendRegular(this.#grantsFile);
+		try {
+			await h.writeFile(line);
+			await h.sync();
+		} finally {
+			await h.close();
+		}
+		this.#grants.push(record);
+		this.#byRequestId.set(record.elevationRequestId, record);
+	}
+
+	async #appendReceipt(receipt: ElevationDispatchReceipt): Promise<void> {
+		const line = Buffer.from(`${JSON.stringify(receipt)}\n`);
+		if (line.length - 1 > MAX_ELEVATION_LINE_BYTES)
+			throw new Error("Elevation receipt row exceeds the maximum byte length");
+		const h = await this.#openAppendRegular(this.#receiptsFile);
+		try {
+			await h.writeFile(line);
+			await h.sync();
+		} finally {
+			await h.close();
+		}
+		this.#receipts.push(receipt);
+		this.#byReceiptRequestId.set(receipt.elevationRequestId, receipt);
+	}
+
+	/**
+	 * Appends one audit row for an elevation transition. Must be called under
+	 * the same elevation-local lock as the grant/receipt appends so the audit
+	 * row and the durable grant row commit together.
+	 */
+	async #appendAudit(entry: Omit<ElevationAuditEntry, "version">): Promise<void> {
+		await this.#audit.append(entry);
+	}
+
+	/**
+	 * Truthful reconciliation before any access: heals a grant row that a
+	 * crash left behind a terminal receipt, lazily expires overdue requests,
+	 * and terminalizes claims left by provably dead broker tenures to
+	 * `consumed`/`uncertain`. Unknown liveness always resolves to
+	 * `in_progress` (fail closed — never fabricate an outcome).
+	 */
+	async #reconcile(
+		grant: ElevationGrantRecord,
+		receipt: ElevationDispatchReceipt | undefined,
+		claimIdentity: ElevationClaimIdentity,
+		now: number,
+	): Promise<ReconcileOutcome> {
+		if (receipt?.state === "dispatched") {
+			if (grant.state !== "dispatched")
+				await this.#appendGrant({ ...grant, state: "dispatched", outcome: receipt.outcome, ts: now });
+			return "ok";
+		}
+		if (receipt?.state === "uncertain") {
+			if (grant.state !== "consumed")
+				await this.#appendGrant({ ...grant, state: "consumed", outcome: receipt.outcome, ts: now });
+			return "uncertain";
+		}
+		if (receipt?.state === "claimed") {
+			if (receiptClaimMatches(receipt, claimIdentity)) return "in_progress";
+			const liveness = this.#classifyLiveness(receipt.claim.pid, receipt.claim.incarnation);
+			if (liveness === "dead") {
+				if (grant.state !== "consumed")
+					await this.#appendGrant({
+						...grant,
+						state: "consumed",
+						outcome: {
+							status: "unknown",
+							message: "Claiming broker tenure ended before dispatch outcome was recorded",
+							dispatchedAt: now,
+						},
+						ts: now,
+					});
+				await this.#appendReceipt(uncertainReceipt(receipt, now));
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: {
+						kind: "consumed",
+						message: "Claiming broker tenure ended before dispatch outcome was recorded",
+					},
+				});
+				return "uncertain";
+			}
+			// Alive or unknown liveness: the claim may still be in flight.
+			return "in_progress";
+		}
+		if ((grant.state === "requested" || grant.state === "granted") && now > grant.expiresAt) {
+			await this.#appendGrant({ ...grant, state: "expired", ts: now });
+			await this.#appendAudit({
+				ts: now,
+				elevationRequestId: grant.elevationRequestId,
+				issueIndex: grant.issueIndex,
+				event: { kind: "expired" },
+			});
+			return "expired";
+		}
+		return "ok";
+	}
+
+	async issue(params: ElevationIssueParams): Promise<ElevationResult<ElevationIssueValue>> {
+		if (!this.#enabled)
+			return elevationFailure("elevation_unavailable", "Elevation is not enabled (GJC_SDK_ELEVATION_ENABLED)");
+		if (!isElevationOperation(params.operation))
+			return elevationFailure("invalid_input", "operation must be an allowlisted control/query/global operation");
+		if (typeof params.input !== "object" || params.input === null || Array.isArray(params.input))
+			return elevationFailure("invalid_input", "input must be a JSON object");
+		if (!isElevationSessionIdentity(params.sessionIdentity))
+			return elevationFailure("invalid_input", "sessionIdentity is malformed");
+		if (!isBrokerOwnerPrincipal(params.principal))
+			return elevationFailure("invalid_input", "principal must be the broker-owner principal");
+		if (!isElevationRequester(params.requester)) return elevationFailure("invalid_input", "requester is malformed");
+		if (params.elevationRequestId !== undefined && !isElevationRequestId(params.elevationRequestId))
+			return elevationFailure("invalid_input", "elevationRequestId must be a UUID");
+		if (
+			params.expiresInMs !== undefined &&
+			(!Number.isSafeInteger(params.expiresInMs) || params.expiresInMs <= 0 || params.expiresInMs > 15 * 60_000)
+		)
+			return elevationFailure(
+				"invalid_input",
+				"expiresInMs must be a positive safe integer no greater than 15 minutes",
+			);
+		const digestResult = elevationRequestDigest({
+			kind: params.operation.kind,
+			sdkId: params.operation.sdkId,
+			input: params.input,
+		});
+		if (!digestResult.ok)
+			return elevationFailure(digestResult.error.code as ElevationErrorCode, digestResult.error.message);
+		const ttlMs = params.expiresInMs ?? this.#ttlMs;
+		const requestId = params.elevationRequestId ?? randomUUID();
+		return this.#mutate(async () => {
+			const now = this.#now();
+			const existing = this.#byRequestId.get(requestId);
+			if (existing) {
+				const identical =
+					existing.requestDigest === digestResult.digest &&
+					existing.operation.kind === params.operation.kind &&
+					existing.operation.sdkId === params.operation.sdkId &&
+					sameSessionIdentity(existing.sessionIdentity, params.sessionIdentity) &&
+					sameBrokerOwnerPrincipal(existing.principal, params.principal);
+				if (!identical)
+					return elevationFailure(
+						"idempotency_conflict",
+						"elevationRequestId was used with different request content",
+					);
+				return {
+					ok: true,
+					value: {
+						replay: true,
+						elevationRequestId: existing.elevationRequestId,
+						issueIndex: existing.issueIndex,
+						requestDigest: existing.requestDigest,
+						state: existing.state,
+						requestedAt: existing.requestedAt,
+						expiresAt: existing.expiresAt,
+						grant: existing,
+					},
+				};
+			}
+			const grant: ElevationGrantRecord = {
+				version: SDK_STATE_VERSION,
+				elevationRequestId: requestId,
+				issueIndex: this.#nextIssueIndex,
+				state: "requested",
+				operation: params.operation,
+				requestDigest: digestResult.digest,
+				sessionIdentity: params.sessionIdentity,
+				principal: params.principal,
+				requester: params.requester,
+				requestedAt: now,
+				expiresAt: now + ttlMs,
+				ts: now,
+			};
+			this.#nextIssueIndex += 1;
+			await this.#appendGrant(grant);
+			await this.#appendAudit({
+				ts: now,
+				elevationRequestId: grant.elevationRequestId,
+				issueIndex: grant.issueIndex,
+				event: { kind: "issued" },
+			});
+			await this.#writeIndex(this.#nextIssueIndex);
+			return {
+				ok: true,
+				value: {
+					replay: false,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					requestDigest: grant.requestDigest,
+					state: grant.state,
+					requestedAt: grant.requestedAt,
+					expiresAt: grant.expiresAt,
+					grant,
+				},
+			};
+		});
+	}
+
+	async answer(params: ElevationAnswerParams): Promise<ElevationResult<ElevationAnswerValue>> {
+		if (!this.#enabled)
+			return elevationFailure("elevation_unavailable", "Elevation is not enabled (GJC_SDK_ELEVATION_ENABLED)");
+		if (!isElevationRequestId(params.elevationRequestId))
+			return elevationFailure("invalid_input", "elevationRequestId must be a UUID");
+		if (params.answer !== "approve" && params.answer !== "deny")
+			return elevationFailure("invalid_input", "answer must be approve or deny");
+		if (typeof params.presentedDigest !== "string" || !SHA256_HEX.test(params.presentedDigest))
+			return elevationFailure("invalid_input", "presentedDigest must be a SHA-256 hash");
+		if (!isBrokerOwnerPrincipal(params.principal))
+			return elevationFailure("invalid_input", "principal must be the broker-owner principal");
+		if (!isElevationAnswerAuthority(params.answerer))
+			return elevationFailure("invalid_input", "answerer is malformed");
+		if (params.currentSessionIdentity !== undefined && !isElevationSessionIdentity(params.currentSessionIdentity))
+			return elevationFailure("invalid_input", "currentSessionIdentity is malformed");
+		return this.#mutate(async () => {
+			const now = this.#now();
+			const grant = this.#byRequestId.get(params.elevationRequestId);
+			if (!grant) return elevationFailure("not_found", "elevation request was not found");
+			const receipt = this.#byReceiptRequestId.get(params.elevationRequestId);
+			if (receipt !== undefined) {
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: { kind: "duplicate_answer" },
+				});
+				return { ok: true, value: { outcome: "duplicate_answer", grant } };
+			}
+			if ((grant.state === "requested" || grant.state === "granted") && now > grant.expiresAt) {
+				const expired: ElevationGrantRecord = { ...grant, state: "expired", ts: now };
+				await this.#appendGrant(expired);
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: { kind: "answered", outcome: "expired" },
+				});
+				return { ok: true, value: { outcome: "expired", grant: expired } };
+			}
+			if (grant.state !== "requested") {
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: { kind: "duplicate_answer" },
+				});
+				return { ok: true, value: { outcome: "duplicate_answer", grant } };
+			}
+			if (!sameBrokerOwnerPrincipal(params.principal, grant.principal)) {
+				const misused: ElevationGrantRecord = { ...grant, state: "misused", ts: now };
+				await this.#appendGrant(misused);
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: { kind: "answered", outcome: "misused" },
+				});
+				return { ok: true, value: { outcome: "misused", grant: misused } };
+			}
+			if (params.presentedDigest !== grant.requestDigest) {
+				const misused: ElevationGrantRecord = { ...grant, state: "misused", ts: now };
+				await this.#appendGrant(misused);
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: { kind: "answered", outcome: "misused" },
+				});
+				return { ok: true, value: { outcome: "misused", grant: misused } };
+			}
+			if (params.currentSessionIdentity === undefined) {
+				const unavailable: ElevationGrantRecord = { ...grant, state: "target_unavailable", ts: now };
+				await this.#appendGrant(unavailable);
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: { kind: "answered", outcome: "target_unavailable" },
+				});
+				return { ok: true, value: { outcome: "target_unavailable", grant: unavailable } };
+			}
+			if (!sameSessionIdentity(params.currentSessionIdentity, grant.sessionIdentity)) {
+				const misused: ElevationGrantRecord = { ...grant, state: "misused", ts: now };
+				await this.#appendGrant(misused);
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: { kind: "answered", outcome: "misused" },
+				});
+				return { ok: true, value: { outcome: "misused", grant: misused } };
+			}
+			if (params.answer === "deny") {
+				const denied: ElevationGrantRecord = { ...grant, state: "denied", ts: now };
+				await this.#appendGrant(denied);
+				await this.#appendAudit({
+					ts: now,
+					elevationRequestId: grant.elevationRequestId,
+					issueIndex: grant.issueIndex,
+					event: { kind: "answered", outcome: "denied" },
+				});
+				return { ok: true, value: { outcome: "denied", grant: denied } };
+			}
+			const granted: ElevationGrantRecord = { ...grant, state: "granted", ts: now };
+			await this.#appendGrant(granted);
+			await this.#appendAudit({
+				ts: now,
+				elevationRequestId: grant.elevationRequestId,
+				issueIndex: grant.issueIndex,
+				event: { kind: "answered", outcome: "granted" },
+			});
+			return { ok: true, value: { outcome: "granted", grant: granted } };
+		});
+	}
+
+	async claim(params: ElevationClaimParams): Promise<ElevationResult<ElevationClaimValue>> {
+		if (!isElevationRequestId(params.elevationRequestId))
+			return elevationFailure("invalid_input", "elevationRequestId must be a UUID");
+		if (!isElevationClaimIdentity(params.claimIdentity))
+			return elevationFailure("invalid_input", "claimIdentity is malformed");
+		if (params.currentSessionIdentity !== undefined && !isElevationSessionIdentity(params.currentSessionIdentity))
+			return elevationFailure("invalid_input", "currentSessionIdentity is malformed");
+		return this.#mutate(async () => {
+			const now = this.#now();
+			const grant = this.#byRequestId.get(params.elevationRequestId);
+			if (!grant) return elevationFailure("not_found", "elevation request was not found");
+			const receipt = this.#byReceiptRequestId.get(params.elevationRequestId);
+			const reconciled = await this.#reconcile(grant, receipt, params.claimIdentity, now);
+			if (reconciled === "in_progress")
+				return elevationFailure("elevation_claim_in_progress", "elevation claim is already in progress");
+			if (reconciled === "uncertain")
+				return elevationFailure(
+					"terminal_uncertain",
+					"elevation grant was consumed with an unknown dispatch outcome; retry requires a new grant",
+				);
+			if (reconciled === "expired") return elevationFailure("expired", "elevation grant has expired");
+			const current = this.#byRequestId.get(params.elevationRequestId) ?? grant;
+			if (current.state === "requested")
+				return elevationFailure("elevation_required", "elevation request has not been granted");
+			if (current.state === "claimed")
+				return elevationFailure("elevation_claim_in_progress", "elevation claim is already in progress");
+			if (current.state !== "granted")
+				return elevationFailure("grant_spent", "elevation grant is already spent or terminal");
+			if (params.currentSessionIdentity === undefined)
+				return elevationFailure("target_unavailable", "session endpoint is unreachable at claim time");
+			if (!sameSessionIdentity(params.currentSessionIdentity, current.sessionIdentity))
+				return elevationFailure(
+					"endpoint_stale",
+					"session endpoint identity no longer matches the elevation grant",
+				);
+			const claimed: ElevationGrantRecord = { ...current, state: "claimed", ts: now };
+			// Receipt before grant: if a crash lands between the two appends
+			// the receipt is authoritative, and the next access truthfully
+			// terminalizes the claim.
+			const receiptRecord = claimReceipt(current.elevationRequestId, current.issueIndex, params.claimIdentity, now);
+			await this.#appendReceipt(receiptRecord);
+			await this.#appendGrant(claimed);
+			await this.#appendAudit({
+				ts: now,
+				elevationRequestId: current.elevationRequestId,
+				issueIndex: current.issueIndex,
+				event: {
+					kind: "claimed",
+					claim: {
+						ownerId: params.claimIdentity.ownerId,
+						epoch: params.claimIdentity.epoch,
+						pid: params.claimIdentity.pid,
+						incarnation: params.claimIdentity.incarnation,
+					},
+				},
+			});
+			return { ok: true, value: { grant: claimed, receipt: receiptRecord } };
+		});
+	}
+
+	async dispatch(params: ElevationDispatchParams): Promise<ElevationResult<ElevationDispatchValue>> {
+		if (!isElevationRequestId(params.elevationRequestId))
+			return elevationFailure("invalid_input", "elevationRequestId must be a UUID");
+		if (!isElevationClaimIdentity(params.dispatchIdentity))
+			return elevationFailure("invalid_input", "dispatchIdentity is malformed");
+		if (!isElevationDispatchOutcome(params.outcome)) return elevationFailure("invalid_input", "outcome is malformed");
+		if (params.outcome.status === "unknown")
+			return elevationFailure("invalid_input", "dispatch outcome unknown is reserved for crash replay");
+		return this.#mutate(async () => {
+			const now = this.#now();
+			const grant = this.#byRequestId.get(params.elevationRequestId);
+			if (!grant) return elevationFailure("not_found", "elevation request was not found");
+			const receipt = this.#byReceiptRequestId.get(params.elevationRequestId);
+			if (!receipt)
+				return elevationFailure("elevation_claim_in_progress", "elevation grant was not claimed before dispatch");
+			if (receipt.state === "claimed" && !receiptClaimMatches(receipt, params.dispatchIdentity)) {
+				const liveness = this.#classifyLiveness(receipt.claim.pid, receipt.claim.incarnation);
+				if (liveness === "dead") {
+					if (grant.state !== "consumed")
+						await this.#appendGrant({
+							...grant,
+							state: "consumed",
+							outcome: {
+								status: "unknown",
+								message: "Claiming broker tenure ended before dispatch outcome was recorded",
+								dispatchedAt: now,
+							},
+							ts: now,
+						});
+					await this.#appendReceipt(uncertainReceipt(receipt, now));
+					await this.#appendAudit({
+						ts: now,
+						elevationRequestId: grant.elevationRequestId,
+						issueIndex: grant.issueIndex,
+						event: {
+							kind: "consumed",
+							message: "Claiming broker tenure ended before dispatch outcome was recorded",
+						},
+					});
+					return elevationFailure(
+						"terminal_uncertain",
+						"elevation grant dispatch outcome is unknown; retry requires a new grant",
+					);
+				}
+				return elevationFailure(
+					"elevation_claim_in_progress",
+					"elevation grant is claimed by another broker tenure",
+				);
+			}
+			if (receipt.state === "dispatched") {
+				if (
+					receipt.dispatch === undefined ||
+					receipt.dispatch.ownerId !== params.dispatchIdentity.ownerId ||
+					receipt.dispatch.epoch !== params.dispatchIdentity.epoch
+				)
+					return elevationFailure("grant_spent", "elevation grant was dispatched by another broker tenure");
+				return { ok: true, value: { grant, receipt } };
+			}
+			if (receipt.state === "uncertain")
+				return elevationFailure(
+					"terminal_uncertain",
+					"elevation grant dispatch outcome is unknown; retry requires a new grant",
+				);
+			if (grant.state !== "claimed")
+				return elevationFailure("grant_spent", "elevation grant is not in the claimed state");
+			const dispatchedGrant: ElevationGrantRecord = {
+				...grant,
+				state: "dispatched",
+				outcome: params.outcome,
+				ts: now,
+			};
+			const dispatchedReceipt = dispatchReceipt(
+				receipt,
+				{
+					ownerId: params.dispatchIdentity.ownerId,
+					epoch: params.dispatchIdentity.epoch,
+					dispatchedAt: now,
+				},
+				params.outcome,
+			);
+			await this.#appendReceipt(dispatchedReceipt);
+			await this.#appendGrant(dispatchedGrant);
+			await this.#appendAudit({
+				ts: now,
+				elevationRequestId: grant.elevationRequestId,
+				issueIndex: grant.issueIndex,
+				event: {
+					kind: "dispatched",
+					dispatch: {
+						ownerId: params.dispatchIdentity.ownerId,
+						epoch: params.dispatchIdentity.epoch,
+						dispatchedAt: now,
+					},
+					outcome:
+						params.outcome.status === "ok"
+							? { status: "ok", dispatchedAt: params.outcome.dispatchedAt }
+							: {
+									status: "failed",
+									code: params.outcome.status === "failed" ? params.outcome.code : "dispatch_failed",
+									message: params.outcome.message,
+									dispatchedAt: params.outcome.dispatchedAt,
+								},
+				},
+			});
+			return { ok: true, value: { grant: dispatchedGrant, receipt: dispatchedReceipt } };
+		});
+	}
+
+	/** Pure read without reconciliation writes; used before actions. */
+	async get(elevationRequestId: string): Promise<ElevationResult<ElevationReadValue>> {
+		if (!isElevationRequestId(elevationRequestId))
+			return elevationFailure("invalid_input", "elevationRequestId must be a UUID");
+		return this.#mutate(async () => {
+			const grant = this.#byRequestId.get(elevationRequestId);
+			if (!grant) return elevationFailure("not_found", "elevation request was not found");
+			return { ok: true, value: { grant, receipt: this.#byReceiptRequestId.get(elevationRequestId) } };
+		});
+	}
+
+	/** Truthful read: reconciles expiry and crash-state claims before returning. */
+	async resolve(
+		elevationRequestId: string,
+		claimIdentity: ElevationClaimIdentity,
+	): Promise<ElevationResult<ElevationReadValue>> {
+		if (!isElevationRequestId(elevationRequestId))
+			return elevationFailure("invalid_input", "elevationRequestId must be a UUID");
+		if (!isElevationClaimIdentity(claimIdentity))
+			return elevationFailure("invalid_input", "claimIdentity is malformed");
+		return this.#mutate(async () => {
+			const grant = this.#byRequestId.get(elevationRequestId);
+			if (!grant) return elevationFailure("not_found", "elevation request was not found");
+			const receipt = this.#byReceiptRequestId.get(elevationRequestId);
+			await this.#reconcile(grant, receipt, claimIdentity, this.#now());
+			const current = this.#byRequestId.get(elevationRequestId) ?? grant;
+			return { ok: true, value: { grant: current, receipt: this.#byReceiptRequestId.get(elevationRequestId) } };
+		});
+	}
+
+	/** Truthful listing: reconciles every grant before returning. */
+	async list(claimIdentity: ElevationClaimIdentity): Promise<ElevationResult<ElevationListValue>> {
+		if (!isElevationClaimIdentity(claimIdentity))
+			return elevationFailure("invalid_input", "claimIdentity is malformed");
+		return this.#mutate(async () => {
+			const now = this.#now();
+			const items: ElevationReadValue[] = [];
+			for (const grant of this.#byRequestId.values()) {
+				const receipt = this.#byReceiptRequestId.get(grant.elevationRequestId);
+				await this.#reconcile(grant, receipt, claimIdentity, now);
+				const current = this.#byRequestId.get(grant.elevationRequestId) ?? grant;
+				items.push({ grant: current, receipt: this.#byReceiptRequestId.get(grant.elevationRequestId) });
+			}
+			return { ok: true, value: { grants: items } };
+		});
+	}
+}
+
+export { isElevationGrantRecord, isElevationOperation };