@rulvar/core 1.98.0 → 1.99.1

package/dist/index.d.ts

@@ -2762,7 +2762,7 @@ interface RefEntryAppender {
 /**
 * Per-run, per-target FIFO serializer of resolution/abandon attempts:
 * classification against the in-memory fold ->
-* durable append -> settle exactly once; losing attempts are ALSO
+* durable append -> a single settle; losing attempts are ALSO
 * appended and become journaled noops by fold classification. Winner
 * effects run strictly after the critical section (the caller's job).
 * Cross-process protection remains the LeasableStore fencing epoch.
@@ -2959,7 +2959,7 @@ declare class Replayer {
   /** Suspended kinds (external, approval): appended once, closed by ref-entries (M2). */
   appendSuspended(input: SuspendedAppend): Promise<JournalEntry>;
   /**
-  * The budget ledger fold: usage sums over terminal entries exactly once; agentsSpawned
+  * The budget ledger fold: usage sums over terminal entries once, never twice; agentsSpawned
   * counts agent dispatches.
   */
   ledger(): Ledger;
@@ -4440,6 +4440,17 @@ interface AgentResult<T> {
   * recoveries; absent when zero.
   */
   schemaRecoveredTerminalExchanges?: number;
+  /**
+  * The evidence floor refusal detail (RV507): present ONLY when an
+  * enforced contract refused an otherwise-ok settle. The ctx layer
+  * folds it into the journaled terminal error data and memoizes the
+  * outcome (the refusal is deterministic from the paid transcript, so
+  * a rerun would only re-pay the same bounded failure).
+  */
+  evidenceFloor?: {
+    recordedEntries: number;
+    minEntries: number;
+  };
 }
 /** One 429's provider-normalized limits, per (provider, model). */
 interface RateLimitObservation {
@@ -4667,6 +4678,20 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
     save(state: CheckpointState): Promise<void>;
   };
   limits: EffectiveUsageLimits;
+  /**
+  * The resolved evidence contract of the invocation (RV507): under
+  * enforce 'refuse' an ok settle whose message window carries fewer
+  * successful `record_evidence` executions (result `recorded: true`)
+  * than `minEntries` is refused as a typed 'terminal' error carrying
+  * the machine-readable counter and threshold. Window-derived exactly
+  * like the terminal partial, so live and resumed segments count the
+  * same total. Absent, and under 'warn', the loop is byte-identical to
+  * before.
+  */
+  evidenceContract?: {
+    minEntries: number;
+    enforce?: "warn" | "refuse";
+  };
   /** Emits agent:stream deltas when true (telemetry only). */
   stream?: boolean;
   /** Host or sibling cancellation. */
@@ -6672,7 +6697,7 @@ declare function stripFencedBlocks(text: string): string;
 * heading nor trip exclusivity. Heading lines compare trimmed, whole
 * line. With `ordered` (default true) the declared headings must
 * appear in declaration order; with `exclusive` (default true) each
-* declared heading must appear exactly once and no undeclared heading
+* declared heading must appear once, unrepeated, and no undeclared heading
 * of the governed level may exist (other levels stay free). Default
 * name 'heading-structure'.
 */
@@ -6736,7 +6761,10 @@ declare const DEFAULT_EVIDENCE_MIN_SHARE = .95;
 * {@link DEFAULT_EVIDENCE_MIN_SHARE}, the plan's 95 percent gate,
 * compared as a ceiling on the required count so an exact boundary like
 * 19 of 20 passes) must appear literally in the result text. Zero child
-* citations pass vacuously. With `requireKnown: true` the contract also
+* citations pass vacuously UNLESS `requireNonEmptyPool: true` (RV507):
+* for an evidence-critical run the empty pool IS the failure, so that
+* mode refuses it with an `empty child citation pool` reason instead of
+* the vacuous pass. With `requireKnown: true` the contract also
 * runs in reverse: every citation in the RESULT must appear in some
 * child's output, so a fabricated but pattern valid citation is
 * rejected instead of silently counting as evidence. Rejection reasons
@@ -6750,6 +6778,7 @@ declare function evidencePreservedValidator(options?: {
   flags?: string;
   minShare?: number;
   requireKnown?: boolean;
+  requireNonEmptyPool?: boolean;
   name?: string;
 }): FinishValidator;
 /**
@@ -7500,6 +7529,19 @@ interface OrchestrateAcceptance {
   */
   acceptPartialChildren?: boolean;
   /**
+  * The spawned-roster floor (RV507): finish is rejected when FEWER
+  * than this many children were spawned, under BOTH child policies.
+  * 'all-ok' alone treats zero spawned children as vacuously complete
+  * (spawn nothing you do not need to succeed), which lets a
+  * fan-out-shaped task settle ok without ever fanning out; the floor
+  * makes the intended decomposition binding. The journaled decision
+  * (and a rejection's error data) carries the actual
+  * `spawnedChildren` beside the configured floor, so a resume rolls
+  * the same verdict forward. Positive integer; policy only, never
+  * part of any identity.
+  */
+  minSpawnedChildren?: number;
+  /**
   * The terminal-output salvage switch (the 1.64.0 experiment review,
   * P0.4 + P1.1; default false). When true, a child that settled
   * 'limit' CARRYING a terminal output counts as a successful child for
@@ -8129,21 +8171,26 @@ interface AgentProfile {
   estCost?: number;
   /**
   * The declared evidence contract of the profile's task (RV303, the
-  * seventh comparison experiment): how many evidence entries the
-  * spawned agent MUST record, and the declared call estimates behind
-  * them. Purely declarative, like estCost: the runtime never enforces
-  * it; {@link preflightEstimate} compares the resulting call floor
+  * seventh comparison experiment; runtime enforcement RV507): how many
+  * evidence entries the spawned agent MUST record, and the declared
+  * call estimates behind them. Under the default `enforce: 'warn'` it
+  * is purely declarative, like estCost: {@link preflightEstimate}
+  * compares the resulting call floor
   * (`minEntries * estCallsPerEntry + overheadCalls`, defaults 3 and 8)
   * against the spawn's effective executed-call ceiling and warns
   * `tool-cap-below-evidence-floor` when the cap cannot fit the
-  * contract. The experiment shape: 14 mandatory entries against an
-  * 84-call cap that two workers exhausted at 10 recorded entries.
+  * contract. Under `enforce: 'refuse'` the floor additionally binds at
+  * the terminal: an ok settle with fewer successful `record_evidence`
+  * executions than `minEntries` becomes a typed error terminal. The
+  * experiment shape: 14 mandatory entries against an 84-call cap that
+  * two workers exhausted at 10 recorded entries.
   */
   evidenceContract?: EvidenceContract;
 }
 /**
-* A declared evidence floor for preflight to judge tool caps against
-* (RV303). Declarative only; see {@link AgentProfile.evidenceContract}.
+* A declared evidence floor (RV303): preflight judges tool caps
+* against it, and under `enforce: 'refuse'` the runtime refuses an ok
+* settle below it (RV507); see {@link AgentProfile.evidenceContract}.
 */
 interface EvidenceContract {
   /** Evidence entries the task must record; positive integer. */
@@ -8152,6 +8199,19 @@ interface EvidenceContract {
   estCallsPerEntry?: number;
   /** Estimated non-evidence overhead calls; default 8. */
   overheadCalls?: number;
+  /**
+  * What the floor does at the child's terminal settle (RV507). The
+  * default 'warn' keeps the historical behavior: the contract is a
+  * preflight signal only. 'refuse' turns an ok finish whose message
+  * window carries fewer successful `record_evidence` executions
+  * (result `recorded: true`; duplicates and verification errors never
+  * count) than `minEntries` into a typed error terminal (kind
+  * 'terminal') whose journaled error data carries the machine-readable
+  * `evidenceFloor: { recordedEntries, minEntries }`; the outcome is
+  * memoized, so a resume rolls the refusal forward instead of
+  * re-paying the invocation. Non-ok terminals are never re-judged.
+  */
+  enforce?: "warn" | "refuse";
 }
 /**
 * Per-spawn options. The

package/dist/index.js

@@ -2781,17 +2781,19 @@ function requireTimerDelayMs(value, site) {
 	if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 2147483647) refuse(site, "an integer between 1 and 2147483647 ms (the Node timer maximum)", value);
 }
 /**
-* A declared evidence contract (RV303): minEntries and
-* estCallsPerEntry positive integers, overheadCalls a nonnegative
-* integer. Shared by the profile intake and the preflight spawn spec so
-* both boundaries refuse the same shapes with the same wording.
+* A declared evidence contract (RV303, enforcement RV507): minEntries
+* and estCallsPerEntry positive integers, overheadCalls a nonnegative
+* integer, enforce one of 'warn' | 'refuse'. Shared by the profile
+* intake and the preflight spawn spec so both boundaries refuse the
+* same shapes with the same wording.
 */
 function validateEvidenceContract(value, site) {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ConfigError(`${site} must be { minEntries, estCallsPerEntry?, overheadCalls? }; got ${typeof value}`);
-	const { minEntries, estCallsPerEntry, overheadCalls } = value;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ConfigError(`${site} must be { minEntries, estCallsPerEntry?, overheadCalls?, enforce? }; got ${typeof value}`);
+	const { minEntries, estCallsPerEntry, overheadCalls, enforce } = value;
 	requirePositiveInteger(minEntries, `${site}.minEntries`);
 	if (estCallsPerEntry !== void 0) requirePositiveInteger(estCallsPerEntry, `${site}.estCallsPerEntry`);
 	if (overheadCalls !== void 0) requireNonNegativeInteger(overheadCalls, `${site}.overheadCalls`);
+	if (enforce !== void 0 && enforce !== "warn" && enforce !== "refuse") throw new ConfigError(`${site}.enforce must be 'warn' or 'refuse'; got ${JSON.stringify(enforce)}`);
 }
 //#endregion
 //#region src/knowledge/file-store.ts
@@ -6601,7 +6603,7 @@ var ResolutionFold = class {
 /**
 * Per-run, per-target FIFO serializer of resolution/abandon attempts:
 * classification against the in-memory fold ->
-* durable append -> settle exactly once; losing attempts are ALSO
+* durable append -> a single settle; losing attempts are ALSO
 * appended and become journaled noops by fold classification. Winner
 * effects run strictly after the critical section (the caller's job).
 * Cross-process protection remains the LeasableStore fencing epoch.
@@ -7193,7 +7195,7 @@ var Replayer = class {
 		});
 	}
 	/**
-	* The budget ledger fold: usage sums over terminal entries exactly once; agentsSpawned
+	* The budget ledger fold: usage sums over terminal entries once, never twice; agentsSpawned
 	* counts agent dispatches.
 	*/
 	ledger() {
@@ -7762,7 +7764,7 @@ function metaMatchesFilter(meta, f) {
 * InMemoryStore (M1-T04): the default journal store. Process-local, so
 * nothing survives a process exit and cross-process resume is
 * impossible (same-process resume of a kept instance works); the store
-* warns loudly exactly once per instance unless constructed with
+* warns loudly once per instance unless constructed with
 * `quiet: true` (the deliberate choice of a test tier).
 * An in-memory TranscriptStore ships alongside for the same default.
 */
@@ -8214,7 +8216,7 @@ var FileTranscriptStore = class {
 * agent type, role 'loop').
 *
 * Inclusion policy, applied to the total and EVERY breakdown alike:
-* terminal usage exactly once, priced per serving slice, entries under
+* terminal usage once, priced per serving slice, entries under
 * abandoned subtrees contribute zero (their spend is tracked separately
 * in the abandoned-spend ledger the orchestrator sees). Attempts that
 * were paid but never abandoned (a cancelled root attempt, a dangling
@@ -11163,7 +11165,7 @@ async function runAgent(options) {
 	* Gates and executes one turn's tool calls in source order. priorParts
 	* carries results already executed before a mid-turn suspension; the
 	* pending state checkpointed at an ask verdict stores RAW model args so
-	* a resume re-runs the chain (hooks apply exactly once) and re-matches
+	* a resume re-runs the chain (hooks apply once) and re-matches
 	* the same approval identity.
 	*/
 	const runToolCalls = async (calls, priorParts) => {
@@ -12515,6 +12517,24 @@ async function runAgent(options) {
 		}
 		endPhase(extractPhase, phaseOutcome(), extractServed);
 	}
+	const evidenceFloor = options.evidenceContract;
+	let evidenceRefusal;
+	if (evidenceFloor?.enforce === "refuse" && status === "ok") {
+		const recordedEntries = messages.reduce((count, message) => count + message.parts.filter((part) => part.type === "tool-result" && part.name === "record_evidence" && part.result?.recorded === true).length, 0);
+		if (recordedEntries < evidenceFloor.minEntries) {
+			status = "error";
+			output = null;
+			evidenceRefusal = {
+				recordedEntries,
+				minEntries: evidenceFloor.minEntries
+			};
+			agentError = {
+				kind: "terminal",
+				retryable: false
+			};
+			errorMessage = `evidence contract unmet: ${String(recordedEntries)} of ${String(evidenceFloor.minEntries)} required evidence entries recorded`;
+		}
+	}
 	const limitPartial = status === "limit" ? latestProgressReport(messages) : void 0;
 	if (limitPartial !== void 0) await saveBoundary();
 	let transcriptRef = "";
@@ -12560,6 +12580,7 @@ async function runAgent(options) {
 	const schemaRejectedTerminalExchanges = terminalName === void 0 ? 0 : messages.reduce((count, message) => count + message.parts.filter((part) => part.type === "tool-result" && part.name === terminalName && part.isError === true && part.result?.error === terminalSchemaRejectionMessage(terminalName)).length, 0);
 	if (schemaRejectedTerminalExchanges > 0) result.schemaRejectedTerminalExchanges = schemaRejectedTerminalExchanges;
 	if (schemaRecoveredTerminalExchanges > 0) result.schemaRecoveredTerminalExchanges = schemaRecoveredTerminalExchanges;
+	if (evidenceRefusal !== void 0) result.evidenceFloor = evidenceRefusal;
 	if (usageApprox) result.usageApprox = true;
 	if (transportRetries > 0) result.transportRetries = transportRetries;
 	if (rateLimitObservations.size > 0) result.rateLimitObservations = [...rateLimitObservations.values()];
@@ -14754,6 +14775,7 @@ function createCtx(internals, rootWorkflow) {
 		if (finalize !== void 0) runAgentOptions.finalize = finalize;
 		runAgentOptions.summarize = summarize;
 		if (profile?.compaction !== void 0) runAgentOptions.compaction = profile.compaction;
+		if (profile?.evidenceContract !== void 0) runAgentOptions.evidenceContract = profile.evidenceContract;
 		if (loopFallbacks.length > 0) runAgentOptions.fallbacks = loopFallbacks;
 		if (retryPolicy !== void 0) runAgentOptions.retry = { policy: retryPolicy };
 		if (internals.quota !== void 0) {
@@ -14974,6 +14996,18 @@ function createCtx(internals, rootWorkflow) {
 				};
 			}
 		}
+		if (result.evidenceFloor !== void 0 && terminalPatch.error !== void 0) {
+			terminalPatch.memoizeOutcome = true;
+			const priorData = terminalPatch.error.data;
+			const dataRecord = typeof priorData === "object" && priorData !== null && !Array.isArray(priorData) ? priorData : {};
+			terminalPatch.error = {
+				...terminalPatch.error,
+				data: {
+					...dataRecord,
+					evidenceFloor: result.evidenceFloor
+				}
+			};
+		}
 		if (checkpointWritten) terminalPatch.checkpointRef = ckptRef;
 		const terminal = await internals.replayer.appendTerminal(running.seq, terminalPatch);
 		internals.events.emit({
@@ -16044,7 +16078,7 @@ const MAX_LISTED_EXTRA_HEADINGS = 5;
 * heading nor trip exclusivity. Heading lines compare trimmed, whole
 * line. With `ordered` (default true) the declared headings must
 * appear in declaration order; with `exclusive` (default true) each
-* declared heading must appear exactly once and no undeclared heading
+* declared heading must appear once, unrepeated, and no undeclared heading
 * of the governed level may exist (other levels stay free). Default
 * name 'heading-structure'.
 */
@@ -16216,7 +16250,10 @@ function listCitations(values) {
 * {@link DEFAULT_EVIDENCE_MIN_SHARE}, the plan's 95 percent gate,
 * compared as a ceiling on the required count so an exact boundary like
 * 19 of 20 passes) must appear literally in the result text. Zero child
-* citations pass vacuously. With `requireKnown: true` the contract also
+* citations pass vacuously UNLESS `requireNonEmptyPool: true` (RV507):
+* for an evidence-critical run the empty pool IS the failure, so that
+* mode refuses it with an `empty child citation pool` reason instead of
+* the vacuous pass. With `requireKnown: true` the contract also
 * runs in reverse: every citation in the RESULT must appear in some
 * child's output, so a fabricated but pattern valid citation is
 * rejected instead of silently counting as evidence. Rejection reasons
@@ -16245,6 +16282,7 @@ function evidencePreservedValidator(options) {
 				for (const match of child.text.match(new RegExp(pattern, globalFlags)) ?? []) cited.add(match);
 			}
 			const reasons = [];
+			if (cited.size === 0 && options?.requireNonEmptyPool === true) reasons.push("empty child citation pool: no ok child output contains a citation matching the pattern");
 			if (cited.size > 0) {
 				const missing = [...cited].filter((citation) => !input.text.includes(citation));
 				const preserved = cited.size - missing.length;
@@ -16774,6 +16812,8 @@ function validateOrchestrateOptions(opts) {
 		if (acceptPartial !== void 0 && typeof acceptPartial !== "boolean") throw new ConfigError(`orchestrate acceptance.acceptPartialChildren must be a boolean; got ${typeof acceptPartial}`);
 		const acceptOutput = opts.acceptance.acceptValidatedTerminalOutputOnLimit;
 		if (acceptOutput !== void 0 && typeof acceptOutput !== "boolean") throw new ConfigError("orchestrate acceptance.acceptValidatedTerminalOutputOnLimit must be a boolean; got " + typeof acceptOutput);
+		const minSpawned = opts.acceptance.minSpawnedChildren;
+		if (minSpawned !== void 0) requirePositiveInteger(minSpawned, "orchestrate acceptance.minSpawnedChildren");
 	}
 	if (opts.finishValidation !== void 0) {
 		const fv = opts.finishValidation;
@@ -18530,7 +18570,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 				degradedReasons.push(status === "running" ? `child ${record.nodeId} was still running when finish validated` : `child ${record.nodeId} settled '${status}'`);
 			}
 			const childPolicy = opts.acceptance.childPolicy;
-			const accepted = childPolicy === "all-ok" ? hardDegraded === 0 : (childStatusCounts.ok ?? 0) + salvaged.length + salvagedOutput.length >= childPolicy.minSuccessful;
+			const minSpawned = opts.acceptance.minSpawnedChildren;
+			const rosterMet = minSpawned === void 0 || sortedRecords.length >= minSpawned;
+			if (!rosterMet) degradedReasons.push(`only ${String(sortedRecords.length)} children were spawned; the acceptance policy requires at least ${String(minSpawned)} spawned children`);
+			const accepted = rosterMet && (childPolicy === "all-ok" ? hardDegraded === 0 : (childStatusCounts.ok ?? 0) + salvaged.length + salvagedOutput.length >= childPolicy.minSuccessful);
 			decision = {
 				decisionType: "orchestrator_acceptance",
 				verdict: accepted ? "accepted" : "rejected",
@@ -18538,6 +18581,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 				childPolicy,
 				childStatusCounts,
 				degradedReasons,
+				...minSpawned === void 0 ? {} : {
+					minSpawnedChildren: minSpawned,
+					spawnedChildren: sortedRecords.length
+				},
 				...salvaged.length === 0 ? {} : { salvagedPartialChildren: salvaged },
 				...salvagedOutput.length === 0 ? {} : { salvagedTerminalOutputChildren: salvagedOutput },
 				...accepted || opts.synthesis === void 0 ? {} : { synthesisSkipped: "synthesis_skipped_by_acceptance" }
@@ -18559,13 +18606,17 @@ function makeOrchestratorWorkflow(goal, opts) {
 				msg: "orchestrator synthesis skipped",
 				data: { reason: decision.synthesisSkipped }
 			}, callingState.spanId);
-			const required = decision.childPolicy === "all-ok" ? "every child ok" : `at least ${String(decision.childPolicy.minSuccessful)} children ok`;
+			const required = (decision.childPolicy === "all-ok" ? "every child ok" : `at least ${String(decision.childPolicy.minSuccessful)} children ok`) + (decision.minSpawnedChildren === void 0 ? "" : `, with at least ${String(decision.minSpawnedChildren)} spawned children`);
 			throw new FailRunError(`the orchestrator acceptance policy rejected the finish: ${String(decision.childStatusCounts.ok ?? 0)} children settled 'ok' but the policy requires ${required}; degraded: ${decision.degradedReasons.join("; ")}`, { data: {
 				source: "orchestrator_acceptance",
 				completion: "rejected",
 				childPolicy: decision.childPolicy,
 				childStatusCounts: decision.childStatusCounts,
 				degradedReasons: decision.degradedReasons,
+				...decision.minSpawnedChildren === void 0 ? {} : {
+					minSpawnedChildren: decision.minSpawnedChildren,
+					spawnedChildren: decision.spawnedChildren ?? 0
+				},
 				...decision.salvagedPartialChildren === void 0 ? {} : { salvagedPartialChildren: decision.salvagedPartialChildren },
 				...decision.salvagedTerminalOutputChildren === void 0 ? {} : { salvagedTerminalOutputChildren: decision.salvagedTerminalOutputChildren },
 				...decision.synthesisSkipped === void 0 ? {} : { synthesisSkipped: decision.synthesisSkipped }

package/package.json

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