@rulvar/core 1.70.0 → 1.71.0

package/dist/index.d.ts

@@ -8646,6 +8646,15 @@ interface PreflightSpawnReport {
   turnFloorUsd?: number;
   /** Executed-call ceiling across any tool mix; null = unlimited. */
   executedToolCallCeiling: number | null;
+  /**
+  * The provider-call ceiling of ONE spawn's whole loop: maxTurns
+  * bounded by the executed-call ceiling plus its final no-tool turn,
+  * plus the finalization summary turn when a tool budget limiter arms
+  * it. Every provider turn is one wire request and one quota
+  * reservation, so this is the per-spawn multiplier of quota demand;
+  * retries sit on top of it.
+  */
+  projectedProviderTurns: number;
   /** Per-tool ceilings for every tool a cap or a unit cost names. */
   toolCeilings: PreflightToolCeiling[];
 }
@@ -8672,7 +8681,8 @@ interface PreflightReport {
       /** min(capUsd, (capFraction ?? 0.2) x ceiling); absent when unresolvable. */effectiveCapUsd?: number;
       finalizeReserveUsd: number;
       finalizeTurns: number; /** Whether the finalize reserve is committed against the run root (extension runs). */
-      reserveCommitted: boolean;
+      reserveCommitted: boolean; /** The orchestrator agent's own loop ceiling, derived exactly like a spawn's. */
+      projectedProviderTurns: number;
     };
   };
   quota: {
@@ -8704,6 +8714,19 @@ interface PreflightReport {
       requestsPerWave: number;
       tokensPerWaveFloor: number;
     }>;
+    /**
+    * The declared wave run to its derived turn ceilings, at the
+    * declared estimates (the second experiment report, rec 9): total
+    * provider calls (fan-out times per-spawn projected turns, before
+    * any retries) and the cumulative token demand with the context
+    * regrowing every turn (turn k re-sends the declared prompt plus
+    * the k-1 prior output bounds, so K turns cost K x est +
+    * outputBound x K(K+1)/2). Absent when nothing is declared.
+    */
+    runCeiling?: {
+      requests: number;
+      tokens: number;
+    };
   };
   findings: PreflightFinding[];
 }

package/dist/index.js

@@ -16722,6 +16722,30 @@ function orchestrate(engine, goal, opts, runOptions) {
 }
 //#endregion
 //#region src/engine/preflight.ts
+/**
+* The overall executed-call ceiling across any tool mix: the cheapest
+* single-tool strategy bounds it from above; maxToolCalls bounds it
+* regardless of mix. A free tool (unit cost 0) lifts the units bound
+* entirely for calls of that tool.
+*/
+function overallExecutedCeiling(limits, toolCeilings) {
+	const overall = toolCeilings.reduce((best, row) => row.ceiling === null ? best : best === null ? row.ceiling : Math.max(best, row.ceiling), null);
+	return limits.maxToolCalls !== void 0 && (overall === null || limits.maxToolCalls < overall) ? limits.maxToolCalls : overall;
+}
+/**
+* The provider-call ceiling of one whole loop: maxTurns bounded by the
+* executed-call ceiling plus the final no-tool turn, plus the
+* finalization summary turn when a tool budget limiter arms it.
+*/
+function projectedProviderTurnsOf(limits, executedToolCallCeiling) {
+	const toolBound = executedToolCallCeiling === null ? void 0 : executedToolCallCeiling + 1;
+	const finalizeTurn = limits.finalizationReserve !== void 0 && (limits.maxToolCalls !== void 0 || limits.toolUnits !== void 0) ? 1 : 0;
+	return (toolBound === void 0 ? limits.maxTurns : Math.min(limits.maxTurns, toolBound)) + finalizeTurn;
+}
+/** Cumulative token demand of one whole loop at the declared estimates. */
+function shapeRunTokens(shape) {
+	return shape.turns * shape.inputFloor + shape.outputBound * shape.turns * (shape.turns + 1) / 2;
+}
 const ANY_TOOL = "(any)";
 function resolveServing(spec) {
 	if (spec === void 0) return;
@@ -16828,11 +16852,13 @@ function preflightEstimate(input) {
 		const finalizeReserveUsd = spec?.finalizeReserveUsd ?? finalizeTurns * flatReserveUsd;
 		const reserveCommitted = input.orchestrator.extension === true;
 		if (reserveCommitted) reservedForFinalizationUsd = finalizeReserveUsd;
+		const echoLimits = mergeUsageLimits(input.orchestrator.limits, void 0, defaults.limits);
 		orchestratorEcho = {
 			...effectiveCapUsd === void 0 ? {} : { effectiveCapUsd },
 			finalizeReserveUsd,
 			finalizeTurns,
-			reserveCommitted
+			reserveCommitted,
+			projectedProviderTurns: projectedProviderTurnsOf(echoLimits, overallExecutedCeiling(echoLimits, toolCeilingsOf(echoLimits)))
 		};
 		if (spec?.capUsd !== void 0 && spec.capFraction === void 0 && effectiveCapUsd !== void 0 && effectiveCapUsd < spec.capUsd) say({
 			severity: "warning",
@@ -16856,6 +16882,7 @@ function preflightEstimate(input) {
 	*/
 	const waveGateInputs = [];
 	const units = [];
+	const shapes = [];
 	for (const spec of spawnSpecs) {
 		const role = spec.role ?? "loop";
 		const label = spec.label ?? role;
@@ -16908,8 +16935,8 @@ function preflightEstimate(input) {
 			cacheWriteTokens: 0
 		});
 		const toolCeilings = toolCeilingsOf(limits);
-		const overall = toolCeilings.reduce((best, row) => row.ceiling === null ? best : best === null ? row.ceiling : Math.max(best, row.ceiling), null);
-		const executedToolCallCeiling = limits.maxToolCalls !== void 0 && (overall === null || limits.maxToolCalls < overall) ? limits.maxToolCalls : overall;
+		const executedToolCallCeiling = overallExecutedCeiling(limits, toolCeilings);
+		const projectedProviderTurns = projectedProviderTurnsOf(limits, executedToolCallCeiling);
 		for (const row of toolCeilings) {
 			if (row.tool === ANY_TOOL) continue;
 			const cost = limits.toolUnits?.costs?.[row.tool];
@@ -16976,6 +17003,7 @@ function preflightEstimate(input) {
 			...outputBound === void 0 ? {} : { maxOutputTokensPerTurn: outputBound },
 			...turnFloorUsd === void 0 ? {} : { turnFloorUsd },
 			executedToolCallCeiling,
+			projectedProviderTurns,
 			toolCeilings
 		});
 		{
@@ -16998,6 +17026,21 @@ function preflightEstimate(input) {
 			if (turnFloorUsd !== void 0) unit.turnFloorUsd = turnFloorUsd;
 			units.push(unit);
 		}
+		{
+			const shape = {
+				label,
+				inputFloor: spec.estInputTokens ?? 0,
+				outputBound: outputBound ?? 0,
+				turns: projectedProviderTurns,
+				count
+			};
+			if (servedBy !== void 0) {
+				const { adapterId, model } = parseModelRef(servedBy);
+				shape.provider = adapterId;
+				shape.model = model;
+			}
+			shapes.push(shape);
+		}
 	}
 	let orchestratorReserveUsd;
 	if (input.orchestrator !== void 0) {
@@ -17027,6 +17070,15 @@ function preflightEstimate(input) {
 				cacheWriteTokens: 0
 			});
 			units.push(unit);
+			shapes.push({
+				label: "orchestrator",
+				provider: adapterId,
+				model,
+				inputFloor: input.orchestrator.estInputTokens ?? 0,
+				outputBound: outputBound ?? 0,
+				turns: projectedProviderTurnsOf(orchLimits, overallExecutedCeiling(orchLimits, toolCeilingsOf(orchLimits))),
+				count: 1
+			});
 			if (effectiveCapUsd !== void 0) orchestratorReserveUsd = Math.max(0, orchestratorAdmissionEstCostUsd(effectiveCapUsd, reservedForFinalizationUsd));
 			else if (pricing === void 0) orchestratorReserveUsd = 0;
 			else orchestratorReserveUsd = admissionReserveUsd({
@@ -17180,6 +17232,48 @@ function preflightEstimate(input) {
 			code: "quota-tokens-below-wave",
 			message: `${name}: the declared wave demands at least ${String(tokens)} tokens against tokensPerMinute ${String(rule.tokensPerMinute)}: expect estimate-driven throttling inside one window`
 		});
+		let runRequests = 0;
+		let runTokens = 0;
+		for (const shape of shapes) {
+			if (shape.provider === void 0 || shape.model === void 0) continue;
+			if (!quotaRuleMatches(rule, {
+				provider: shape.provider,
+				model: shape.model,
+				...engine.quota?.tenant === void 0 ? {} : { tenant: engine.quota.tenant },
+				estimate: {
+					requests: 1,
+					inputTokens: 0
+				}
+			})) continue;
+			runRequests += shape.count * shape.turns;
+			runTokens += shape.count * shapeRunTokens(shape);
+			if (rule.tokensPerMinute !== void 0 && shape.outputBound > 0) {
+				const k = Math.max(1, Math.floor((rule.tokensPerMinute - shape.inputFloor) / shape.outputBound) + 1);
+				if (k <= shape.turns) say({
+					severity: "warning",
+					code: "quota-turn-never-fits",
+					message: `spawn '${shape.label}': by turn ${String(k)} of ${String(shape.turns)} the context-grown reservation (about ${String(shape.inputFloor + k * shape.outputBound)} tokens) exceeds ${name} tokensPerMinute ${String(rule.tokensPerMinute)} outright: the limiter denies it as never fitting the window (no wait helps) and the invocation fails after paying for the earlier turns`,
+					spawn: shape.label
+				});
+			}
+		}
+		if (rule.requestsPerMinute !== void 0 && requests <= rule.requestsPerMinute && runRequests > rule.requestsPerMinute) say({
+			severity: "warning",
+			code: "quota-requests-below-run",
+			message: `${name}: the declared wave fits ${String(requests)} dispatches under requestsPerMinute ${String(rule.requestsPerMinute)}, but run to its turn ceilings it projects up to ${String(runRequests)} provider calls (fan-out times per-spawn turns, before any retries): expect synthetic rate-limit denials and backoff across about ${String(Math.ceil(runRequests / rule.requestsPerMinute))} windows`
+		});
+		if (rule.tokensPerMinute !== void 0 && tokens <= rule.tokensPerMinute && runTokens > rule.tokensPerMinute) say({
+			severity: "warning",
+			code: "quota-tokens-below-run",
+			message: `${name}: the declared wave demands ${String(tokens)} tokens up front, but with the context regrowing every turn its loops project about ${String(runTokens)} tokens against tokensPerMinute ${String(rule.tokensPerMinute)}: expect estimate-driven throttling across about ${String(Math.ceil(runTokens / rule.tokensPerMinute))} windows`
+		});
+	});
+	const runCeiling = shapes.length === 0 ? void 0 : shapes.reduce((sum, shape) => ({
+		requests: sum.requests + shape.count * shape.turns,
+		tokens: sum.tokens + shape.count * shapeRunTokens(shape)
+	}), {
+		requests: 0,
+		tokens: 0
 	});
 	const severityRank = {
 		error: 0,
@@ -17217,7 +17311,8 @@ function preflightEstimate(input) {
 		exposure: {
 			maxInFlight,
 			...overshootOneTurnFloorUsd === void 0 ? {} : { overshootOneTurnFloorUsd },
-			perProvider
+			perProvider,
+			...runCeiling === void 0 ? {} : { runCeiling }
 		},
 		findings
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.70.0",
+  "version": "1.71.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",