immune-brain 3.6.3 → 3.6.5

package/plugins/immune-brain/runtime/github_issue_tracker.ts

@@ -57,6 +57,7 @@ export interface InitiativePublicationInput {
 	tasks: Array<{
 		slice_id: string;
 		intent: string;
+		acceptance: Array<{ id: string; summary: string }>;
 		projection?: TaskProjection;
 	}>;
 }
@@ -85,6 +86,18 @@ export interface GithubInitiativePublicationResult {
 	message: string;
 }
 
+export interface GithubInitiativeObservation {
+	contract: "immune_brain/github_initiative_observation/v1";
+	initiative_id: string;
+	issue_number: number;
+	tasks: Array<{
+		task_id: string;
+		slice_id: string;
+		issue_number: number;
+		blocked_by: string[];
+	}>;
+}
+
 export interface TaskProjection {
 	result?: string;
 	current_behavior?: string;
@@ -275,8 +288,8 @@ export function createGhTransport(binary = "gh"): GhTransport {
 	return {
 		run(args, options = {}) {
 			return new Promise((complete) => {
-				let stdout = Buffer.alloc(0);
-				let stderr = Buffer.alloc(0);
+				let stdout: Buffer = Buffer.alloc(0);
+				let stderr: Buffer = Buffer.alloc(0);
 				let timedOut = false;
 				let outputExceeded = false;
 				let timer: ReturnType<typeof setTimeout> | undefined;
@@ -304,7 +317,7 @@ export function createGhTransport(binary = "gh"): GhTransport {
 					finish(1, error instanceof Error ? error.message : String(error));
 					return;
 				}
-				const append = (current: Buffer, chunk: Buffer): Buffer => {
+				const append = (current: Buffer, chunk: Uint8Array): Buffer => {
 					const available = Math.max(0, MAX_GH_OUTPUT - stdout.length - stderr.length);
 					if (chunk.length > available) {
 						outputExceeded = true;
@@ -312,17 +325,22 @@ export function createGhTransport(binary = "gh"): GhTransport {
 					}
 					return available > 0 ? Buffer.concat([current, chunk.subarray(0, available)]) : current;
 				};
-				child.stdout.on("data", (chunk: Buffer) => { stdout = append(stdout, chunk); });
-				child.stderr.on("data", (chunk: Buffer) => { stderr = append(stderr, chunk); });
+				const { stdout: childOut, stderr: childErr, stdin: childIn } = child;
+				if (!childOut || !childErr || !childIn) {
+					finish(1, "gh was spawned without the stdio pipes this reader requires");
+					return;
+				}
+				childOut.on("data", (chunk: Uint8Array) => { stdout = append(stdout, chunk); });
+				childErr.on("data", (chunk: Uint8Array) => { stderr = append(stderr, chunk); });
 				child.once("error", (error) => { finish(1, error.message); });
-				child.stdin.once("error", (error) => { finish(1, error.message); });
+				childIn.once("error", (error) => { finish(1, error.message); });
 				timer = setTimeout(() => {
 					timedOut = true;
 					child.kill("SIGKILL");
 				}, GH_TIMEOUT_MS);
 				child.once("close", (code) => { finish(code ?? 1); });
 				try {
-					child.stdin.end(options.stdin ?? "");
+					childIn.end(options.stdin ?? "");
 				} catch (error) {
 					finish(1, error instanceof Error ? error.message : String(error));
 				}
@@ -371,7 +389,7 @@ function parseSubIssueNumbers(raw: string): number[] {
 	if (!Array.isArray(pages)) throw new Error("gh returned malformed Sub-issue list");
 	return pages.map((item, index) => {
 		const number = (item as { number?: unknown })?.number;
-		if (!Number.isSafeInteger(number)) throw new Error(`gh returned a malformed Sub-issue entry at ${index}`);
+		if (typeof number !== "number" || !Number.isSafeInteger(number)) throw new Error(`gh returned a malformed Sub-issue entry at ${index}`);
 		return number;
 	});
 }
@@ -547,6 +565,63 @@ async function readBlockedByIds(
 	}
 }
 
+export async function observeGithubInitiative(
+	root: string,
+	initiativeId: string,
+	gh: GhTransport = createGhTransport(),
+): Promise<GithubInitiativeObservation> {
+	const id = identifier(initiativeId, "initiative_id");
+	const source = await snapshot(resolve(root), gh, "create-initiative");
+	if ("contract" in source) throw new Error(source.message);
+	const parent = initiativeLookup(source.issues, source.repository.id, id);
+	if (parent.kind === "missing") throw new Error(`Initiative ${id} is not published`);
+	if (parent.kind === "ambiguous") throw new Error(parent.message);
+	const subIssueNumbers = await readSubIssueNumbers(root, gh, "create-initiative", source.repository, parent.issue.number);
+	if (!Array.isArray(subIssueNumbers)) throw new Error(subIssueNumbers.message);
+	if (new Set(subIssueNumbers).size !== subIssueNumbers.length)
+		throw new Error(`Initiative ${id} has duplicate native Sub-issue relations`);
+	const tasks = subIssueNumbers.map((issueNumber) => {
+		const matches = source.issues.filter((issue) => issue.number === issueNumber);
+		if (matches.length !== 1) throw new Error(`Initiative ${id} references an unreadable Sub-issue #${issueNumber}`);
+		const issue = matches[0];
+		const taskId = ownershipMarkerValue(issue.body, "task-id");
+		const sliceId = ownershipMarkerValue(issue.body, "slice-id");
+		if (!taskId || !sliceId || ownershipMarkerValue(issue.body, "initiative-id") !== id)
+			throw new Error(`Sub-issue #${issueNumber} has invalid Initiative ownership markers`);
+		const owned = ownedTaskLookup(source.issues, source.repository.id, taskId, id, sliceId);
+		if (owned.kind !== "found" || owned.issue.number !== issueNumber)
+			throw new Error(owned.kind === "ambiguous" ? owned.message : `Sub-issue #${issueNumber} has invalid Task ownership`);
+		return { task_id: taskId, slice_id: sliceId, issue_number: issueNumber, issue_id: issue.id };
+	});
+	if (new Set(tasks.map((task) => task.task_id)).size !== tasks.length)
+		throw new Error(`Initiative ${id} has duplicate Task identities`);
+	if (new Set(tasks.map((task) => task.slice_id)).size !== tasks.length)
+		throw new Error(`Initiative ${id} has duplicate Slice identities`);
+	const taskByIssueId = new Map(tasks.map((task) => [task.issue_id, task.task_id]));
+	const observed: GithubInitiativeObservation["tasks"] = [];
+	for (const task of tasks.sort((left, right) => left.task_id < right.task_id ? -1 : left.task_id > right.task_id ? 1 : 0)) {
+		const blockerIds = await readBlockedByIds(root, gh, "create-initiative", source.repository, task.issue_number);
+		if (!Array.isArray(blockerIds)) throw new Error(blockerIds.message);
+		const blockedBy = blockerIds.map((blockerId) => {
+			const blocker = taskByIssueId.get(blockerId);
+			if (!blocker) throw new Error(`Task ${task.task_id} depends on an Issue outside Initiative ${id}`);
+			return blocker;
+		}).sort();
+		observed.push({
+			task_id: task.task_id,
+			slice_id: task.slice_id,
+			issue_number: task.issue_number,
+			blocked_by: blockedBy,
+		});
+	}
+	return {
+		contract: "immune_brain/github_initiative_observation/v1",
+		initiative_id: id,
+		issue_number: parent.issue.number,
+		tasks: observed,
+	};
+}
+
 async function confirmBlockedBy(
 	root: string,
 	gh: GhTransport,
@@ -1065,7 +1140,7 @@ function preflightPublication(root: string, input: InitiativePublicationInput):
 	const publications = input.tasks.map((task, index) => {
 		if (!task || typeof task !== "object" || Array.isArray(task)) throw new Error(`tasks[${index}] must be an object`);
 		if (typeof task.intent !== "string") throw new Error(`tasks[${index}].intent must be a string`);
-		return taskPublication(root, input.initiative_id, task.slice_id, task.intent, task.projection);
+		return taskPublication(root, input.initiative_id, task.slice_id, task.intent, task.acceptance, task.projection);
 	});
 	const operations = publications.map((publication) => publication.operation);
 	const taskIds = new Set<string>();
@@ -1259,7 +1334,14 @@ function isSuccessfulTrackerStatus(status: TrackerStatus): boolean {
 	return status === "created" || status === "updated" || status === "already_current";
 }
 
-function taskPublication(root: string, initiativeId: string, sliceId: string, intentPath: string, projection?: TaskProjection): PreparedPublicationTask {
+function taskPublication(
+	root: string,
+	initiativeId: string,
+	sliceId: string,
+	intentPath: string,
+	acceptance: unknown,
+	projection?: TaskProjection,
+): PreparedPublicationTask {
 	const absoluteRoot = resolve(root);
 	const absolutePath = resolve(absoluteRoot, intentPath);
 	const rel = relative(absoluteRoot, absolutePath);
@@ -1270,6 +1352,20 @@ function taskPublication(root: string, initiativeId: string, sliceId: string, in
 	const read = readTaskIntent(absoluteRoot, taskId);
 	if (read.intent_ref.path !== rel) throw new Error("TaskIntent path must match its canonical sidecar path");
 	const intent = read.intent;
+	if (!Array.isArray(acceptance)) throw new Error(`Task ${taskId} requires public acceptance summaries`);
+	const expectedIds = new Set(intent.acceptance.map((item) => item.id));
+	const publicById = new Map<string, { id: string; summary: string }>();
+	acceptance.forEach((item, index) => {
+		if (!item || typeof item !== "object" || Array.isArray(item))
+			throw new Error(`Task ${taskId} acceptance[${index}] must be an object`);
+		const raw = item as Record<string, unknown>;
+		const id = identifier(raw.id, `Task ${taskId} acceptance[${index}].id`);
+		if (!expectedIds.has(id)) throw new Error(`Task ${taskId} has unknown public acceptance id: ${id}`);
+		if (publicById.has(id)) throw new Error(`Task ${taskId} has duplicate public acceptance id: ${id}`);
+		publicById.set(id, { id, summary: projectionText(raw.summary, `Task ${taskId} acceptance[${index}].summary`, 500) });
+	});
+	const missingIds = [...expectedIds].filter((id) => !publicById.has(id));
+	if (missingIds.length) throw new Error(`Task ${taskId} is missing public acceptance ids: ${missingIds.join(", ")}`);
 	return {
 		operation: validateOperation({
 			op: "upsert-task",
@@ -1278,7 +1374,7 @@ function taskPublication(root: string, initiativeId: string, sliceId: string, in
 			slice_id: sliceId,
 			goal: intent.goal,
 			risk: intent.risk,
-			acceptance: intent.acceptance.map((item) => ({ id: item.id, summary: item.assertion })),
+			acceptance: intent.acceptance.map((item) => publicById.get(item.id)!),
 			projection,
 		}) as Extract<TrackerOperation, { op: "upsert-task" }>,
 		intent_path: read.intent_ref.path,

package/plugins/immune-brain/runtime/kernel/application.ts

@@ -160,6 +160,7 @@ export function applyTaskAction(
 			action.type === "record_approval" ||
 			action.type === "approve_breaking_intent_revision" ||
 			action.type === "request_rework" ||
+			action.type === "authorize_rework" ||
 			action.type === "stop" ||
 			action.type === "resolve_user_decision";
 
@@ -260,6 +261,11 @@ export function applyTaskAction(
 		}
 
 		if (input.terminal) {
+			// A tombstone may only record a terminal lifecycle. Nothing upstream
+			// proved that, so an active record could have been tombstoned as
+			// `terminal_lifecycle: "active"` in violation of its own contract.
+			if (nextRecord.lifecycle === "active")
+				throw new Error("terminal settlement requires a done or stopped TaskRecord lifecycle");
 			const tombstone: TaskTombstone = {
 				contract: TASK_TOMBSTONE_CONTRACT,
 				task_id,

package/plugins/immune-brain/runtime/kernel/assurance_projection.ts

@@ -25,9 +25,10 @@ export interface AssuranceAuthorizationReadiness {
 	/**
 	 * Kernel-decidable authorization readiness:
 	 * - "resolve_user_decision": exactly one open unresolved-user-decision finding;
+	 * - "authorize_rework": an open replan boundary can be overridden by the user;
 	 * - "none": nothing uniquely decidable from Kernel facts.
 	 */
-	state: "resolve_user_decision" | "none";
+	state: "resolve_user_decision" | "authorize_rework" | "none";
 	/** Non-null only when Kernel facts prove the authorization is blocked. */
 	blocked: string | null;
 }
@@ -75,6 +76,8 @@ export function deriveAssuranceAuthorization(input: {
 			state: "none",
 			blocked: `resolve-user-decision requires exactly one open user decision; found ${input.open_user_decision_count}`,
 		};
+	if (input.next_obligation === "revise_intent")
+		return { state: "authorize_rework", blocked: null };
 	return { state: "none", blocked: null };
 }
 

package/plugins/immune-brain/runtime/kernel/batch_authority.ts

@@ -0,0 +1,407 @@
+// Batch Authorization for unattended Initiative batch runs. NOT exported from
+// kernel/index.ts. One literal-user confirmation binds an ordered child plan;
+// each child consumes exactly one slot and derives its own Enrollment
+// capability from a freshly recomputed preparation at enroll time.
+//
+// The confirmation cannot bind a preparation digest: enrollment rejects a moved
+// Git HEAD, and every settled child moves it. The batch binds `plan_digest`
+// plus an advancing HEAD lineage instead.
+
+import { createHash } from "node:crypto";
+import { createCapabilityRegistry } from "./capability_registry";
+import type { EnrollmentCapabilityBinding } from "./enrollment_authority";
+import { preparePiCanary, type PiCanaryPreparation } from "./pi_canary_prepare";
+
+export const BATCH_AUTHORITY_CAPABILITY_BRAND = Symbol.for(
+	"assurance-kernel.batch-authority-capability-brand",
+);
+
+const GIT_COMMIT_ID = /^[a-f0-9]{40}$/;
+
+/** review-7(3rd rework): typed expiry marker thrown at the Kernel enrollment
+ * boundary so the driver can classify a real enrollment-time expiry as an
+ * intentional budget stop without free-form message matching. */
+export class BatchAuthorizationExpiryError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "BatchAuthorizationExpiryError";
+	}
+}
+
+export interface BatchPlanChild {
+	task_id: string;
+	intent_path: string;
+	intent_revision: number;
+	intent_content_hash: string;
+	blocked_by: string[];
+}
+
+export interface BatchBudget {
+	max_children: number;
+	deadline_at: string;
+	qa_failure_limit: number;
+}
+
+export interface BatchAuthorizationBinding {
+	batch_id: string;
+	initiative_slug: string;
+	plan_digest: string;
+	branch: string;
+	base_head: string;
+	budget: BatchBudget;
+	actor_id: string;
+	confirmation_ref: string;
+	expires_at: string;
+	nonce: string;
+}
+
+export interface ValidatedBatchAuthorization {
+	batch_id: string;
+	initiative_slug: string;
+	plan_digest: string;
+	branch: string;
+	base_head: string;
+	budget: BatchBudget;
+	actor_id: string;
+	confirmation_ref: string;
+	issued_at: string;
+	expires_at: string;
+	nonce: string;
+}
+
+export interface BatchAuthorityRegistry {
+	readonly brand: symbol;
+	/**
+	 * Issue one Batch Authorization bound to an exact ordered child plan.
+	 * The plan is retained so per-child consumption can prove membership.
+	 */
+	issue(
+		binding: BatchAuthorizationBinding,
+		children: BatchPlanChild[],
+		issuedAt?: string,
+	): object;
+	inspect(
+		capability: object,
+		expected: BatchAuthorizationBinding,
+		now?: number,
+	): ValidatedBatchAuthorization;
+	children(capability: object): BatchPlanChild[];
+	consumedChildren(capability: object): string[];
+	isChildConsumed(capability: object, taskId: string): boolean;
+	/** Mark exactly one child slot used; the authorization stays valid for the rest. */
+	consumeChild(
+		capability: object,
+		expected: BatchAuthorizationBinding,
+		taskId: string,
+		now?: number,
+	): ValidatedBatchAuthorization;
+	/** Undo one slot consumption when the bound write did not commit. */
+	releaseChild(capability: object, taskId: string): void;
+	isExhausted(capability: object): boolean;
+}
+
+function sha256Hex(bytes: string): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function stableStringify(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+	const record = value as Record<string, unknown>;
+	return `{${Object.keys(record)
+		.sort()
+		.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+		.join(",")}}`;
+}
+
+/**
+ * The authorization subject. A TaskIntent carries no Initiative or dependency
+ * field, so the confirmed ordered plan — not remote tracker state — is what the
+ * literal user approves, and this digest is what binds it.
+ */
+export function computeBatchPlanDigest(children: BatchPlanChild[]): string {
+	const canonical = children.map((child) => ({
+		blocked_by: [...child.blocked_by],
+		intent_content_hash: child.intent_content_hash,
+		intent_path: child.intent_path,
+		intent_revision: child.intent_revision,
+		task_id: child.task_id,
+	}));
+	return `sha256:${sha256Hex(stableStringify(canonical))}`;
+}
+
+function requireNonEmpty(binding: BatchAuthorizationBinding): void {
+	const missing: string[] = [];
+	for (const key of [
+		"batch_id",
+		"initiative_slug",
+		"plan_digest",
+		"branch",
+		"base_head",
+		"actor_id",
+		"confirmation_ref",
+		"expires_at",
+		"nonce",
+	] as const) {
+		const value = binding[key];
+		if (value === undefined || value === null || value === "") missing.push(key);
+	}
+	if (!binding.budget || typeof binding.budget !== "object") missing.push("budget");
+	if (missing.length > 0)
+		throw new Error(`batch authorization binding is incomplete: ${missing.join(", ")}`);
+}
+
+function validateBudget(budget: BatchBudget, issuedAt: string): void {
+	if (!Number.isInteger(budget.max_children) || budget.max_children <= 0)
+		throw new Error("batch budget max_children must be a positive integer");
+	if (!Number.isInteger(budget.qa_failure_limit) || budget.qa_failure_limit <= 0)
+		throw new Error("batch budget qa_failure_limit must be a positive integer");
+	const deadline = Date.parse(budget.deadline_at);
+	if (Number.isNaN(deadline) || deadline <= Date.parse(issuedAt))
+		throw new Error("batch budget must have a future deadline_at");
+}
+
+function validateChildren(children: BatchPlanChild[], planDigest: string): void {
+	if (!Array.isArray(children) || children.length === 0)
+		throw new Error("batch authorization requires a non-empty child plan");
+	const seen = new Set<string>();
+	for (const child of children) {
+		if (!child || typeof child !== "object")
+			throw new Error("batch plan child must be an object");
+		for (const key of ["task_id", "intent_path", "intent_content_hash"] as const) {
+			if (typeof child[key] !== "string" || child[key] === "")
+				throw new Error(`batch plan child ${key} must be a non-empty string`);
+		}
+		if (!Number.isInteger(child.intent_revision) || child.intent_revision <= 0)
+			throw new Error("batch plan child intent_revision must be a positive integer");
+		if (!Array.isArray(child.blocked_by) || child.blocked_by.some((id) => typeof id !== "string" || id === ""))
+			throw new Error("batch plan child blocked_by must be an array of task ids");
+		if (seen.has(child.task_id))
+			throw new Error(`batch plan child ${child.task_id} appears more than once`);
+		seen.add(child.task_id);
+	}
+	for (const child of children) {
+		for (const blocker of child.blocked_by) {
+			if (!seen.has(blocker))
+				throw new Error(
+					`batch plan child ${child.task_id} is blocked by ${blocker}, which is not in the confirmed plan`,
+				);
+		}
+	}
+	const dependencies = new Map(children.map((child) => [child.task_id, child.blocked_by]));
+	const visiting = new Set<string>();
+	const visited = new Set<string>();
+	function visit(taskId: string): void {
+		if (visiting.has(taskId)) throw new Error(`batch plan dependency cycle at ${taskId}`);
+		if (visited.has(taskId)) return;
+		visiting.add(taskId);
+		for (const blocker of dependencies.get(taskId)!) visit(blocker);
+		visiting.delete(taskId);
+		visited.add(taskId);
+	}
+	for (const child of children) visit(child.task_id);
+	if (computeBatchPlanDigest(children) !== planDigest)
+		throw new Error("batch plan digest does not match the confirmed child plan");
+}
+
+export function createBatchAuthorityRegistry(): BatchAuthorityRegistry {
+	const inner = createCapabilityRegistry<
+		BatchAuthorizationBinding,
+		BatchAuthorizationBinding,
+		ValidatedBatchAuthorization
+	>(
+		BATCH_AUTHORITY_CAPABILITY_BRAND,
+		{
+			validateBinding(binding, issuedAt) {
+				requireNonEmpty(binding);
+				if (binding.actor_id !== "user")
+					throw new Error("batch authorization requires a literal-user actor_id");
+				if (!GIT_COMMIT_ID.test(binding.base_head))
+					throw new Error("batch authorization base_head must be a committed 40-hex commit id");
+				const expires = Date.parse(binding.expires_at);
+				if (Number.isNaN(expires) || expires <= Date.parse(issuedAt))
+					throw new Error("batch authorization must have a future expiry");
+				validateBudget(binding.budget, issuedAt);
+			},
+			validateAndProject(state, expected, now) {
+				// Fail closed on an unusable clock. `now` reaches here as
+				// Date.parse(...) from callers, and NaN makes every `<=` compare
+				// false, which would silently accept an expired authorization.
+				if (!Number.isFinite(now))
+					throw new Error("batch authorization requires a valid clock");
+				const expires = Date.parse(state.expires_at);
+				if (Number.isNaN(expires) || expires <= now)
+					throw new BatchAuthorizationExpiryError("batch authorization has expired");
+				if (Date.parse(state.budget.deadline_at) <= now)
+					throw new BatchAuthorizationExpiryError("batch authorization deadline has expired");
+				for (const key of Object.keys(expected) as Array<keyof BatchAuthorizationBinding>) {
+					if (key === "budget") {
+						const a = state.budget ?? ({} as BatchBudget);
+						const b = expected.budget ?? ({} as BatchBudget);
+						if (
+							a.max_children !== b.max_children ||
+							a.deadline_at !== b.deadline_at ||
+							a.qa_failure_limit !== b.qa_failure_limit
+						)
+							throw new Error("batch authorization budget mismatch");
+						continue;
+					}
+					if (state[key] !== expected[key])
+						throw new Error(`batch authorization ${key} mismatch`);
+				}
+				return {
+					batch_id: state.batch_id,
+					initiative_slug: state.initiative_slug,
+					plan_digest: state.plan_digest,
+					branch: state.branch,
+					base_head: state.base_head,
+					budget: { ...state.budget },
+					actor_id: state.actor_id,
+					confirmation_ref: state.confirmation_ref,
+					issued_at: state.issued_at,
+					expires_at: state.expires_at,
+					nonce: state.nonce,
+				};
+			},
+		},
+		"batch authorization",
+	);
+
+	const plans = new WeakMap<object, BatchPlanChild[]>();
+	const consumed = new WeakMap<object, Set<string>>();
+
+	function planOf(capability: object): BatchPlanChild[] {
+		const plan = plans.get(capability);
+		if (!plan) throw new Error("batch authorization capability is not recognized by this registry");
+		return plan;
+	}
+
+	function slotsOf(capability: object): Set<string> {
+		const slots = consumed.get(capability);
+		if (!slots) throw new Error("batch authorization capability is not recognized by this registry");
+		return slots;
+	}
+
+	return {
+		brand: inner.brand,
+		issue(binding, children, issuedAt = new Date().toISOString()) {
+			requireNonEmpty(binding);
+			validateChildren(children, binding.plan_digest);
+			const capability = inner.issue(binding, issuedAt) as object;
+			plans.set(
+				capability,
+				children.map((child) => ({ ...child, blocked_by: [...child.blocked_by] })),
+			);
+			consumed.set(capability, new Set<string>());
+			return capability;
+		},
+		inspect(capability, expected, now = Date.now()) {
+			planOf(capability);
+			return inner.inspect(capability, expected, now);
+		},
+		children(capability) {
+			return planOf(capability).map((child) => ({ ...child, blocked_by: [...child.blocked_by] }));
+		},
+		consumedChildren(capability) {
+			return [...slotsOf(capability)];
+		},
+		isChildConsumed(capability, taskId) {
+			return slotsOf(capability).has(taskId);
+		},
+		consumeChild(capability, expected, taskId, now = Date.now()) {
+			const validated = this.inspect(capability, expected, now);
+			const plan = planOf(capability);
+			if (!plan.some((child) => child.task_id === taskId))
+				throw new Error(`batch_child_not_in_plan: ${taskId}`);
+			const slots = slotsOf(capability);
+			if (slots.has(taskId)) throw new Error(`batch_child_slot_consumed: ${taskId}`);
+			slots.add(taskId);
+			return validated;
+		},
+		releaseChild(capability, taskId) {
+			slotsOf(capability).delete(taskId);
+		},
+		isExhausted(capability) {
+			return slotsOf(capability).size >= planOf(capability).length;
+		},
+	};
+}
+
+export interface DeriveChildEnrollmentInput {
+	capability: object;
+	binding: BatchAuthorizationBinding;
+	task_id: string;
+	/** Batch HEAD lineage: base_head, then each commit this batch created. */
+	expected_head: string;
+	now: string;
+}
+
+export interface DerivedChildEnrollment {
+	child: BatchPlanChild;
+	preparation: PiCanaryPreparation;
+	binding: EnrollmentCapabilityBinding;
+}
+
+/**
+ * Derive one child's Enrollment binding from a Batch Authorization. The
+ * preparation digest is recomputed here, never carried from the confirmation.
+ */
+export function deriveChildEnrollment(
+	root: string,
+	registry: BatchAuthorityRegistry,
+	input: DeriveChildEnrollmentInput,
+): DerivedChildEnrollment {
+	const validated = registry.inspect(input.capability, input.binding, Date.parse(input.now));
+	const child = registry
+		.children(input.capability)
+		.find((entry) => entry.task_id === input.task_id);
+	if (!child) throw new Error(`batch_child_not_in_plan: ${input.task_id}`);
+	if (registry.isChildConsumed(input.capability, input.task_id))
+		throw new Error(`batch_child_slot_consumed: ${input.task_id}`);
+	if (!GIT_COMMIT_ID.test(input.expected_head))
+		throw new Error("batch_head_lineage_broken: expected_head is not a commit id");
+
+	const preparation = preparePiCanary(root, { task_id: input.task_id, now: input.now });
+	if (!preparation.git_base_head)
+		throw new Error(preparation.git_error ?? "enrollment requires a committed Git HEAD");
+	if (preparation.git_base_head !== input.expected_head)
+		throw new Error(
+			`batch_head_lineage_broken: expected ${input.expected_head}, found ${preparation.git_base_head}`,
+		);
+	if (!preparation.intent)
+		throw new Error(`batch_child_intent_changed: ${input.task_id} intent sidecar is unreadable`);
+	if (
+		preparation.intent.path !== child.intent_path ||
+		preparation.intent.revision !== child.intent_revision ||
+		preparation.intent.content_hash !== child.intent_content_hash
+	)
+		throw new Error(`batch_child_intent_changed: ${input.task_id}`);
+
+	// The lineage starts at the confirmed base_head. Until this batch has
+	// settled a child there is no commit it could have created, so a
+	// caller-supplied expected_head other than base_head is not a lineage.
+	// Checked last so the intent-divergence reason keeps its precedence.
+	if (
+		registry.consumedChildren(input.capability).length === 0 &&
+		input.expected_head !== validated.base_head
+	)
+		throw new Error(
+			`batch_head_lineage_broken: the first child must enroll on the confirmed base_head ${validated.base_head}, not ${input.expected_head}`,
+		);
+
+	return {
+		child,
+		preparation,
+		binding: {
+			task_id: child.task_id,
+			intent_path: child.intent_path,
+			intent_revision: child.intent_revision,
+			intent_content_hash: child.intent_content_hash,
+			preparation_digest: preparation.digest,
+			actor_id: validated.actor_id,
+			confirmation_ref: validated.confirmation_ref,
+			expires_at: validated.expires_at,
+			nonce: `${validated.nonce}:${child.task_id}`,
+		},
+	};
+}