immune-brain 5.0.0 → 5.1.0

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

@@ -64,6 +64,76 @@ export interface BatchRunStateRecord {
 	updated_at: string;
 }
 
+/**
+ * Lane-mode child states. `integrated` plays the role `committed` plays in the
+ * serial record: it is what unblocks dependents. `released` is recorded by the
+ * lane steward once an integrated Lane is gone.
+ */
+export type BatchLaneChildRunState =
+	| "pending"
+	| "lane_admitted"
+	| "enrolled"
+	| "settled"
+	| "lane_committed"
+	| "integrated"
+	| "released"
+	| "needs_human"
+	| "skipped_blocked";
+
+export interface BatchLaneBinding {
+	/** Absolute, real path of the admitted Lane worktree. */
+	path: string;
+	branch: string;
+	/** The batch head the Lane was provisioned at and the child was enrolled on. */
+	base_head: string;
+	/** Commit created in the Lane after the Lane Kernel settled the child. */
+	lane_commit: string | null;
+}
+
+export interface BatchLaneChildRun {
+	task_id: string;
+	slice_id: string;
+	blocked_by: string[];
+	state: BatchLaneChildRunState;
+	reason: string | null;
+	/** Commit on the batch branch once this child is integrated. */
+	commit: string | null;
+	lane: BatchLaneBinding | null;
+	qa_failures: number;
+}
+
+/**
+ * Lane-mode batch state. A serial batch never writes this contract; a v1
+ * record is never upgraded. Every v1-gated reader skips it by contract.
+ */
+export interface BatchLaneRunStateRecord {
+	contract: "assurance_kernel/batch_run_state/v2";
+	batch_id: string;
+	initiative_slug: string;
+	plan_digest: string;
+	base_head: string;
+	branch?: string;
+	confirmation_time: string;
+	budget: {
+		max_children: number;
+		qa_failure_limit: number;
+	};
+	max_parallel: number;
+	batch_state: BatchRunState;
+	children: BatchLaneChildRun[];
+	/** Batch-branch commits produced by integration, in integration order. */
+	commits: string[];
+	adopted_heads?: Array<{ from: string; to: string }>;
+	created_at: string;
+	updated_at: string;
+}
+
+export type AnyBatchRunStateRecord = BatchRunStateRecord | BatchLaneRunStateRecord;
+
+export function isLaneBatchRecord(record: AnyBatchRunStateRecord): record is BatchLaneRunStateRecord {
+	return record.contract === "assurance_kernel/batch_run_state/v2";
+}
+
 const BATCH_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 
 const CHILD_RUN_STATES: ReadonlySet<string> = new Set([
@@ -108,13 +178,13 @@ function statePath(batchId: string): string {
  * `authorization_expires_at` and `budget.deadline_at`. They are ignored on read
  * and never written back.
  */
-function withoutRetiredClock(record: BatchRunStateRecord): BatchRunStateRecord {
-	const { authorization_expires_at: _expiry, ...rest } = record as BatchRunStateRecord & { authorization_expires_at?: unknown };
-	const { deadline_at: _deadline, ...budget } = rest.budget as BatchRunStateRecord["budget"] & { deadline_at?: unknown };
-	return { ...rest, budget };
+function withoutRetiredClock<T extends AnyBatchRunStateRecord>(record: T): T {
+	const { authorization_expires_at: _expiry, ...rest } = record as T & { authorization_expires_at?: unknown };
+	const { deadline_at: _deadline, ...budget } = rest.budget as T["budget"] & { deadline_at?: unknown };
+	return { ...rest, budget } as unknown as T;
 }
 
-function canonicalBytes(record: BatchRunStateRecord): string {
+function canonicalBytes(record: AnyBatchRunStateRecord): string {
 	return `${JSON.stringify(withoutRetiredClock(record), null, 2)}\n`;
 }
 
@@ -348,6 +418,240 @@ export function writeBatchRunState(
 	});
 }
 
+
+const LANE_CHILD_STATES: ReadonlySet<string> = new Set([
+	"pending",
+	"lane_admitted",
+	"enrolled",
+	"settled",
+	"lane_committed",
+	"integrated",
+	"released",
+	"needs_human",
+	"skipped_blocked",
+]);
+
+/** Lane-mode states whose child must carry a Lane binding. */
+const LANE_BOUND_STATES: ReadonlySet<string> = new Set([
+	"lane_admitted",
+	"enrolled",
+	"settled",
+	"lane_committed",
+	"integrated",
+	"released",
+]);
+
+function validateLaneRecordShape(value: unknown, batchId: string): asserts value is BatchLaneRunStateRecord {
+	if (typeof value !== "object" || value === null)
+		throw new Error(`batch run state ${batchId} is not an object`);
+	const record = value as Record<string, unknown>;
+	if (record.contract !== "assurance_kernel/batch_run_state/v2")
+		throw new Error(`batch run state ${batchId} has an unknown contract`);
+	if (record.batch_id !== batchId)
+		throw new Error(`batch run state ${batchId} carries batch_id ${String(record.batch_id)}`);
+	if (typeof record.plan_digest !== "string" || !record.plan_digest)
+		throw new Error(`batch run state ${batchId} has an invalid plan_digest`);
+	if (typeof record.base_head !== "string" || !record.base_head)
+		throw new Error(`batch run state ${batchId} has an invalid base_head`);
+	if (record.branch !== undefined && (typeof record.branch !== "string" || !record.branch))
+		throw new Error(`batch run state ${batchId} has an invalid branch`);
+	if (!isCanonicalTimestamp(record.confirmation_time))
+		throw new Error(`batch run state ${batchId} has an invalid confirmation_time`);
+	if (!isCanonicalTimestamp(record.created_at) || !isCanonicalTimestamp(record.updated_at))
+		throw new Error(`batch run state ${batchId} has invalid state timestamps`);
+	if (!Array.isArray(record.children) || record.children.length === 0)
+		throw new Error(`batch run state ${batchId} has no children`);
+	if (!BATCH_RUN_STATES.has(String(record.batch_state)))
+		throw new Error(`batch run state ${batchId} has an invalid batch_state`);
+	if (typeof record.max_parallel !== "number" || !Number.isSafeInteger(record.max_parallel) || record.max_parallel <= 0)
+		throw new Error(`batch run state ${batchId} has an invalid max_parallel`);
+	const budget = record.budget as Record<string, unknown>;
+	if (
+		typeof record.budget !== "object" ||
+		record.budget === null ||
+		typeof budget.max_children !== "number" ||
+		!Number.isInteger(budget.max_children) ||
+		budget.max_children <= 0 ||
+		typeof budget.qa_failure_limit !== "number" ||
+		!Number.isInteger(budget.qa_failure_limit) ||
+		budget.qa_failure_limit <= 0
+	)
+		throw new Error(`batch run state ${batchId} has an invalid budget`);
+	if (!Array.isArray(record.commits) || record.commits.some((c) => typeof c !== "string"))
+		throw new Error(`batch run state ${batchId} has an invalid commits list`);
+	if (
+		record.adopted_heads !== undefined &&
+		(!Array.isArray(record.adopted_heads) ||
+			record.adopted_heads.some(
+				(a: unknown) =>
+					typeof a !== "object" ||
+					a === null ||
+					typeof (a as { from?: unknown }).from !== "string" ||
+					!(a as { from: string }).from ||
+					typeof (a as { to?: unknown }).to !== "string" ||
+					!(a as { to: string }).to,
+			))
+	)
+		throw new Error(`batch run state ${batchId} has an invalid adopted_heads list`);
+	const seenTaskIds = new Set<string>();
+	for (const child of record.children) {
+		if (
+			typeof child !== "object" ||
+			child === null ||
+			typeof child.task_id !== "string" ||
+			!child.task_id ||
+			typeof child.slice_id !== "string" ||
+			!child.slice_id
+		)
+			throw new Error(`batch run state ${batchId} has an invalid child entry`);
+		if (!LANE_CHILD_STATES.has(String(child.state)))
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid state`);
+		if (!Array.isArray(child.blocked_by) || child.blocked_by.some((b: unknown) => typeof b !== "string"))
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid blocked_by`);
+		if (
+			(child.reason !== null && typeof child.reason !== "string") ||
+			(child.commit !== null && typeof child.commit !== "string")
+		)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has invalid terminal fields`);
+		if (typeof child.qa_failures !== "number" || !Number.isInteger(child.qa_failures) || child.qa_failures < 0)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid qa_failures`);
+		const lane = child.lane as BatchLaneBinding | null | undefined;
+		if (lane !== null) {
+			if (
+				typeof lane !== "object" ||
+				typeof lane.path !== "string" ||
+				!lane.path ||
+				typeof lane.branch !== "string" ||
+				!lane.branch ||
+				typeof lane.base_head !== "string" ||
+				!lane.base_head ||
+				(lane.lane_commit !== null && typeof lane.lane_commit !== "string")
+			)
+				throw new Error(`batch run state ${batchId} child ${child.task_id} has an invalid lane`);
+		}
+		if (LANE_BOUND_STATES.has(child.state) && lane === null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} is ${child.state} without a lane`);
+		if ((child.state === "pending" || child.state === "skipped_blocked") && lane !== null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} is ${child.state} but holds a lane`);
+		const integrated = child.state === "integrated" || child.state === "released";
+		if (integrated && child.commit === null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} is ${child.state} without a commit`);
+		if (!integrated && child.commit !== null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} has a commit but is not integrated`);
+		if (integrated && lane?.lane_commit === null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} is ${child.state} without a lane commit`);
+		if (child.state === "lane_committed" && lane?.lane_commit === null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} is lane_committed without a lane commit`);
+		if ((child.state === "needs_human" || child.state === "skipped_blocked") && child.reason === null)
+			throw new Error(`batch run state ${batchId} child ${child.task_id} needs a terminal reason`);
+		if (seenTaskIds.has(child.task_id))
+			throw new Error(`batch run state ${batchId} has a duplicate child ${child.task_id}`);
+		seenTaskIds.add(child.task_id);
+	}
+	for (const child of record.children) {
+		if (child.commit !== null && !record.commits.includes(child.commit))
+			throw new Error(`batch run state ${batchId} child ${child.task_id} commit is missing from commits`);
+	}
+	const inFlight = (child: { state: string }) =>
+		child.state === "lane_admitted" ||
+		child.state === "enrolled" ||
+		child.state === "settled" ||
+		child.state === "lane_committed";
+	if (
+		(record.batch_state === "budget_stopped" || record.batch_state === "failed" || record.batch_state === "rejected") &&
+		record.children.some(inFlight)
+	)
+		throw new Error(`batch run state ${batchId} is ${String(record.batch_state)} but a child is still mid-flight`);
+	if (
+		record.batch_state === "completed" &&
+		record.children.some((child) => child.state !== "integrated" && child.state !== "released")
+	)
+		throw new Error(`batch run state ${batchId} is completed but a child is not integrated`);
+}
+
+export function prepareBatchLaneRunState(input: {
+	batch_id: string;
+	initiative_slug: string;
+	children: BatchPlanChild[];
+	plan_digest: string;
+	base_head: string;
+	branch?: string;
+	confirmation_time: string;
+	budget: { max_children: number; qa_failure_limit: number };
+	max_parallel: number;
+	now: string;
+}): BatchLaneRunStateRecord {
+	validateBatchId(input.batch_id);
+	return {
+		contract: "assurance_kernel/batch_run_state/v2",
+		batch_id: input.batch_id,
+		initiative_slug: input.initiative_slug,
+		plan_digest: input.plan_digest,
+		base_head: input.base_head,
+		branch: input.branch ?? `imm/${input.initiative_slug}`,
+		confirmation_time: input.confirmation_time,
+		budget: input.budget,
+		max_parallel: input.max_parallel,
+		batch_state: "prepared",
+		children: input.children.map((child) => ({
+			task_id: child.task_id,
+			slice_id: child.slice_id,
+			blocked_by: [...child.blocked_by],
+			state: "pending",
+			reason: null,
+			commit: null,
+			lane: null,
+			qa_failures: 0,
+		})),
+		commits: [],
+		created_at: input.now,
+		updated_at: input.now,
+	};
+}
+
+/** Validate a captured v2 snapshot without reading or writing filesystem state. */
+export function parseBatchLaneRunState(raw: string, batchId: string): BatchLaneRunStateRecord {
+	validateBatchId(batchId);
+	const parsed: unknown = JSON.parse(raw);
+	validateLaneRecordShape(parsed, batchId);
+	return withoutRetiredClock(parsed);
+}
+
+/** Parse either record version by its contract; an unknown contract is refused. */
+export function parseAnyBatchRunState(raw: string, batchId: string): AnyBatchRunStateRecord {
+	validateBatchId(batchId);
+	const parsed: unknown = JSON.parse(raw);
+	if (typeof parsed === "object" && parsed !== null && (parsed as { contract?: unknown }).contract === "assurance_kernel/batch_run_state/v2")
+		return parseBatchLaneRunState(raw, batchId);
+	return parseBatchRunState(raw, batchId);
+}
+
+/** Read the persisted record of either version; null when the batch has none. */
+export function readAnyBatchRunState(root: string, batchId: string): AnyBatchRunStateRecord | null {
+	const path = statePath(batchId);
+	if (!existsSync(join(root, path))) return null;
+	return parseAnyBatchRunState(readSecureProjectFile(root, path), batchId);
+}
+
+export function readBatchLaneRunState(root: string, batchId: string): BatchLaneRunStateRecord | null {
+	const path = statePath(batchId);
+	if (!existsSync(join(root, path))) return null;
+	return parseBatchLaneRunState(readSecureProjectFile(root, path), batchId);
+}
+
+export function writeBatchLaneRunState(root: string, record: BatchLaneRunStateRecord): BatchLaneRunStateRecord {
+	const path = statePath(record.batch_id);
+	validateLaneRecordShape(record, record.batch_id);
+	return withKernelStoreLock(root, () => {
+		const existing = existsSync(join(root, path)) ? readSecureProjectFile(root, path) : null;
+		if (existing !== null && existing === canonicalBytes(record)) return record;
+		const stored = withoutRetiredClock({ ...record, updated_at: new Date().toISOString() });
+		ensureSecureDirectory(root, join(".imm", "state", "batches"));
+		writeFileAtomically(root, path, canonicalBytes(stored));
+		return stored;
+	});
+}
+
 export interface BatchRunReport {
 	contract: "assurance_kernel/batch_run_report/v1";
 	batch_id: string;
@@ -372,6 +676,50 @@ export interface BatchRunReport {
 	created_at: string;
 }
 
+/**
+ * The lane-mode report: the serial report's identity fields with lane children
+ * and `handoffs[]` in place of the single `handoff`. Handoffs are observations,
+ * never readiness.
+ */
+export interface BatchLaneRunReport {
+	contract: "assurance_kernel/batch_run_report/v1";
+	batch_id: string;
+	initiative_slug: string;
+	batch_state: BatchRunState;
+	max_parallel: number;
+	children: BatchLaneChildRun[];
+	commits: string[];
+	reason: string | null;
+	handoffs: BatchLaneHandoff[];
+	/** Offers refused at admission; a refused offer wrote nothing. */
+	lane_refusals?: Array<{ task_id: string; path: string; reason: string }>;
+	next_action: string;
+	created_at: string;
+}
+
+export type BatchLaneHandoff =
+	| {
+			role: "lane-steward";
+			action: "provision";
+			task_id: string;
+			lane_branch: string;
+			base_head: string;
+			executor_hosts: readonly string[];
+	  }
+	| { role: "lane-steward"; action: "release"; task_id: string; lane_branch: string }
+	| {
+			role: "executor";
+			task_id: string;
+			run_id: string | null;
+			record_revision: string;
+			next_obligation: import("../kernel/types").AssuranceObligation;
+			lane_branch: string;
+			/** Where the Executor Host must be rooted; an observation, never authority. */
+			lane_path: string;
+	  };
+
+type PersistableReport = Pick<BatchRunReport | BatchLaneRunReport, "contract" | "batch_id" | "batch_state">;
+
 function reportPath(batchId: string): string {
 	validateBatchId(batchId);
 	return join(".imm", "state", "batches", `${batchId}.report.json`);
@@ -380,7 +728,7 @@ function reportPath(batchId: string): string {
 /** Persist one current stop report per batch. Terminal reports are immutable;
  * a resumable needs_human report may be replaced by the later stop reached
  * after a fresh literal-user confirmation. */
-export function writeBatchRunReport(root: string, report: BatchRunReport): BatchRunReport {
+export function writeBatchRunReport<T extends PersistableReport>(root: string, report: T): T {
 	const relative = reportPath(report.batch_id);
 	return withKernelStoreLock(root, () => {
 		const path = join(root, relative);
@@ -392,7 +740,7 @@ export function writeBatchRunReport(root: string, report: BatchRunReport): Batch
 				(original as BatchRunReport).contract !== "assurance_kernel/batch_run_report/v1"
 			)
 				throw new Error(`batch run report ${report.batch_id} has an unknown contract`);
-			const prior = original as BatchRunReport;
+			const prior = original as T;
 			if (canonicalReportBytes(prior) === canonicalReportBytes(report)) return prior;
 			if (prior.batch_state !== "needs_human") return prior;
 		}
@@ -402,7 +750,7 @@ export function writeBatchRunReport(root: string, report: BatchRunReport): Batch
 	});
 }
 
-function canonicalReportBytes(report: BatchRunReport): string {
+function canonicalReportBytes(report: PersistableReport): string {
 	return `${JSON.stringify(report, null, 2)}\n`;
 }
 

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

@@ -1,4 +1,5 @@
 import type { GithubInitiativeObservation } from "../github_issue_tracker";
+import type { LocalInitiativeObservation } from "../local_initiative";
 
 export interface BatchPlanBudget {
 	max_children: number;
@@ -49,15 +50,30 @@ export interface BatchPlanChild {
 	intent_content_hash: string | null;
 }
 
+/** Start waves of enrollable children: each is ready and pairwise scope-disjoint. */
+export type BatchPlanParallelGroups = string[][];
+
+/**
+ * A ready child held out of a start wave because its scope cannot be proved
+ * disjoint from the listed children, so it serializes after them.
+ */
+export interface BatchPlanScopeConflict {
+	task_id: string;
+	overlaps_with: string[];
+}
+
 export interface BatchPlan {
 	contract: "assurance_kernel/batch_plan/v1";
 	initiative_slug: string;
 	confirmation_time: string;
-	tracker_observation: GithubInitiativeObservation;
+	tracker_observation: InitiativeObservation;
 	children: BatchPlanChild[];
 	enrollable: BatchPlanDigestChild[];
 	plan_digest: string;
 	budget: BatchPlanBudget;
+	/** Additive projection; not part of `plan_digest`. */
+	parallel_groups: BatchPlanParallelGroups;
+	scope_conflicts: BatchPlanScopeConflict[];
 }
 
 export interface ProjectBatchPlanInput {
@@ -65,7 +81,10 @@ export interface ProjectBatchPlanInput {
 	budget?: BatchPlanBudgetInput;
 }
 
+/** What either Initiative carrier yields: the Tasks, their Slices, and their dependencies. */
+export type InitiativeObservation = GithubInitiativeObservation | LocalInitiativeObservation;
+
 export type InitiativeObservationReader = (
 	root: string,
 	initiativeSlug: string,
-) => Promise<GithubInitiativeObservation>;
+) => Promise<InitiativeObservation>;

package/plugins/immune-brain/skills/imm-run/SKILL.md

@@ -25,6 +25,10 @@ or all references as an entry prerequisite.
 
 - common: [Shared Guards](../../dist/BASELINE.md#shared-guards), [Workflow Activation](../../dist/BASELINE.md#workflow-activation), [Host Confirmation Boundary](../../dist/BASELINE.md#host-confirmation-boundary), [Kernel Canary Routing and Authority](../../dist/imm-run.md#kernel-canary-routing-and-authority)
 - unattended batch run, or any question about whether `imm-run` starts one: [Unattended Batch Opt-In](../../dist/imm-run.md#unattended-batch-opt-in)
+- parallel batch (`max_parallel`, `lane_offers`, Lane admission or integration): [Parallel Batch Opt-In](../../dist/imm-run.md#parallel-batch-opt-in)
+- a lane-mode report carries an `executor` handoff, or a Lane's Executor Host session has ended: [Lane Executor Supervision](../../dist/imm-run.md#lane-executor-supervision)
+- that Parent runs inside Herdr (`HERDR_ENV=1`): [Herdr Lane Tabs](../../dist/imm-run.md#herdr-lane-tabs)
+- a lane-mode batch is about to start, to resolve the repository's parallelism, Executor Host, model and effort: [Lane Preferences](../../dist/imm-run.md#lane-preferences)
 - steady execution: [Verification and Local Recovery](../../dist/BASELINE.md#verification-and-local-recovery), [Execution Loop](../../dist/imm-run.md#execution-loop), [Observable Output](../../dist/imm-run.md#observable-output)
 - rework, scope expansion, breaking revision, user decision, stop, interruption or unknown state before any action: [Decisions and Recovery](../../dist/imm-run.md#decisions-and-recovery), [Failure Output](../../dist/imm-run.md#failure-output); re-read `status`, then the pending obligation. Rework submits the verdict before editing, and an uncertain interruption resumes from exact task/run authority facts rather than a summary.
 - review or post-settlement learning: [Review and Learning](../../dist/imm-run.md#review-and-learning)