@rulvar/core 1.198.0 → 1.200.0

package/dist/index.d.ts

@@ -9421,6 +9421,24 @@ interface OrchestrateOptions {
   */
   onUnsettledAtExit?: "cancel" | "drain";
   /**
+  * The parallel_agents admission policy (RV1908). 'fail-fast' (the
+  * default, the RV805 shape) admits in submission order and stops at
+  * the first refusal, tasks after it never attempted. 'try-all'
+  * attempts every task and reports every refusal, so one refused
+  * sibling no longer hides whether the rest would seat. 'all-or-none'
+  * projects the WHOLE batch against the live remainder first and
+  * refuses it typed with zero admissions when it cannot seat
+  * entirely; a non-budget failure mid-batch cancels the admitted
+  * siblings, best-effort atomicity over a machinery that cannot
+  * un-admit. Independent of the policy, a declared
+  * acceptance.minSpawnedChildren arms the roster pre-check: a batch
+  * large enough to seat the floor whose feasible count cannot reach
+  * it is refused before paying for the first child, the four-role
+  * benchmark's primary arm shape, where two workers were paid in
+  * full and the settle verdict was bound to reject them.
+  */
+  parallelAdmission?: "fail-fast" | "try-all" | "all-or-none";
+  /**
   * The opt in deterministic host validation of the finish result, with
   * bounded repair; see {@link FinishValidationSpec}.
   */
@@ -12973,6 +12991,15 @@ interface PreflightReport {
     * synthesis reserve, matching the runtime that then commits none.
     */
     synthesisReserveUsd: number;
+    /**
+    * The smallest run ceiling that seats the WHOLE declared wave
+    * (RV1907): every row's reserve plus the finalization and synthesis
+    * carve-outs. Children admit strictly below exact fill, so a viable
+    * ceiling must sit strictly ABOVE this figure; the four-role
+    * benchmark's $6.00 sat $0.98 below it and lost its third and
+    * fourth workers. Present whenever the wave has rows.
+    */
+    requiredMinimumCeilingUsd?: number;
     wave: PreflightAdmissionRow[];
     admitted: number;
     denied: number;
@@ -12985,7 +13012,18 @@ interface PreflightReport {
     * documented overshoot bound is one turn per in-flight agent; real
     * turns grow with the prompt, so this is the floor of that bound.
     */
-    overshootOneTurnFloorUsd?: number; /** Per-provider first-wave demand at the declared estimates. */
+    overshootOneTurnFloorUsd?: number;
+    /**
+    * The smallest in-flight exposure cap under which the declared wave
+    * can breathe (RV1907): the finalization and synthesis carve-outs
+    * plus the turn floors of the maxInFlight most expensive declared
+    * dispatches, the orchestrator's own turn among them. Below it the
+    * root's next turn is refused beside a full child wave, the
+    * recovery arm's exact death; the RV1902 wait recovers the run, but
+    * only a cap at or above this floor avoids the stall entirely.
+    * Absent when no declared turn prices.
+    */
+    requiredMinimumExposureUsd?: number; /** Per-provider first-wave demand at the declared estimates. */
     perProvider: Record<string, {
       inFlight: number;
       requestsPerWave: number;
@@ -13311,7 +13349,21 @@ declare function buildOrchestratorTools(runtime: OrchestratorRuntime, profileCar
   * opted-in run's toolset hash and re-key their resumes, so the new
   * tool re-keys only runs that opt into IT.
   */
-  settledResultsTool?: boolean;
+  settledResultsTool?: boolean; /** The parallel_agents admission policy (RV1908); default 'fail-fast'. */
+  parallelAdmission?: "fail-fast" | "try-all" | "all-or-none";
+  /**
+  * The batch projection seam (RV1908): the live remainder and the
+  * per-task dispatch projection the embedded gate itself uses, plus
+  * the run's admitted-children count and the declared acceptance
+  * roster floor. Runtime behavior only, never part of the tool
+  * schema or description, so toolset hashes stay byte identical.
+  */
+  batchGate?: {
+    rosterFloor?: number;
+    admittedChildren: () => number;
+    projectionUsd: (task: SpawnAgentParams) => number;
+    remainderUsd: () => number | undefined;
+  };
 }): ToolDef[];
 //#endregion
 //#region src/engine/events.d.ts

package/dist/index.js

@@ -19058,23 +19058,77 @@ function buildOrchestratorTools(runtime, profileCardText, options) {
 		parameters: PARALLEL_AGENTS_SCHEMA,
 		execute: async (input) => {
 			const tasks = input.tasks;
+			const policy = options?.parallelAdmission ?? "fail-fast";
+			const gate = options?.batchGate;
+			if (gate !== void 0) {
+				const remainder = gate.remainderUsd();
+				if (remainder !== void 0) {
+					let accumulated = 0;
+					let feasible = 0;
+					for (const task of tasks) {
+						const projection = gate.projectionUsd(task);
+						if (remainder < accumulated + projection) break;
+						accumulated += projection;
+						feasible += 1;
+					}
+					const admittedSoFar = gate.admittedChildren();
+					const floor = gate.rosterFloor;
+					if (floor !== void 0 && admittedSoFar + tasks.length >= floor && admittedSoFar + feasible < floor) return {
+						handles: [],
+						refused: {
+							index: feasible,
+							code: "roster_floor",
+							reason: `the batch can seat ${String(feasible)} of its ${String(tasks.length)} tasks under the live remainder, and the ${String(admittedSoFar)} already admitted cannot reach acceptance.minSpawnedChildren ${String(floor)}: refused before paying for a roster the settle verdict is bound to reject`
+						}
+					};
+					if (policy === "all-or-none" && feasible < tasks.length) return {
+						handles: [],
+						refused: {
+							index: feasible,
+							code: "batch_atomic",
+							reason: `all-or-none: the batch's ${String(tasks.length)} reserves do not fit the live remainder ${remainder.toFixed(4)} USD (${String(feasible)} would seat); nothing was admitted and nothing was paid`
+						}
+					};
+				}
+			}
 			const handles = [];
+			const refusals = [];
 			for (const [index, task] of tasks.entries()) {
 				let spawned;
 				try {
 					spawned = await runtime.spawn(task);
 				} catch (thrown) {
+					const failure = {
+						index,
+						...thrown instanceof RulvarError ? { code: thrown.code } : {},
+						reason: thrown instanceof Error ? thrown.message : String(thrown)
+					};
+					if (policy === "try-all") {
+						refusals.push(failure);
+						continue;
+					}
+					if (policy === "all-or-none" && handles.length > 0) {
+						for (const handle of handles) await runtime.cancel(handle, "rulvar:batch-atomic-rollback");
+						return {
+							handles: [],
+							refused: {
+								...failure,
+								reason: `all-or-none: task ${String(index)} failed after ${String(handles.length)} sibling(s) were admitted; the siblings were cancelled (${failure.reason})`
+							}
+						};
+					}
 					return {
 						handles,
-						refused: {
-							index,
-							...thrown instanceof RulvarError ? { code: thrown.code } : {},
-							reason: thrown instanceof Error ? thrown.message : String(thrown)
-						}
+						refused: failure
 					};
 				}
 				handles.push(spawned.handle);
 			}
+			if (refusals.length > 0) return {
+				handles,
+				refused: refusals[0],
+				refusals
+			};
 			return { handles };
 		}
 	});
@@ -20817,6 +20871,7 @@ function validateOrchestrateOptions(opts) {
 	if (opts.maxSpawns !== void 0) requireNonNegativeInteger(opts.maxSpawns, "orchestrate maxSpawns");
 	if (opts.renderBudgetChars !== void 0) requireNonNegativeInteger(opts.renderBudgetChars, "orchestrate renderBudgetChars");
 	if (opts.onUnsettledAtExit !== void 0 && opts.onUnsettledAtExit !== "cancel" && opts.onUnsettledAtExit !== "drain") throw new ConfigError(`orchestrate onUnsettledAtExit must be 'cancel' or 'drain'; got ${String(opts.onUnsettledAtExit)}`);
+	if (opts.parallelAdmission !== void 0 && opts.parallelAdmission !== "fail-fast" && opts.parallelAdmission !== "try-all" && opts.parallelAdmission !== "all-or-none") throw new ConfigError(`orchestrate parallelAdmission must be 'fail-fast', 'try-all' or 'all-or-none'; got ${String(opts.parallelAdmission)}`);
 	if (opts.acceptance !== void 0) {
 		const policy = opts.acceptance.childPolicy;
 		const minSuccessful = typeof policy === "object" && policy !== null && !Array.isArray(policy) ? policy.minSuccessful : void 0;
@@ -22036,7 +22091,20 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const tools = [...buildOrchestratorTools(orchestratorRuntime, fullCardText, {
 			childResultTools: opts?.exposeChildResultTools === true,
 			settledResultsTool: opts?.exposeSettledResultsTool === true,
-			sectionalFinish: coordSectionalFinish
+			sectionalFinish: coordSectionalFinish,
+			...opts?.parallelAdmission === void 0 ? {} : { parallelAdmission: opts.parallelAdmission },
+			batchGate: {
+				...(opts?.acceptance)?.minSpawnedChildren === void 0 ? {} : { rosterFloor: (opts?.acceptance)?.minSpawnedChildren },
+				admittedChildren: () => admittedSpawnCount,
+				projectionUsd: (task) => {
+					const profile = internals.defaults.profiles?.[task.agentType];
+					return admission.projectedDispatchReserveUsd({
+						...profile?.estCost === void 0 ? {} : { estCostUsd: profile.estCost },
+						...task.budgetUsd === void 0 ? {} : { budgetUsd: task.budgetUsd }
+					});
+				},
+				remainderUsd: () => internals.budget.remainderOf(callingState.budgetScope ?? "run")
+			}
 		}), ...extension?.tools(io) ?? []];
 		/**
 		* The RV-204 finish validation hook, installed on the terminal tool
@@ -24550,6 +24618,7 @@ function preflightEstimate(input) {
 	}
 	const admitted = wave.filter((row) => row.admitted).length;
 	const denied = wave.length - admitted;
+	const requiredMinimumCeilingUsd = wave.length === 0 ? void 0 : wave.reduce((sum, row) => sum + row.reserveUsd, 0) + reservedForFinalizationUsd + synthesisHoldUsd;
 	if (wave.length > 0 && denied > 0) {
 		const deniedLabels = wave.filter((row) => !row.admitted).map((row) => row.label);
 		if (admitted === 0) say({
@@ -24614,6 +24683,12 @@ function preflightEstimate(input) {
 		code: "in-flight-exposure-cap",
 		message: `RunOptions.maxInFlightExposureUsd ${exposureCapUsd.toFixed(4)} USD bounds spent money plus live dispatch estimates: a dispatch whose estimate does not fit is refused typed before the provider call, so the worst concurrent overshoot past the cap is the estimate error of the in-flight turns, not one whole turn per agent`
 	});
+	const requiredMinimumExposureUsd = overshootOneTurnFloorUsd === void 0 ? void 0 : reservedForFinalizationUsd + synthesisHoldUsd + overshootOneTurnFloorUsd;
+	if (exposureCapUsd !== void 0 && overshootOneTurnFloorUsd !== void 0 && requiredMinimumExposureUsd !== void 0 && requiredMinimumExposureUsd > exposureCapUsd) say({
+		severity: "warning",
+		code: "exposure-cap-tight",
+		message: `maxInFlightExposureUsd ${exposureCapUsd.toFixed(4)} USD sits below the declared wave's breathing floor ${requiredMinimumExposureUsd.toFixed(4)} USD (finalize + synthesis reserves ${(reservedForFinalizationUsd + synthesisHoldUsd).toFixed(4)} plus the ${String(pricedTurns.length)} most expensive concurrent turn floors ${overshootOneTurnFloorUsd.toFixed(4)}): a coordinating turn beside a full child wave will be refused pre-wire and park until a hold releases (RV1902); raise the cap to at least the floor to avoid the stall entirely`
+	});
 	const quotaConfigured = engine.quota !== void 0;
 	if (!quotaConfigured && maxInFlight > 1 && units.length > 0) say({
 		severity: "info",
@@ -24800,6 +24875,7 @@ function preflightEstimate(input) {
 			...ceilingUsd === void 0 ? {} : { ceilingUsd },
 			reservedForFinalizationUsd,
 			synthesisReserveUsd: synthesisHoldUsd,
+			...requiredMinimumCeilingUsd === void 0 ? {} : { requiredMinimumCeilingUsd },
 			wave,
 			admitted,
 			denied
@@ -24807,6 +24883,7 @@ function preflightEstimate(input) {
 		exposure: {
 			maxInFlight,
 			...overshootOneTurnFloorUsd === void 0 ? {} : { overshootOneTurnFloorUsd },
+			...requiredMinimumExposureUsd === void 0 ? {} : { requiredMinimumExposureUsd },
 			perProvider,
 			...runCeiling === void 0 ? {} : { runCeiling }
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.198.0",
+  "version": "1.200.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",