@rulvar/core 1.3.0 → 1.3.2

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.js

@@ -348,7 +348,7 @@ const PINNED_FIELDS = [
 	"status"
 ];
 function assertPinnedFields(before, after, site) {
-	for (const field of PINNED_FIELDS) if (before[field] !== after[field]) throw new ConfigError(`serialization hook ${site} modified the kernel field '${field}' (docs/03, 12.8: ordering and identity fields MUST pass through unmodified)`);
+	for (const field of PINNED_FIELDS) if (before[field] !== after[field]) throw new ConfigError(`serialization hook ${site} modified the kernel field '${field}' (ordering and identity fields MUST pass through unmodified)`);
 }
 /** Wraps a journal store with the hook; lease capability is preserved. */
 function wrapJournalStore(inner, hook) {
@@ -1602,11 +1602,11 @@ function findAnchor(node, anchor) {
 }
 function canonicalizeNode(node, root, refStack) {
 	if (typeof node === "boolean") return node;
-	if ("$dynamicRef" in node || "$dynamicAnchor" in node) throw new ConfigError("Dynamic references ($dynamicRef/$dynamicAnchor) are forbidden in rulvar schemas (docs/03, section \"schemaHash and toolsetHash derivation\")");
+	if ("$dynamicRef" in node || "$dynamicAnchor" in node) throw new ConfigError("Dynamic references ($dynamicRef/$dynamicAnchor) are forbidden in rulvar schemas ");
 	const ref = node.$ref;
 	if (typeof ref === "string") {
-		if (!ref.startsWith("#")) throw new ConfigError(`Remote $ref '${ref}' is forbidden in rulvar schemas; only fragment-only local references resolve (docs/03, section "schemaHash and toolsetHash derivation")`);
-		if (refStack.includes(ref)) throw new ConfigError(`Recursive local $ref '${ref}' cannot be inlined; recursive schemas are not canonicalizable (docs/03, section "schemaHash and toolsetHash derivation")`);
+		if (!ref.startsWith("#")) throw new ConfigError(`Remote $ref '${ref}' is forbidden in rulvar schemas; only fragment-only local references resolve`);
+		if (refStack.includes(ref)) throw new ConfigError(`Recursive local $ref '${ref}' cannot be inlined; recursive schemas are not canonicalizable`);
 		const target = ref.startsWith("#/") ? resolvePointer(root, ref.slice(1)) : ref === "#" ? root : findAnchor(root, ref.slice(1));
 		if (target === void 0 || typeof target !== "object" && typeof target !== "boolean") throw new ConfigError(`Local $ref '${ref}' does not resolve to a schema`);
 		refStack.push(ref);
@@ -1879,7 +1879,7 @@ function gateIssues(gate, path) {
 		return issues;
 	}
 	const ruledOut = gate.attribution?.ruledOut;
-	if (!Array.isArray(ruledOut) || ruledOut.length === 0) issues.push(`${path}: the human gate requires the attribution attestation (a non-empty ruledOut checklist; docs/05, section "The human gate")`);
+	if (!Array.isArray(ruledOut) || ruledOut.length === 0) issues.push(`${path}: the human gate requires the attribution attestation (a non-empty ruledOut checklist)`);
 	else for (const entry of ruledOut) if (typeof entry !== "string" || !RULED_OUT_VOCABULARY.has(entry)) issues.push(`${path}: ruledOut entry '${String(entry)}' is outside the checklist`);
 	if (typeof gate.approver !== "string" || gate.approver.length === 0) issues.push(`${path}: the human gate requires an approver`);
 	return issues;
@@ -1897,8 +1897,8 @@ function claimIssues(claim, path, options) {
 	if (Number.isNaN(Date.parse(claim.expiresAt))) issues.push(`${path}: expiresAt is not a date`);
 	else if (!Number.isNaN(Date.parse(claim.observedAt)) && Date.parse(claim.expiresAt) <= Date.parse(claim.observedAt)) issues.push(`${path}: expiresAt must follow observedAt`);
 	if (options?.evalCommitter !== true) {
-		if (claim.class === "eval-measured") issues.push(`${path}: eval-measured claims are committable only under the eval-committer gate (the eval-committer identity; docs/05, 5.4); the editorial path carries human-editorial only`);
-		if (claim.metrics !== void 0) issues.push(`${path}: the metrics block is writable only by the eval-committer identity (docs/05, security channel 4)`);
+		if (claim.class === "eval-measured") issues.push(`${path}: eval-measured claims are committable only under the eval-committer gate (the eval-committer identity); the editorial path carries human-editorial only`);
+		if (claim.metrics !== void 0) issues.push(`${path}: the metrics block is writable only by the eval-committer identity `);
 	}
 	if (options?.evalCommitter === true && claim.class === "eval-measured") {
 		if (claim.metrics === void 0) issues.push(`${path}: an eval-measured claim carries its metrics block`);
@@ -1947,7 +1947,7 @@ function capIssues(claims, cap = 8) {
 		counts.set(key, (counts.get(key) ?? 0) + 1);
 	}
 	const issues = [];
-	for (const [key, count] of counts) if (count > cap) issues.push(`active claims for (${key}) would reach ${String(count)}, over the cap ${String(cap)} (docs/06, Appendix A); supersede or archive first`);
+	for (const [key, count] of counts) if (count > cap) issues.push(`active claims for (${key}) would reach ${String(count)}, over the cap ${String(cap)}; supersede or archive first`);
 	return issues.sort();
 }
 /**
@@ -2137,10 +2137,10 @@ function checkFloors(options) {
 	const { ref, role, floors, taskClass } = options;
 	if (floors === void 0) return;
 	const roleViolation = violates(ref, floors.byRole?.[role]);
-	if (roleViolation !== void 0) throw new ConfigError(`quality floor violation: '${ref}' is floored out for role '${role}' (${roleViolation}); floors are hard router constraints (docs/04, section 9)`);
+	if (roleViolation !== void 0) throw new ConfigError(`quality floor violation: '${ref}' is floored out for role '${role}' (${roleViolation}); floors are hard router constraints`);
 	if (taskClass !== void 0) {
 		const classViolation = violates(ref, floors.byTaskClass?.[taskClass]);
-		if (classViolation !== void 0) throw new ConfigError(`quality floor violation: '${ref}' is floored out for taskClass '${taskClass}' (${classViolation}); floors are hard router constraints (docs/04, section 9)`);
+		if (classViolation !== void 0) throw new ConfigError(`quality floor violation: '${ref}' is floored out for taskClass '${taskClass}' (${classViolation}); floors are hard router constraints`);
 	}
 }
 //#endregion
@@ -2523,7 +2523,7 @@ const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
 * reference all fail here.
 */
 function tool(init) {
-	if (!TOOL_NAME_PATTERN.test(init.name)) throw new ConfigError(`tool name '${init.name}' must match ^[a-zA-Z0-9_-]{1,64}$ (docs/08, section "tool() definition and ToolDef")`);
+	if (!TOOL_NAME_PATTERN.test(init.name)) throw new ConfigError(`tool name '${init.name}' must match ^[a-zA-Z0-9_-]{1,64}$ (https://docs.rulvar.com/guide/tools)`);
 	canonicalizeSchema(projectToJsonSchema(init.parameters));
 	return {
 		kind: "tool",
@@ -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 land with compileScript in M6 (docs/06, section "Script runners")`);
+		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 (isToolDef(spec)) {
 			tools.push(spec);
 			continue;
@@ -2593,9 +2593,9 @@ async function resolveToolset(specs, session) {
 	}
 	const seen = /* @__PURE__ */ new Map();
 	for (const def of tools) {
-		if (!TOOL_NAME_PATTERN.test(def.name)) throw new ConfigError(`imported tool name '${def.name}' must match ^[a-zA-Z0-9_-]{1,64}$; namespace it with the source prefix option (docs/08, section 6.4)`);
-		if (seen.has(def.name)) throw new ConfigError(`duplicate tool name '${def.name}' in one toolset; disambiguate with the MCP prefix option (docs/08, sections 1.1 and 6.4)`);
-		if (def.executor !== "inprocess") throw new ConfigError(`tool '${def.name}' declares executor '${def.executor}', but this engine implements only 'inprocess' in v1 (docs/08, section 7.1)`);
+		if (!TOOL_NAME_PATTERN.test(def.name)) throw new ConfigError(`imported tool name '${def.name}' must match ^[a-zA-Z0-9_-]{1,64}$; namespace it with the source prefix option`);
+		if (seen.has(def.name)) throw new ConfigError(`duplicate tool name '${def.name}' in one toolset; disambiguate with the MCP prefix option`);
+		if (def.executor !== "inprocess") throw new ConfigError(`tool '${def.name}' declares executor '${def.executor}', but this engine implements only 'inprocess' in v1`);
 		seen.set(def.name, def);
 	}
 	const contracts = tools.map((def) => toolContract(def));
@@ -2637,7 +2637,7 @@ function buildToolContext(seed) {
 */
 function validateConfig(cfg) {
 	const forbid = (key) => {
-		if (cfg[key] !== void 0) throw new ConfigError(`mcp: '${key}' is not a config key of the '${cfg.transport}' transport (docs/08, section 6.2: exactly the keys matching the chosen transport)`);
+		if (cfg[key] !== void 0) throw new ConfigError(`mcp: '${key}' is not a config key of the '${cfg.transport}' transport (exactly the keys matching the chosen transport)`);
 	};
 	switch (cfg.transport) {
 		case "stdio":
@@ -2732,7 +2732,7 @@ function mcp(cfg) {
 	};
 	const toDef = (client, wire) => {
 		const name = cfg.prefix === void 0 ? wire.name : `${cfg.prefix}_${wire.name}`;
-		if (!TOOL_NAME_PATTERN.test(name)) throw new ConfigError(`mcp: imported tool name '${name}' must match ^[a-zA-Z0-9_-]{1,64}$ (docs/08, section 6.4)`);
+		if (!TOOL_NAME_PATTERN.test(name)) throw new ConfigError(`mcp: imported tool name '${name}' must match ^[a-zA-Z0-9_-]{1,64}$ `);
 		const risk = cfg.risk?.[wire.name];
 		return tool({
 			name,
@@ -2826,7 +2826,7 @@ var GitWorktreeProvider = class {
 		try {
 			await git(this.repoRoot, ["rev-parse", "--git-common-dir"]);
 		} catch {
-			throw new ConfigError(`worktree isolation requires a git repository at '${this.repoRoot}' (docs/08, section 8.3)`);
+			throw new ConfigError(`worktree isolation requires a git repository at '${this.repoRoot}' `);
 		}
 		const dir = await mkdtemp(join(tmpdir(), `rulvar-wt-${spawn.runId.slice(0, 8)}-`));
 		await git(this.repoRoot, [
@@ -2860,7 +2860,7 @@ var GitWorktreeProvider = class {
 					this.pinned.add(dir);
 					return;
 				}
-				this.onWarn(`worktree pin cap (${this.maxPinned}) reached; dropping the tree of a failed agent instead of retaining it (docs/08, section 8.4)`);
+				this.onWarn(`worktree pin cap (${this.maxPinned}) reached; dropping the tree of a failed agent instead of retaining it`);
 			}
 			try {
 				await git(this.repoRoot, [
@@ -3175,7 +3175,7 @@ function isKeyDeriver(value) {
 function buildDeriverRegistry(extraDerivers) {
 	const registry = /* @__PURE__ */ new Map([[deriverV1.hashVersion, deriverV1], [deriverV2.hashVersion, deriverV2]]);
 	for (const extra of extraDerivers ?? []) {
-		if (!isKeyDeriver(extra)) throw new ConfigError("extraDerivers entries must implement the KeyDeriver SPI (docs/03, section 4.2)");
+		if (!isKeyDeriver(extra)) throw new ConfigError("extraDerivers entries must implement the KeyDeriver SPI");
 		registry.set(extra.hashVersion, extra);
 	}
 	return registry;
@@ -3372,7 +3372,7 @@ const DEFAULT_ESCALATION_LIMITS = {
 * change semantics (per logical task, not per node).
 */
 function validateEscalationLimits(raw) {
-	if (raw !== void 0 && "maxEscalationsPerNode" in raw) throw new ConfigError("config knob 'maxEscalationsPerNode' was renamed: escalations are counted per logical task across respawns via the lineage chain; use 'maxEscalationsPerLogicalTask' (XF-10; docs/07, section 6.5)");
+	if (raw !== void 0 && "maxEscalationsPerNode" in raw) throw new ConfigError("config knob 'maxEscalationsPerNode' was renamed: escalations are counted per logical task across respawns via the lineage chain; use 'maxEscalationsPerLogicalTask' (XF-10)");
 	const limits = { ...DEFAULT_ESCALATION_LIMITS };
 	if (raw?.maxEscalationsPerLogicalTask !== void 0) limits.maxEscalationsPerLogicalTask = requireCount(raw.maxEscalationsPerLogicalTask, "maxEscalationsPerLogicalTask");
 	if (raw?.maxAttemptsPerLogicalTask !== void 0) limits.maxAttemptsPerLogicalTask = requireCount(raw.maxAttemptsPerLogicalTask, "maxAttemptsPerLogicalTask");
@@ -3850,7 +3850,7 @@ function profileRegistrySnapshotHash(profiles) {
 * must be non-negative integers; kMax at least 1.
 */
 function validateTerminationLimits(raw) {
-	if ("maxEscalationsPerNode" in raw) throw new ConfigError("config knob 'maxEscalationsPerNode' was renamed: escalations are counted per logical task across respawns via the lineage chain; use 'maxEscalationsPerLogicalTask' (XF-10; docs/07, section 6.5)");
+	if ("maxEscalationsPerNode" in raw) throw new ConfigError("config knob 'maxEscalationsPerNode' was renamed: escalations are counted per logical task across respawns via the lineage chain; use 'maxEscalationsPerLogicalTask' (XF-10)");
 	const record = raw;
 	const count = (name, fallback) => {
 		const value = record[name] ?? fallback;
@@ -3990,7 +3990,7 @@ var TerminationAccount = class {
 		};
 		if (lineage !== void 0) {
 			const ladderLength = lineage.ladderLength ?? 1;
-			if (ladderLength > this.limits.kMax) throw new ConfigError(`ladder length ${String(ladderLength)} exceeds the frozen kMax ${String(this.limits.kMax)}; admit() must reject with ladder_exceeds_frozen before debiting (docs/07, 11.8)`);
+			if (ladderLength > this.limits.kMax) throw new ConfigError(`ladder length ${String(ladderLength)} exceeds the frozen kMax ${String(this.limits.kMax)}; admit() must reject with ladder_exceeds_frozen before debiting`);
 			if (lineage.isNew && !this.lineages.has(lineage.logicalTaskId)) this.lineages.set(lineage.logicalTaskId, {
 				escalationUnitsRemaining: this.limits.maxEscalationsPerLogicalTask,
 				rungsRemaining: ladderLength - 1,
@@ -4067,7 +4067,7 @@ var TerminationAccount = class {
 	async debit(resource, lineage, context) {
 		const attempt = this.tryDebit(resource, lineage);
 		if (attempt.ok) return attempt;
-		if (this.deniedWriter === void 0) throw new ConfigError(`termination debit of ${resource} underflowed and no deniedWriter is bound; the denied entry MUST precede the surfaced error (docs/07, 11.3)`);
+		if (this.deniedWriter === void 0) throw new ConfigError(`termination debit of ${resource} underflowed and no deniedWriter is bound; the denied entry MUST precede the surfaced error`);
 		return {
 			ok: false,
 			deniedEntryRef: await this.deniedWriter({
@@ -4174,7 +4174,7 @@ function foldTermination(entries) {
 	/** First-closing-wins over resolution targets (DEF-4): losers never debit. */
 	const closedTargets = /* @__PURE__ */ new Set();
 	const assertBalance = (entry, what, embedded, recomputed) => {
-		if (typeof embedded === "number" && embedded !== recomputed) throw new PlanInvariantError(`termination fold divergence at seq ${String(entry.seq)}: ${what} recomputes to ${String(recomputed)} but the entry embeds ${String(embedded)} (docs/07, 11.6: the debit fold is authoritative)`, { data: {
+		if (typeof embedded === "number" && embedded !== recomputed) throw new PlanInvariantError(`termination fold divergence at seq ${String(entry.seq)}: ${what} recomputes to ${String(recomputed)} but the entry embeds ${String(embedded)} (the debit fold is authoritative)`, { data: {
 			entryRef: entry.seq,
 			what,
 			embedded,
@@ -4712,7 +4712,7 @@ function validateEntryShape(entry) {
 		return issues;
 	}
 	const legal = LEGAL_STATUSES[entry.kind];
-	if (legal !== void 0 && !legal.includes(entry.status)) issues.push(issue(`status '${entry.status}' is not legal for kind '${entry.kind}' (docs/03 section 5.3)`));
+	if (legal !== void 0 && !legal.includes(entry.status)) issues.push(issue(`status '${entry.status}' is not legal for kind '${entry.kind}'`));
 	if (entry.status === "skipped") issues.push(issue("'skipped' is a derived fold status and is never persisted"));
 	if (REF_ENTRY_KINDS$1.has(entry.kind)) {
 		if (entry.ref === void 0) issues.push(issue(`ref-entry kind '${entry.kind}' requires ref (the target seq)`));
@@ -4734,10 +4734,10 @@ function validateEntryShape(entry) {
 		if (payload === void 0 || typeof payload.decisionType !== "string") issues.push(issue("decision entries carry a decisionType discriminator", ["value"]));
 	}
 	if (entry.kind === "external" || entry.kind === "approval") {
-		if (entry.kind === "external" && entry.deadlineAt !== void 0) issues.push(issue("awaitExternal has NO deadline in v1 (docs/03 section 8.1)"));
+		if (entry.kind === "external" && entry.deadlineAt !== void 0) issues.push(issue("awaitExternal has NO deadline in v1"));
 	}
 	if (entry.deadlineAt !== void 0 && entry.status !== "suspended") issues.push(issue("deadlineAt is legal only on suspended entries"));
-	if (entry.status === "escalated" && entry.escalation === void 0) issues.push(issue("terminal escalated entries carry the validated EscalationReport (docs/03 5.4)"));
+	if (entry.status === "escalated" && entry.escalation === void 0) issues.push(issue("terminal escalated entries carry the validated EscalationReport"));
 	if (entry.escalation !== void 0 && entry.status !== "escalated") issues.push(issue("the escalation payload is legal only on status 'escalated'"));
 	return issues;
 }
@@ -5638,7 +5638,7 @@ var ExternalRegistry = class ExternalRegistry {
 	*/
 	async awaitExternal(scope, spanId, key, options) {
 		const scopeKey = `${scope}${key}`;
-		if (this.keysByScope.has(scopeKey)) throw new ConfigError(`duplicate awaitExternal key '${key}' in scope '${scope}' (docs/03, section 8.1)`);
+		if (this.keysByScope.has(scopeKey)) throw new ConfigError(`duplicate awaitExternal key '${key}' in scope '${scope}'`);
 		this.keysByScope.add(scopeKey);
 		const identity = {
 			kind: "external",
@@ -6778,7 +6778,7 @@ function resolveModelInvocation(options) {
 		if (fields.ladder !== void 0) delete merged.model;
 		else if (fields.model !== void 0) delete merged.ladder;
 	}
-	if (merged.ladder !== void 0) throw new ConfigError(`a ladder ModelSpec wins wire resolution for role '${role}': ladder execution is owned by the PlanRunner ladder driver, which resolves each rung attempt to a concrete model override (docs/07, section 10); dispatch laddered profiles through orchestratePlanned or pass a plain ModelRef or ModelChoice`);
+	if (merged.ladder !== void 0) throw new ConfigError(`a ladder ModelSpec wins wire resolution for role '${role}': ladder execution is owned by the PlanRunner ladder driver, which resolves each rung attempt to a concrete model override; dispatch laddered profiles through orchestratePlanned or pass a plain ModelRef or ModelChoice`);
 	if (merged.model === void 0) throw new ConfigError(`no model resolves for role '${role}': set AgentOpts.model, a profile model, or engine defaults.routing`);
 	checkFloors({
 		ref: merged.model,
@@ -6847,7 +6847,7 @@ const TRIGGER_CLASSES = [
 ];
 function validateGate(gate, rungCount, index) {
 	if (gate.kind === "mechanical") {
-		if (typeof gate.profile !== "string" || gate.profile === "") throw new ConfigError(`ladder acceptance gate ${String(index)}: a mechanical gate names a registered gate profile (docs/04, section 12)`);
+		if (typeof gate.profile !== "string" || gate.profile === "") throw new ConfigError(`ladder acceptance gate ${String(index)}: a mechanical gate names a registered gate profile`);
 		return;
 	}
 	if (gate.kind === "judge") {
@@ -6869,16 +6869,16 @@ function validateGate(gate, rungCount, index) {
 * member by declaration).
 */
 function canonicalizeLadder(spec, options) {
-	if (!Array.isArray(spec.rungs) || spec.rungs.length === 0) throw new ConfigError("a ladder declares at least one rung (docs/04, section 12)");
+	if (!Array.isArray(spec.rungs) || spec.rungs.length === 0) throw new ConfigError("a ladder declares at least one rung");
 	if (!Number.isInteger(spec.startTier) || spec.startTier < 0 || spec.startTier >= spec.rungs.length) throw new ConfigError(`ladder startTier ${String(spec.startTier)} is not a declared rung index of a ${String(spec.rungs.length)}-rung ladder`);
-	for (const trigger of spec.escalateOn) if (!TRIGGER_CLASSES.includes(trigger)) throw new ConfigError(`unknown ladder trigger '${String(trigger)}': the vocabulary is closed to ${TRIGGER_CLASSES.join(", ")} (docs/04, section 12)`);
+	for (const trigger of spec.escalateOn) if (!TRIGGER_CLASSES.includes(trigger)) throw new ConfigError(`unknown ladder trigger '${String(trigger)}': the vocabulary is closed to ${TRIGGER_CLASSES.join(", ")}`);
 	const rungs = spec.rungs.map((rung, index) => {
 		parseModelRef(rung.model);
 		if (!Number.isInteger(rung.maxTurns) || rung.maxTurns <= 0) throw new ConfigError(`ladder rung ${String(index)}: maxTurns is a positive integer`);
 		if (!Number.isInteger(rung.maxTokens) || rung.maxTokens <= 0) throw new ConfigError(`ladder rung ${String(index)}: maxTokens is a positive integer`);
 		if (rung.maxCostUsd !== void 0 && !(rung.maxCostUsd > 0)) throw new ConfigError(`ladder rung ${String(index)}: maxCostUsd is positive when present`);
 		const effort = rung.effort ?? options?.chainEffort;
-		if (effort === void 0) throw new ConfigError(`ladder rung ${String(index)} resolves no effort: the canonical ladder embeds explicit efforts (docs/04, section 8.2); declare rung.effort or a chain effort`);
+		if (effort === void 0) throw new ConfigError(`ladder rung ${String(index)} resolves no effort: the canonical ladder embeds explicit efforts; declare rung.effort or a chain effort`);
 		return {
 			model: rung.model,
 			effort,
@@ -8658,7 +8658,7 @@ var RunBudget = class {
 		let cursor = scope;
 		while (cursor !== void 0) {
 			const account = this.accounts.get(cursor);
-			if (account === void 0) throw new ConfigError(`unknown budget account '${cursor}': openAccount precedes any charge (docs/06, 5.4)`);
+			if (account === void 0) throw new ConfigError(`unknown budget account '${cursor}': openAccount precedes any charge`);
 			chain.push(account);
 			cursor = account.parentScope;
 		}
@@ -8912,7 +8912,7 @@ var AdmissionController = class {
 	admittedTotal = 0;
 	constructor(options) {
 		const maxDepth = options.maxDepth ?? 1;
-		if (maxDepth < 1 || maxDepth > 4) throw new ConfigError(`maxDepth ${String(maxDepth)} is outside [1, ${String(4)}] (docs/06, Appendix A: default 1, hard ceiling 4)`);
+		if (maxDepth < 1 || maxDepth > 4) throw new ConfigError(`maxDepth ${String(maxDepth)} is outside [1, ${String(4)}] (default 1, hard ceiling 4)`);
 		this.budget = options.budget;
 		this.maxDepth = maxDepth;
 		this.maxChildrenPerNode = options.maxChildrenPerNode ?? 16;
@@ -8944,7 +8944,7 @@ var AdmissionController = class {
 	* keep the engine lifetime cap semantics unchanged.
 	*/
 	bindTermination(account) {
-		if (this.terminationAccount !== void 0 && this.terminationAccount !== account) throw new ConfigError("one run carries exactly one TerminationAccount (docs/07, 11.2)");
+		if (this.terminationAccount !== void 0 && this.terminationAccount !== account) throw new ConfigError("one run carries exactly one TerminationAccount");
 		this.terminationAccount = account;
 	}
 	/** The bound account, when this is a PlanRunner run (DEF-2). */
@@ -8960,7 +8960,7 @@ var AdmissionController = class {
 	* (`lineage_exhausted`); never touches budget or structural limits.
 	*/
 	evaluateLineage(spec) {
-		if (spec.lineage !== void 0 && typeof spec.lineage.causeRef !== "number") throw new ConfigError("a lineage continuation demands a causeRef: the seq of the entry that caused the rebirth (docs/03, 10.1, rule 2)");
+		if (spec.lineage !== void 0 && typeof spec.lineage.causeRef !== "number") throw new ConfigError("a lineage continuation demands a causeRef: the seq of the entry that caused the rebirth");
 		const index = this.lineage();
 		const continued = spec.lineage?.continues;
 		const statsBefore = index !== void 0 && continued !== void 0 ? index.statsOf(continued) : void 0;
@@ -9671,7 +9671,7 @@ function createCtx(internals) {
 			});
 		};
 		const isolation = opts.isolation ?? profile?.isolation ?? "none";
-		if (typeof isolation === "object" && isolation.kind === "worktree" && internals.isolation === void 0) throw new ConfigError("worktree isolation requires an IsolationProvider: pass defaults.isolation to createEngine (docs/08, section 8.2)");
+		if (typeof isolation === "object" && isolation.kind === "worktree" && internals.isolation === void 0) throw new ConfigError("worktree isolation requires an IsolationProvider: pass defaults.isolation to createEngine");
 		const floorContext = {
 			...internals.floors === void 0 ? {} : { floors: internals.floors },
 			...profile?.taskClass === void 0 ? {} : { taskClass: profile.taskClass }
@@ -9717,9 +9717,9 @@ function createCtx(internals) {
 		}
 		const escalation = opts.escalation ?? profile?.escalation;
 		if (escalation !== void 0) {
-			if (escalation.flavor === "B" && escalation.deadlineMs === void 0) throw new ConfigError("flavor 'B' escalation requires an explicit deadlineMs: the suspension deadline has no engine default (docs/06, Appendix A; docs/07, section 6.2)");
+			if (escalation.flavor === "B" && escalation.deadlineMs === void 0) throw new ConfigError("flavor 'B' escalation requires an explicit deadlineMs: the suspension deadline has no engine default");
 			if (opts.result !== "full" && internals.onEscalation === void 0) throw new ConfigError("a spawn that opts into escalation from a plain value-form call needs an onEscalation hook (or use result: 'full')");
-			if (escalation.flavor === "B" && escalation.deadlineMs === void 0) throw new ConfigError("escalation flavor 'B' requires an explicit deadlineMs (docs/06, Appendix A)");
+			if (escalation.flavor === "B" && escalation.deadlineMs === void 0) throw new ConfigError("escalation flavor 'B' requires an explicit deadlineMs");
 		}
 		const declaredTools = opts.tools ?? profile?.tools ?? [];
 		const toolset = await resolveToolset(escalation === void 0 ? declaredTools : [...declaredTools, escalateTool()], { runId: internals.runId });
@@ -10225,7 +10225,7 @@ function createCtx(internals) {
 			if (internals.external === void 0) throw new ConfigError("flavor B escalation requires the engine run context");
 			const request = result.escalationRequest;
 			const deadlineMs = escalation.deadlineMs;
-			if (deadlineMs === void 0) throw new ConfigError("flavor 'B' escalation requires an explicit deadlineMs (docs/06, Appendix A)");
+			if (deadlineMs === void 0) throw new ConfigError("flavor 'B' escalation requires an explicit deadlineMs");
 			const defaultDecision = escalation.defaultDecision ?? { kind: "accept" };
 			let timer;
 			const decisionOutcome = await internals.external.awaitDecision({
@@ -10550,9 +10550,9 @@ function createCtx(internals) {
 		let name;
 		if (typeof wfOrName === "string") {
 			const registered = internals.defaults.workflows?.[wfOrName];
-			if (registered === void 0) throw new ConfigError(`unknown workflow '${wfOrName}': register it under defaults.workflows (docs/06, 10.4)`);
+			if (registered === void 0) throw new ConfigError(`unknown workflow '${wfOrName}': register it under defaults.workflows`);
 			const candidate = registered;
-			if (candidate.kind !== "workflow") throw new ConfigError(`registry entry '${wfOrName}' is not a defineWorkflow value (docs/06, 10.4)`);
+			if (candidate.kind !== "workflow") throw new ConfigError(`registry entry '${wfOrName}' is not a defineWorkflow value`);
 			wf = candidate;
 			name = wfOrName;
 		} else {
@@ -10881,12 +10881,12 @@ function resolveDispatchOpts(spec, defaults) {
 	const opts = {};
 	if (spec.outputSchemaRef !== void 0) {
 		const schema = defaults.schemas?.[spec.outputSchemaRef];
-		if (schema === void 0) throw new ConfigError(`unknown outputSchemaRef '${spec.outputSchemaRef}': register it under defaults.schemas (docs/08, section "SchemaSpec"; docs/07, 4.2)`);
+		if (schema === void 0) throw new ConfigError(`unknown outputSchemaRef '${spec.outputSchemaRef}': register it under defaults.schemas`);
 		opts.schema = schema;
 	}
 	if (spec.toolsetRef !== void 0) {
 		const tools = defaults.toolsets?.[spec.toolsetRef];
-		if (tools === void 0) throw new ConfigError(`unknown toolsetRef '${spec.toolsetRef}': register it under defaults.toolsets (docs/08, section "tool() definition"; docs/07, 4.2)`);
+		if (tools === void 0) throw new ConfigError(`unknown toolsetRef '${spec.toolsetRef}': register it under defaults.toolsets (https://docs.rulvar.com/guide/tools)`);
 		opts.tools = tools;
 	}
 	const extended = spec;
@@ -10936,16 +10936,16 @@ function makeOrchestratorWorkflow(goal, opts) {
 			const runCeiling = internals.budget.accountView(callingState.budgetScope ?? "run")?.ceilingUsd;
 			const spec = opts?.budget;
 			const fraction = spec?.capFraction ?? .2;
-			if (fraction > 1) throw new OrchestratorCapConfigError(`capFraction ${String(fraction)} exceeds 1.0 (docs/07, 12.2: opting out of the cap is explicit only, up to 1.0 inclusive)`);
+			if (fraction > 1) throw new OrchestratorCapConfigError(`capFraction ${String(fraction)} exceeds 1.0 (opting out of the cap is explicit only, up to 1.0 inclusive)`);
 			const fromFraction = runCeiling === void 0 ? void 0 : fraction * runCeiling;
 			const bounds = [spec?.capUsd, fromFraction].filter((bound) => bound !== void 0);
-			if (extension !== void 0 && bounds.length === 0) throw new OrchestratorCapConfigError("the orchestrator cap is unresolvable: the run has no USD ceiling and no explicit budget.capUsd; PlanRunner requires a resolved effectiveCap (docs/07, 12.2)");
+			if (extension !== void 0 && bounds.length === 0) throw new OrchestratorCapConfigError("the orchestrator cap is unresolvable: the run has no USD ceiling and no explicit budget.capUsd; PlanRunner requires a resolved effectiveCap");
 			if (bounds.length > 0) {
 				const effectiveCapUsd = Math.min(...bounds);
 				const turnEstimateUsd = internals.flatReserveUsd ?? .5;
 				const finalizeTurns = spec?.finalizeTurns ?? 2;
 				const finalizeReserveUsd = spec?.finalizeReserveUsd ?? finalizeTurns * turnEstimateUsd;
-				if (extension !== void 0 && effectiveCapUsd < finalizeReserveUsd) throw new OrchestratorCapConfigError(`effectiveCap ${effectiveCapUsd.toFixed(4)} USD is below the finalize reserve ${finalizeReserveUsd.toFixed(4)} USD (docs/07, 12.2)`);
+				if (extension !== void 0 && effectiveCapUsd < finalizeReserveUsd) throw new OrchestratorCapConfigError(`effectiveCap ${effectiveCapUsd.toFixed(4)} USD is below the finalize reserve ${finalizeReserveUsd.toFixed(4)} USD`);
 				orchestratorAccount = callingState.scope === "" ? "orchestrator" : `${callingState.scope}/orchestrator`;
 				internals.budget.openAccount(orchestratorAccount, {
 					parentScope: callingState.budgetScope ?? "run",
@@ -11282,7 +11282,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 				const scope = childScopeOf();
 				const profile = internals.defaults.profiles?.[params.agentType];
 				const profileModel = profile?.model;
-				if (profileModel !== void 0 && typeof profileModel !== "string" && "ladder" in profileModel) throw new ConfigError(`agentType '${params.agentType}' declares a ladder; ladder execution is owned by the plan extension, which resolves each rung attempt to a concrete model override (docs/07, section 10); spawn a concrete profile instead`);
+				if (profileModel !== void 0 && typeof profileModel !== "string" && "ladder" in profileModel) throw new ConfigError(`agentType '${params.agentType}' declares a ladder; ladder execution is owned by the plan extension, which resolves each rung attempt to a concrete model override; spawn a concrete profile instead`);
 				const decision = admission.admit({
 					origin: "spawn_agent",
 					name: params.agentType,
@@ -11817,7 +11817,7 @@ function createEngine(options) {
 	function run(wf, args, opts, resumeCtx) {
 		if (wf.kind !== "workflow" && wf.kind !== "compiled-workflow") throw new ConfigError("engine.run accepts in-process Workflow values or compileScript CompiledWorkflow values");
 		const compiled = wf.kind === "compiled-workflow" ? wf : void 0;
-		if (compiled !== void 0 && options.runners?.sandbox === void 0) throw new ConfigError("running a CompiledWorkflow requires a sandbox runner: pass createEngine({ runners: { sandbox: new WorkerSandboxRunner() } }) from @rulvar/planner (docs/06, sections 8.2 and 10.1)");
+		if (compiled !== void 0 && options.runners?.sandbox === void 0) throw new ConfigError("running a CompiledWorkflow requires a sandbox runner: pass createEngine({ runners: { sandbox: new WorkerSandboxRunner() } }) from @rulvar/planner ");
 		const runId = resumeCtx?.runId ?? opts?.runId ?? mintRunId();
 		const registry = buildDeriverRegistry(options.extraDerivers);
 		const spans = new SpanRegistry();
@@ -12087,12 +12087,12 @@ function createEngine(options) {
 			if (supplied === void 0 && meta?.workflowSourceRef === void 0) {
 				const name = meta?.workflowName;
 				const registered = name === void 0 ? void 0 : defaults.workflows?.[name];
-				if (registered === void 0) throw new ConfigError(`engine.resume(runId) with no workflow resolves by the RunMeta-recorded name from defaults.workflows (docs/06, 10.2); run '${runId}' records ` + (name === void 0 ? "no workflowName" : `workflow '${name}', which is not registered`) + "; register it under defaults.workflows or pass the workflow value");
+				if (registered === void 0) throw new ConfigError(`engine.resume(runId) with no workflow resolves by the RunMeta-recorded name from defaults.workflows; run '${runId}' records ` + (name === void 0 ? "no workflowName" : `workflow '${name}', which is not registered`) + "; register it under defaults.workflows or pass the workflow value");
 				supplied = registered;
 			}
 			let bound;
 			if (supplied === void 0) {
-				if (meta?.workflowSourceRef === void 0) throw new ConfigError("engine.resume requires the workflow for in-process runs (docs/06, section \"Engine and ops API\"); only compiled runs with a persisted source resume bare");
+				if (meta?.workflowSourceRef === void 0) throw new ConfigError("engine.resume requires the workflow for in-process runs (https://docs.rulvar.com/guide/durability); only compiled runs with a persisted source resume bare");
 				const blob = await transcripts.get(meta.workflowSourceRef);
 				if (blob === null) throw new ConfigError(`resume: run '${runId}' records workflowSourceRef '${meta.workflowSourceRef}' but the transcript store has no such blob`);
 				const source = new TextDecoder().decode(blob);
@@ -12107,7 +12107,7 @@ function createEngine(options) {
 				if (meta?.workflowName !== void 0 && meta.workflowName !== supplied.name) throw new ConfigError(`resume binding mismatch: run '${runId}' was started by workflow '${meta.workflowName}', not '${supplied.name}'`);
 				if (supplied.kind === "compiled-workflow") {
 					const expectedHash = hashWorkflowSource(supplied.source);
-					if (meta?.workflowHash !== void 0 && meta.workflowHash !== expectedHash) throw new ConfigError(`resume binding mismatch: the supplied CompiledWorkflow source hash differs from the one recorded for run '${runId}' (docs/06, 10.2)`);
+					if (meta?.workflowHash !== void 0 && meta.workflowHash !== expectedHash) throw new ConfigError(`resume binding mismatch: the supplied CompiledWorkflow source hash differs from the one recorded for run '${runId}'`);
 				} else {
 					const expectedHash = hashWorkflowBody(supplied);
 					if (meta?.workflowHash !== void 0 && meta.workflowHash !== expectedHash) process.emitWarning(`resume: the body of workflow '${supplied.name}' changed since run '${runId}' started; orphans and misses will be reported honestly`, {
@@ -12318,7 +12318,7 @@ function createSandboxBridge(ctx, options) {
 					for (const key of Object.keys(rawOpts)) if (!SANDBOX_AGENT_OPT_KEYS.has(key)) throw new ConfigError(`sandbox agent option '${key}' is outside the sanctioned dialect; allowed: ` + [...SANDBOX_AGENT_OPT_KEYS].sort().join(", "));
 					if (rawOpts.tools !== void 0) {
 						const tools = rawOpts.tools;
-						if (!(Array.isArray(tools) && tools.every((v) => typeof v === "string"))) throw new ConfigError("sandbox agent tools must be registered profile NAMES (docs/06, 8.3)");
+						if (!(Array.isArray(tools) && tools.every((v) => typeof v === "string"))) throw new ConfigError("sandbox agent tools must be registered profile NAMES");
 					}
 					const opts = rawOpts;
 					return toJournalValue(await ctx.agent(record.prompt, opts) ?? null, "sandbox agent result");
@@ -12334,7 +12334,7 @@ function createSandboxBridge(ctx, options) {
 				}
 				case "workflow": {
 					const record = asRecord(params, "workflow params");
-					if (typeof record.name !== "string") throw new ConfigError("sandbox workflow calls take a registered workflow NAME (docs/06, 2.5)");
+					if (typeof record.name !== "string") throw new ConfigError("sandbox workflow calls take a registered workflow NAME");
 					const callOpts = {};
 					if (typeof record.key === "string") callOpts.key = record.key;
 					return toJournalValue(await ctx.workflow(record.name, record.args ?? null, callOpts) ?? null, "sandbox workflow result");

package/package.json

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