immune-brain 4.6.0 → 5.1.0

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

@@ -24,18 +24,18 @@ export function batchQaFailureFacts(record: Pick<TaskRecord, "history"> & { find
 import type { BatchPlanChild } from "./types";
 import { ownUnpersistedBatchHead, takeReconfirmation } from "./batch_reconfirmation";
 import {
+	createDefaultBatchGitPort,
 	type BatchRunnerGitPort,
-	type BatchGitPreflightResult,
-	runBatchGitPreflight,
-	commitBatchChild,
-	lookupBatchCommit,
 } 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,
@@ -43,7 +43,9 @@ import {
 	writeBatchRunReport,
 } from "./batch_state";
 
-/** Kernel-facing ports the driver needs. Host adapters supply these. */
+/** Kernel-facing ports the driver needs. Host adapters supply these. Git
+ * operations are not Kernel-port members: the runner drives them through
+ * BatchRunnerGitPort alone (D5 of docs/specs/deepen-authority-seams.spec.md). */
 export interface BatchRunnerKernelPort {
 	/** Enroll one child through the batch-derived capability. */
 	enrollTask(input: {
@@ -57,31 +59,6 @@ export interface BatchRunnerKernelPort {
 	}): Promise<{ record_revision: string }>;
 	/** Drive one enrolled child toward its own Kernel terminal settlement. */
 	advanceTask(root: string, taskId: string): Promise<BatchChildAdvanceResult>;
-	/** Scope-bound commit after Kernel reports a child done. */
-	commitChild?(
-		root: string,
-		taskId: string,
-		batchId: string,
-		head: string,
-		branch?: string,
-		intentPath?: string,
-	): Promise<{ commit: string }>;
-	/** review-3(5th round): read the already-created batch commit for a child,
-	 * or null when none exists. Lets crash recovery adopt an existing commit
-	 * instead of replaying the commitChild mutation. */
-	lookupBatchCommit?(
-		root: string,
-		taskId: string,
-		batchId: string,
-		expectedHead?: string,
-		branch?: string,
-	): Promise<{ commit: string } | null>;
-	/** Optional Git preflight check. */
-	gitPreflight?(input: {
-		root: string;
-		initiative_slug: string;
-		base_head: string;
-	}): Promise<BatchGitPreflightResult> | BatchGitPreflightResult;
 	/** review-2(5th round): read-only claim projection for enrollment
 	 * reconciliation after an interruption between enrollTask and its state
 	 * persistence. Uses the real AssuranceProjectionResult contract; batch
@@ -127,6 +104,16 @@ 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
+ * the real repository operations when the Host supplies none. */
+function batchGitPortOf(input: StartBatchInput): BatchRunnerGitPort {
+	return input.git ?? createDefaultBatchGitPort();
 }
 
 export type { BatchRunReport } from "./batch_state";
@@ -340,16 +327,10 @@ async function validatePersistedRun(input: StartBatchInput, record: BatchRunStat
 			if (child.commit !== null) throw new Error("uncommitted batch child has a commit");
 			continue;
 		}
-		const evidence = input.git?.lookupBatchCommit
-			? await input.git.lookupBatchCommit(input.root, child.task_id, record.batch_id, undefined, record.branch)
-			: input.kernel.lookupBatchCommit
-				? await input.kernel.lookupBatchCommit(input.root, child.task_id, record.batch_id, undefined, record.branch)
-				: await lookupBatchCommit({
-					root: input.root,
-					taskId: child.task_id,
-					batchId: record.batch_id,
-					branch: record.branch,
-				});
+		const git = batchGitPortOf(input);
+		const evidence = await git.lookupBatchCommit(
+			input.root, child.task_id, record.batch_id, undefined, record.branch,
+		);
 		if (!evidence || evidence.commit !== child.commit) {
 			// Distinguish an unreachable recorded commit (external HEAD regression)
 			// from a fabricated record: reachability is only checkable in a real repo.
@@ -461,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 })),
@@ -477,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.
@@ -620,23 +613,11 @@ async function startBatchLocked(input: StartBatchInput): Promise<BatchRunReport>
 		}
 
 		// Mandatory batch branch preflight: run before any child is enrolled.
-		const preflightResult = input.git?.preflight
-			? await input.git.preflight({
-				root: input.root,
-				initiative_slug: input.initiative_slug,
-				base_head: input.base_head,
-			})
-			: input.kernel.gitPreflight
-				? await input.kernel.gitPreflight({
-					root: input.root,
-					initiative_slug: input.initiative_slug,
-					base_head: input.base_head,
-				})
-				: runBatchGitPreflight({
-					root: input.root,
-					initiative_slug: input.initiative_slug,
-					base_head: input.base_head,
-				});
+		const preflightResult = await batchGitPortOf(input).preflight({
+			root: input.root,
+			initiative_slug: input.initiative_slug,
+			base_head: input.base_head,
+		});
 
 		if (!preflightResult.ok) {
 			const rejected = prepareBatchRunState({ ...input, now: input.now });
@@ -1027,23 +1008,9 @@ async function driveInterruptedChild(
 			// review-1(6th round): a lookup failure must fail closed, not fall
 			// through to commitChild, which could replay an existing commit.
 			try {
-				existing = input.git?.lookupBatchCommit
-					? await input.git.lookupBatchCommit(input.root, child.task_id, input.batch_id, head, record.branch)
-					: input.kernel.lookupBatchCommit
-						? await input.kernel.lookupBatchCommit(
-							input.root,
-							child.task_id,
-							input.batch_id,
-							head,
-							record.branch,
-						)
-						: await lookupBatchCommit({
-							root: input.root,
-							taskId: child.task_id,
-							batchId: input.batch_id,
-							expectedHead: head,
-							branch: record.branch,
-						});
+				existing = await batchGitPortOf(input).lookupBatchCommit(
+					input.root, child.task_id, input.batch_id, head, record.branch,
+				);
 			} catch (error: unknown) {
 				const message =
 					error instanceof Error ? error.message : String(error);
@@ -1075,22 +1042,10 @@ async function driveInterruptedChild(
 			}
 			const planChild = input.children.find((c) => c.task_id === child.task_id);
 			const intentPath = planChild?.intent_path ?? undefined;
-			const doCommit = async () => {
-				if (input.git?.commitChild) {
-					return input.git.commitChild(input.root, child.task_id, input.batch_id, head, record.branch, intentPath);
-				}
-				if (input.kernel.commitChild) {
-					return input.kernel.commitChild(input.root, child.task_id, input.batch_id, head, record.branch, intentPath);
-				}
-				return commitBatchChild({
-					root: input.root,
-					taskId: child.task_id,
-					batchId: input.batch_id,
-					expectedHead: head,
-					branch: record.branch,
-					intentPath,
-				});
-			};
+			const doCommit = async () =>
+				batchGitPortOf(input).commitChild(
+					input.root, child.task_id, input.batch_id, head, record.branch, intentPath,
+				);
 			if (existing && !record.commits.length && existsSync(join(input.root, ".git")) && !ownUnpersistedBatchHead(input.root, record, existing.commit))
 				throw new Error("first unpersisted batch commit provenance is invalid");
 			const adopted =

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 };
+}