immune-brain 5.0.0 → 5.1.0

package/plugins/immune-brain/runtime/unattended/batch_plan.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { stableStringify } from "../canonical_json";
-import { observeGithubInitiative, type GithubInitiativeObservation } from "../github_issue_tracker";
+import { observeGithubInitiative } from "../github_issue_tracker";
+import { hasLocalInitiative, observeLocalInitiative } from "../local_initiative";
 import { readTaskTombstone } from "../kernel/backend_claim";
 import {
 	observeTaskIntent,
@@ -8,12 +9,14 @@ import {
 } from "../kernel/intent";
 import { readTaskRecordRaw } from "../kernel/storage";
 import { inspectSpecBinding, type SpecBindingInspection } from "../kernel/spec_binding";
+import { projectParallelGroups } from "./batch_schedule";
 import type {
 	BatchPlan,
 	BatchPlanBudget,
 	BatchPlanChild,
 	BatchPlanChildReason,
 	BatchPlanDigestChild,
+	InitiativeObservation,
 	InitiativeObservationReader,
 	ProjectBatchPlanInput,
 } from "./types";
@@ -57,12 +60,22 @@ function timestamp(value: unknown, name: string): { milliseconds: number; iso: s
 	return { milliseconds, iso: new Date(milliseconds).toISOString() };
 }
 
-function normalizeObservation(value: GithubInitiativeObservation, initiativeSlug: string): GithubInitiativeObservation {
-	if (!value || value.contract !== "immune_brain/github_initiative_observation/v1")
+/**
+ * The Initiative's carrier decides the reader: a Local carrier file owns its
+ * slug and is read with no GitHub operation; every other slug is a GitHub one.
+ */
+export const observeInitiative: InitiativeObservationReader = async (root, initiativeSlug) =>
+	hasLocalInitiative(root, initiativeSlug)
+		? observeLocalInitiative(root, initiativeSlug)
+		: observeGithubInitiative(root, initiativeSlug);
+
+function normalizeObservation(value: InitiativeObservation, initiativeSlug: string): InitiativeObservation {
+	const local = value?.contract === "immune_brain/local_initiative_observation/v1";
+	if (!value || (!local && value.contract !== "immune_brain/github_initiative_observation/v1"))
 		throw new Error("tracker returned an invalid Initiative observation contract");
 	if (value.initiative_id !== initiativeSlug)
 		throw new Error("tracker returned an observation for another Initiative");
-	if (!Number.isSafeInteger(value.issue_number) || value.issue_number <= 0)
+	if (!local && (!Number.isSafeInteger(value.issue_number) || value.issue_number <= 0))
 		throw new Error("tracker returned an invalid Initiative Issue number");
 	if (!Array.isArray(value.tasks)) throw new Error("tracker returned an invalid Initiative Task list");
 	const taskIds = new Set<string>();
@@ -71,7 +84,8 @@ function normalizeObservation(value: GithubInitiativeObservation, initiativeSlug
 		if (!task || typeof task !== "object") throw new Error(`tracker Task ${index} is invalid`);
 		if (!ID_PATTERN.test(task.task_id)) throw new Error(`tracker Task ${index} has an invalid task_id`);
 		if (!ID_PATTERN.test(task.slice_id)) throw new Error(`tracker Task ${index} has an invalid slice_id`);
-		if (!Number.isSafeInteger(task.issue_number) || task.issue_number <= 0)
+		const issueNumber = (task as { issue_number?: number }).issue_number;
+		if (!local && (!Number.isSafeInteger(issueNumber) || issueNumber! <= 0))
 			throw new Error(`tracker Task ${task.task_id} has an invalid Issue number`);
 		if (!Array.isArray(task.blocked_by) || task.blocked_by.some((id) => typeof id !== "string" || !ID_PATTERN.test(id)))
 			throw new Error(`tracker Task ${task.task_id} has invalid blocked_by dependencies`);
@@ -88,13 +102,15 @@ function normalizeObservation(value: GithubInitiativeObservation, initiativeSlug
 		const unknown = task.blocked_by.find((id) => !taskIds.has(id));
 		if (unknown) throw new Error(`tracker Task ${task.task_id} depends on unknown Task ${unknown}`);
 	}
-	return { ...value, tasks: tasks.sort((left, right) => compareIds(left.task_id, right.task_id)) };
+	return { ...value, tasks: tasks.sort((left, right) => compareIds(left.task_id, right.task_id)) } as InitiativeObservation;
 }
 
-function dependencyOrder(observation: GithubInitiativeObservation): GithubInitiativeObservation["tasks"] {
-	const remaining = new Map(observation.tasks.map((task) => [task.task_id, task]));
+type ObservedTask = { task_id: string; slice_id: string; blocked_by: string[] };
+
+function dependencyOrder(observation: InitiativeObservation): ObservedTask[] {
+	const remaining = new Map<string, ObservedTask>(observation.tasks.map((task) => [task.task_id, task]));
 	const done = new Set<string>();
-	const order: GithubInitiativeObservation["tasks"] = [];
+	const order: ObservedTask[] = [];
 	while (remaining.size) {
 		const ready = [...remaining.values()]
 			.filter((task) => task.blocked_by.every((id) => done.has(id)))
@@ -109,7 +125,7 @@ function dependencyOrder(observation: GithubInitiativeObservation): GithubInitia
 	return order;
 }
 
-function dependencyClosures(order: GithubInitiativeObservation["tasks"]): Map<string, string[]> {
+function dependencyClosures(order: ObservedTask[]): Map<string, string[]> {
 	const closures = new Map<string, string[]>();
 	for (const task of order) {
 		const closure = new Set<string>();
@@ -138,7 +154,7 @@ export async function projectBatchPlan(
 	root: string,
 	initiativeSlug: string,
 	input: ProjectBatchPlanInput,
-	readInitiative: InitiativeObservationReader = observeGithubInitiative,
+	readInitiative: InitiativeObservationReader = observeInitiative,
 ): Promise<BatchPlan> {
 	if (!ID_PATTERN.test(initiativeSlug)) throw new Error("initiative_slug is invalid");
 	if (!input || typeof input !== "object") throw new Error("batch plan input is required");
@@ -147,6 +163,7 @@ export async function projectBatchPlan(
 	const order = dependencyOrder(trackerObservation);
 	const closures = dependencyClosures(order);
 	const children: BatchPlanChild[] = [];
+	const scopeHints = new Map<string, string[]>();
 	for (const task of order) {
 		const blockedBy = closures.get(task.task_id)!;
 		const child = { task_id: task.task_id, slice_id: task.slice_id, blocked_by: blockedBy };
@@ -187,6 +204,7 @@ export async function projectBatchPlan(
 				});
 				continue;
 			}
+			scopeHints.set(task.task_id, [...read.intent.scope_hint]);
 			children.push({
 				...child,
 				status: "enrollable",
@@ -233,5 +251,12 @@ export async function projectBatchPlan(
 		enrollable,
 		plan_digest: planDigest,
 		budget: budget(input, enrollable.length),
+		...projectParallelGroups(
+			enrollable.map((child) => ({
+				task_id: child.task_id,
+				blocked_by: child.blocked_by,
+				scope_hint: scopeHints.get(child.task_id)!,
+			})),
+		),
 	};
 }

package/plugins/immune-brain/runtime/unattended/batch_preflight.ts

@@ -26,7 +26,7 @@ import { pathMatchesScope } from "../workspace_scope";
 import { captureBatchReconfirmation, retainReconfirmation, ownUnpersistedBatchHead, type ReconfirmationSnapshot } from "./batch_reconfirmation";
 import { projectBatchPlan } from "./batch_plan";
 import { batchReason, type BatchReasonKey } from "./batch_reasons";
-import { isTerminalBatchState, readBatchRunState, type BatchRunStateRecord } from "./batch_state";
+import { isLaneBatchRecord, isTerminalBatchState, readAnyBatchRunState, type AnyBatchRunStateRecord, type BatchRunStateRecord } from "./batch_state";
 import type {
 	BatchPlanBudget,
 	BatchPlanChild,
@@ -50,7 +50,7 @@ export interface BatchPreflightProjection {
 	initiative_slug: string;
 	batch_branch: string;
 	is_resuming: boolean;
-	existing_batch: BatchRunStateRecord | null;
+	existing_batch: AnyBatchRunStateRecord | null;
 	base_head: string;
 	budget: BatchPlanBudget;
 	plan_digest: string;
@@ -59,6 +59,9 @@ export interface BatchPreflightProjection {
 	risk_by_task: Record<string, string>;
 	/** Children the plan excluded, in plan order. Empty on a resume. */
 	excluded: Array<{ task_id: string; slice_id: string; reason: string }>;
+	/** Start waves and serialized-by-scope children; empty on a resume. */
+	parallel_groups: string[][];
+	scope_conflicts: Array<{ task_id: string; overlaps_with: string[] }>;
 }
 
 export type BatchPreflightOutcome =
@@ -109,8 +112,8 @@ export function findResumableBatchSlugForTask(root: string, taskId: string): str
 	for (const file of readdirSync(batchesDir)) {
 		if (!file.endsWith(".json")) continue;
 		try {
-			const record = JSON.parse(readFileSync(join(batchesDir, file), "utf8")) as BatchRunStateRecord;
-			if (record?.contract !== "assurance_kernel/batch_run_state/v1") continue;
+			const record = JSON.parse(readFileSync(join(batchesDir, file), "utf8")) as AnyBatchRunStateRecord;
+			if (record?.contract !== "assurance_kernel/batch_run_state/v1" && record?.contract !== "assurance_kernel/batch_run_state/v2") continue;
 			if (record.batch_state !== "running" && record.batch_state !== "needs_human") continue;
 			if (record.children.some((child) => child.task_id === taskId && (child.state === "enrolled" || child.state === "settled")))
 				return record.initiative_slug;
@@ -128,7 +131,7 @@ export function findResumableBatchSlugForTask(root: string, taskId: string): str
  */
 export type BatchRecordLookup =
 	| { corrupt: true; path: string }
-	| { corrupt: false; record: BatchRunStateRecord }
+	| { corrupt: false; record: AnyBatchRunStateRecord }
 	| null;
 
 export function findExistingActiveBatch(root: string, initiativeSlug: string): BatchRecordLookup {
@@ -144,8 +147,8 @@ export function findExistingActiveBatch(root: string, initiativeSlug: string): B
 			// initiative as batchless could authorize a parallel run.
 			return { corrupt: true, path: file };
 		}
-		const candidate = record as BatchRunStateRecord;
-		if (candidate?.contract !== "assurance_kernel/batch_run_state/v1") continue;
+		const candidate = record as AnyBatchRunStateRecord;
+		if (candidate?.contract !== "assurance_kernel/batch_run_state/v1" && candidate?.contract !== "assurance_kernel/batch_run_state/v2") continue;
 		if (candidate.initiative_slug !== initiativeSlug) continue;
 		const validStates = new Set([
 			"prepared",
@@ -166,7 +169,7 @@ export function findExistingActiveBatch(root: string, initiativeSlug: string): B
 		}
 		if (isTerminalBatchState(candidate.batch_state)) continue;
 		try {
-			const record = readBatchRunState(root, file.slice(0, -5));
+			const record = readAnyBatchRunState(root, file.slice(0, -5));
 			if (record) return { corrupt: false, record };
 		} catch {
 			// Reuse the state owner's full validation before offering a renewal.
@@ -181,10 +184,10 @@ export function findExistingActiveBatch(root: string, initiativeSlug: string): B
  * not a batch to resume. Its branch and commit lineage may be reused by a new,
  * explicitly confirmed run, while its record and terminal report stay intact.
  */
-export function findSettledBatchRecord(root: string, initiativeSlug: string): BatchRunStateRecord | null {
+export function findSettledBatchRecord(root: string, initiativeSlug: string): AnyBatchRunStateRecord | null {
 	const batchesDir = join(root, ".imm", "state", "batches");
 	if (!existsSync(batchesDir)) return null;
-	let newest: BatchRunStateRecord | null = null;
+	let newest: AnyBatchRunStateRecord | null = null;
 	for (const file of readdirSync(batchesDir).sort()) {
 		if (!file.endsWith(".json")) continue;
 		let record: unknown;
@@ -194,8 +197,8 @@ export function findSettledBatchRecord(root: string, initiativeSlug: string): Ba
 			// The active lookup already fails closed on an unreadable record.
 			continue;
 		}
-		const candidate = record as BatchRunStateRecord;
-		if (candidate?.contract !== "assurance_kernel/batch_run_state/v1") continue;
+		const candidate = record as AnyBatchRunStateRecord;
+		if (candidate?.contract !== "assurance_kernel/batch_run_state/v1" && candidate?.contract !== "assurance_kernel/batch_run_state/v2") continue;
 		if (candidate.initiative_slug !== initiativeSlug) continue;
 		if (!isTerminalBatchState(candidate.batch_state)) continue;
 		if (typeof candidate.batch_id !== "string" || typeof candidate.base_head !== "string") continue;
@@ -294,7 +297,7 @@ export function expectedBatchHead(record: {
  */
 export function isOwnBatchClaim(
 	root: string,
-	existingBatch: BatchRunStateRecord,
+	existingBatch: AnyBatchRunStateRecord,
 	taskId: string,
 	batchBranch: string,
 ): boolean {
@@ -407,6 +410,8 @@ interface PlanSurface {
 	recovery_children: BatchPlanChild[];
 	risk_by_task: Record<string, string>;
 	excluded: Array<{ task_id: string; slice_id: string; reason: string }>;
+	parallel_groups: string[][];
+	scope_conflicts: Array<{ task_id: string; overlaps_with: string[] }>;
 }
 
 type PlanSurfaceOutcome =
@@ -422,7 +427,7 @@ async function projectPlanSurface(input: {
 	root: string;
 	initiative_slug: string;
 	is_resuming: boolean;
-	existing_batch: BatchRunStateRecord | null;
+	existing_batch: AnyBatchRunStateRecord | null;
 	now: string;
 	readInitiative?: InitiativeObservationReader;
 }): Promise<PlanSurfaceOutcome> {
@@ -430,6 +435,8 @@ async function projectPlanSurface(input: {
 	let recoveryChildren: BatchPlanChild[] = [];
 	let planDigest: string;
 	let excluded: Array<{ task_id: string; slice_id: string; reason: string }> = [];
+	let parallelGroups: string[][] = [];
+	let scopeConflicts: Array<{ task_id: string; overlaps_with: string[] }> = [];
 	const riskByTask = new Map<string, string>();
 	// Only an active run supplies children and budget; a terminal record supplies
 	// branch provenance, never the plan or authorization of the next run.
@@ -469,7 +476,8 @@ async function projectPlanSurface(input: {
 				// Keep the risk captured by the authoritative read above; a stale
 				// reconstructed path must never fabricate a risk later.
 				riskByTask.set(c.task_id, read.intent?.risk ?? "material");
-				const isDone = c.state === "committed" || c.state === "settled";
+				// A lane child integrated or released is already on the batch branch.
+				const isDone = ["committed", "settled", "integrated", "released"].includes(c.state);
 				return {
 					task_id: c.task_id,
 					slice_id: c.slice_id,
@@ -508,6 +516,8 @@ async function projectPlanSurface(input: {
 			return { ok: false, key: "empty_enrollable_set", detail: "" };
 
 		budget = plan.budget;
+		parallelGroups = plan.parallel_groups;
+		scopeConflicts = plan.scope_conflicts;
 		const enrollableChildById = new Map(plan.enrollable.map((c) => [c.task_id, c]));
 		recoveryChildren = plan.children
 			.filter((c) => c.status === "enrollable")
@@ -544,6 +554,8 @@ async function projectPlanSurface(input: {
 				[...riskByTask.entries()].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)),
 			),
 			excluded,
+			parallel_groups: parallelGroups,
+			scope_conflicts: scopeConflicts,
 		},
 	};
 }
@@ -560,8 +572,8 @@ export async function projectBatchPreflight(
 	if (found?.corrupt)
 		return reject("batch_state_unreadable", found.path);
 	// Settled records retain branch provenance; only active records are resumed.
-	const activeRecord: BatchRunStateRecord | null = found ? found.record : null;
-	const existingBatch: BatchRunStateRecord | null = activeRecord ?? findSettledBatchRecord(root, initiativeSlug);
+	const activeRecord: AnyBatchRunStateRecord | null = found ? found.record : null;
+	const existingBatch: AnyBatchRunStateRecord | null = activeRecord ?? findSettledBatchRecord(root, initiativeSlug);
 	const isResuming = activeRecord !== null;
 	const batchBranch = `imm/${initiativeSlug}`;
 
@@ -645,7 +657,7 @@ export async function projectBatchPreflight(
 	if (!planSurface.ok)
 		return reject(planSurface.key, planSurface.detail);
 	let reconfirmation: ReconfirmationSnapshot | undefined;
-	if (activeRecord && activeRecord.plan_digest !== planSurface.surface.plan_digest) {
+	if (activeRecord && !isLaneBatchRecord(activeRecord) && activeRecord.plan_digest !== planSurface.surface.plan_digest) {
 		try { reconfirmation = await captureBatchReconfirmation(root, activeRecord, planSurface.surface.recovery_children); }
 		catch { return reject("plan_projection_failed", "batch plan reconfirmation is not eligible"); }
 	}
@@ -661,6 +673,8 @@ export async function projectBatchPreflight(
 		recovery_children: planSurface.surface.recovery_children,
 		risk_by_task: planSurface.surface.risk_by_task,
 		excluded: planSurface.surface.excluded,
+		parallel_groups: planSurface.surface.parallel_groups,
+		scope_conflicts: planSurface.surface.scope_conflicts,
 	};
 	if (reconfirmation) Object.defineProperty(projection, "reconfirmation", { value: reconfirmation });
 	return { ok: true, projection };
@@ -683,8 +697,8 @@ export interface BatchDriftProjection {
 export async function projectBatchDrift(options: BatchPreflightOptions): Promise<BatchDriftProjection> {
 	const { root, initiative_slug: initiativeSlug, readInitiative } = options;
 	const found = findExistingActiveBatch(root, initiativeSlug);
-	const activeRecord: BatchRunStateRecord | null = found && !found.corrupt ? found.record : null;
-	const existingBatch: BatchRunStateRecord | null = activeRecord ?? findSettledBatchRecord(root, initiativeSlug);
+	const activeRecord: AnyBatchRunStateRecord | null = found && !found.corrupt ? found.record : null;
+	const existingBatch: AnyBatchRunStateRecord | null = activeRecord ?? findSettledBatchRecord(root, initiativeSlug);
 	const isResuming = activeRecord !== null;
 	const batchBranch = `imm/${initiativeSlug}`;
 	const activeClaimTaskId = readActiveClaimTaskId(root);
@@ -727,6 +741,9 @@ export interface BatchConfirmationFacts {
 	reuse_blockers: string[];
 	children: Array<{ task_id: string; slice_id: string; risk: string; status: BatchPlanChildStatus }>;
 	excluded: Array<{ task_id: string; slice_id: string; reason: string }>;
+	/** Start waves and the children that serialize because their scopes overlap. */
+	parallel_groups: string[][];
+	scope_conflicts: Array<{ task_id: string; overlaps_with: string[] }>;
 }
 
 /**
@@ -790,7 +807,7 @@ export async function authorizeBatch<HostRejection>(
 	// ADR-0005 Decision 1: a resume of an intact, still-binding authorization
 	// reuses it instead of opening a second native gate. Anything that no longer
 	// binds falls through to the gate below, which names the reason.
-	const ownsUnpersistedHead = isResuming && existingBatch !== null && existingBatch.plan_digest === planDigest &&
+	const ownsUnpersistedHead = isResuming && existingBatch !== null && !isLaneBatchRecord(existingBatch) && existingBatch.plan_digest === planDigest &&
 		expectedBatchHead(existingBatch) !== baseHead && ownUnpersistedBatchHead(root, existingBatch, baseHead);
 	// A fast-forward on the batch branch is the user's own work: the runner adopts
 	// it, so it neither blocks reuse nor counts as moved provenance.
@@ -830,6 +847,8 @@ export async function authorizeBatch<HostRejection>(
 			status: child.status,
 		})),
 		excluded: projection.excluded,
+		parallel_groups: projection.parallel_groups,
+		scope_conflicts: projection.scope_conflicts,
 	};
 
 	let requestId: string | null = null;
@@ -856,7 +875,7 @@ export async function authorizeBatch<HostRejection>(
 	if (drift.plan_digest !== planDigest)
 		return { outcome: "rejected", rejection: batchRejection("plan_changed", drift.plan_digest) };
 	if (drift.base_head === null) return { outcome: "rejected", rejection: batchRejection("repository_became_unreadable") };
-	if (drift.base_head !== baseHead || (ownsUnpersistedHead && !ownUnpersistedBatchHead(root, existingBatch!, baseHead)))
+	if (drift.base_head !== baseHead || (ownsUnpersistedHead && !ownUnpersistedBatchHead(root, existingBatch as BatchRunStateRecord, baseHead)))
 		return { outcome: "rejected", rejection: batchRejection("head_moved", drift.base_head) };
 
 	// The drift projection's own claim read happened before its plan read; this

package/plugins/immune-brain/runtime/unattended/batch_runner.ts

@@ -28,11 +28,14 @@ import {
 	type BatchRunnerGitPort,
 } from "./batch_git";
 import { classifyBatchLineage, expectedBatchHead } from "./batch_preflight";
+import { laneRejectionReport, runLaneBatch, type LaneOffer } from "./batch_lanes";
 import {
 	type BatchRunStateRecord,
 	type BatchChildRun,
 	type BatchRunReport,
+	isLaneBatchRecord,
 	isTerminalBatchState,
+	readAnyBatchRunState,
 	prepareBatchRunState,
 	readBatchRunState,
 	writeBatchRunState,
@@ -101,6 +104,10 @@ export interface StartBatchInput {
 	now: string;
 	kernel: BatchRunnerKernelPort;
 	git?: BatchRunnerGitPort;
+	/** Present only in lane mode: how many children may run at once. */
+	max_parallel?: number;
+	/** Present only in lane mode: Lanes someone else created, offered to the batch. */
+	lane_offers?: LaneOffer[];
 }
 
 /** One git seam: the injected BatchRunnerGitPort, or the default adapter over
@@ -435,11 +442,17 @@ export async function startBatch(input: StartBatchInput): Promise<BatchRunReport
 function rejectionReport(input: StartBatchInput, reason: string): BatchRunReport {
 	const persisted = (() => {
 		try {
-			return readBatchRunState(input.root, input.batch_id);
+			return readAnyBatchRunState(input.root, input.batch_id);
 		} catch {
 			return null;
 		}
 	})();
+	if (persisted !== null && isLaneBatchRecord(persisted))
+		return laneRejectionReport(
+			persisted,
+			reason,
+			"settle the reported kernel store condition and retry in the current Host",
+		) as unknown as BatchRunReport;
 	return reportFor(
 		{
 			...(persisted ?? prepareBatchRunState({ ...input, children: [], now: input.now })),
@@ -451,6 +464,12 @@ function rejectionReport(input: StartBatchInput, reason: string): BatchRunReport
 }
 
 async function startBatchLocked(input: StartBatchInput): Promise<BatchRunReport> {
+	// Lane mode is selected by `max_parallel` or by a recorded v2 batch; a batch
+	// given neither keeps the serial path below unchanged.
+	const recorded = readAnyBatchRunState(input.root, input.batch_id);
+	if (input.max_parallel !== undefined || (recorded !== null && isLaneBatchRecord(recorded)))
+		return (await runLaneBatch(input, recorded)) as unknown as BatchRunReport;
+
 	// Validation failure before the first enrollment: zero writes, rejected.
 	// reportFor only builds the report object; finalize would persist it and
 	// the spec forbids any write on a pre-enrollment rejection.

package/plugins/immune-brain/runtime/unattended/batch_schedule.ts

@@ -0,0 +1,162 @@
+// Pure scheduling for unattended batches. No I/O, no persisted state, no Host
+// concept: given child states, dependency edges, scope hints and a parallelism
+// limit it answers which children may start now, and which children of a plan
+// serialize because their scopes cannot be proved disjoint.
+import type { BatchPlanParallelGroups, BatchPlanScopeConflict } from "./types";
+
+/**
+ * Child states the scheduler understands. The serial record (v1) uses
+ * `committed`; the lane record names the same milestone `integrated`/`released`
+ * and adds the in-flight lane states. Listing both keeps this function usable
+ * for either record without a persisted-state change.
+ */
+export type ScheduleChildState =
+	| "pending"
+	| "lane_admitted"
+	| "enrolled"
+	| "settled"
+	| "lane_committed"
+	| "committed"
+	| "integrated"
+	| "released"
+	| "needs_human"
+	| "skipped_blocked";
+
+const IN_FLIGHT_STATES: ReadonlySet<ScheduleChildState> = new Set([
+	"lane_admitted",
+	"enrolled",
+	"settled",
+	"lane_committed",
+]);
+
+const DONE_STATES: ReadonlySet<ScheduleChildState> = new Set(["committed", "integrated", "released"]);
+
+export interface ScheduleChild {
+	task_id: string;
+	state: ScheduleChildState;
+	blocked_by: string[];
+	scope_hint: string[];
+}
+
+const WILDCARD = /[*?[\]{}!]/;
+
+/**
+ * Reduce one scope entry to the directory prefix it is certain to live under.
+ * A literal path keeps all its segments. A pattern keeps only the whole
+ * segments before its first wildcard: `src/foo*` could match `src/foobar/x`, so
+ * the partial segment `foo` is not a safe prefix. An empty result means the
+ * entry can match anywhere. Anything that is not a plain repository-relative
+ * path is also treated as matching anywhere, because disjointness is only ever
+ * claimed for entries that can be proved.
+ */
+function scopePrefix(entry: string): string[] {
+	if (typeof entry !== "string") return [];
+	let value = entry.trim().toLowerCase();
+	while (value.startsWith("./")) value = value.slice(2);
+	if (!value || value.startsWith("/") || value.includes("\\")) return [];
+	const wildcard = value.search(WILDCARD);
+	const literal = wildcard === -1 ? value : value.slice(0, value.lastIndexOf("/", wildcard) + 1);
+	const segments = literal.split("/").filter((segment) => segment.length > 0);
+	if (segments.some((segment) => segment === "." || segment === "..")) return [];
+	return segments;
+}
+
+function prefixOverlaps(left: string[], right: string[]): boolean {
+	if (!left.length || !right.length) return true;
+	const shared = Math.min(left.length, right.length);
+	for (let index = 0; index < shared; index += 1) if (left[index] !== right[index]) return false;
+	return true;
+}
+
+/**
+ * Two scope lists overlap unless every pair of entries is provably disjoint:
+ * neither entry's directory prefix equals or contains the other. Identical,
+ * nested, and wildcard scopes therefore overlap; an empty list proves nothing
+ * about the child and overlaps everything.
+ */
+export function scopesOverlap(left: readonly string[], right: readonly string[]): boolean {
+	if (!left.length || !right.length) return true;
+	const rightPrefixes = right.map(scopePrefix);
+	return left.some((entry) => {
+		const prefix = scopePrefix(entry);
+		return rightPrefixes.some((other) => prefixOverlaps(prefix, other));
+	});
+}
+
+function positiveLimit(maxParallel: number): number {
+	if (maxParallel === Number.POSITIVE_INFINITY) return maxParallel;
+	if (!Number.isSafeInteger(maxParallel) || maxParallel <= 0)
+		throw new Error("max_parallel must be a positive safe integer");
+	return maxParallel;
+}
+
+/**
+ * The children that may start now, in record order. A pending child starts when
+ * every dependency is done, its scope is disjoint from every in-flight child and
+ * from every child already chosen in this call, and the in-flight count stays
+ * below `maxParallel`. With `maxParallel` 1 and nothing in flight this is
+ * exactly the serial runner's choice: the first pending child whose
+ * dependencies are done.
+ */
+export function startableChildren(children: readonly ScheduleChild[], maxParallel: number): string[] {
+	const limit = positiveLimit(maxParallel);
+	const done = new Set(children.filter((child) => DONE_STATES.has(child.state)).map((child) => child.task_id));
+	const occupied = children.filter((child) => IN_FLIGHT_STATES.has(child.state));
+	const startable: string[] = [];
+	for (const child of children) {
+		if (occupied.length >= limit) break;
+		if (child.state !== "pending") continue;
+		if (!child.blocked_by.every((id) => done.has(id))) continue;
+		if (occupied.some((other) => scopesOverlap(child.scope_hint, other.scope_hint))) continue;
+		startable.push(child.task_id);
+		occupied.push(child);
+	}
+	return startable;
+}
+
+export interface PlanScheduleChild {
+	task_id: string;
+	blocked_by: string[];
+	scope_hint: string[];
+}
+
+/**
+ * Project a plan's enrollable children into start waves. Each wave is the
+ * largest set that is ready (every dependency in an earlier wave) and pairwise
+ * scope-disjoint, chosen in plan order. A child that was ready but left out of
+ * a wave because its scope overlaps a member of that wave is reported once with
+ * every child it overlapped, so a confirmation can say why it serializes.
+ */
+export function projectParallelGroups(children: readonly PlanScheduleChild[]): {
+	parallel_groups: BatchPlanParallelGroups;
+	scope_conflicts: BatchPlanScopeConflict[];
+} {
+	const remaining = [...children];
+	const placed = new Set<string>();
+	const groups: BatchPlanParallelGroups = [];
+	const conflicts = new Map<string, Set<string>>();
+	while (remaining.length) {
+		const ready = remaining.filter((child) => child.blocked_by.every((id) => placed.has(id)));
+		if (!ready.length) throw new Error("Initiative Task dependencies must form an acyclic graph");
+		const wave: PlanScheduleChild[] = [];
+		for (const child of ready) {
+			const overlapped = wave.filter((member) => scopesOverlap(child.scope_hint, member.scope_hint));
+			if (overlapped.length) {
+				const known = conflicts.get(child.task_id) ?? new Set<string>();
+				for (const member of overlapped) known.add(member.task_id);
+				conflicts.set(child.task_id, known);
+				continue;
+			}
+			wave.push(child);
+		}
+		groups.push(wave.map((child) => child.task_id));
+		for (const child of wave) {
+			placed.add(child.task_id);
+			remaining.splice(remaining.indexOf(child), 1);
+		}
+	}
+	const scopeConflicts = children
+		.filter((child) => conflicts.has(child.task_id))
+		.map((child) => ({ task_id: child.task_id, overlaps_with: [...conflicts.get(child.task_id)!].sort() }));
+	return { parallel_groups: groups, scope_conflicts: scopeConflicts };
+}