@rulvar/core 1.3.1 → 1.4.0

package/README.md

@@ -0,0 +1,40 @@
+# @rulvar/core
+
+The rulvar engine in one dependency-light package: the L0 contracts and
+SPI interfaces, the journal kernel behind the never-pay-twice invariant,
+the model router with the capability and price registry, the agent
+runtime, the tool system and MCP bus, the `ctx` primitives and run
+engine, the dynamic orchestrator, the in-memory and JSONL reference
+stores, and the typed event stream. Zero provider SDK dependencies:
+adapters plug in from their own packages. Key exports: `createEngine`,
+`defineWorkflow`, `tool`, `mcp`, `orchestrate`, `InMemoryStore`,
+`JsonlFileStore`.
+
+Part of [rulvar](https://rulvar.com), an embeddable TypeScript engine
+for durable, budget-bounded multi-agent LLM workflows, where a completed
+LLM call is never paid for twice. Full documentation:
+[docs.rulvar.com](https://docs.rulvar.com).
+
+## Install
+
+```bash
+pnpm add @rulvar/core
+```
+
+Most applications start with the umbrella instead: `pnpm add
+@rulvar/rulvar` bundles this engine with both first-class adapters and
+the recommended model defaults. The a la carte path pairs the core with
+exactly the pieces you need, for example
+`pnpm add @rulvar/core @rulvar/anthropic @rulvar/store-sqlite`.
+
+## Documentation
+
+- [Quickstart](https://docs.rulvar.com/guide/quickstart)
+- [Architecture](https://docs.rulvar.com/guide/architecture)
+- [Workflows](https://docs.rulvar.com/guide/workflows) and
+  [The journal](https://docs.rulvar.com/guide/journal)
+- [API reference](https://docs.rulvar.com/api/%40rulvar/core/)
+
+## License
+
+[Apache-2.0](https://github.com/o-stepper/rulvar/blob/main/LICENSE)

package/dist/index.d.ts

@@ -697,6 +697,14 @@ type RunMeta = {
   workflowName?: string; /** Content hash of the body or of the compiled source. */
   workflowHash?: string; /** TranscriptStore ref of the persisted CompiledWorkflow source. */
   workflowSourceRef?: string;
+  /**
+  * The run's immutable USD ceiling (RunOptions.budgetUsd), recorded so
+  * resume restores the original invocation's bound. Absent when the
+  * run started without a ceiling. Stores must round-trip the field
+  * (the conformance kit checks); a store that drops it degrades a
+  * resumed run to uncapped.
+  */
+  budgetUsd?: number;
 };
 type RunFilter = {
   status?: string;
@@ -2867,8 +2875,10 @@ type PermissionHook = (toolName: string, input: unknown, ctx: ToolContext) => Ho
 * position matches every tool WITHOUT declared risk: presets treat the
 * undeclared state conservatively. Argv rules
 * match through the real shell matcher; domain rules are
-* ADVISORY outside the first-party fetch tool: they never
-* change a verdict in M5, and matches surface in audit events.
+* ADVISORY for every tool in the current release: they never
+* change a verdict, and matches surface in the tool:end audit
+* fields (enforcement will live in a first-party fetch tool
+* when one ships).
 */
 type RiskRuleValue = ToolRisk | "undeclared";
 type PermissionRule = {
@@ -2928,8 +2938,8 @@ type PermissionVerdict = ({
   input: unknown;
 }) & {
   /**
-  * Advisory domain-rule matches: reported in audit
-  * events, never enforced outside the first-party fetch tool.
+  * Advisory domain-rule matches: reported in the tool:end
+  * audit fields, never enforced in the current release.
   */
   advisory?: PermissionRule[];
 };
@@ -3893,12 +3903,23 @@ type AdaptiveEvents = {
   coversToOrdinal: number;
   renderSize: number;
 } | {
+  /**
+  * Two emitted shapes share the discriminant: the cap-freeze form
+  * carries { atCap: true, spentUsd, capUsd, finalizeReserveUsd },
+  * and the per-wake digest form carries atCap plus the passive
+  * WakeBudgetBlock fields (runSpentUsd .. softWarning).
+  */
   type: "orchestrator:budget";
-  entryRef: number;
-  spentUsd: number;
-  effectiveCapUsd: number;
-  reserveUsedUsd: number;
-  frozen: boolean;
+  atCap: boolean;
+  spentUsd?: number;
+  capUsd?: number;
+  finalizeReserveUsd?: number;
+  runSpentUsd?: number;
+  runCeilingUsd?: number;
+  orchestratorSpentUsd?: number;
+  orchestratorCapUsd?: number;
+  orchestratorShare?: number;
+  softWarning?: boolean;
 } | {
   type: "escalation:raised";
   entryRef: number;
@@ -3920,7 +3941,12 @@ type AdaptiveEvents = {
   spawnUnitsAfter: number;
 } | {
   type: "spawn:rejected";
-  entryRef: number;
+  /**
+  * The journaled admission decision entry; absent for the
+  * pre-admission config gates (orchestrate maxSpawns), which
+  * reject before anything is journaled.
+  */
+  entryRef?: number;
   code: string;
   agentType: string;
   logicalTaskId?: string;
@@ -3971,6 +3997,12 @@ type AdaptiveEvents = {
   frozenValue: Json;
   liveValue: Json;
 } | {
+  /**
+  * Declared for hosts; not emitted today. The compatibility scan
+  * runs strictly before a run's event stream exists, so the
+  * refusal travels only as the typed JournalCompatibilityError
+  * (which carries the same fields).
+  */
   type: "journal:compat";
   code: "HASH_VERSION_TOO_OLD" | "HASH_VERSION_TOO_NEW";
   found: number;
@@ -4773,7 +4805,14 @@ declare class ExternalRegistry {
   private activity;
   private quiesceListener?;
   private quiesceScheduled;
-  constructor(replayer: Replayer);
+  private readonly emitEvent?;
+  constructor(replayer: Replayer, emitEvent?: (body: WorkflowEventBody) => void);
+  /**
+  * Live resolution telemetry: applied when the attempt won the
+  * first-closing-wins fold, superseded when it lost. Emitted for live
+  * attempts only; folds of prior entries at resume re-emit nothing.
+  */
+  private emitResolutionOutcome;
   /** Wraps every non-suspension async operation (agents, steps). */
   enter(): () => void;
   /**
@@ -5568,6 +5607,9 @@ declare class InMemoryStore implements JournalStore {
   private readonly runs;
   private readonly metas;
   private warned;
+  constructor(options?: {
+    quiet?: boolean;
+  });
   append(runId: string, e: JournalEntry): Promise<void>;
   load(runId: string): Promise<JournalEntry[]>;
   putMeta(m: RunMeta): Promise<void>;

package/dist/index.js

@@ -2583,7 +2583,7 @@ async function resolveToolset(specs, session) {
 	if (specs === void 0 || specs.length === 0) return emptyToolset();
 	const tools = [];
 	for (const spec of specs) {
-		if (typeof spec === "string") throw new ConfigError(`tools by registered name ('${spec}') resolve only inside the worker sandbox; name-based tool registries exist for compiled scripts only (https://docs.rulvar.com/guide/planner)`);
+		if (typeof spec === "string") throw new ConfigError(`tools by registered name ('${spec}') are not supported here: pass ToolDef or ToolSource values. Registered toolset names exist only for the dynamic orchestrator's spawn_agent toolsetRef (https://docs.rulvar.com/guide/tools)`);
 		if (isToolDef(spec)) {
 			tools.push(spec);
 			continue;
@@ -5576,8 +5576,31 @@ var ExternalRegistry = class ExternalRegistry {
 	activity = 0;
 	quiesceListener;
 	quiesceScheduled = false;
-	constructor(replayer) {
+	emitEvent;
+	constructor(replayer, emitEvent) {
 		this.replayer = replayer;
+		this.emitEvent = emitEvent;
+	}
+	/**
+	* Live resolution telemetry: applied when the attempt won the
+	* first-closing-wins fold, superseded when it lost. Emitted for live
+	* attempts only; folds of prior entries at resume re-emit nothing.
+	*/
+	emitResolutionOutcome(targetRef, by, outcome) {
+		if (this.emitEvent === void 0) return;
+		if (outcome.applied) this.emitEvent({
+			type: "resolution:applied",
+			targetRef,
+			entryRef: outcome.seq,
+			by
+		});
+		else this.emitEvent({
+			type: "resolution:superseded",
+			targetRef,
+			entryRef: outcome.seq,
+			supersededBy: outcome.supersededBy,
+			reason: outcome.reason
+		});
 	}
 	/** Wraps every non-suspension async operation (agents, steps). */
 	enter() {
@@ -5805,6 +5828,7 @@ var ExternalRegistry = class ExternalRegistry {
 	*/
 	async submitResolution(entryRef, attempt) {
 		const outcome = await this.replayer.resolveSuspended(entryRef, attempt);
+		this.emitResolutionOutcome(entryRef, attempt.by, outcome);
 		if (outcome.applied) {
 			const waiter = this.waiters.get(entryRef);
 			if (waiter !== void 0) {
@@ -5838,6 +5862,7 @@ var ExternalRegistry = class ExternalRegistry {
 			by: "external",
 			value
 		});
+		this.emitResolutionOutcome(waiter.entryRef, "external", outcome);
 		if (outcome.applied) {
 			this.waiters.delete(waiter.entryRef);
 			waiter.resolve(value);
@@ -5853,7 +5878,10 @@ function deepCopy(value) {
 var InMemoryStore = class {
 	runs = /* @__PURE__ */ new Map();
 	metas = /* @__PURE__ */ new Map();
-	warned = false;
+	warned;
+	constructor(options) {
+		this.warned = options?.quiet === true;
+	}
 	append(runId, e) {
 		this.warnOnce();
 		const entries = this.runs.get(runId) ?? [];
@@ -5885,7 +5913,7 @@ var InMemoryStore = class {
 	warnOnce() {
 		if (this.warned) return;
 		this.warned = true;
-		process.emitWarning("InMemoryStore keeps journals in process memory: nothing survives the process and resume is disabled. Use JsonlFileStore (M2) or @rulvar/store-sqlite (M5) for durable runs.", {
+		process.emitWarning("InMemoryStore keeps journals in process memory: nothing survives a process exit, and a run cannot be resumed from another process. Use JsonlFileStore (M2) or @rulvar/store-sqlite (M5) for durable runs.", {
 			code: "RULVAR_INMEMORY_STORE",
 			type: "RulvarWarning"
 		});
@@ -6518,6 +6546,12 @@ function liftRetainedParts(providerMetadata, adapter) {
 }
 //#endregion
 //#region src/model/retry.ts
+/**
+* Captured at module load, before the InProcessRunner's nondeterminism
+* guard can patch the global: the engine's own jitter is journal
+* invisible and must never be blamed on workflow code.
+*/
+const nativeRandom = Math.random;
 /** Appendix A committed defaults (M4 entry gate, PR #26). */
 const DEFAULT_RETRY_POLICY = {
 	attempts: 3,
@@ -6553,7 +6587,7 @@ function retryClassOf(error) {
 * equal-jitter: half the backoff is deterministic, half random, so a
 * jittered delay never collapses to zero.
 */
-function retryDelayMs(policy, retryIndex, retryAfterMs, random = Math.random) {
+function retryDelayMs(policy, retryIndex, retryAfterMs, random = nativeRandom) {
 	if (retryAfterMs !== void 0) return retryAfterMs;
 	const { initialMs, factor, maxMs, jitter } = policy.backoff;
 	const base = Math.min(maxMs, initialMs * factor ** retryIndex);
@@ -7213,7 +7247,7 @@ function ruleMatches(rule, toolName, risk, input) {
 }
 /**
 * Advisory domain-rule matches for the audit payload:
-* reported, never enforced outside first-party fetch.
+* reported, never enforced in the current release.
 */
 function advisoryMatches(chain, toolName) {
 	return [...chain.deny, ...chain.ask].filter((rule) => "domains" in rule && rule.tool === toolName);
@@ -9977,7 +10011,15 @@ function createCtx(internals) {
 			if (prior !== void 0) {
 				claimed.add(prior.seq);
 				const recorded = prior.value;
-				if (recorded.reject !== void 0) throw new AdmissionRejectedError(`lineage admission rejected agent spawn (${recorded.reject.code}; recorded verdict)`, { data: { reason: recorded.reject } });
+				if (recorded.reject !== void 0) {
+					internals.events.emit({
+						type: "spawn:rejected",
+						entryRef: prior.seq,
+						code: recorded.reject.code,
+						agentType
+					}, state.spanId, true);
+					throw new AdmissionRejectedError(`lineage admission rejected agent spawn (${recorded.reject.code}; recorded verdict)`, { data: { reason: recorded.reject } });
+				}
 			} else {
 				const evaluated = admission.evaluateLineage({
 					name: agentType,
@@ -10000,7 +10042,7 @@ function createCtx(internals) {
 				};
 				if (evaluated.decision.kind === "reject") decisionValue.reject = { code: evaluated.decision.reason.code };
 				else decisionValue.lineage = evaluated.decision.lineage;
-				await internals.replayer.appendSinglePhase({
+				const decisionEntry = await internals.replayer.appendSinglePhase({
 					scope: state.scope,
 					key: "",
 					kind: "decision",
@@ -10008,7 +10050,15 @@ function createCtx(internals) {
 					spanId: internals.spans.mint(state.spanId),
 					value: decisionValue
 				});
-				if (evaluated.decision.kind === "reject") throw new AdmissionRejectedError(`lineage admission rejected agent spawn (${evaluated.decision.reason.code})`, { data: { reason: evaluated.decision.reason } });
+				if (evaluated.decision.kind === "reject") {
+					internals.events.emit({
+						type: "spawn:rejected",
+						entryRef: decisionEntry.seq,
+						code: evaluated.decision.reason.code,
+						agentType
+					}, state.spanId);
+					throw new AdmissionRejectedError(`lineage admission rejected agent spawn (${evaluated.decision.reason.code})`, { data: { reason: evaluated.decision.reason } });
+				}
 				admission.registerLineageAdmit(evaluated.decision.lineage.logicalTaskId);
 			}
 		}
@@ -10112,7 +10162,12 @@ function createCtx(internals) {
 					data
 				}, toolSpanId)
 			});
-			const chain = compilePermissionChain(internals.defaults.permissions, profile?.permissions);
+			const compiledChain = compilePermissionChain(internals.defaults.permissions, profile?.permissions);
+			const readonlyDeny = { risk: ["write", "destructive"] };
+			const chain = isolation === "readonly" ? {
+				...compiledChain,
+				deny: [...compiledChain.deny, readonlyDeny]
+			} : compiledChain;
 			toolRuntime = {
 				defs: toolset.tools,
 				contracts: toolset.contracts,
@@ -11278,7 +11333,14 @@ function makeOrchestratorWorkflow(goal, opts) {
 				if (recovered !== void 0) return { handle: recovered.handle };
 				const recoveredRejection = rejectedByOrdinal.get(spawnOrdinal);
 				if (recoveredRejection !== void 0) throw new AdmissionRejectedError(`admission rejected spawn ordinal ${String(spawnOrdinal)} (recovered verdict)`, { data: { decision: recoveredRejection } });
-				if (opts?.maxSpawns !== void 0 && spawnOrdinal >= opts.maxSpawns) throw new AdmissionRejectedError(`orchestrate maxSpawns ${String(opts.maxSpawns)} reached`, { data: { reason: { code: "lifetime" } } });
+				if (opts?.maxSpawns !== void 0 && spawnOrdinal >= opts.maxSpawns) {
+					internals.events.emit({
+						type: "spawn:rejected",
+						code: "lifetime",
+						agentType: params.agentType
+					}, callingState.spanId);
+					throw new AdmissionRejectedError(`orchestrate maxSpawns ${String(opts.maxSpawns)} reached`, { data: { reason: { code: "lifetime" } } });
+				}
 				const scope = childScopeOf();
 				const profile = internals.defaults.profiles?.[params.agentType];
 				const profileModel = profile?.model;
@@ -11312,7 +11374,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 					spec: params,
 					decision
 				};
-				await internals.replayer.appendSinglePhase({
+				const decisionEntry = await internals.replayer.appendSinglePhase({
 					scope: callingState.scope,
 					key: "",
 					kind: "decision",
@@ -11322,11 +11384,19 @@ function makeOrchestratorWorkflow(goal, opts) {
 				});
 				if (decision.verdict.kind === "reject") {
 					rejectedByOrdinal.set(spawnOrdinal, decision);
+					internals.events.emit({
+						type: "spawn:rejected",
+						entryRef: decisionEntry.seq,
+						code: decision.verdict.reason.code,
+						agentType: params.agentType
+					}, callingState.spanId);
 					throw new AdmissionRejectedError(`admission rejected spawn_agent '${params.agentType}' (${decision.verdict.reason.code})`, { data: { reason: decision.verdict.reason } });
 				}
 				if (decision.verdict.kind !== "admit") throw new ConfigError(`admission verdict '${decision.verdict.kind}' has no producer before M7 (DEF-5)`);
 				internals.events.emit({
 					type: "spawn:admitted",
+					entryRef: decisionEntry.seq,
+					verdict: decision.verdict.kind,
 					agentType: params.agentType,
 					logicalTaskId: decision.verdict.lineage.logicalTaskId,
 					spawnUnitsAfter: decision.verdict.spawnUnitsAfter
@@ -11740,8 +11810,12 @@ var InProcessRunner = class {
 			const priorRandom = Math.random;
 			let warnedNow = false;
 			let warnedRandom = false;
+			const libraryCaller = () => {
+				const caller = (/* @__PURE__ */ new Error()).stack?.split("\n")[3];
+				return caller !== void 0 && caller.includes("node_modules");
+			};
 			Date.now = function rulvarPatchedDateNow() {
-				if (!warnedNow) {
+				if (!warnedNow && !libraryCaller()) {
 					warnedNow = true;
 					process.emitWarning("bare Date.now() called inside a rulvar run; use ctx.now() so the value is journaled and stable on replay", {
 						code: "RULVAR_BARE_DATE_NOW",
@@ -11751,7 +11825,7 @@ var InProcessRunner = class {
 				return priorNow();
 			};
 			Math.random = function rulvarPatchedMathRandom() {
-				if (!warnedRandom) {
+				if (!warnedRandom && !libraryCaller()) {
 					warnedRandom = true;
 					process.emitWarning("bare Math.random() called inside a rulvar run; use ctx.random() so the value is journaled and stable on replay", {
 						code: "RULVAR_BARE_MATH_RANDOM",
@@ -11829,8 +11903,9 @@ function createEngine(options) {
 		});
 		const rootSpanId = spans.mint();
 		let budgetSeed;
+		const ceilingUsd = opts?.budgetUsd ?? resumeCtx?.budgetUsd;
 		const makeBudget = () => new RunBudget({
-			...opts?.budgetUsd === void 0 ? {} : { ceilingUsd: opts.budgetUsd },
+			...ceilingUsd === void 0 ? {} : { ceilingUsd },
 			lifetimeSpawnCap: options.budgetDefaults?.lifetimeSpawnCap ?? 500,
 			events: { emit: (body) => bus.emit(body, rootSpanId) },
 			priceUsd,
@@ -11889,7 +11964,7 @@ function createEngine(options) {
 				...options.budgetDefaults?.lineage === void 0 ? {} : { limits: options.budgetDefaults.lineage }
 			}
 		});
-		const external = new ExternalRegistry(replayer);
+		const external = new ExternalRegistry(replayer, (body) => bus.emit(body, rootSpanId));
 		let transcriptCounter = 0;
 		const internals = {
 			runId,
@@ -11950,6 +12025,7 @@ function createEngine(options) {
 			updatedAt: new Date(realNow()).toISOString(),
 			...opts?.name === void 0 ? {} : { name: opts.name },
 			...opts?.tags === void 0 ? {} : { tags: opts.tags },
+			...ceilingUsd === void 0 ? {} : { budgetUsd: ceilingUsd },
 			workflowName: wf.name,
 			workflowHash: compiled === void 0 ? hashWorkflowBody(wf) : hashWorkflowSource(compiled.source),
 			...compiled === void 0 ? {} : { workflowSourceRef: workflowSourceRef(runId) }
@@ -12125,6 +12201,7 @@ function createEngine(options) {
 				strict: resumeOptions?.dryRun ?? false,
 				invalidate: resumeOptions?.invalidate ?? [],
 				...resumeOptions?.lease === void 0 ? {} : { lease: resumeOptions.lease },
+				...typeof meta?.budgetUsd === "number" ? { budgetUsd: meta.budgetUsd } : {},
 				previewResolve
 			});
 		})();

package/package.json

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