@rulvar/core 1.235.0 → 1.237.0

package/dist/index.d.ts

@@ -1217,6 +1217,15 @@ type RunMeta = {
     allowUnpriced?: string[];
   };
   /**
+  * The host-declared config identity (RunOptions.configFingerprint,
+  * RV3210): an opaque pin over what the workflow body closes over,
+  * recorded at genesis and compared on every resume that asserts one.
+  * Absent when the run declared none. A store that drops the field
+  * degrades the check to the UNRECORDED warning, never a false pass
+  * or a false refusal (absence means NOT RECORDED).
+  */
+  configFingerprint?: string;
+  /**
   * Count of execution segments this run has STARTED (a fresh start
   * writes 1; every resume writes prior + 1, durably, BEFORE the
   * segment emits its first event). The engine derives each segment's
@@ -1670,6 +1679,46 @@ interface TerminalEnvelope {
   /** Agents admitted over the run's lifetime, resume seed included. */
   agentsSpawned: number;
   /**
+  * Whether the artifact this terminal carries passed the declared
+  * finish contract (RV2506), mirrored onto the envelope since RV3304:
+  * the 2026-08-12 comparison run settled ok/complete over a retained
+  * contradiction, and neither the HTTP response nor the persisted
+  * rebuild could say whether anything ever judged the deliverable.
+  * Absent when no contract judged anything; absence means NOT
+  * RECORDED, never "accepted".
+  */
+  deliverableAccepted?: boolean;
+  /**
+  * Whether this terminal carries a deliverable to read at all
+  * (RV2506); same mirror and posture. Distinct from
+  * `deliverableAccepted`: an unjudged artifact still EXISTS, and a
+  * run with no artifact still has a completion claim.
+  */
+  resultAvailable?: boolean;
+  /**
+  * The journal seq of the decision entry recording the acceptance of
+  * the artifact this terminal carries (RV2506); same mirror, absent
+  * unless the acceptance actually rendered. Read it with
+  * `rulvar inspect` to see WHICH validators accepted WHICH hash.
+  */
+  acceptedArtifactRef?: number;
+  /**
+  * The claim consistency pass meta, detached (RV3304): `judgedStage`,
+  * `judgedHash`, the coverage grade and the `findings` count, so the
+  * surface a consumer gates on says WHAT was semantically verified,
+  * over WHICH document, and what the judge found, without reaching
+  * into the workflow value. Mutating this copy never touches the
+  * outcome the engine owns.
+  */
+  claimConsistencyMeta?: Record<string, unknown>;
+  /**
+  * The host declared config identity the run was started under
+  * (RV3210), echoed here since RV3304 so a decision consumer binds
+  * the verdict above to the configuration that produced it without a
+  * second read of the run record. Absent when the run declared none.
+  */
+  configFingerprint?: string;
+  /**
   * Where THIS copy of the envelope was assembled (RV1209). Absent, the
   * historical byte contract, means the settlement chokepoint built it
   * from the live outcome, so every field above is the run's own
@@ -7784,6 +7833,24 @@ interface RunOptions {
   /** Explicit id; otherwise the engine mints a ULID. */
   runId?: string;
   /**
+  * An opaque host-declared identity over the config the workflow body
+  * CLOSES OVER (RV3210, the honest answer to `hashWorkflowBody`'s
+  * closure blindness: the body-text hash cannot see captured values,
+  * so two byte-identical bodies over different closures pin
+  * identically). Recorded in RunMeta at genesis and compared on every
+  * resume that supplies one: a mismatch refuses the resume typed
+  * BEFORE ownership, meta writes, and appends, because the host
+  * itself asserted the identity; a recorded fingerprint the resume
+  * does not supply warns (`RULVAR_RESUME_FINGERPRINT_UNCHECKED`), and
+  * a supplied fingerprint the run never recorded warns
+  * (`RULVAR_RESUME_FINGERPRINT_UNRECORDED`) instead of failing,
+  * because absence means NOT RECORDED. The preferred pattern is still
+  * to close over nothing and pass config through args; the
+  * fingerprint is the pin for what must stay closed over. A non-empty
+  * string of at most 512 characters.
+  */
+  configFingerprint?: string;
+  /**
   * Run ceiling B0; immutable after start. Enforced by projected
   * admission (a spawn whose reserve does not fit is denied before any
   * dispatch), the per-turn guard with a budget-derived maxOutputTokens
@@ -7931,6 +7998,18 @@ interface ResumeOptions {
   */
   bodyHash?: "warn" | "refuse";
   /**
+  * The host's asserted config identity for this resume (RV3210),
+  * compared against the RunMeta-recorded
+  * {@link RunOptions.configFingerprint} BEFORE ownership, meta
+  * writes, or any append. Both present and unequal is a typed
+  * ConfigError always, no posture knob: supplying the fingerprint IS
+  * the assertion. A recorded fingerprint the resume does not supply
+  * warns (`RULVAR_RESUME_FINGERPRINT_UNCHECKED`); a supplied one the
+  * run never recorded warns (`RULVAR_RESUME_FINGERPRINT_UNRECORDED`),
+  * because absence means NOT RECORDED, never a verdict.
+  */
+  configFingerprint?: string;
+  /**
   * Dry-run: replay-strict matching; the first would-be-live call throws
   * JournalMissError and the run settles with that typed error, zero live
   * calls performed.
@@ -10322,7 +10401,12 @@ interface OrchestrateClaimConsistency {
   * explicitly (a ConfigError without that synthesis, the
   * contradictions precedent), and non-empty findings block the
   * `skipWhenDraftValid` gate: a draft contradicting its own pool
-  * never earns the skip. 'fail' fails the run typed with
+  * never earns the skip. The carry can only ride a prompt that still
+  * lies ahead, so it binds the pass that runs BEFORE the synthesis:
+  * under `stage: 'both'` the draft pass carries and the final pass
+  * reports, and `stage: 'final'` with 'carry' is a ConfigError at
+  * intake, because a posture that reads as a gate must not quietly
+  * behave as 'report'. 'fail' fails the run typed with
   * `data.source` 'orchestrator_claim_consistency' BEFORE any
   * synthesis dispatch; the judge itself has already been paid, which
   * is the honest minimum for a semantic verdict. A judge that does
@@ -10546,6 +10630,18 @@ interface OrchestrateClaimConsistencyMeta {
   */
   judgeDeclined?: true;
   /**
+  * How many judged contradictions the pass FOUND on the judged
+  * document, present exactly when the judge settled ok (RV3304): `0`
+  * is a clean verdict, a positive count is a disagreement that stayed
+  * wherever the posture did not stop the run. The findings themselves
+  * ride `claimContradictions` beside this meta on the acceptance
+  * envelope, but the meta travels ALONE onto RunOutcome, the
+  * journaled run settle, and the terminal envelope, and the
+  * 2026-08-12 comparison run settled ok/complete over a retained
+  * finding no terminal surface could count.
+  */
+  findings?: number;
+  /**
   * The one field a consumer reads INSTEAD of inferring semantic
   * health from an empty findings array (RV1702):
   * {@link claimCoverageOf} over this meta, so `completion:
@@ -12116,7 +12212,7 @@ interface RunHandle<R> {
 //#endregion
 //#region src/engine/terminal-envelope.d.ts
 /** The outcome facts the assembler reads; a structural subset of RunOutcome. */
-type TerminalOutcomeFacts = Pick<RunOutcome<unknown>, "status" | "error" | "completion"> & {
+type TerminalOutcomeFacts = Pick<RunOutcome<unknown>, "status" | "error" | "completion" | "deliverableAccepted" | "resultAvailable" | "acceptedArtifactRef" | "claimConsistencyMeta"> & {
   usage: RunOutcome<unknown>["usage"];
   cost: Pick<RunOutcome<unknown>["cost"], "totalUsd" | "grossUsd" | "byModel"> & {
     usageApprox?: boolean;
@@ -12144,7 +12240,8 @@ declare function terminalEnvelopeOf(input: {
   settlement?: {
     settledReason?: "superseded";
   };
-  provenance?: "journal";
+  provenance?: "journal"; /** The run's declared config identity (RV3210), echoed onto the envelope (RV3304). */
+  configFingerprint?: string;
 }): TerminalEnvelope;
 //#endregion
 //#region src/l0/decision-chain.d.ts
@@ -13036,6 +13133,18 @@ declare function lastRunSettle(entries: readonly JournalEntry[]): {
   * recorded" rather than as a claim.
   */
   rejectedFinishCandidates?: RejectedFinishCandidate[];
+  /**
+  * The semantic outcome the settle recorded (RV3304), read back
+  * the same defensive way: the acceptance verdict, the
+  * deliverable presence, the acceptance ref and the judge meta,
+  * so a restarted reader recovers the facts a live consumer
+  * gated on. Absent on journals written before the lift carried
+  * them; absence means NOT RECORDED, never a verdict.
+  */
+  deliverableAccepted?: boolean;
+  resultAvailable?: boolean;
+  acceptedArtifactRef?: number;
+  claimConsistencyMeta?: Record<string, unknown>;
 } | undefined;
 /**
 * Whether a terminal figure counts THIS segment's work or the whole
@@ -14016,6 +14125,17 @@ interface StatementReconciliation {
   componentToleranceUsd: number;
   verdict: "match" | "divergence" | "partial-coverage" | "no-overlap";
   /**
+  * How much of the MATCHED statement claims money (RV3306):
+  * 'complete' when every matched export row (requests mode) or every
+  * component line (categories mode) carries a dollar claim, a row
+  * total or a component split; 'partial' when some do; 'none' when
+  * the statement matched on identity and usage alone, or matched
+  * nothing. Kept apart from row coverage on purpose: coverage says
+  * the records line up, this says whether the provider actually
+  * stated dollars over them.
+  */
+  dollarCoverage: "complete" | "partial" | "none";
+  /**
   * The settlement-grade composite, first class (RV1006): true exactly
   * when the verdict is 'match' AND coverage is complete AND no row's
   * usage is unknown AND no model went unpriced. A 'match' alone is
@@ -14024,9 +14144,22 @@ interface StatementReconciliation {
   * consumer must not assemble this predicate by hand. The last two
   * conditions overlap today's verdict semantics deliberately: the
   * predicate states the full contract so it cannot drift apart from
-  * a future verdict refinement.
+  * a future verdict refinement. Note what it does NOT require: a
+  * dollar claim. A usage-only export that matches on identity and
+  * tokens reads `settleable: true`; gate MONETARY closure on
+  * `monetarySettleable` below.
   */
   settleable: boolean;
+  /**
+  * The MONETARY settlement predicate (RV3306): `settleable` AND
+  * complete dollar coverage. `settleable` answers "do the records
+  * agree"; this answers "may money close against this statement".
+  * The 2026-08-12 audit named the difference on this exact module: a
+  * usage-only request export settled 'match' without one dollar of
+  * provider evidence, and a finance pipeline gating on `settleable`
+  * alone would have closed money against it.
+  */
+  monetarySettleable: boolean;
 }
 /**
 * Reconciles the invoice against a normalized provider export. Pure and
@@ -14304,6 +14437,17 @@ interface PreflightOrchestratorSpec {
   * the finding entirely. Default 2.
   */
   headroomTurns?: number;
+  /**
+  * The `ceiling-headroom-thin` threshold as a fraction of the ceiling
+  * (RV3208, the 2026-08-11 experiment's admission cliff: a $7.00
+  * ceiling over a $6.80 required minimum left 2.86 percent headroom,
+  * and a small pricing or context drift would have refused the whole
+  * workflow at admission). The finding warns when
+  * `ceilingHeadroomShare` sits below this fraction. A number in
+  * [0, 1]; 0 (the default) keeps the finding silent, so declared
+  * configs are byte identical until a host opts in.
+  */
+  minCeilingHeadroomShare?: number;
 }
 /** The full input: engine surface, run surface, and the declared wave. */
 interface PreflightInput {
@@ -14531,6 +14675,20 @@ interface PreflightReport {
     */
     requiredMinimumCeilingUsd?: number;
     /**
+    * The ceiling minus the required minimum (RV3208): the absolute
+    * dollars of drift the admission survives before the wave stops
+    * seating. Present beside requiredMinimumCeilingUsd whenever a
+    * ceiling is declared.
+    */
+    ceilingHeadroomUsd?: number;
+    /**
+    * The same headroom as a fraction of the ceiling (RV3208): the
+    * one-field read of the admission cliff (the 2026-08-11 experiment
+    * ran at 0.0286). Present beside ceilingHeadroomUsd on positive
+    * ceilings.
+    */
+    ceilingHeadroomShare?: number;
+    /**
     * The live-root-exposure term of the wave projection (RV2004): the
     * orchestrator's own worst-case turn floor, the money coordination
     * has ALWAYS already spent (and holds in flight) by the time any

package/dist/index.js

@@ -1327,6 +1327,20 @@ function detachedError(error) {
 	}
 }
 /**
+* A detached copy of the judge meta (RV3304), the `detachedError`
+* posture: Json shaped by construction, so a structured clone
+* reproduces it exactly, and a host that smuggled something exotic
+* past the type falls back to a shallow copy rather than throwing at
+* the settlement chokepoint.
+*/
+function detachedMeta(meta) {
+	try {
+		return structuredClone(meta);
+	} catch {
+		return { ...meta };
+	}
+}
+/**
 * Assembles one terminal envelope (RV1105). `settlement` present means
 * nothing durable records the terminal: `settled` reads false, and the
 * optional `settledReason: 'superseded'` names the fenced-out segment
@@ -1356,6 +1370,11 @@ function terminalEnvelopeOf(input) {
 	};
 	if (outcome.error !== void 0) envelope.error = detachedError(outcome.error);
 	if (outcome.completion !== void 0) envelope.completion = outcome.completion;
+	if (outcome.deliverableAccepted !== void 0) envelope.deliverableAccepted = outcome.deliverableAccepted;
+	if (outcome.resultAvailable !== void 0) envelope.resultAvailable = outcome.resultAvailable;
+	if (outcome.acceptedArtifactRef !== void 0) envelope.acceptedArtifactRef = outcome.acceptedArtifactRef;
+	if (outcome.claimConsistencyMeta !== void 0) envelope.claimConsistencyMeta = detachedMeta(outcome.claimConsistencyMeta);
+	if (input.configFingerprint !== void 0) envelope.configFingerprint = input.configFingerprint;
 	if (outcome.cost.wireRequests !== void 0) envelope.wireRequests = outcome.cost.wireRequests;
 	if (input.settlement?.settledReason !== void 0) envelope.settledReason = input.settlement.settledReason;
 	if (input.provenance !== void 0) envelope.provenance = input.provenance;
@@ -8806,17 +8825,36 @@ function lastRunSettle(entries) {
 		if (value?.decisionType === "run_settle" && typeof value.runStatus === "string" && RUN_STATUSES.has(value.runStatus)) {
 			const completion = value.completion;
 			const rejected = readRejectedFinishCandidates(value.rejectedFinishCandidates);
+			const judgeMeta = readClaimConsistencyMeta(value.claimConsistencyMeta);
 			return {
 				runStatus: value.runStatus,
 				seq: entry.seq,
 				...typeof value.outputHash === "string" ? { outputHash: value.outputHash } : {},
 				...completion === "complete" || completion === "partial" || completion === "rejected" ? { completion } : {},
-				...rejected === void 0 ? {} : { rejectedFinishCandidates: rejected }
+				...rejected === void 0 ? {} : { rejectedFinishCandidates: rejected },
+				...typeof value.deliverableAccepted === "boolean" ? { deliverableAccepted: value.deliverableAccepted } : {},
+				...typeof value.resultAvailable === "boolean" ? { resultAvailable: value.resultAvailable } : {},
+				...typeof value.acceptedArtifactRef === "number" && Number.isSafeInteger(value.acceptedArtifactRef) && value.acceptedArtifactRef >= 0 ? { acceptedArtifactRef: value.acceptedArtifactRef } : {},
+				...judgeMeta === void 0 ? {} : { claimConsistencyMeta: judgeMeta }
 			};
 		}
 	}
 }
 /**
+* The judge meta of a persisted settle, or `undefined` (RV3304). The
+* whole object drops unless its load bearing fields are shaped as the
+* live producer writes them (`judgeInvoked`, the coverage grade, the
+* judged stage and hash): a partially shaped meta read as a verdict
+* would claim semantic ground the journal does not hold, the same
+* posture as `readRejectedFinishCandidates`.
+*/
+function readClaimConsistencyMeta(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return;
+	const meta = raw;
+	if (typeof meta.judgeInvoked !== "boolean" || typeof meta.coverage !== "string" || meta.judgedStage !== "draft" && meta.judgedStage !== "final" || typeof meta.judgedHash !== "string") return;
+	return { ...raw };
+}
+/**
 * The rejected finish candidates of a persisted settle, or `undefined`
 * (RV2605). The WHOLE list drops on any malformed row, the same posture
 * the live lift takes (RV2507): a partial history read as complete
@@ -9286,6 +9324,21 @@ function reduceInvocationTable(events) {
 */
 const CLAIM_JUDGE_LABEL = "claim-consistency-judge";
 /**
+* Whether a synthesize span's label names a claim-consistency judge
+* invocation: the exact {@link CLAIM_JUDGE_LABEL}, or a suffixed
+* variant of it (the final pass dispatches under
+* `claim-consistency-judge-final` since RV2509 so the two passes of
+* `stage: 'both'` stay separable). BOTH reducers must classify through
+* this one predicate (RV3302): the live fold compared the label for
+* exact equality while the journal fold accepted the suffix, and the
+* 2026-08-12 comparison run reported semanticJudgeMs 0 with the whole
+* 272923 ms window read as final composition on the live surface
+* while the journal fold correctly split 224864 against 48059.
+*/
+function isClaimJudgeLabel(label) {
+	return label === "claim-consistency-judge" || (label?.startsWith(`claim-consistency-judge-`) ?? false);
+}
+/**
 * The label the final synthesis (composition) invocation dispatches
 * under (RV2901). The engine labelling its OWN dispatches is what lets
 * `criticalPathFromJournal` split the synthesize bucket offline: the
@@ -9366,7 +9419,7 @@ function reduceCriticalPath(events) {
 				if (started === void 0) break;
 				if (started.role === "synthesize") {
 					const wall = Math.max(0, at - started.at);
-					const judge = started.label === CLAIM_JUDGE_LABEL;
+					const judge = isClaimJudgeLabel(started.label);
 					synthesisMs += wall;
 					if (judge) semanticJudgeMs += wall;
 					else finalCompositionMs += wall;
@@ -9510,7 +9563,7 @@ function criticalPathFromJournal(entries) {
 			continue;
 		}
 		labelledSynthesis = true;
-		if (label === "claim-consistency-judge" || label.startsWith(`claim-consistency-judge-`)) semanticJudgeMs += wall;
+		if (isClaimJudgeLabel(label)) semanticJudgeMs += wall;
 		else finalCompositionMs += wall;
 	}
 	const segments = logicalRunTelemetry(ordered).segments;
@@ -16111,6 +16164,7 @@ function reconcileStatement(invoice, statement, options) {
 	let statementComponents;
 	let matchedStatementRows = 0;
 	let matchedUsdRows = 0;
+	let matchedDollarRows = 0;
 	let tokenMismatches = 0;
 	let partialOverlap = false;
 	const tokenMismatchSample = [];
@@ -16215,6 +16269,7 @@ function reconcileStatement(invoice, statement, options) {
 		for (const row of statement.rows) {
 			if (!matchedStatement.has(row.responseId)) continue;
 			matchedStatementRows += 1;
+			if (row.usd !== void 0 || row.componentsUsd !== void 0) matchedDollarRows += 1;
 			if (row.usd !== void 0) {
 				matchedUsdRows += 1;
 				totalSeen = true;
@@ -16320,6 +16375,10 @@ function reconcileStatement(invoice, statement, options) {
 	else if (matchedRows === 0 && !partialOverlap) verdict = "no-overlap";
 	else if (!coverageComplete) verdict = "partial-coverage";
 	else verdict = "match";
+	const dollarClaims = statement.kind === "requests" ? matchedDollarRows : components.filter((line) => line.statementUsd !== void 0).length;
+	const dollarSlots = statement.kind === "requests" ? matchedStatementRows : components.length;
+	const dollarCoverage = dollarSlots > 0 && dollarClaims === dollarSlots ? "complete" : dollarClaims > 0 ? "partial" : "none";
+	const settleable = verdict === "match" && coverageComplete && usageUnknownRows === 0 && unpricedModels.size === 0;
 	return {
 		mode: statement.kind,
 		coverage: {
@@ -16345,7 +16404,9 @@ function reconcileStatement(invoice, statement, options) {
 		usageUnknownRows,
 		componentToleranceUsd,
 		verdict,
-		settleable: verdict === "match" && coverageComplete && usageUnknownRows === 0 && unpricedModels.size === 0
+		dollarCoverage,
+		settleable,
+		monetarySettleable: settleable && dollarCoverage === "complete"
 	};
 }
 /** A cell that is absent by export convention: missing, null, or ''. */
@@ -16587,10 +16648,15 @@ function persistedTerminalEnvelope(input) {
 			outcome: {
 				status: settle.runStatus,
 				...settle.completion === void 0 ? {} : { completion: settle.completion },
+				...settle.deliverableAccepted === void 0 ? {} : { deliverableAccepted: settle.deliverableAccepted },
+				...settle.resultAvailable === void 0 ? {} : { resultAvailable: settle.resultAvailable },
+				...settle.acceptedArtifactRef === void 0 ? {} : { acceptedArtifactRef: settle.acceptedArtifactRef },
+				...settle.claimConsistencyMeta === void 0 ? {} : { claimConsistencyMeta: settle.claimConsistencyMeta },
 				usage: ledger.usage,
 				cost: costReportFromJournal(input.entries, input.priceUsd)
 			},
 			agentsSpawned: ledger.agentsSpawned,
+			...input.meta?.configFingerprint === void 0 ? {} : { configFingerprint: input.meta.configFingerprint },
 			provenance: "journal"
 		})
 	};
@@ -22549,6 +22615,7 @@ function validateOrchestrateOptions(opts) {
 		const stage = consistency.stage ?? "draft";
 		if (stage !== "draft" && stage !== "final" && stage !== "both") throw new ConfigError("orchestrate claimConsistency.stage must be 'draft', 'final' or 'both'; got " + JSON.stringify(consistency.stage));
 		if (stage !== "draft" && opts.synthesis === void 0) throw new ConfigError(`orchestrate claimConsistency.stage '${stage}' requires synthesis: without the post-fan-in invocation the coordination draft IS the final artifact, and the default 'draft' already judges it`);
+		if (stage === "final" && onFound === "carry") throw new ConfigError("orchestrate claimConsistency.onFound 'carry' cannot pair with stage 'final': the final pass runs after the synthesis, so there is no prompt left to carry the findings into; use 'report' or 'fail', or keep a carried draft pass with stage 'both'");
 		if (consistency.pattern !== void 0) {
 			if (typeof consistency.pattern !== "string") throw new ConfigError(`orchestrate claimConsistency.pattern must be a string; got ${typeof consistency.pattern}`);
 			let probe;
@@ -24848,7 +24915,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 				reason
 			}));
 			claimFindingsFound = findings;
-			claimConsistencyMeta = finishMeta({ judgeInvoked: true });
+			claimConsistencyMeta = finishMeta({
+				judgeInvoked: true,
+				findings: findings.length
+			});
 			announce();
 			if (onFound !== "fail" || findings.length === 0) return;
 			throw new FailRunError(`the claim-consistency judge found ${String(findings.length)} contradiction${findings.length === 1 ? "" : "s"} between the draft and the settled child pool: ` + findings.map((finding) => `${finding.anchor} (${finding.reason})`).join("; "), { data: {
@@ -26769,6 +26839,14 @@ function preflightEstimate(input) {
 		code: "reserve-line-headroom",
 		message: `the admitted wave's steady state sits ${reserveLineHeadroomUsd.toFixed(4)} USD under the reserve line ${reserveLineUsd.toFixed(4)} USD (the ceiling minus the synthesis reserve), less than ${String(headroomTurns)} coordination turn floors of headroom (${liveRootExposureTermUsd.toFixed(4)} USD each): child spend past the declared estimates eats that headroom, the coordination loop is then refused at the line, and the run settles partial with the synthesis redeemed from its reserve (RV2101); size the wave below the line or raise the ceiling to keep coordinating past it`
 	});
+	const ceilingHeadroomUsd = ceilingUsd === void 0 || requiredMinimumCeilingUsd === void 0 ? void 0 : ceilingUsd - requiredMinimumCeilingUsd;
+	const ceilingHeadroomShare = ceilingHeadroomUsd === void 0 || ceilingUsd === void 0 || ceilingUsd <= 0 ? void 0 : ceilingHeadroomUsd / ceilingUsd;
+	const minCeilingHeadroomShare = input.orchestrator?.minCeilingHeadroomShare ?? 0;
+	if (ceilingHeadroomShare !== void 0 && minCeilingHeadroomShare > 0 && ceilingHeadroomShare < minCeilingHeadroomShare) say({
+		severity: "warning",
+		code: "ceiling-headroom-thin",
+		message: `the ceiling headroom is ${(ceilingHeadroomShare * 100).toFixed(2)} percent of the ceiling (${(ceilingHeadroomUsd ?? 0).toFixed(4)} USD over the required minimum ${(requiredMinimumCeilingUsd ?? 0).toFixed(4)} USD), below the declared ${(minCeilingHeadroomShare * 100).toFixed(2)} percent floor: a small pricing or context drift refuses the whole wave at admission; raise the ceiling or slim the wave`
+	});
 	{
 		const judgeEstUsd = input.orchestrator?.claimConsistency?.judge?.estCost;
 		if (judgeEstUsd !== void 0 && effectiveCapUsd !== void 0 && synthesisHoldUsd > 0) {
@@ -27052,6 +27130,8 @@ function preflightEstimate(input) {
 			reservedForFinalizationUsd,
 			synthesisReserveUsd: synthesisHoldUsd,
 			...requiredMinimumCeilingUsd === void 0 ? {} : { requiredMinimumCeilingUsd },
+			...ceilingHeadroomUsd === void 0 ? {} : { ceilingHeadroomUsd },
+			...ceilingHeadroomShare === void 0 ? {} : { ceilingHeadroomShare },
 			...liveRootExposureTermUsd > 0 ? { liveRootExposureTermUsd } : {},
 			...reserveLineUsd === void 0 ? {} : { reserveLineUsd },
 			...reserveLineHeadroomUsd === void 0 ? {} : { reserveLineHeadroomUsd },
@@ -27588,6 +27668,10 @@ function parseDeadlineAt(value) {
 	if (month < 1 || month > 12 || day < 1 || day > daysInMonth) refuse();
 	return parsed;
 }
+/** Validates a declared config fingerprint (RV3210): a non-empty string of at most 512 chars. */
+function requireConfigFingerprint(value, site) {
+	if (typeof value !== "string" || value.length === 0 || value.length > 512) throw new ConfigError(`${site} must be a non-empty string of at most 512 characters; got ` + (typeof value === "string" ? `${String(value.length)} characters` : JSON.stringify(value)));
+}
 /** Content hash of an in-process workflow body (run-to-definition binding). */
 function hashWorkflowBody(wf) {
 	return createHash("sha256").update(wf.body.toString(), "utf8").digest("hex");
@@ -27894,6 +27978,7 @@ function createEngine(options) {
 		if (wf.kind !== "workflow" && wf.kind !== "compiled-workflow") throw new ConfigError("engine.run accepts in-process Workflow values or compileScript CompiledWorkflow values");
 		if (opts?.budgetUsd !== void 0) requireNonNegativeNumber(opts.budgetUsd, "RunOptions.budgetUsd");
 		if (opts?.maxInFlightExposureUsd !== void 0) requireNonNegativeNumber(opts.maxInFlightExposureUsd, "RunOptions.maxInFlightExposureUsd");
+		if (opts?.configFingerprint !== void 0) requireConfigFingerprint(opts.configFingerprint, "RunOptions.configFingerprint");
 		if (opts?.clampTurnToExposure !== void 0 && typeof opts.clampTurnToExposure !== "boolean") throw new ConfigError("RunOptions.clampTurnToExposure must be a boolean; got " + JSON.stringify(opts.clampTurnToExposure));
 		if (opts?.strictPricing !== void 0 && typeof opts.strictPricing !== "boolean" && (typeof opts.strictPricing !== "object" || opts.strictPricing === null || Array.isArray(opts.strictPricing))) throw new ConfigError("RunOptions.strictPricing must be a boolean or an options object; got " + JSON.stringify(opts.strictPricing));
 		if (opts?.limits !== void 0) validateUsageLimits(opts.limits, "RunOptions.limits");
@@ -27929,6 +28014,7 @@ function createEngine(options) {
 			...opts.strictPricing.maxRatesAgeDays === void 0 ? {} : { maxRatesAgeDays: opts.strictPricing.maxRatesAgeDays },
 			...opts.strictPricing.allowUnpriced === void 0 ? {} : { allowUnpriced: [...opts.strictPricing.allowUnpriced] }
 		};
+		const configFingerprint = opts?.configFingerprint ?? resumeCtx?.configFingerprint;
 		const makeBudget = () => new RunBudget({
 			...ceilingUsd === void 0 ? {} : { ceilingUsd },
 			...exposureCapUsd === void 0 ? {} : { maxInFlightExposureUsd: exposureCapUsd },
@@ -28109,6 +28195,7 @@ function createEngine(options) {
 			...ceilingUsd === void 0 ? {} : { budgetUsd: ceilingUsd },
 			...exposureCapUsd === void 0 ? {} : { maxInFlightExposureUsd: exposureCapUsd },
 			...strictPricing === void 0 ? {} : { strictPricing },
+			...configFingerprint === void 0 ? {} : { configFingerprint },
 			...argsBinding.argsProvided === void 0 ? {} : { argsProvided: argsBinding.argsProvided },
 			...argsBinding.argsHash === void 0 ? {} : { argsHash: argsBinding.argsHash },
 			...genesis === void 0 ? {} : { genesis },
@@ -28402,6 +28489,7 @@ function createEngine(options) {
 				workflow: wf.name,
 				outcome: outcomeFacts,
 				agentsSpawned: budget.spent().agentsSpawned,
+				...configFingerprint === void 0 ? {} : { configFingerprint },
 				...settlementFailure !== void 0 ? { settlement: {} } : supersededBy !== void 0 ? { settlement: { settledReason: "superseded" } } : {}
 			});
 			const outcome = {
@@ -28508,6 +28596,20 @@ function createEngine(options) {
 				}
 				bound = supplied;
 			}
+			{
+				const supplied = resumeOptions?.configFingerprint;
+				if (supplied !== void 0) requireConfigFingerprint(supplied, "ResumeOptions.configFingerprint");
+				const recorded = typeof meta?.configFingerprint === "string" ? meta.configFingerprint : void 0;
+				if (supplied !== void 0 && recorded !== void 0 && supplied !== recorded) throw new ConfigError(`resume: the supplied configFingerprint does not match the one run '${runId}' recorded at genesis; the config the workflow closes over changed, and the host declared exactly this check. Resume under the original config, or drop the option to proceed under the loud warning`);
+				if (supplied !== void 0 && recorded === void 0) process.emitWarning(`resume: a configFingerprint was supplied but run '${runId}' never recorded one; the assertion cannot be verified (absence means NOT RECORDED)`, {
+					code: "RULVAR_RESUME_FINGERPRINT_UNRECORDED",
+					type: "RulvarWarning"
+				});
+				if (supplied === void 0 && recorded !== void 0) process.emitWarning(`resume: run '${runId}' recorded a configFingerprint at genesis and this resume did not supply one; the declared config identity goes unchecked`, {
+					code: "RULVAR_RESUME_FINGERPRINT_UNCHECKED",
+					type: "RulvarWarning"
+				});
+			}
 			const priorEntries = (await journal.load(runId)).map((entry) => normalizeEntry(entry));
 			scanJournalCompatibility(runId, priorEntries, buildDeriverRegistry(options.extraDerivers));
 			if (priorEntries.some((entry) => entry.usageSemantics === void 0 && (entry.servedBy?.startsWith("openai:") === true && (entry.usage?.cacheWriteTokens ?? 0) > 0 || (entry.usageByModel?.some((slice) => slice.servedBy.startsWith("openai:") && slice.usage.cacheWriteTokens > 0) ?? false)))) process.emitWarning(`resume: run '${runId}' contains OpenAI cache-write usage recorded without a usage-semantics stamp. Entries written by rulvar v1.19.0 double-counted cache writes into inputTokens, so their recorded cost and budget debits are OVERSTATED; unstamped entries from v1.20.0 are correct. Resuming keeps the recorded debits. Audit procedure: https://docs.rulvar.com/guide/providers#openai-legacy-cache-journals`, {
@@ -28534,6 +28636,7 @@ function createEngine(options) {
 				...typeof meta?.argsHash === "string" ? { argsHash: meta.argsHash } : {},
 				...typeof meta?.genesis === "string" ? { genesis: meta.genesis } : {},
 				...typeof meta?.execKeyDerivation === "number" ? { execKeyDerivation: meta.execKeyDerivation } : {},
+				...typeof meta?.configFingerprint === "string" ? { configFingerprint: meta.configFingerprint } : {},
 				previewResolve
 			});
 		})();

package/package.json

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