@rulvar/core 1.190.0 → 1.192.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). */
@@ -8103,6 +8127,13 @@ interface RunFactPairsFold {
   pairs: ClaimPair[];
   /** True when more sentences matched than `max` allowed to report. */
   truncated: boolean;
+  /**
+  * The UNCAPPED count of matched run-claim sentences (RV1809): with
+  * only `truncated` a consumer knew the bound cut the fold but not by
+  * how much, so no run-fact coverage ratio was computable from the
+  * meta alone.
+  */
+  candidates: number;
 }
 /**
 * Pairs draft sentences that speak about the RUN with the run's own
@@ -9467,6 +9498,32 @@ interface OrchestrateClaimConsistency {
   * `runFacts: true`.
   */
   runFactTerms?: string[];
+  /**
+  * The declared coverage floor (RV1809): the minimum
+  * coveredCitingSentences over draftCitingSentences ratio, in
+  * (0, 1]. The nineteenth benchmark's pass covered 36 of 122 citing
+  * sentences and graded itself 'partial' honestly, but nothing could
+  * ENFORCE a floor: a consumer had to read the counts and decide
+  * externally. Below the floor, `onLowCoverage` decides. A draft
+  * with zero citing sentences is vacuously full and never trips it.
+  */
+  minimumCoverageRatio?: number;
+  /**
+  * The run-fact coverage floor (RV1809): the minimum judged run-fact
+  * pairs over matched run-fact candidates ratio, in (0, 1]. Requires
+  * `runFacts: true`; a draft with zero matched run claims never
+  * trips it.
+  */
+  runFactCoverageRatio?: number;
+  /**
+  * What a below-floor ratio does (RV1809): 'report' (the default)
+  * stamps the machine-readable `lowCoverage` block on the meta;
+  * 'fail' fails the run typed BEFORE the judge dispatch, exactly
+  * like `onUncoveredCritical`, so a run that cannot meet its
+  * declared verification floor never pays for a partial verdict.
+  * Requires at least one declared floor.
+  */
+  onLowCoverage?: "report" | "fail";
 }
 /** One judged contradiction: the pair plus the judge's one-sentence reason. */
 interface ClaimContradictionFinding extends ClaimPair {
@@ -9510,6 +9567,26 @@ interface OrchestrateClaimConsistencyMeta {
   runFactPairs?: number;
   /** Present under `runFacts` when more run claims matched than the bound. */
   runFactPairsTruncated?: true;
+  /**
+  * Present under `runFacts` (RV1809): the UNCAPPED count of matched
+  * run-claim sentences, so the run-fact coverage ratio is computable
+  * from the meta alone, live or from a persisted outcome.
+  */
+  runFactCandidates?: number;
+  /**
+  * Present when a declared coverage floor was not met under
+  * `onLowCoverage: 'report'` (RV1809): each ratio beside its floor,
+  * machine-readable, so "complete but under-verified by the declared
+  * floor" is a field, not an external computation. Under 'fail' the
+  * run fails typed instead and the meta stamps this block on the way
+  * out.
+  */
+  lowCoverage?: {
+    coverageRatio: number;
+    coverageFloor?: number;
+    runFactRatio?: number;
+    runFactFloor?: number;
+  };
   /** True when the judge invocation was dispatched. */
   judgeInvoked: boolean;
   /** Present when the judge invocation did not settle ok. */
@@ -10462,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;
   /**

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)
@@ -20179,7 +20198,8 @@ function pairRunFactClaims(draftText, sheet, options) {
 	}
 	return {
 		pairs: matched,
-		truncated: total > matched.length
+		truncated: total > matched.length,
+		candidates: total
 	};
 }
 /** Derives the {@link ClaimCoverageGrade} of a claim-consistency meta. */
@@ -20819,6 +20839,10 @@ function validateOrchestrateOptions(opts) {
 			if (consistency.runFacts !== true) throw new ConfigError("orchestrate claimConsistency.runFactTerms rides the runFacts pass; set claimConsistency.runFacts true");
 			if (!Array.isArray(consistency.runFactTerms) || consistency.runFactTerms.some((term) => typeof term !== "string" || term.length === 0)) throw new ConfigError("orchestrate claimConsistency.runFactTerms must be an array of nonempty strings; got " + JSON.stringify(consistency.runFactTerms));
 		}
+		for (const [label, ratio] of [["minimumCoverageRatio", consistency.minimumCoverageRatio], ["runFactCoverageRatio", consistency.runFactCoverageRatio]]) if (ratio !== void 0 && (typeof ratio !== "number" || !Number.isFinite(ratio) || ratio <= 0 || ratio > 1)) throw new ConfigError(`orchestrate claimConsistency.${label} must be a number in (0, 1]; got ` + JSON.stringify(ratio));
+		if (consistency.runFactCoverageRatio !== void 0 && consistency.runFacts !== true) throw new ConfigError("orchestrate claimConsistency.runFactCoverageRatio rides the runFacts pass; set claimConsistency.runFacts true");
+		if (consistency.onLowCoverage !== void 0 && consistency.onLowCoverage !== "report" && consistency.onLowCoverage !== "fail") throw new ConfigError("orchestrate claimConsistency.onLowCoverage must be 'report' or 'fail'; got " + JSON.stringify(consistency.onLowCoverage));
+		if (consistency.onLowCoverage !== void 0 && consistency.minimumCoverageRatio === void 0 && consistency.runFactCoverageRatio === void 0) throw new ConfigError("orchestrate claimConsistency.onLowCoverage needs a declared floor; set minimumCoverageRatio or runFactCoverageRatio");
 		if (consistency.judge !== void 0) {
 			const judge = consistency.judge;
 			if (typeof judge !== "object" || judge === null || Array.isArray(judge)) throw new ConfigError(`orchestrate claimConsistency.judge must be an object; got ${JSON.stringify(consistency.judge)}`);
@@ -22710,8 +22734,22 @@ function makeOrchestratorWorkflow(goal, opts) {
 				},
 				...runFold === void 0 ? {} : {
 					runFactPairs: runFold.pairs.length,
-					...runFold.truncated ? { runFactPairsTruncated: true } : {}
-				}
+					...runFold.truncated ? { runFactPairsTruncated: true } : {},
+					runFactCandidates: runFold.candidates
+				},
+				...(() => {
+					const coverageRatio = fold.draftCitingSentences === 0 ? 1 : fold.coveredCitingSentences / fold.draftCitingSentences;
+					const runFactRatio = runFold === void 0 || runFold.candidates === 0 ? void 0 : runFold.pairs.length / runFold.candidates;
+					const belowCoverage = spec.minimumCoverageRatio !== void 0 && fold.draftCitingSentences > 0 && coverageRatio < spec.minimumCoverageRatio;
+					const belowRunFacts = spec.runFactCoverageRatio !== void 0 && runFactRatio !== void 0 && runFactRatio < spec.runFactCoverageRatio;
+					if (!belowCoverage && !belowRunFacts) return {};
+					return { lowCoverage: {
+						coverageRatio,
+						...spec.minimumCoverageRatio === void 0 ? {} : { coverageFloor: spec.minimumCoverageRatio },
+						...runFactRatio === void 0 ? {} : { runFactRatio },
+						...spec.runFactCoverageRatio === void 0 ? {} : { runFactFloor: spec.runFactCoverageRatio }
+					} };
+				})()
 			};
 			const finishMeta = (flags) => {
 				const bare = {
@@ -22723,6 +22761,16 @@ function makeOrchestratorWorkflow(goal, opts) {
 					coverage: claimCoverageOf(bare)
 				};
 			};
+			if (spec.onLowCoverage === "fail" && metaBase.lowCoverage !== void 0) {
+				claimConsistencyMeta = finishMeta({ judgeInvoked: false });
+				const low = metaBase.lowCoverage;
+				throw new FailRunError(`the claim-consistency pass is below a declared coverage floor (coverage ${low.coverageRatio.toFixed(3)}` + (low.coverageFloor === void 0 ? "" : ` under floor ${String(low.coverageFloor)}`) + (low.runFactRatio === void 0 ? "" : `; run facts ${low.runFactRatio.toFixed(3)}` + (low.runFactFloor === void 0 ? "" : ` under floor ${String(low.runFactFloor)}`)) + "), and the armed onLowCoverage posture cannot pass the draft", { data: {
+					source: "orchestrator_claim_consistency",
+					lowCoverage: low,
+					claimConsistencyMeta,
+					...snapshot ?? {}
+				} });
+			}
 			if (spec.onUncoveredCritical === "fail" && fold.criticalUncovered !== void 0 && fold.criticalUncovered.length > 0) {
 				claimConsistencyMeta = finishMeta({ judgeInvoked: false });
 				throw new FailRunError(`the claim-consistency pass left ${String(fold.criticalUncoveredTotal ?? 0)} critical draft anchor(s) unjudged (${fold.criticalUncovered.join(", ")}), and the armed onUncoveredCritical posture cannot pass the draft`, { data: {
@@ -25155,6 +25203,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");
@@ -25331,6 +25380,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.190.0",
+  "version": "1.192.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",