@rulvar/core 1.235.0 → 1.236.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
@@ -7784,6 +7793,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 +7958,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.
@@ -14304,6 +14343,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 +14581,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

@@ -26769,6 +26769,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 +27060,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 +27598,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 +27908,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 +27944,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 +28125,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 },
@@ -28508,6 +28525,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 +28565,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.236.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",