@rulvar/core 1.191.0 → 1.193.0

package/dist/index.d.ts

@@ -2381,6 +2381,14 @@ type AgentEvents = {
   label?: string;
   error: WireError;
   willRetry: boolean;
+} | {
+  type: "quota:denied";
+  agentType: string;
+  label?: string; /** The denied model ref. */
+  model?: string; /** The limiter's reason ('tokensPerMinute 1800000 exhausted'). */
+  reason?: string;
+  retryAfterMs?: number;
+  willRetry: true;
 } | {
   type: "agent:schema-retry";
   agentType: string;
@@ -5192,6 +5200,12 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
   adapter: ProviderAdapter;
   resolved: ResolvedInvocation;
   /**
+  * The versioned compat flag (RV1810): emit the legacy `agent:error`
+  * twin beside `quota:denied` for recoverable pre-wire quota waits.
+  * Default off: the wait speaks its own type only.
+  */
+  quotaDeniedAgentError?: boolean;
+  /**
   * Transport failover chain for the loop phase (M4-T04):
   * resolved fallback targets tried in order on
   * transport or rate-limit failures after retries exhaust. Failover is
@@ -7070,6 +7084,16 @@ interface CreateEngineOptions {
     modelKnowledge?: ModelKnowledgeStore;
   };
   defaults?: EngineDefaults;
+  /**
+  * Telemetry compat posture (RV1810). `quotaDeniedAgentError: true`
+  * restores the legacy `agent:error` twin beside the primary
+  * `quota:denied` event for recoverable pre-wire quota waits, for
+  * consumers still keyed to the old type. Default off: healthy
+  * throttling speaks its own type and never reads as failure.
+  */
+  telemetry?: {
+    quotaDeniedAgentError?: boolean;
+  };
   budgetDefaults?: BudgetDefaults;
   concurrency?: {
     perRun?: number; /** Per-adapter-id caps; unlimited unless configured (Appendix A; M4-T07). */
@@ -10515,6 +10539,10 @@ interface RunInternals {
     gates?: Record<string, MechanicalGateProfile>; /** Engine-wide admission countTokens policy (RV1804); default 'allow'. */
     countTokens?: "allow" | "deny";
   };
+  /** Telemetry compat posture (RV1810). */
+  telemetry?: {
+    /** Emit the legacy agent:error twin beside quota:denied. */quotaDeniedAgentError?: boolean;
+  };
   /** Engine-scoped per-provider keyed limiter (M4-T07). */
   providerLimiter?: KeyedLimiter;
   /**
@@ -12525,6 +12553,14 @@ interface PreflightOrchestratorSpec {
     };
     acceptPartialChildren?: boolean;
     acceptValidatedTerminalOutputOnLimit?: boolean;
+    /**
+    * Mirrors OrchestrateAcceptance.minSpawnedChildren (RV1901, the
+    * four-role benchmark's primary defect): declaring it lets the
+    * admission projection judge whether the declared wave can seat
+    * the roster the acceptance policy demands, instead of green-
+    * lighting a wave the settle verdict is bound to reject.
+    */
+    minSpawnedChildren?: number;
   };
   /**
   * The separate synthesis invocation (RV-211), when the orchestration
@@ -12686,6 +12722,15 @@ interface PreflightAdmissionRow {
   reserveUsd: number;
   admitted: boolean;
   deniedBy?: "budget" | "spawn-cap" | "orchestrator-max-spawns";
+  /**
+  * The run-root money already held when this row was evaluated:
+  * committed reserves of the earlier rows plus the finalization and
+  * synthesis carve-outs (RV1901). The row admits iff held + reserveUsd
+  * fits the ceiling (children strictly below it at exact fill), so a
+  * denied row's arithmetic is auditable term by term. Present only
+  * under a USD ceiling.
+  */
+  heldAtEvaluationUsd?: number;
 }
 /** The machine-readable preflight report; JSON-serializable throughout. */
 interface PreflightReport {
@@ -12728,6 +12773,15 @@ interface PreflightReport {
   admission: {
     ceilingUsd?: number;
     reservedForFinalizationUsd: number;
+    /**
+    * The synthesis payload carve-out the projection holds against the
+    * run root, exactly the live commitSynthesisReserve mirror (RV1901):
+    * a capped orchestrator with budget.synthesisReserveUsd registers it
+    * on the root before any spawn admits, so the wave arithmetic must
+    * hold it too. Zero when the orchestrator is uncapped or declares no
+    * synthesis reserve, matching the runtime that then commits none.
+    */
+    synthesisReserveUsd: number;
     wave: PreflightAdmissionRow[];
     admitted: number;
     denied: number;

package/dist/index.js

@@ -12407,7 +12407,25 @@ async function runAgent(options) {
 					const retryAfter = (outcome.wireError?.data)?.retryAfterMs;
 					if (outcome.wireError !== void 0) {
 						if (outcome.quotaDenied !== true) transportRetries += 1;
-						events?.emit({
+						if (outcome.quotaDenied === true) {
+							const denialData = outcome.wireError.data;
+							events?.emit({
+								type: "quota:denied",
+								agentType,
+								label: options.label,
+								model: target.resolved.ref,
+								...typeof denialData?.reason === "string" ? { reason: denialData.reason } : {},
+								...typeof denialData?.retryAfterMs === "number" ? { retryAfterMs: denialData.retryAfterMs } : {},
+								willRetry: true
+							});
+							if (options.quotaDeniedAgentError === true) events?.emit({
+								type: "agent:error",
+								agentType,
+								label: options.label,
+								error: outcome.wireError,
+								willRetry: true
+							});
+						} else events?.emit({
 							type: "agent:error",
 							agentType,
 							label: options.label,
@@ -17579,6 +17597,7 @@ function createCtx(internals, rootWorkflow) {
 			resolved: loopResolved,
 			limits,
 			events: agentSink,
+			...internals.telemetry?.quotaDeniedAgentError === true ? { quotaDeniedAgentError: true } : {},
 			transcript: {
 				mintRef: internals.mintTranscriptRef,
 				put: (ref, blob) => internals.transcripts.put(ref, blob, internals.lease)
@@ -23765,9 +23784,11 @@ function preflightEstimate(input) {
 	const coordinationRepairReserve = input.orchestrator?.synthesis === void 0 ? finishRepairReserve : 0;
 	let orchestratorEcho;
 	let reservedForFinalizationUsd = 0;
+	let synthesisHoldUsd = 0;
 	let effectiveCapUsd;
 	if (input.orchestrator !== void 0) {
 		if (input.orchestrator.estInputTokens !== void 0) requireNonNegativeInteger(input.orchestrator.estInputTokens, "preflight.orchestrator.estInputTokens");
+		if (input.orchestrator.acceptance?.minSpawnedChildren !== void 0) requirePositiveInteger$2(input.orchestrator.acceptance.minSpawnedChildren, "preflight.orchestrator.acceptance.minSpawnedChildren");
 		const spec = input.orchestrator.budget;
 		const fraction = spec?.capFraction ?? .2;
 		const fromFraction = ceilingUsd === void 0 ? void 0 : fraction * ceilingUsd;
@@ -23777,6 +23798,7 @@ function preflightEstimate(input) {
 		const finalizeReserveUsd = spec?.finalizeReserveUsd ?? finalizeTurns * flatReserveUsd;
 		const reserveCommitted = input.orchestrator.extension === true;
 		if (reserveCommitted) reservedForFinalizationUsd = finalizeReserveUsd;
+		if (effectiveCapUsd !== void 0) synthesisHoldUsd = Math.max(0, spec?.synthesisReserveUsd ?? 0);
 		const echoLimits = mergeUsageLimits(input.orchestrator.limits, void 0, defaults.limits);
 		orchestratorEcho = {
 			...effectiveCapUsd === void 0 ? {} : { effectiveCapUsd },
@@ -24189,9 +24211,11 @@ function preflightEstimate(input) {
 	let committed = 0;
 	let spawned = 0;
 	let children = 0;
+	let childrenDeniedByBudget = 0;
+	const heldAgainstRoot = () => committed + reservedForFinalizationUsd + synthesisHoldUsd;
 	const admitAgainstRoot = (reserveUsd, strictAtFill = false) => {
 		if (ceilingUsd === void 0) return true;
-		const held = committed + reservedForFinalizationUsd;
+		const held = heldAgainstRoot();
 		if (held >= ceilingUsd) return false;
 		const fill = held + reserveUsd;
 		return strictAtFill ? fill < ceilingUsd : fill <= ceilingUsd;
@@ -24205,7 +24229,8 @@ function preflightEstimate(input) {
 			label: "orchestrator",
 			reserveUsd,
 			admitted: deniedBy === void 0,
-			...deniedBy === void 0 ? {} : { deniedBy }
+			...deniedBy === void 0 ? {} : { deniedBy },
+			...ceilingUsd === void 0 ? {} : { heldAtEvaluationUsd: heldAgainstRoot() }
 		});
 		if (deniedBy === void 0) {
 			committed += reserveUsd;
@@ -24224,7 +24249,7 @@ function preflightEstimate(input) {
 			else if (maxSpawns !== void 0 && children >= maxSpawns) deniedBy = "orchestrator-max-spawns";
 			else {
 				if (orchestrateWave && ceilingUsd !== void 0) {
-					const remainder = ceilingUsd - committed - reservedForFinalizationUsd;
+					const remainder = ceilingUsd - heldAgainstRoot();
 					const projection = dispatchProjectionReserveUsd(gate, flatReserveUsd);
 					if (remainder <= 0 || remainder <= projection) deniedBy = "budget";
 				}
@@ -24234,13 +24259,14 @@ function preflightEstimate(input) {
 				label,
 				reserveUsd,
 				admitted: deniedBy === void 0,
-				...deniedBy === void 0 ? {} : { deniedBy }
+				...deniedBy === void 0 ? {} : { deniedBy },
+				...ceilingUsd === void 0 ? {} : { heldAtEvaluationUsd: heldAgainstRoot() }
 			});
 			if (deniedBy === void 0) {
 				committed += reserveUsd;
 				spawned += 1;
 				children += 1;
-			}
+			} else if (deniedBy === "budget") childrenDeniedByBudget += 1;
 		}
 	}
 	const admitted = wave.filter((row) => row.admitted).length;
@@ -24258,6 +24284,19 @@ function preflightEstimate(input) {
 			message: `the declared wave admits ${String(admitted)} of ${String(wave.length)} spawns; denied before any work: ${deniedLabels.join(", ")}`
 		});
 	}
+	{
+		const acceptance = input.orchestrator?.acceptance;
+		const minSuccessfulFloor = acceptance?.childPolicy !== void 0 && acceptance.childPolicy !== "all-ok" ? acceptance.childPolicy.minSuccessful : void 0;
+		const rosterFloor = Math.max(acceptance?.minSpawnedChildren ?? 0, minSuccessfulFloor ?? 0);
+		if (rosterFloor > 0 && children < rosterFloor && childrenDeniedByBudget > 0) {
+			const demandedBy = (acceptance?.minSpawnedChildren ?? 0) >= (minSuccessfulFloor ?? 0) ? "acceptance.minSpawnedChildren" : "acceptance.childPolicy.minSuccessful";
+			say({
+				severity: "error",
+				code: "admission-below-roster-floor",
+				message: `the declared wave seats ${String(children)} of the ${String(rosterFloor)} children ${demandedBy} demands (${String(childrenDeniedByBudget)} denied by budget): the run would pay for the seated work and still settle rejected; re-admission after a child settles frees money only when its settled spend stays below the released reserve`
+			});
+		}
+	}
 	if (ceilingUsd === void 0 && wave.length > 0) say({
 		severity: "info",
 		code: "no-usd-ceiling",
@@ -24481,6 +24520,7 @@ function preflightEstimate(input) {
 		admission: {
 			...ceilingUsd === void 0 ? {} : { ceilingUsd },
 			reservedForFinalizationUsd,
+			synthesisReserveUsd: synthesisHoldUsd,
 			wave,
 			admitted,
 			denied
@@ -25184,6 +25224,7 @@ function createEngine(options) {
 		if (profile.countTokens !== void 0 && !["allow", "deny"].includes(profile.countTokens)) throw new ConfigError(`createEngine defaults.profiles['${name}'].countTokens must be 'allow' or 'deny'`);
 	}
 	if (options.defaults?.countTokens !== void 0 && !["allow", "deny"].includes(options.defaults.countTokens)) throw new ConfigError("createEngine defaults.countTokens must be 'allow' or 'deny'");
+	if (options.telemetry?.quotaDeniedAgentError !== void 0 && typeof options.telemetry.quotaDeniedAgentError !== "boolean") throw new ConfigError("createEngine telemetry.quotaDeniedAgentError must be a boolean");
 	validateDeterminismConfig(options.determinism);
 	validateEngineQuotaConfig(options.quota);
 	if (options.security?.argsHashSalt !== void 0 && (typeof options.security.argsHashSalt !== "string" || options.security.argsHashSalt === "")) throw new ConfigError("createEngine security.argsHashSalt must be a nonempty string when given");
@@ -25360,6 +25401,7 @@ function createEngine(options) {
 				...defaults.gates === void 0 ? {} : { gates: defaults.gates },
 				...defaults.countTokens === void 0 ? {} : { countTokens: defaults.countTokens }
 			},
+			...options.telemetry === void 0 ? {} : { telemetry: options.telemetry },
 			errorPolicy: wf.errorPolicy,
 			dropped: [],
 			cost: {

package/package.json

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