@rulvar/core 1.189.0 → 1.191.0

package/dist/index.d.ts

@@ -8103,6 +8103,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 +9474,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 +9543,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. */
@@ -11238,14 +11291,31 @@ interface McpConfig {
   * request timeout per tools/list page and per tools/call; without
   * them the SDK's own 60s default request timeout applies. A call
   * timeout surfaces as the tool's error result, never past policy.
-  * Each a positive finite number of milliseconds.
+  * discoveryMs (RV1808) is the WALL-CLOCK cap over one whole
+  * tools/list sweep, all pages included: per-page listMs cannot bound
+  * a server that answers every page promptly and paginates forever
+  * with unique cursors under maxPages' radar only when maxPages is
+  * set, and cannot bound a slow-but-under-listMs page crawl at all.
+  * On expiry the sweep refuses typed. Each a positive finite number
+  * of milliseconds.
   */
   timeouts?: {
     connectMs?: number;
     listMs?: number;
     callMs?: number;
+    discoveryMs?: number;
   };
   /**
+  * Demand the discovery bounds (RV1808): with `requireBounds: true`
+  * the source refuses at construction unless maxTools, maxPages,
+  * maxSchemaBytes, and timeouts.discoveryMs are ALL declared. The
+  * production posture: an unbounded discovery sweep against a remote
+  * registry is an availability decision someone should have made on
+  * purpose, so the flag turns the four absences into one typed error
+  * naming what is missing instead of four silent unboundeds.
+  */
+  requireBounds?: boolean;
+  /**
   * streamable-http only (RV1516): headers injected into EVERY wire
   * request through a wrapped fetch. The hook form is awaited before
   * each send, so it IS the refresh point: rotate a token in the hook

package/dist/index.js

@@ -4055,11 +4055,21 @@ function validateBounds(cfg) {
 	for (const key of [
 		"connectMs",
 		"listMs",
-		"callMs"
+		"callMs",
+		"discoveryMs"
 	]) {
 		const value = cfg.timeouts?.[key];
 		if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) throw new ConfigError(`mcp: 'timeouts.${key}' must be a positive finite number of milliseconds, got ${String(value)}`);
 	}
+	if (cfg.requireBounds === true) {
+		const missing = [
+			...cfg.maxTools === void 0 ? ["maxTools"] : [],
+			...cfg.maxPages === void 0 ? ["maxPages"] : [],
+			...cfg.maxSchemaBytes === void 0 ? ["maxSchemaBytes"] : [],
+			...cfg.timeouts?.discoveryMs === void 0 ? ["timeouts.discoveryMs"] : []
+		];
+		if (missing.length > 0) throw new ConfigError(`mcp: requireBounds demands every discovery bound; missing ${missing.join(", ")}`);
+	}
 	if (cfg.drift !== void 0 && cfg.drift !== "rekey" && cfg.drift !== "refuse") throw new ConfigError(`mcp: 'drift' must be 'rekey' or 'refuse', got '${String(cfg.drift)}'`);
 	const headers = cfg.http?.headers;
 	if (headers !== void 0 && typeof headers !== "function" && typeof headers !== "object") throw new ConfigError("mcp: 'http.headers' must be a record of header values or a (possibly async) function returning one");
@@ -4201,13 +4211,19 @@ function mcp(cfg) {
 		const tools = [];
 		let cursor;
 		let pages = 0;
+		const visited = /* @__PURE__ */ new Set();
+		const startedAt = Date.now();
+		const discoveryMs = cfg.timeouts?.discoveryMs;
 		const listOptions = cfg.timeouts?.listMs === void 0 ? void 0 : { timeout: cfg.timeouts.listMs };
 		do {
+			if (discoveryMs !== void 0 && Date.now() - startedAt > discoveryMs) throw new ConfigError(`mcp: tools/list of '${sourceIdOf(cfg)}' exceeded the discovery deadline (timeouts.discoveryMs ${discoveryMs}) after ${pages} page(s)`);
+			if (cursor !== void 0) visited.add(cursor);
 			const page = await client.listTools(cursor === void 0 ? {} : { cursor }, listOptions);
 			pages += 1;
 			tools.push(...page.tools);
 			if (cfg.maxTools !== void 0 && tools.length > cfg.maxTools) throw new ConfigError(`mcp: tools/list of '${sourceIdOf(cfg)}' returned at least ${tools.length} wire tools, over the declared maxTools ${cfg.maxTools}; raise the cap or trim the server`);
 			if (page.nextCursor !== void 0 && page.nextCursor !== "" && page.nextCursor === cursor) throw new ConfigError(`mcp: tools/list of '${sourceIdOf(cfg)}' returned the cursor it was queried with ('${page.nextCursor}') on page ${pages}: the pagination makes no progress`);
+			if (page.nextCursor !== void 0 && page.nextCursor !== "" && visited.has(page.nextCursor)) throw new ConfigError(`mcp: tools/list of '${sourceIdOf(cfg)}' returned a cursor this sweep already visited ('${page.nextCursor}') on page ${pages}: the pagination cycles`);
 			cursor = page.nextCursor;
 			if (cfg.maxPages !== void 0 && pages >= cfg.maxPages && cursor !== void 0 && cursor !== "") throw new ConfigError(`mcp: tools/list of '${sourceIdOf(cfg)}' still reports another page after ${pages} page(s), over the declared maxPages ${cfg.maxPages}; raise the cap or trim the server`);
 		} while (cursor !== void 0 && cursor !== "");
@@ -20163,7 +20179,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. */
@@ -20803,6 +20820,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)}`);
@@ -22694,8 +22715,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 = {
@@ -22707,6 +22742,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: {

package/package.json

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