gentle-pi 2.3.0 → 2.5.0

package/lib/native-pointer-region.ts

@@ -0,0 +1,164 @@
+import {
+	MouseRegion,
+	type Component,
+	type TuiMouseEvent,
+	type TuiMouseEventResult,
+} from "@earendil-works/pi-tui";
+
+export type NativePointerCallback = (event: TuiMouseEvent) => TuiMouseEventResult | undefined;
+
+export interface NativePointerRegionCallbacks {
+	onHover?: NativePointerCallback;
+	onLeave?: (event?: TuiMouseEvent) => void;
+	onPress?: NativePointerCallback;
+	onClick?: NativePointerCallback;
+	onWheel?: NativePointerCallback;
+}
+
+export interface NativePointerMouseObserver {
+	beforeMouse(event: TuiMouseEvent): void;
+	afterMouse(event: TuiMouseEvent): void;
+}
+
+/**
+ * A composable adapter around the public MouseRegion component.
+ * Child dispatch stays first, so an already handled child result is unchanged.
+ */
+export class NativePointerRegion implements Component {
+	private readonly adapter: MouseRegion;
+	private readonly callbacks: NativePointerRegionCallbacks;
+	private readonly scope: NativePointerScope | undefined;
+	private hovered = false;
+	private disabled = false;
+	private disposed = false;
+	private renderedWidth: number | undefined;
+
+	constructor(child: Component, callbacks: NativePointerRegionCallbacks, scope?: NativePointerScope) {
+		this.callbacks = callbacks;
+		this.scope = scope;
+		this.adapter = new MouseRegion(child, (event) => this.handlePointer(event));
+		this.scope?.register(this);
+	}
+
+	render(width: number): string[] {
+		if (this.renderedWidth !== undefined && this.renderedWidth !== width) this.clearHover();
+		this.renderedWidth = width;
+		return this.adapter.render(width);
+	}
+
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (this.disposed) return undefined;
+		return this.adapter.handleMouse(event);
+	}
+
+	invalidate(): void {
+		this.renderedWidth = undefined;
+		this.clearHover();
+		this.adapter.invalidate();
+	}
+
+	setDisabled(disabled: boolean): void {
+		if (this.disabled === disabled) return;
+		this.disabled = disabled;
+		if (disabled) this.clearHover();
+	}
+
+	clearHover(event?: TuiMouseEvent): boolean {
+		if (!this.hovered) return false;
+		this.hovered = false;
+		this.callbacks.onLeave?.(event);
+		return true;
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.clearHover();
+		this.scope?.unregister(this);
+	}
+
+	private handlePointer(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (this.disabled || this.disposed) return undefined;
+		if (event.type === "move" && event.button === "none") {
+			this.scope?.markMove(this, event);
+			this.hovered = true;
+			return this.callbacks.onHover?.(event);
+		}
+		if (event.type === "press") return this.callbacks.onPress?.(event);
+		if (event.type === "click") return this.callbacks.onClick?.(event);
+		if (event.type === "wheel") return this.callbacks.onWheel?.(event);
+		return undefined;
+	}
+}
+
+/** Coordinates pointer regions with a root-compatible native mouse observer. */
+export class NativePointerScope {
+	private readonly regions = new Set<NativePointerRegion>();
+	private moved = false;
+	private disabled = false;
+	private disposed = false;
+
+	wrap(child: Component, callbacks: NativePointerRegionCallbacks): NativePointerRegion {
+		const region = new NativePointerRegion(child, callbacks, this);
+		region.setDisabled(this.disabled);
+		if (this.disposed) region.dispose();
+		return region;
+	}
+
+	createMouseObserver(requestRender?: () => void): NativePointerMouseObserver {
+		return {
+			beforeMouse: (event) => {
+				if (!this.disposed && event.type === "move" && event.button === "none") this.moved = false;
+			},
+			afterMouse: (event) => {
+				if (!this.isInRoot(event) || this.moved) return;
+				if (this.clearHover(event)) requestRender?.();
+			},
+		};
+	}
+
+	setDisabled(disabled: boolean): void {
+		this.disabled = disabled;
+		for (const region of this.regions) region.setDisabled(disabled);
+	}
+
+	invalidate(): void {
+		this.clearHover();
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		for (const region of [...this.regions]) region.dispose();
+	}
+
+	register(region: NativePointerRegion): void {
+		if (!this.disposed) this.regions.add(region);
+	}
+
+	unregister(region: NativePointerRegion): void {
+		this.regions.delete(region);
+	}
+
+	markMove(region: NativePointerRegion, event: TuiMouseEvent): void {
+		this.moved = true;
+		for (const candidate of this.regions) {
+			if (candidate !== region) candidate.clearHover(event);
+		}
+	}
+
+	private clearHover(event?: TuiMouseEvent): boolean {
+		let changed = false;
+		for (const region of this.regions) changed = region.clearHover(event) || changed;
+		return changed;
+	}
+
+	private isInRoot(event: TuiMouseEvent): boolean {
+		return !this.disposed && event.type === "move" && event.button === "none" &&
+			event.x >= 0 && event.x < event.width && event.y >= 0 && event.y < event.height;
+	}
+}
+
+export function createNativePointerScope(): NativePointerScope {
+	return new NativePointerScope();
+}

package/lib/native-review-cli.ts

@@ -5,6 +5,7 @@ import { dirname, isAbsolute, join, posix, win32 } from "node:path";
 import { promisify } from "node:util";
 import { PackageLocalGentleAiBinaryMissingError, resolveGentleAiBinary } from "./gentle-ai-binary.ts";
 import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "./review-relay-contract.ts";
+import { decodeReviewAssessmentV1, type ReviewAssessmentV1 } from "./review-risk-assessment.ts";
 import {
 	REVIEW_INTEGRATION_CONTRACT,
 	decodeReviewAcknowledgedV1,
@@ -59,6 +60,7 @@ export const NATIVE_REVIEW_OPERATION = {
 	RECONCILE_AUTHORITY: "review/reconcile-authority",
 	REPAIR_LEGACY_ALIAS: "review/repair-legacy-alias",
 	MODE: "review/mode",
+	ASSESS: "review/assess",
 	REPAIR: "review/repair",
 	CAPTURE_RESULT: "review/capture-result",
 	CAPTURE_CORRECTION_PLAN: "review/capture-correction-plan",
@@ -109,6 +111,11 @@ export interface NativeReviewCli {
 	// outside the negotiated review-integration protocol — same shape as
 	// reviewStatus/reclaim above.
 	reviewMode?(request: NativeReviewModeRequest): Promise<NativeReviewModeResult>;
+	// Read-only risk assessment (gentle-ai#4295, landing in parallel with
+	// gentle-pi#662). Same plain-versioned shape as reviewMode/reviewStatus:
+	// an older binary without the verb, or any other process/decode failure,
+	// rejects the returned promise -- callers fail closed to `high` risk.
+	assess?(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1>;
 }
 
 export const NATIVE_REVIEW_MODE_OPERATION = {
@@ -151,6 +158,17 @@ export interface NativeReviewModeRequest {
 	signal?: AbortSignal;
 }
 
+// Read-only risk assessment request (gentle-pi#662). `baseRef` requires
+// explicit `committedOnly` acknowledgement, exactly like Native START's
+// baseRef/committedOnly pairing, because both select a committed range
+// instead of the ambient working tree.
+export interface NativeReviewAssessRequest {
+	cwd: string;
+	baseRef?: string;
+	committedOnly?: boolean;
+	signal?: AbortSignal;
+}
+
 export interface NativeReviewModeStatus {
 	global: NativeReviewModeValue;
 	cloneLocal: NativeReviewModeValue;
@@ -261,7 +279,6 @@ export interface NativeReviewAbandonRequest {
 	snapshotIdentity: string;
 	capturedLensResults: readonly string[];
 	findingsPresent: boolean;
-	evidenceRecordsPresent: boolean;
 	actor: string;
 	reason: string;
 	maintainerAuthorization: string;
@@ -498,8 +515,13 @@ export const NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION = {
 } as const;
 export type NativeReviewAuthorityEntryVersion = (typeof NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION)[keyof typeof NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION];
 
-export const NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS = NATIVE_REVIEW_AUTHORITY_STATUS;
-export type NativeReviewAuthorityEntryStatus = NativeReviewAuthorityStatus;
+export const NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS = {
+	...NATIVE_REVIEW_AUTHORITY_STATUS,
+	INCOMPLETE_STORE_ENTRY: "incomplete-store-entry",
+	HISTORICAL_PRE_RECEIPT: "historical-pre-receipt",
+	INVALIDATED: "invalidated",
+} as const;
+export type NativeReviewAuthorityEntryStatus = (typeof NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS)[keyof typeof NATIVE_REVIEW_AUTHORITY_ENTRY_STATUS];
 
 export const NATIVE_REVIEW_LOCK_STATUS = {
 	OWNED: "owned",
@@ -541,6 +563,10 @@ export interface NativeReviewRecovery {
 	recoveredAt: string;
 	maintainerAuthorization?: string;
 }
+export interface NativeReviewDiscardedWorkSummary {
+	capturedLensResults: readonly string[];
+	findingsPresent: boolean;
+}
 export interface NativeReviewAuthorityEntry {
 	version: NativeReviewAuthorityEntryVersion;
 	lineageId?: string;
@@ -551,6 +577,7 @@ export interface NativeReviewAuthorityEntry {
 	snapshotIdentity?: string;
 	chainIdentity?: string;
 	recovery?: NativeReviewRecovery;
+	discardedWork?: NativeReviewDiscardedWorkSummary;
 	problems: readonly string[];
 }
 export interface NativeReviewAuthorityLock {
@@ -789,6 +816,33 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// the columns match the 2.5.0-rc.3 row. riskEvidence and hint stay dark:
 	// still not proven to reach the negotiated START path Pi reads.
 	"2.5.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// Ground-truthed against the published v2.6.0 binary installed from its
+	// signed archive: `review capabilities` on the v2 lane advertises
+	// capabilities/v2.5 (protocol minor 5) and answers status/v7, consent/v3,
+	// and the `start/v4` continuation, all of which the decoders already read.
+	// `review mode status --json` still answers `gentle-ai.rdd-mode-status/v1`
+	// and `review validate --gate pre-commit` still answers
+	// `gentle-ai.review-gate-result/v1` carrying `delivery`, both verified
+	// against the binary. Declining the consent/v3 prompt during `review start`
+	// still returns `risk_evidence` only on that blocking envelope, never on
+	// the negotiated `start/v4` continuation, so riskEvidence and hint stay
+	// dark for the same reason they have on every row since 2.2.0: still not
+	// proven to reach the negotiated START path Pi reads. The closed fields Pi
+	// consumes did not change between 2.5.0 and 2.6.0, so the columns match
+	// the 2.5.0 row.
+	"2.6.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// Ground-truthed against the published v2.7.0 binary installed from its
+	// signed archive: `review capabilities` on the v2 lane still advertises
+	// capabilities/v2.5 (protocol minor 5) and answers status/v7, consent/v3,
+	// and the `start/v4` continuation, all of which the decoders already read.
+	// `review mode status --json` still answers `gentle-ai.rdd-mode-status/v1`
+	// and `review validate --gate pre-commit` still answers
+	// `gentle-ai.review-gate-result/v1` carrying `delivery`, both verified
+	// against the binary. riskEvidence and hint stay dark for the same reason
+	// they have on every row since 2.2.0: still not proven to reach the
+	// negotiated START path Pi reads. The closed fields Pi consumes did not
+	// change between 2.6.0 and 2.7.0, so the columns match the 2.6.0 row.
+	"2.7.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {
@@ -1031,8 +1085,15 @@ function decodeNativeReviewRecovery(value: unknown): NativeReviewRecovery {
 		...(recovery.maintainer_authorization === undefined ? {} : { maintainerAuthorization: requiredString(recovery.maintainer_authorization) }),
 	};
 }
+function decodeNativeReviewDiscardedWorkSummary(value: unknown): NativeReviewDiscardedWorkSummary {
+	const discardedWork = exactObject(value, ["captured_lens_results", "findings_present"]);
+	return {
+		capturedLensResults: stringArray(discardedWork.captured_lens_results),
+		findingsPresent: booleanValue(discardedWork.findings_present),
+	};
+}
 function decodeNativeReviewStatusEntry(value: unknown): NativeReviewAuthorityEntry {
-	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery"]);
+	const entry = exactObject(value, ["version", "path", "status", "problems"], ["lineage_id", "state", "revision", "snapshot_identity", "chain_identity", "recovery", "discarded_work"]);
 	return {
 		version: enumString(entry.version, Object.values(NATIVE_REVIEW_AUTHORITY_ENTRY_VERSION)) as NativeReviewAuthorityEntryVersion,
 		...(entry.lineage_id === undefined ? {} : { lineageId: requiredString(entry.lineage_id) }),
@@ -1043,6 +1104,7 @@ function decodeNativeReviewStatusEntry(value: unknown): NativeReviewAuthorityEnt
 		...(entry.snapshot_identity === undefined ? {} : { snapshotIdentity: sha256Identity(entry.snapshot_identity) }),
 		...(entry.chain_identity === undefined ? {} : { chainIdentity: requiredString(entry.chain_identity) }),
 		...(entry.recovery === undefined ? {} : { recovery: decodeNativeReviewRecovery(entry.recovery) }),
+		...(entry.discarded_work === undefined ? {} : { discardedWork: decodeNativeReviewDiscardedWorkSummary(entry.discarded_work) }),
 		problems: stringArray(entry.problems),
 	};
 }
@@ -1357,9 +1419,7 @@ class NativeReviewPlainCli {
 			if (!isCanonicalProcessString(value)) throw new TypeError(`Native ABANDON ${name} must be a non-empty, trimmed, NUL-free string`);
 		}
 		if (!Array.isArray(request.capturedLensResults) || request.capturedLensResults.some((entry) => !isCanonicalProcessString(entry))) throw new TypeError("Native ABANDON capturedLensResults must be an array of non-empty, trimmed, NUL-free strings");
-		for (const [name, value] of [["findingsPresent", request.findingsPresent], ["evidenceRecordsPresent", request.evidenceRecordsPresent]] as const) {
-			if (typeof value !== "boolean") throw new TypeError(`Native ABANDON ${name} must be a boolean`);
-		}
+		if (typeof request.findingsPresent !== "boolean") throw new TypeError("Native ABANDON findingsPresent must be a boolean");
 		if (request.maintainerAuthorization !== nativeReviewAbandonAuthorization(request)) throw new TypeError("Native ABANDON maintainerAuthorization must match the exact lineage, revision, snapshot, reason, discarded-work, and actor binding");
 		const execution = await this.execute(NATIVE_REVIEW_OPERATION.ABANDON, request.cwd, [
 			"review", "abandon", "--cwd", request.cwd,
@@ -1448,7 +1508,11 @@ class NativeReviewPlainCli {
 	}
 }
 
-export function nativeReviewAbandonAuthorization(request: Pick<NativeReviewAbandonRequest, "lineage" | "expectedRevision" | "snapshotIdentity" | "capturedLensResults" | "findingsPresent" | "evidenceRecordsPresent" | "actor" | "reason">): string {
+export function nativeReviewAbandonAuthorization(request: Pick<NativeReviewAbandonRequest, "lineage" | "expectedRevision" | "snapshotIdentity" | "capturedLensResults" | "findingsPresent" | "actor" | "reason">): string {
+	// gentle-ai 0ed9225f removed evidence records from the discarded-work summary,
+	// so the native v2 gate verifies an exact eight-line binding (schema, lineage,
+	// revision, snapshot_identity, reason, captured_lens_results, findings_present,
+	// actor) — there is no evidence_records_present line to derive or relay.
 	return [
 		"gentle-ai.review-abandon-authorization/v2",
 		`lineage=${request.lineage}`,
@@ -1457,7 +1521,6 @@ export function nativeReviewAbandonAuthorization(request: Pick<NativeReviewAband
 		`reason=${request.reason}`,
 		`captured_lens_results=${request.capturedLensResults.join(",")}`,
 		`findings_present=${request.findingsPresent}`,
-		`evidence_records_present=${request.evidenceRecordsPresent}`,
 		`actor=${request.actor.trim()}`,
 	].join("\n");
 }
@@ -1580,14 +1643,20 @@ function splitNativeConsentInvocation(invocation: string): readonly string[] {
 	let quote: "'" | '"' | undefined;
 	let escaping = false;
 	let started = false;
-	for (const character of invocation.trim()) {
+	const source = invocation.trim();
+	for (let index = 0; index < source.length; index += 1) {
+		const character = source[index]!;
 		if (escaping) {
 			current += character;
 			escaping = false;
 			started = true;
 			continue;
 		}
-		if (character === "\\" && quote !== "'") {
+		// Provider invocations are not shell commands. Keep every path backslash
+		// verbatim, including quoted UNC and drive-root paths. Outside quotes,
+		// only a backslash before whitespace joins a space-containing token.
+		const next = source[index + 1];
+		if (character === "\\" && quote === undefined && next !== undefined && /\s/.test(next)) {
 			escaping = true;
 			started = true;
 			continue;
@@ -1678,7 +1747,9 @@ function consentInvocationArguments(request: NativeReviewConsentAnswerRequest):
 	if (words[0] !== "gentle-ai" || words[1] !== "review" || words[2] !== "start") throw new NativeReviewConsentBindingError("consent-invocation-not-start", "Native consent invocation is not a provider review START");
 	const arguments_ = words.slice(1);
 	if (exactConsentOption(arguments_, "--contract") !== REVIEW_INTEGRATION_CONTRACT) throw new NativeReviewConsentBindingError("consent-invocation-contract-changed", "Native consent invocation contract changed");
-	if (exactConsentOption(arguments_, "--cwd") !== request.cwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
+	const providerCwd = exactConsentOption(arguments_, "--cwd");
+	const requestedCwd = normalizeNativeReviewCwd(request.cwd);
+	if (normalizeNativeReviewCwd(providerCwd) !== requestedCwd) throw new NativeReviewConsentBindingError("consent-invocation-cwd-changed", "Native consent invocation repository binding changed");
 	if (exactConsentOption(arguments_, "--target") !== request.consent.targetIdentity) throw new NativeReviewConsentBindingError("consent-invocation-target-changed", "Native consent invocation target binding changed");
 	if (exactConsentOption(arguments_, "--projection") !== request.consent.projection) throw new NativeReviewConsentBindingError("consent-invocation-projection-changed", "Native consent invocation projection binding changed");
 	const lineageId = optionalConsentLineageOption(arguments_);
@@ -2178,6 +2249,26 @@ export class NativeReviewCliV216 implements NativeReviewCli {
 		return decode(NATIVE_REVIEW_OPERATION.MODE, mutating, () => decodeNativeReviewMode(execution.body, request.operation));
 	}
 
+	// Read-only risk assessment (gentle-ai#4295, gentle-pi#662). Never mutates;
+	// an older binary without the verb, or any other process/decode failure,
+	// rejects -- callers (the `gentle_review` tool's `assess` operation) fail
+	// closed to `high`.
+	async assess(request: NativeReviewAssessRequest): Promise<ReviewAssessmentV1> {
+		if (request.baseRef !== undefined && !isCanonicalProcessString(request.baseRef)) throw new TypeError("Native ASSESS baseRef must be a non-empty, trimmed, NUL-free string");
+		if (request.baseRef !== undefined && request.committedOnly !== true) throw new TypeError("Native ASSESS baseRef requires explicit committedOnly acknowledgement");
+		if (request.baseRef === undefined && request.committedOnly !== undefined) throw new TypeError("Native ASSESS committedOnly requires an explicit baseRef");
+		const cwd = await canonicalNativeReviewCwd(request.cwd);
+		const execution = await this.invoke(
+			NATIVE_REVIEW_OPERATION.ASSESS,
+			cwd,
+			["review", "assess", "--cwd", cwd, ...(request.baseRef === undefined ? [] : ["--base-ref", request.baseRef, "--committed-only"]), "--json"],
+			false,
+			request.signal,
+			this.executablePath(NATIVE_REVIEW_OPERATION.ASSESS, false),
+		);
+		return decode(NATIVE_REVIEW_OPERATION.ASSESS, false, () => decodeReviewAssessmentV1(execution.body));
+	}
+
 	// Recovery commands are version-gated plain CLI operations outside the
 	// negotiated integration-v1 contract, exactly like reviewStatus.
 	reclaim(request: NativeReviewReclaimRequest): Promise<NativeReviewRecoveryResult> {

package/lib/provider-contract-bundle.ts

@@ -31,6 +31,8 @@ export const PI_RUNTIME_IDENTITY = "pi";
 export const SUPPORTED_PROVIDER_CONTRACT_MAJOR = 1;
 // `runtimes` became part of the manifest in contract 1.1.0.
 export const RUNTIMES_REQUIRED_SINCE_MINOR = 1;
+// `orchestration` became part of the manifest in contract 1.2.0.
+export const ORCHESTRATION_REQUIRED_SINCE_MINOR = 2;
 // Exactly the provider roles gentle-pi supports, in the manifest's strict order.
 export const PROVIDER_CONTRACT_ROLE_IDS = ["lens", "refuter", "targeted-validator"] as const;
 // Every mandatory capability a role may declare. An unknown mandatory
@@ -42,6 +44,13 @@ const MAX_FILE_BYTES = 4 * 1024 * 1024;
 const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
 const MAX_MANIFEST_BYTES = 64 * 1024;
 const BUNDLE_ENTRY_COUNT = 8;
+// Generous fixed safety bound on raw archive/tree entries read BEFORE the
+// manifest itself is parsed (the exact expected count, base entries plus one
+// per `orchestration` runtime, is known only after manifest decode). Real
+// contracts register a handful of runtimes; this bound only rules out an
+// absurd smuggled inventory, it is not the exact-count check.
+const MAX_ORCHESTRATION_ENTRIES = 64;
+const MAX_RAW_BUNDLE_ENTRIES = BUNDLE_ENTRY_COUNT + MAX_ORCHESTRATION_ENTRIES;
 // setuid/setgid/sticky, any execute bit, or world-writable content is never
 // acceptable for a data-only contract bundle.
 const FORBIDDEN_MODE_BITS = 0o7113;
@@ -84,7 +93,13 @@ export interface VerifiedProviderContractBundle {
 	/** Present exactly when the manifest declares the runtime registry (>= 1.1.0). */
 	readonly runtimes: readonly string[] | undefined;
 	readonly roles: readonly VerifiedProviderRole[];
-	/** Canonical path -> exact verified bytes for all eight entries. */
+	/**
+	 * Verified runtime-bound review execution contract text, runtime identity
+	 * -> UTF-8 `orchestration/<runtime>.md` contents. Empty before contract
+	 * 1.2.0, where `orchestration` does not exist in the manifest.
+	 */
+	readonly orchestration: ReadonlyMap<string, string>;
+	/** Canonical path -> exact verified bytes for all entries (base eight plus one per orchestration runtime). */
 	readonly entries: ReadonlyMap<string, Buffer>;
 	/** Canonical path -> SHA-256 of the exact verified bytes. */
 	readonly entrySha256: ReadonlyMap<string, string>;
@@ -306,6 +321,23 @@ function parseManifestRole(value: unknown, index: number): ManifestRole {
 	};
 }
 
+interface ManifestOrchestrationEntry {
+	readonly runtime: string;
+	readonly file: ManifestFileReference;
+}
+
+function parseOrchestrationEntry(value: unknown, index: number): ManifestOrchestrationEntry {
+	const where = `manifest.orchestration[${index}]`;
+	const object = requireObject(value, where);
+	requireExactKeys(object, ["runtime", "file"], ["runtime", "file"], where);
+	const runtime = requireString(object.runtime, `${where}.runtime`);
+	if (!RUNTIME_IDENTITY_PATTERN.test(runtime)) invalid(`${where}.runtime ${JSON.stringify(runtime)} is not a runtime identity`);
+	const file = parseFileReference(object.file, `${where}.file`);
+	const expectedPath = `orchestration/${runtime}.md`;
+	if (file.path !== expectedPath) invalid(`${where}.file.path must be ${JSON.stringify(expectedPath)}`);
+	return { runtime, file };
+}
+
 interface ParsedManifest {
 	readonly contractSemver: string;
 	readonly major: number;
@@ -315,13 +347,14 @@ interface ParsedManifest {
 	readonly runtimes: readonly string[] | undefined;
 	readonly readme: ManifestFileReference;
 	readonly roles: readonly ManifestRole[];
+	readonly orchestration: readonly ManifestOrchestrationEntry[];
 }
 
 function parseManifest(payload: Buffer): ParsedManifest {
 	const object = decodeStrictManifestObject(payload);
 	requireExactKeys(
 		object,
-		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles"],
+		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles", "orchestration"],
 		["schema", "contract_semver", "transport_capability", "readme", "roles"],
 		"manifest",
 	);
@@ -365,6 +398,33 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		invalid(`manifest.runtimes does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
 	}
 
+	const orchestrationRequired = minor >= ORCHESTRATION_REQUIRED_SINCE_MINOR;
+	let orchestration: readonly ManifestOrchestrationEntry[] = [];
+	if (Object.prototype.hasOwnProperty.call(object, "orchestration")) {
+		if (!orchestrationRequired) {
+			invalid(`manifest.orchestration is not part of contract ${contractSemver}; it exists from 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0`);
+		}
+		if (!Array.isArray(object.orchestration) || object.orchestration.length === 0) {
+			invalid("manifest.orchestration must be a non-empty array");
+		}
+		const parsedOrchestration = object.orchestration.map((entry, index) => parseOrchestrationEntry(entry, index));
+		for (let position = 0; position < parsedOrchestration.length; position += 1) {
+			const entry = parsedOrchestration[position] as ManifestOrchestrationEntry;
+			if (position > 0 && (parsedOrchestration[position - 1] as ManifestOrchestrationEntry).runtime >= entry.runtime) {
+				invalid("manifest.orchestration must be strictly sorted by runtime and unique");
+			}
+			if (runtimes === undefined || !runtimes.includes(entry.runtime)) {
+				invalid(`manifest.orchestration[${position}].runtime ${JSON.stringify(entry.runtime)} is not registered in manifest.runtimes`);
+			}
+		}
+		if (!parsedOrchestration.some((entry) => entry.runtime === PI_RUNTIME_IDENTITY)) {
+			invalid(`manifest.orchestration does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
+		}
+		orchestration = parsedOrchestration;
+	} else if (orchestrationRequired) {
+		invalid(`manifest.orchestration is required from contract 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0 (got ${contractSemver} without it)`);
+	}
+
 	if (!Array.isArray(object.roles)) invalid("manifest.roles must be an array");
 	const roles = object.roles.map((role, index) => parseManifestRole(role, index));
 	if (roles.length !== PROVIDER_CONTRACT_ROLE_IDS.length) {
@@ -385,6 +445,7 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		runtimes,
 		readme: parseFileReference(object.readme, "manifest.readme"),
 		roles,
+		orchestration,
 	};
 }
 
@@ -467,8 +528,8 @@ export function bundleTreeSha256(entrySha256: ReadonlyMap<string, string>): stri
 
 /** Verifies a complete in-memory bundle inventory. The single trust anchor. */
 export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<string, Buffer>): VerifiedProviderContractBundle {
-	if (rawEntries.size !== BUNDLE_ENTRY_COUNT) {
-		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${BUNDLE_ENTRY_COUNT} are expected`);
+	if (rawEntries.size > MAX_RAW_BUNDLE_ENTRIES) {
+		invalid(`bundle inventory has ${rawEntries.size} files; at most ${MAX_RAW_BUNDLE_ENTRIES} are ever expected`);
 	}
 	for (const [name, payload] of rawEntries) {
 		if (!isCanonicalBundlePath(name)) invalid(`bundle path ${JSON.stringify(name)} is unsafe`);
@@ -478,6 +539,14 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 	if (manifestPayload === undefined) invalid("bundle is missing manifest.json");
 	const manifest = parseManifest(manifestPayload);
 
+	// The exact expected inventory size is only known once the manifest is
+	// decoded: base entries plus exactly one `orchestration/<runtime>.md` per
+	// registered orchestration runtime.
+	const expectedEntryCount = BUNDLE_ENTRY_COUNT + manifest.orchestration.length;
+	if (rawEntries.size !== expectedEntryCount) {
+		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${expectedEntryCount} are expected`);
+	}
+
 	verifyFileReference(rawEntries, manifest.readme, "README.md");
 	const expected = new Set(["README.md", "manifest.json"]);
 	for (const role of manifest.roles) {
@@ -485,6 +554,13 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 		expected.add(`schemas/${role.id}.schema.json`);
 		expected.add(`vectors/${role.id}.json`);
 	}
+	const orchestration = new Map<string, string>();
+	for (const entry of manifest.orchestration) {
+		const path = `orchestration/${entry.runtime}.md`;
+		const payload = verifyFileReference(rawEntries, entry.file, path);
+		orchestration.set(entry.runtime, payload.toString("utf8"));
+		expected.add(path);
+	}
 	for (const name of rawEntries.keys()) {
 		if (!expected.has(name)) invalid(`bundle has unexpected file ${JSON.stringify(name)}`);
 	}
@@ -514,6 +590,7 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 			vectorPath: role.vector.path,
 			vectorSha256: role.vector.sha256,
 		})),
+		orchestration,
 		entries,
 		entrySha256,
 		treeSha256: bundleTreeSha256(entrySha256),
@@ -566,7 +643,7 @@ export function verifyProviderContractBundleTree(directory: string): VerifiedPro
 			}
 			if (!isCanonicalBundlePath(relativeName)) invalid(`bundle tree path ${JSON.stringify(relativeName)} is unsafe`);
 			if (details.size > MAX_FILE_BYTES) invalid(`bundle tree entry ${JSON.stringify(relativeName)} exceeds its size limit`);
-			if (entries.size >= BUNDLE_ENTRY_COUNT) invalid(`bundle tree has more than ${BUNDLE_ENTRY_COUNT} files`);
+			if (entries.size >= MAX_RAW_BUNDLE_ENTRIES) invalid(`bundle tree has more than ${MAX_RAW_BUNDLE_ENTRIES} files`);
 			entries.set(relativeName, readFileSync(absolute));
 		}
 	};
@@ -628,7 +705,7 @@ function readTarEntries(expanded: Buffer): Map<string, Buffer> {
 		if (size > MAX_FILE_BYTES) invalid(`tar entry ${JSON.stringify(name)} exceeds its size limit`);
 		totalBytes += size;
 		if (totalBytes > MAX_BUNDLE_BYTES) invalid("tar entries exceed the bundle size limit");
-		if (entries.size >= BUNDLE_ENTRY_COUNT) invalid(`tar has more than ${BUNDLE_ENTRY_COUNT} entries`);
+		if (entries.size >= MAX_RAW_BUNDLE_ENTRIES) invalid(`tar has more than ${MAX_RAW_BUNDLE_ENTRIES} entries`);
 		const padding = (TAR_BLOCK_SIZE - (size % TAR_BLOCK_SIZE)) % TAR_BLOCK_SIZE;
 		if (expanded.length - offset < size + padding) invalid("tar stream ends before a complete entry");
 		entries.set(name, Buffer.from(expanded.subarray(offset, offset + size)));
@@ -696,6 +773,11 @@ export function generateProviderContractBaselines(bundle: VerifiedProviderContra
 		mandatory_capabilities: mandatory,
 		runtimes: bundle.runtimes === undefined ? null : [...bundle.runtimes],
 		pi_registered: piRuntimeRegistration(bundle).registered,
+		orchestration: [...bundle.orchestration.keys()].sort().map((runtime) => ({
+			runtime,
+			path: `orchestration/${runtime}.md`,
+			sha256: bundle.entrySha256.get(`orchestration/${runtime}.md`),
+		})),
 	};
 	return new Map([
 		[PROVIDER_ROLES_BASELINE_FILE, `${JSON.stringify(roles, null, 2)}\n`],