@rulvar/core 1.0.0 → 1.2.0

package/dist/index.js

@@ -14,7 +14,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/l0/errors.ts
 /**
 * Base class for all engine-raised errors. "Retryable" means the engine's
-* own retry machinery (RetryPolicy under the journal, docs/04) MAY retry;
+* own retry machinery (RetryPolicy under the journal) MAY retry;
 * it never means a provider SDK autoretry, which is disabled.
 */
 var RulvarError = class extends Error {
@@ -79,8 +79,8 @@ var ScriptRejected = class extends RulvarError {
 };
 /**
 * Refusal to open a journal whose hashVersion falls outside the engine's
-* support window (docs/03, section "hashVersion"; producers ship in M2).
-* The registry code is 'journal_compat'; the docs/03 sub-codes live on
+* support window (producers ship in M2).
+* The registry code is 'journal_compat'; the sub-codes live on
 * `subCode` and in `data`.
 */
 var JournalCompatibilityError = class extends RulvarError {
@@ -118,8 +118,7 @@ var JournalCompatibilityError = class extends RulvarError {
 };
 /**
 * A resolution attempt against an already-closed suspension, rejected under
-* the first-closing-wins fold; appends no entry (docs/03, section
-* "Suspension and resolutions"; producers ship in M2).
+* the first-closing-wins fold; appends no entry (producers ship in M2).
 */
 var InvalidResolutionError = class extends RulvarError {
 	code = "invalid_resolution";
@@ -132,7 +131,7 @@ var InvalidResolutionError = class extends RulvarError {
 };
 /**
 * A breach of the total per-run append order: an unfenced concurrent writer
-* or a store violating contract A2 (docs/03, section "Storage SPI").
+* or a store violating contract A2 (https://docs.rulvar.com/guide/stores).
 */
 var JournalOrderViolation = class extends RulvarError {
 	code = "journal_order_violation";
@@ -143,7 +142,7 @@ var JournalOrderViolation = class extends RulvarError {
 		});
 	}
 };
-/** PlanRunner plan-invariant rejection (docs/07; producers ship in M7). */
+/** PlanRunner plan-invariant rejection (producers ship in M7). */
 var PlanInvariantError = class extends RulvarError {
 	code = "plan_invariant";
 	constructor(message, opts) {
@@ -155,7 +154,7 @@ var PlanInvariantError = class extends RulvarError {
 };
 /**
 * Raised at resume when the refolded plan state disagrees with the
-* journaled planHash chain (docs/07; producers ship in M7).
+* journaled planHash chain (producers ship in M7).
 */
 var ReplayPlanHashMismatch = class extends RulvarError {
 	code = "replay_plan_hash_mismatch";
@@ -168,8 +167,7 @@ var ReplayPlanHashMismatch = class extends RulvarError {
 };
 /**
 * Invalid orchestrator cap and finalize-reserve configuration, thrown
-* before the first LLM call (docs/06, section "Three-layer budget", DEF-7;
-* producers ship in M6/M7).
+* before the first LLM call (DEF-7; producers ship in M6/M7).
 */
 var OrchestratorCapConfigError = class extends RulvarError {
 	code = "orchestrator_cap_config";
@@ -196,8 +194,7 @@ var JournalMissError = class extends RulvarError {
 /**
 * The run budget ceiling blocked further work. The budget guard denial is
 * a decision entry; ctx primitives throw this as AgentError kind 'budget';
-* the run reports outcome 'exhausted', overriding 'error' (docs/06, section
-* "Three-layer budget").
+* the run reports outcome 'exhausted', overriding 'error'.
 */
 var BudgetExhaustedError = class extends RulvarError {
 	code = "budget_exhausted";
@@ -210,13 +207,12 @@ var BudgetExhaustedError = class extends RulvarError {
 };
 /**
 * A structural admission rejection (maxDepth, maxChildrenPerNode,
-* maxTotalSpawns) from the AdmissionController (docs/07, section
-* "AdmissionController"; M6-T06). The rejection verdict is embedded in
+* maxTotalSpawns) from the AdmissionController (M6-T06). The rejection verdict is embedded in
 * the carrying spawn-admission decision entry and replays identically;
 * the error surfaces the embedded AdmitRejectReason in `data` to the
 * caller (a typed tool error for orchestrators) and MUST NOT tear down
 * the run. Budget-code rejections throw BudgetExhaustedError instead,
-* keeping the docs/06 5.7 exhaustion semantics.
+* keeping the budget exhaustion semantics (https://docs.rulvar.com/guide/budgets).
 */
 var AdmissionRejectedError = class extends RulvarError {
 	code = "admission_rejected";
@@ -228,8 +224,8 @@ var AdmissionRejectedError = class extends RulvarError {
 	}
 };
 /**
-* A WorkerSandboxRunner resource-limit breach (docs/06, section 8.2;
-* M6-T02): crossing timeoutMs or memoryMb terminates the worker and the
+* A WorkerSandboxRunner resource-limit breach (M6-T02): crossing
+* timeoutMs or memoryMb terminates the worker and the
 * run completes with outcome 'error' carrying this error's WireError
 * projection; `data` records { reason: 'timeout' | 'memory', limit }.
 * The class itself is never journaled as an entry of its own.
@@ -245,8 +241,7 @@ var SandboxError = class extends RulvarError {
 };
 /**
 * acquire() on a currently held lease. Retryable by contract: retry after
-* the lease ttl elapses or the holder releases (docs/03, section
-* "Storage SPI").
+* the lease ttl elapses or the holder releases.
 */
 var LeaseHeldError = class extends RulvarError {
 	code = "lease_held";
@@ -260,8 +255,7 @@ var LeaseHeldError = class extends RulvarError {
 /**
 * commit() on a ModelKnowledgeStore against a snapshot version that is
 * no longer current. Retryable by contract: re-read current(), rebase
-* the ops, commit again, mirroring the lease fencing discipline
-* (docs/05, section "Commit discipline").
+* the ops, commit again, mirroring the lease fencing discipline.
 */
 var KnowledgeCasError = class extends RulvarError {
 	code = "knowledge_cas";
@@ -274,8 +268,8 @@ var KnowledgeCasError = class extends RulvarError {
 };
 /**
 * Projects an AgentError to its WireError form: code 'agent', with kind,
-* retryAfterMs, and issues carried in data (docs/02, section "Error
-* taxonomy"). Issue paths are flattened to JSON-safe segments.
+* retryAfterMs, and issues carried in data. Issue paths are flattened to
+* JSON-safe segments.
 */
 function agentErrorToWire(error, message) {
 	const data = { kind: error.kind };
@@ -319,8 +313,7 @@ function agentErrorFromWire(wire) {
 //#region src/l0/serialization.ts
 /**
 * The L0 serialization hook and the default secret-masking policy
-* (M8-T04; docs/03, section "Serialization hook"; docs/09, section
-* "Redaction and sensitive data"; OQ-20/OQ-22 interim rules executed).
+* (M8-T04; OQ-20/OQ-22 interim rules executed).
 *
 * The hook is the single policy point between the engine and
 * persistence: redact/encrypt at the append and put boundaries,
@@ -336,13 +329,13 @@ function agentErrorFromWire(wire) {
 * emitted WorkflowEvent passes it (opt out per engine via
 * `redaction: { maskEvents: false }`); the OTel exporter applies it to
 * string attributes. It masks strings that look like credentials; it is
-* deliberately conservative (docs/09, section 8: the pattern set is
+* deliberately conservative (the pattern set is
 * tuned on dogfood payloads, OQ-22 stays open for that).
 */
 /**
 * The kernel orders and matches on these BEFORE values are consulted;
 * a hook that rewrites them would corrupt replay silently, so drift is
-* a loud ConfigError at the boundary (docs/03, 12.8).
+* a loud ConfigError at the boundary.
 */
 const PINNED_FIELDS = [
 	"hashVersion",
@@ -543,8 +536,7 @@ function monotonicUlidFactory(options) {
 //#region src/l0/messages.ts
 /**
 * Returns a per-engine minter of CanonicalId values. Monotonic within the
-* factory instance; never a module-level singleton (docs/02, section
-* "Dependency rules": no module state).
+* factory instance; never a module-level singleton (no module state).
 */
 function createCanonicalIdMinter(options) {
 	return monotonicUlidFactory(options);
@@ -1442,8 +1434,7 @@ var Validator = class {
 /**
 * RFC 8785 (JSON Canonicalization Scheme) serializer.
 *
-* Backs content-key derivation and schema hashing (docs/03, sections
-* "Identity model" and "schemaHash and toolsetHash derivation"):
+* Backs content-key derivation and schema hashing:
 * lexicographically sorted object members (UTF-16 code units), minimal
 * escaping, no insignificant whitespace, ECMAScript number formatting.
 *
@@ -1488,8 +1479,8 @@ function jcsSerialize(value) {
 * SchemaSpec, Out<S> inference, JSON Schema projection, canonical schema
 * derivation, and the schemaHash/toolsetHash functions (M1-T03).
 *
-* Owning specs: docs/08-tools-permissions-spec.md, section "SchemaSpec";
-* docs/03-journal-spec.md, section "schemaHash and toolsetHash derivation".
+* Public contracts: https://docs.rulvar.com/guide/tools (SchemaSpec) and
+* https://docs.rulvar.com/guide/journal (hash derivation).
 */
 /**
 * Form-1 guard: the value implements the Standard Schema interface. Some
@@ -1504,8 +1495,7 @@ function isSchemaPairSpec(spec) {
 	return typeof spec === "object" && spec !== null && !("~standard" in spec) && "jsonSchema" in spec && typeof spec.validate === "function";
 }
 /**
-* Derives the JSON Schema of a SchemaSpec (docs/08, section "JSON Schema
-* derivation and acceptance rules"). Form 1 projects via the
+* Derives the JSON Schema of a SchemaSpec. Form 1 projects via the
 * StandardJSONSchemaV1 input() converter, target draft 2020-12 with
 * draft-07 fallback; a library without the projection is a typed
 * ConfigError at definition time, never at first call. Transforming
@@ -1532,8 +1522,7 @@ function projectToJsonSchema(spec) {
 }
 /**
 * Annotation-only keywords stripped by canonicalization; `format` is
-* retained because it is validation-relevant in the vendored validator
-* (docs/03, section "schemaHash and toolsetHash derivation").
+* retained because it is validation-relevant in the vendored validator.
 */
 const ANNOTATION_KEYWORDS = /* @__PURE__ */ new Set([
 	"title",
@@ -1577,8 +1566,7 @@ const SUBSCHEMA_ARRAY_KEYWORDS = /* @__PURE__ */ new Set([
 /**
 * Keywords that are pure reference infrastructure: dead weight once every
 * local $ref has been inlined, removed from the canonical form so that a
-* $defs rename or an unused definition never shifts a content key
-* (docs/03, section "schemaHash and toolsetHash derivation").
+* $defs rename or an unused definition never shifts a content key.
 */
 const REF_INFRASTRUCTURE_KEYWORDS = /* @__PURE__ */ new Set([
 	"$defs",
@@ -1652,8 +1640,7 @@ function canonicalizeNode(node, root, refStack) {
 	return out;
 }
 /**
-* Canonical schema derivation (docs/03, section "schemaHash and
-* toolsetHash derivation"): local fragment-only $ref inlined (recursion is
+* Canonical schema derivation: local fragment-only $ref inlined (recursion is
 * a ConfigError), remote and dynamic references forbidden, annotation
 * keywords stripped (format retained), reference infrastructure ($defs,
 * definitions, $anchor) removed once inlined. The result feeds JCS
@@ -1667,8 +1654,7 @@ function sha256Hex$3(text) {
 }
 /**
 * The schemaHash used when no structured-output schema is declared: the
-* hash of the canonical `true` schema (docs/03, section "schemaHash and
-* toolsetHash derivation").
+* hash of the canonical `true` schema.
 */
 const EMPTY_SCHEMA_HASH = sha256Hex$3("true");
 /** The toolsetHash of an empty toolset: the hash of the canonical empty contract array. */
@@ -1691,8 +1677,7 @@ function schemaHashOfSpec(spec) {
 * contract tuples (name, description, canonical parameters, version)
 * sorted by name. Tool description IS part of the contract; schema
 * annotations inside parameters are not. An absent version participates as
-* absent (docs/03, section "schemaHash and toolsetHash derivation";
-* docs/08, section "toolsetHash contract").
+* absent.
 */
 function toolsetHash(contracts) {
 	return sha256Hex$3(jcsSerialize([...contracts].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).map((contract) => {
@@ -1714,7 +1699,7 @@ function pointerToPath(instanceLocation) {
 	});
 }
 /**
-* Runtime validation per form (docs/08, section "Runtime validation"):
+* Runtime validation per form:
 * form 1 via the Standard Schema's own validate, form 2 via the pair's
 * type guard, form 3 via the vendored draft 2020-12 validator. The same
 * machinery backs the structured-output tiers of the Agent Runtime.
@@ -1767,8 +1752,7 @@ const CURRENT_HASH_VERSION = 2;
 /**
 * Round-1 normalization: hashVersion is taken from `hashVersion`, else
 * from the legacy `v` field, else 1. Stores are never rewritten;
-* normalization happens at read (docs/03, section "The single versioning
-* mechanism").
+* normalization happens at read.
 */
 function normalizeEntry(raw) {
 	const record = raw;
@@ -1783,15 +1767,15 @@ function normalizeEntry(raw) {
 //#endregion
 //#region src/knowledge/decay.ts
 /**
-* Grounding and decay (M11-T03; docs/05, section "Grounding and
-* decay"). The decay owner: the asymmetric TTL table, the expiry
+* Grounding and decay (M11-T03). The decay owner: the asymmetric
+* TTL table, the expiry
 * filter the read path applies at every pin AND repin (M10-T03), the
 * re-measurement queue (a STATUS FILTER, not infrastructure), and the
 * archive-never-delete maintenance helpers (historical runs keep their
 * audit trail).
 */
 /**
-* The asymmetric TTL table (docs/05, section "Grounding and decay"):
+* The asymmetric TTL table:
 * a false negative is costlier through lock-in, so weaknesses expire
 * sooner than strengths.
 */
@@ -1807,14 +1791,14 @@ const CLAIM_TTL_DAYS = {
 };
 /** Inbox proposals expire after 14 days (reserved for M12 phase 3). */
 const INBOX_PROPOSAL_TTL_DAYS = 14;
-/** The docs/05 TTL applied to an observedAt ISO date. */
+/** The asymmetric TTL applied to an observedAt ISO date. */
 function claimExpiry(claimClass, polarity, observedAt) {
 	const base = Date.parse(observedAt);
 	if (Number.isNaN(base)) throw new ConfigError(`claimExpiry: observedAt is not a date: '${observedAt}'`);
 	const days = CLAIM_TTL_DAYS[claimClass][polarity];
 	return new Date(base + days * 864e5).toISOString();
 }
-/** True when the claim steers nothing at `at` (docs/05, read-path filters). */
+/** True when the claim steers nothing at `at` (the read-path filter). */
 function claimExpired(claim, at) {
 	const expiry = Date.parse(claim.expiresAt);
 	const now = Date.parse(at);
@@ -1824,7 +1808,7 @@ function ttlState(claim, at) {
 	return claimExpired(claim, at) ? "expired" : "holds";
 }
 /**
-* The re-measurement queue (docs/05, section "Grounding and decay"):
+* The re-measurement queue:
 * expired eval-measured claims that are still ACTIVE. Just a status
 * filter: the next sweep re-measures these subjects; nothing archives
 * them (archiving would empty the queue and hide the decay).
@@ -1833,9 +1817,9 @@ function remeasureQueue(claims, at) {
 	return claims.filter((claim) => claim.status === "active" && claim.class === "eval-measured" && claimExpired(claim, at));
 }
 /**
-* Deprecation maintenance (docs/05: "deprecations, which archive
-* claims, never delete them, so historical runs keep their audit
-* trail"): archive ops for every non-terminal claim of the deprecated
+* Deprecation maintenance (deprecations archive claims, never delete
+* them, so historical runs keep their audit trail): archive ops for
+* every non-terminal claim of the deprecated
 * models. The caller commits them under its own gate-free archive ops.
 */
 function archiveDeprecatedModelOps(claims, deprecated) {
@@ -1849,8 +1833,7 @@ function archiveDeprecatedModelOps(claims, deprecated) {
 //#endregion
 //#region src/knowledge/claims.ts
 /**
-* Claim validators, the editorial path (M10-T02; docs/05, sections
-* "Data model", "The human gate", "Grounding and decay"). The types
+* Claim validators, the editorial path (M10-T02). The types
 * live with the SPI (l0/spi/knowledge.ts); this module owns the
 * RUNTIME enforcement that the types promise:
 *
@@ -1864,9 +1847,9 @@ function archiveDeprecatedModelOps(claims, deprecated) {
 * - statements stay bounded, evidence stays mandatory, TTL fields stay
 *   coherent.
 */
-/** docs/06, Appendix A: KB active-claims cap, default 8 per (model, taskClass). */
+/** Appendix A: KB active-claims cap, default 8 per (model, taskClass). */
 const KB_ACTIVE_CLAIMS_CAP = 8;
-/** docs/05, section "Data model": statement <= 200 chars. */
+/** The committed data model bound: statement <= 200 chars. */
 const CLAIM_STATEMENT_MAX_CHARS = 200;
 const RULED_OUT_VOCABULARY = /* @__PURE__ */ new Set([
 	"prompt",
@@ -1913,8 +1896,8 @@ function claimIssues(claim, path, options) {
 	return issues;
 }
 /**
-* The coherence square of the committer identity (docs/05, 5.4;
-* M11-T01): an eval-committer-gated claim MUST be eval-measured,
+* The coherence square of the committer identity (M11-T01): an
+* eval-committer-gated claim MUST be eval-measured,
 * authored by the eval pipeline, and carry metrics; anything else is
 * an identity mismatch, schema-enforced.
 */
@@ -1941,7 +1924,7 @@ function claimOpIssues(op, index) {
 	return issues;
 }
 /**
-* The commit-time cap (docs/06, Appendix A): active claims per
+* The commit-time cap (Appendix A): active claims per
 * (model, taskClass) after the batch applies. Supersede chains keep
 * only the head active by construction (applyClaimOps flips the prior
 * to 'superseded'), so a supersede never grows the count.
@@ -1971,8 +1954,7 @@ function validateEditorialCommit(ops, claimsAfter, options) {
 //#endregion
 //#region src/knowledge/epoch.ts
 /**
-* modelEpoch capture (M11-T04; docs/05, section "Grounding and
-* decay"). An HONESTLY COARSE signal: the registry version, the
+* modelEpoch capture (M11-T04). An HONESTLY COARSE signal: the registry version, the
 * price-table version, and the caps hash catch overt model swaps and
 * deprecations; silent alias re-pointing is a documented uncaught case
 * absent probes (the canary fingerprint in @rulvar/evals compensates,
@@ -1999,8 +1981,7 @@ function modelEpochOf(inputs) {
 * FileModelKnowledgeStore (M10-T01): the default ModelKnowledgeStore, a
 * single JSON file in the project (`./rulvar.models.json`),
 * git-diffable, serverless, embeddable. The git review of that file IS
-* the human gate's medium (docs/05, sections "Data model" and "Format
-* decision rationale"); the store itself only enforces the mechanics:
+* the human gate's medium; the store itself only enforces the mechanics:
 * CAS by monotonic version (mirroring the lease fencing discipline),
 * append-only claim evolution (supersede and archive flip status, never
 * delete), and atomic replace on write.
@@ -2130,7 +2111,7 @@ var FileModelKnowledgeStore = class {
 *
 * Named strong default models live ONLY in the umbrella `rulvar`
 * package config, never here: the core ships the floor mechanism, the
-* umbrella ships opinions (docs/04, section "Role quality floors").
+* umbrella ships opinions.
 */
 function violates(ref, constraint) {
 	if (constraint === void 0) return;
@@ -2154,11 +2135,11 @@ function checkFloors(options) {
 }
 //#endregion
 //#region src/knowledge/card.ts
-/** docs/06, Appendix A: the KB card render budget (characters). */
+/** The KB card render budget (characters). */
 const KB_CARD_RENDER_BUDGET_CHARS = 4096;
 /**
 * The ladders a run declares: every advertised profile whose model
-* spec is a ladder (docs/04, section 12). The card is tier-relative to
+* spec is a ladder. The card is tier-relative to
 * exactly these.
 */
 function collectDeclaredLadders(profiles) {
@@ -2193,7 +2174,7 @@ function floored(model, taskClass, floors) {
 	}
 }
 /**
-* The admission filter (docs/05, 4.1): status active, unexpired at
+* The admission filter: status active, unexpired at
 * `now`, and the subject reachable through the run's declared ladders
 * after the role-floor filter.
 */
@@ -2211,8 +2192,7 @@ function tiersOf(claim, ladders) {
 	return coordinates;
 }
 /**
-* The verified-layer compiler (M11-T06; docs/05, sections "Read path"
-* and "Composition with the model layer"): start-tier recommendations
+* The verified-layer compiler (M11-T06): start-tier recommendations
 * per (ladder, taskClass) compiled EXCLUSIVELY from eval-measured
 * claims. A strength on a rung below the default votes down (start
 * cheaper); a weakness on the default rung or below votes up. The net
@@ -2257,9 +2237,9 @@ function compileVerifiedLayer(claims, ladders) {
 	return rows;
 }
 /**
-* The deterministic card render (docs/05, 4.3). Pure: same filtered
+* The deterministic card render. Pure: same filtered
 * claims and ladders give byte-identical text. The render budget is
-* docs/06 Appendix A (4096 chars); over it, the OLDEST-observed notes
+* 4096 chars; over it, the OLDEST-observed notes
 * withhold first behind an explicit marker.
 */
 function modelKnowledgeCard(claims, ladders, options) {
@@ -2271,6 +2251,30 @@ function modelKnowledgeCard(claims, ladders, options) {
 		lines.push("Verified layer (start-tier recommendations, clamped one rung from the default):");
 		for (const row of verified) lines.push(`- ladder '${row.ladder}', taskClass '${row.taskClass}': start tier ${String(row.recommendedTier)} (default ${String(row.defaultTier)}, eval evidence, ${String(row.votes)} claim${row.votes === 1 ? "" : "s"})`);
 	}
+	const profileLines = [];
+	for (const [name, profile] of Object.entries(options?.profiles ?? {}).sort(([left], [right]) => left < right ? -1 : 1)) {
+		const model = profile.model;
+		if (typeof model !== "string") continue;
+		const matched = claims.filter((claim) => claim.class === "eval-measured" && claim.subject.model === model && (profile.effort === void 0 || claim.subject.effort === profile.effort));
+		if (matched.length === 0) continue;
+		const byClass = /* @__PURE__ */ new Map();
+		for (const claim of [...matched].sort((left, right) => left.id < right.id ? -1 : 1)) {
+			const verdict = claim.polarity === "strength" ? "strong" : "weak";
+			const prior = byClass.get(claim.taskClass);
+			byClass.set(claim.taskClass, prior === "weak" ? "weak" : verdict);
+		}
+		const strong = [...byClass.entries()].filter(([, verdict]) => verdict === "strong").map(([taskClass]) => taskClass).sort();
+		const weak = [...byClass.entries()].filter(([, verdict]) => verdict === "weak").map(([taskClass]) => taskClass).sort();
+		const parts = [];
+		if (strong.length > 0) parts.push(`strong ${strong.join(", ")}`);
+		if (weak.length > 0) parts.push(`weak ${weak.join(", ")}`);
+		profileLines.push(`- ${name}: ${parts.join("; ")}`);
+	}
+	if (profileLines.length > 0) {
+		lines.push("Profile evidence (eval-measured, folded over each profile model):");
+		lines.push(...profileLines);
+		lines.push("Spawn guidance: prefer the cheapest profile marked strong for the task at hand; avoid profiles marked weak at it.");
+	}
 	const noteLines = claims.filter((claim) => claim.class === "human-editorial").sort((left, right) => left.observedAt === right.observedAt ? left.id < right.id ? -1 : 1 : left.observedAt < right.observedAt ? 1 : -1).map((claim) => {
 		return `- [${tiersOf(claim, ladders).join(", ")}] ${claim.taskClass} ${claim.polarity} (confidence ${claim.confidence}, observed ${claim.observedAt}, expires ${claim.expiresAt}): ${claim.statement}`;
 	});
@@ -2318,7 +2322,7 @@ function compilePermissionPreset(preset) {
 //#endregion
 //#region src/tools/shell-matcher.ts
 /**
-* Lexes a command into segments per the docs/08 5.2 algorithm. Quotes
+* Lexes a command into segments per the matching algorithm above. Quotes
 * and escapes are honored; nothing is expanded; `$(`, backticks, `<(`,
 * `>(`, and `<<` (outside single quotes) poison their segment.
 */
@@ -2498,16 +2502,15 @@ function matchShellCommand(command, rules) {
 * execute body never invalidates a journal; changing semantics is
 * signaled by bumping version.
 *
-* Owning spec: docs/08-tools-permissions-spec.md, sections "Tool
-* definition and toolsetHash" and "SchemaSpec".
+* Public docs: https://docs.rulvar.com/guide/tools
 */
-/** First-party provider tool-name constraint intersection (docs/08, section 1.1). */
+/** First-party provider tool-name constraint intersection. */
 const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
 /**
 * Defines a tool. Definition-time failures are typed ConfigErrors, never
 * first-call surprises: an illegal name, a Standard Schema without the
 * JSON Schema projection, a recursive local $ref, or a remote/dynamic
-* reference all fail here (docs/08, sections 1.1 and 2.3).
+* 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")`);
@@ -2526,8 +2529,7 @@ function tool(init) {
 }
 /**
 * The identity projection: the contract tuple that enters toolsetHash.
-* parameters is the canonicalized derived JSON Schema (docs/03, section
-* "schemaHash and toolsetHash derivation").
+* parameters is the canonicalized derived JSON Schema.
 */
 function toolContract(def) {
 	const parameters = canonicalizeSchema(projectToJsonSchema(def.parameters));
@@ -2549,8 +2551,7 @@ function toolContract(def) {
 * for the agent's lifetime; provider-side drift of a source's tools
 * changes the content key of NEW spawns only.
 *
-* Owning spec: docs/08-tools-permissions-spec.md, sections "toolsetHash
-* contract", "ToolSource seam", and "Filtering and prefixing".
+* Docs: https://docs.rulvar.com/guide/tools.
 */
 /** The empty toolset (no tools declared anywhere). */
 function emptyToolset() {
@@ -2565,8 +2566,8 @@ function isToolDef(spec) {
 }
 /**
 * Expands sources, validates every tool name and duplicate names across
-* the whole toolset (ConfigError at spawn time; docs/08 sections 1.1 and
-* 6.4), and computes the toolsetHash over contracts sorted by name.
+* the whole toolset (ConfigError at spawn time), and computes the
+* toolsetHash over contracts sorted by name.
 */
 async function resolveToolset(specs, session) {
 	if (specs === void 0 || specs.length === 0) return emptyToolset();
@@ -2622,7 +2623,7 @@ function buildToolContext(seed) {
 * contract. Pinned SDK line: @modelcontextprotocol/sdk ^1.29 (the v2
 * migration is the explicit post-M3 task M5-T10; risk R1).
 *
-* Owning spec: docs/08-tools-permissions-spec.md, section "MCP bus".
+* Docs: https://docs.rulvar.com/guide/mcp.
 */
 function validateConfig(cfg) {
 	const forbid = (key) => {
@@ -2674,7 +2675,7 @@ function errorText(result) {
 * first tools() call; tools/list is fetched with cursor pagination until
 * exhaustion and cached per session; a listChanged notification
 * invalidates the cache, affecting subsequently spawned agents only (a
-* spawn's toolset snapshot is immutable by construction; docs/08 6.3).
+* spawn's toolset snapshot is immutable by construction).
 */
 function mcp(cfg) {
 	validateConfig(cfg);
@@ -2773,13 +2774,12 @@ function mcp(cfg) {
 * retain failed trees under the shared pin cap.
 *
 * The sandbox is a determinism and blast-radius boundary, NOT a security
-* boundary (docs/08, sections 7.2 and 8; docs/01 NFR security posture).
+* boundary.
 *
-* Owning spec: docs/08-tools-permissions-spec.md, section "Isolation and
-* worktree lifecycle".
+* Full contract: https://docs.rulvar.com/guide/tools
 */
 const execFileAsync = promisify(execFile);
-/** docs/06 Appendix A: the shared pin cap (park/unpark and retainWorktree). */
+/** Appendix A: the shared pin cap (park/unpark and retainWorktree). */
 const DEFAULT_MAX_PINNED_WORKTREES = 4;
 async function git(cwd, args) {
 	const { stdout } = await execFileAsync("git", [
@@ -2791,7 +2791,7 @@ async function git(cwd, args) {
 }
 /**
 * The shipped git worktree lifecycle. A non-git host is a typed
-* ConfigError at acquire (docs/08, section 8.3, rule 1).
+* ConfigError at acquire.
 */
 var GitWorktreeProvider = class {
 	repoRoot;
@@ -2881,7 +2881,7 @@ var GitWorktreeProvider = class {
 * spawn kind and content-key derivation, sha256 over RFC 8785 JCS
 * canonical JSON. Frozen as part of the hashVersion 2 profile in M2.
 *
-* Owning spec: docs/03-journal-spec.md, section "Identity model" (DEF-6
+* Identity model contract: https://docs.rulvar.com/guide/journal (DEF-6
 * framing). Excluded from every content key: cosmetics (label, phase),
 * handling policy (onError, retry, replay), policy fields
 * (memoizeOutcome), lineage blocks, and spanId.
@@ -2889,8 +2889,8 @@ var GitWorktreeProvider = class {
 /**
 * The identity projection of a CanonicalModelSpec. For the plain-model
 * kind the projection is `{ model, effort? }` WITHOUT the kind
-* discriminant, exactly as fixed by the docs/03 section 1.5 worked
-* example; `effort` is omitted when unresolved. The ladder embedding lands
+* discriminant, exactly as frozen by the hashVersion 2 profile;
+* `effort` is omitted when unresolved. The ladder embedding lands
 * with ladder execution (M7).
 */
 function modelSpecIdentity(spec) {
@@ -2924,7 +2924,7 @@ function identityJcs(input) {
 	return jcsSerialize(projectIdentity(input));
 }
 /**
-* key = sha256(JCS(IdentityInput)) (docs/03, section "Content key").
+* key = sha256(JCS(IdentityInput)).
 */
 function deriveContentKey(input) {
 	return createHash("sha256").update(identityJcs(input), "utf8").digest("hex");
@@ -2936,7 +2936,7 @@ function deriveContentKey(input) {
 * of wall-clock (invariant I3: structure comes from call-and-return only).
 * The grammar is part of the hashVersion 2 profile.
 *
-* Owning spec: docs/03-journal-spec.md, section "Scope-path grammar".
+* Full contract: https://docs.rulvar.com/guide/journal.
 *
 * Segment rules: a sequential body is ONE scope (sequential calls add no
 * segment; they are distinguished by key and ordinal only). ctx.phase is
@@ -3071,12 +3071,12 @@ var ParallelSiteCounter = class {
 * per-engine deriver registry, the support-window compatibility scan, and
 * the versioned KeyRing for matching. A profile is immutable after
 * release and versions the ENTIRE identity and replay pipeline as one
-* unit (docs/03, section "hashVersion").
+* unit. Full contract: https://docs.rulvar.com/guide/journal-compatibility.
 */
 function sha256Hex$2(text) {
 	return createHash("sha256").update(text, "utf8").digest("hex");
 }
-/** The full v2 table; the three kernel amendments live in these rules (docs/03, section 6.3). */
+/** The full v2 table; the three kernel amendments live in these rules. */
 const V2_TABLE = {
 	ok: "replay",
 	escalated: "replay",
@@ -3111,7 +3111,7 @@ const deriverV2 = {
 		budgetAccount: "root"
 	}
 };
-/** Kinds that did not exist in round 1: incomparable under v1 (docs/03, section 4.3). */
+/** Kinds that did not exist in round 1: incomparable under v1. */
 const V1_INEXPRESSIBLE_KINDS = /* @__PURE__ */ new Set([
 	"decision",
 	"plan.revision",
@@ -3159,8 +3159,8 @@ function isKeyDeriver(value) {
 }
 /**
 * Builds the per-engine deriver registry: the shipped v1/v2 profiles plus
-* EngineOptions.extraDerivers, the ONLY window extender (docs/03, section
-* 4.5). A malformed extra deriver is a ConfigError before any run effect.
+* EngineOptions.extraDerivers, the ONLY window extender. A malformed
+* extra deriver is a ConfigError before any run effect.
 */
 function buildDeriverRegistry(extraDerivers) {
 	const registry = /* @__PURE__ */ new Map([[deriverV1.hashVersion, deriverV1], [deriverV2.hashVersion, deriverV2]]);
@@ -3173,7 +3173,7 @@ function buildDeriverRegistry(extraDerivers) {
 /**
 * The one compatibility scan: immediately after load, strictly BEFORE any
 * live call, any append, and any admission reserve; repeated at lease
-* acquire in queue mode (docs/03, section 4.5). Side-effect free.
+* acquire in queue mode. Side-effect free.
 */
 function scanJournalCompatibility(runId, entries, registry) {
 	const versions = [...registry.keys()];
@@ -3197,8 +3197,7 @@ function scanJournalCompatibility(runId, entries, registry) {
 }
 /**
 * KeyRing over the registry: the live call is projected DOWN into the
-* profile of the stored entry; there is no upward canonization (docs/03,
-* section 4.7).
+* profile of the stored entry; there is no upward canonization.
 */
 function registryKeyRing(registry) {
 	return { keyFor(identity, hashVersion) {
@@ -3219,11 +3218,11 @@ function registryKeyRing(registry) {
 * addressable); step 2 applies the per-status table of the ENTRY'S OWN
 * hashVersion profile, carrying the three kernel amendments:
 * memoizeOutcome on task-class failures, abandon-derived skipped, and
-* escalated-replays-as-ok (docs/03, section "Replay predicate (DEF-1)").
+* escalated-replays-as-ok (https://docs.rulvar.com/guide/journal).
 */
 /**
 * task-class: schema-mismatch, terminal, non-retryable tool. transport,
-* rate-limit, and budget are never memoized (docs/03, section 6.4).
+* rate-limit, and budget are never memoized.
 */
 function classifyAgentError(e) {
 	if (e.kind === "schema-mismatch" || e.kind === "terminal") return "task";
@@ -3232,7 +3231,7 @@ function classifyAgentError(e) {
 }
 /**
 * The child scope-prefix an abandon over `target` covers transitively.
-* Agent spawns nest under agent:<seq> (docs/03, section 2.2); a child
+* Agent spawns nest under agent:<seq>; a child
 * workflow's subtree runs under the wf:<name>:<ordinal> scope recorded in
 * its dispatch payload (M6-T06). A child entry without the payload
 * (foreign journals) degrades to the agent:<seq> convention, which covers
@@ -3249,7 +3248,7 @@ function childCoveragePrefix(target) {
 * Builds the AbandonFold in ONE pass at load, in append order, pinned for
 * the entire resume (DEF-1 ordering rule 4). Coverage is the target seq
 * itself plus, transitively, every entry under the target's child
-* scope-prefix (docs/03, sections 6.2 and 8.4). Repeated abandons over an
+* scope-prefix. Repeated abandons over an
 * already-covered target fold to noop.
 */
 function buildAbandonFold(entries) {
@@ -3335,8 +3334,8 @@ function dispositionHook(fold, registry, invalidated) {
 * Lineage: LogicalTaskId, approach signatures, and the counter folds
 * (M7-T02, DEF-3).
 *
-* Owning spec: docs/03-journal-spec.md, section "Lineage (DEF-3)";
-* docs/07-adaptive-orchestration-spec.md, section "Lineage (DEF-3)".
+* Public contract: https://docs.rulvar.com/guide/journal and
+* https://docs.rulvar.com/guide/adaptive-orchestration.
 *
 * The LTID answers "is this the same logical task across rebirths".
 * NodeId remains plan-node identity; the content key remains the identity
@@ -3349,9 +3348,9 @@ function dispositionHook(fold, registry, invalidated) {
 * in decision entries are READ on replay, never recomputed; a fold
 * recomputation over the same prefix serves only as an integrity assert.
 */
-/** approachSig/approachSigCoarse derivation version (docs/03, 10.7). */
+/** approachSig/approachSigCoarse derivation version. */
 const LINEAGE_SIG_VERSION = 1;
-/** Deterministic LTIDs canonized onto legacy journals (docs/03, 10.7). */
+/** Deterministic LTIDs canonized onto legacy journals. */
 const LEGACY_LTID_PREFIX = "legacy:";
 const DEFAULT_ESCALATION_LIMITS = {
 	maxEscalationsPerLogicalTask: 2,
@@ -3377,7 +3376,7 @@ function sha256Hex$1(text) {
 	return createHash("sha256").update(text, "utf8").digest("hex");
 }
 /**
-* Approach-tag normalization (docs/03, 10.2): NFC, lowercase, runs of
+* Approach-tag normalization: NFC, lowercase, runs of
 * non-alphanumerics collapse into a hyphen, truncate to 32 characters; an
 * empty value canonicalizes to 'default'. Prompt prose never enters any
 * signature: rephrasings collide by construction, not by heuristic.
@@ -3386,7 +3385,7 @@ function normalizeApproachTag(raw) {
 	const collapsed = (raw ?? "").normalize("NFC").toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 32);
 	return collapsed === "" ? "default" : collapsed;
 }
-/** The isolation string entering approachSigCoarse (docs/03, 10.3). */
+/** The isolation string entering approachSigCoarse. */
 function canonicalIsolationTag(spec) {
 	if (spec === void 0) return "none";
 	return typeof spec === "string" ? spec : spec.kind;
@@ -3394,7 +3393,7 @@ function canonicalIsolationTag(spec) {
 /**
 * approachSigCoarse = sha256(JCS({ sigVersion, agentType, toolsetHash,
 * schemaHash, isolation })). Feeds the stall detector and the oscillation
-* guard, which keys ACROSS LTID boundaries (docs/07, 3.8).
+* guard, which keys ACROSS LTID boundaries.
 */
 function approachSigCoarse(inputs) {
 	return sha256Hex$1(jcsSerialize({
@@ -3417,7 +3416,7 @@ function approachSigOf(coarse, tag) {
 * The deterministic signature inputs assigned to legacy spawns (journals
 * written before lineage existed) and to attempts whose producers did not
 * record signature inputs: stable constants, never wall-clock, so replay
-* canonizes identically on every engine (docs/03, 10.7).
+* canonizes identically on every engine.
 */
 const LEGACY_SIGNATURE_INPUTS = {
 	agentType: "legacy",
@@ -3441,7 +3440,7 @@ function classifyAttemptOutcome(terminal) {
 		default: return "task-error";
 	}
 }
-/** Outcome classes that lengthen the stall streak (docs/03, 10.4). */
+/** Outcome classes that lengthen the stall streak. */
 const STALLING_OUTCOMES = /* @__PURE__ */ new Set([
 	"task-error",
 	"no-progress",
@@ -3459,7 +3458,7 @@ function asRecord$2(value) {
 * Reads the computed SpawnLineage block of a decision payload, tolerating
 * pre-DEF-3 producers (M6 journals): a verdict lineage block without
 * signatures canonizes onto the deterministic legacy signature constants,
-* so folds over old journals stay byte-stable (docs/03, 10.7).
+* so folds over old journals stay byte-stable.
 */
 function readSpawnLineage(decision) {
 	if (decision === void 0) return;
@@ -3484,8 +3483,7 @@ function readSpawnLineage(decision) {
 * The incremental lineage fold: attempts, escalation debits, stall
 * streaks, single-live-attempt, and legacy canonization, computed from
 * journal entries only. `absorb` is idempotent by seq cursor; every read
-* accepts an optional `uptoSeq` pin so renders stay snapshot-stable
-* (docs/03, 10.4; docs/07, 8.3).
+* accepts an optional `uptoSeq` pin so renders stay snapshot-stable.
 */
 var LineageIndex = class {
 	attemptsByLtid = /* @__PURE__ */ new Map();
@@ -3671,7 +3669,7 @@ var LineageIndex = class {
 	* attempt whose bound key matches (an at-least-once redispatch of the
 	* same slot after cancelled/error/limit); else a legacy attempt is
 	* canonized with the deterministic 'legacy:' + contentHash LTID
-	* (docs/03, 10.7: random ULIDs on replay are forbidden).
+	* (random ULIDs on replay are forbidden).
 	*/
 	bindRoot(slotScope, entry) {
 		const queue = this.queueByScope.get(slotScope) ?? [];
@@ -3721,13 +3719,13 @@ var LineageIndex = class {
 	* True while the LTID has an unsettled attempt (admitted, dispatched, or
 	* redispatched without a terminal), including admits whose decision
 	* entries have not landed yet. Backs the single-live-attempt invariant:
-	* a competing admit gets `lineage_busy` (docs/03, 10.5).
+	* a competing admit gets `lineage_busy`.
 	*/
 	hasLiveAttempt(logicalTaskId) {
 		if ((this.pendingAdmits.get(logicalTaskId) ?? 0) > 0) return true;
 		return (this.attemptsByLtid.get(logicalTaskId) ?? []).some((attempt) => attempt.outcome === void 0);
 	}
-	/** The stall streak per docs/03, 10.4 (pinnable to a snapshot seq). */
+	/** The stall streak (pinnable to a snapshot seq). */
 	stallStreak(logicalTaskId, uptoSeq = Number.POSITIVE_INFINITY) {
 		let streak = 0;
 		for (const attempt of this.attemptsOf(logicalTaskId, uptoSeq)) {
@@ -3741,7 +3739,7 @@ var LineageIndex = class {
 		}
 		return streak;
 	}
-	/** The pinned LineageStats render (docs/03, 10.3). */
+	/** The pinned LineageStats render. */
 	statsOf(logicalTaskId, uptoSeq = Number.POSITIVE_INFINITY) {
 		const attempts = this.attemptsOf(logicalTaskId, uptoSeq);
 		const groups = /* @__PURE__ */ new Map();
@@ -3781,8 +3779,8 @@ var LineageIndex = class {
 /**
 * TerminationAccount and the termination lemma (M7-T03, DEF-2).
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, section 11;
-* docs/06-execution-spec.md, Appendix A defaults; XF-07/XF-09 cap fields.
+* Public contract: https://docs.rulvar.com/guide/budgets;
+* committed defaults declared below; XF-07/XF-09 cap fields.
 *
 * One construction is committed: a single per-run account with an
 * exclusively DEBIT-ONLY API and a limits vector frozen at start in the
@@ -3808,7 +3806,7 @@ function sha256Hex(text) {
 /**
 * Reads the declared ladder length of one agent profile. Ladders are
 * declared through the profile's ModelSpec (`model: { ladder }`, or the
-* loop-role routing entry; docs/04, section 12). The reader is defensive
+* loop-role routing entry). The reader is defensive
 * so the snapshot is total over every registry shape (an undeclared
 * ladder has length 1: the single implicit rung).
 */
@@ -3829,7 +3827,7 @@ function kMaxOf(profiles) {
 /**
 * The deterministic profile-registry snapshot hash frozen inside
 * termination.init: profile names mapped to their declared ladder
-* lengths, canonical JSON, sha256 (docs/07, 11.6).
+* lengths, canonical JSON, sha256.
 */
 function profileRegistrySnapshotHash(profiles) {
 	const projection = {};
@@ -3871,11 +3869,11 @@ function validateTerminationLimits(raw) {
 function lineageWeightOf(limits) {
 	return limits.maxEscalationsPerLogicalTask + limits.kMax;
 }
-/** Phi0 = V0 + C * S0, finite and fixed in termination.init (docs/07, 11.4). */
+/** Phi0 = V0 + C * S0, finite and fixed in termination.init. */
 function phiInitialOf(limits) {
 	return limits.maxRevisionsPerRun + lineageWeightOf(limits) * limits.maxTotalSpawns;
 }
-/** Builds the termination.init value payload (docs/07, 11.6). */
+/** Builds the termination.init value payload. */
 function buildTerminationInitValue(limits, registrySnapshotHash) {
 	return {
 		limits,
@@ -3891,7 +3889,7 @@ function readTerminationInit(entry) {
 	return value;
 }
 /**
-* Config-drift detection at resume (docs/07, 11.2): the journaled vector
+* Config-drift detection at resume: the journaled vector
 * always wins; every differing field is reported for the
 * `termination:config-drift` event. Dynamic budget top-up via restart is
 * excluded by construction.
@@ -3909,9 +3907,9 @@ function terminationConfigDrift(frozen, live) {
 	return drift;
 }
 /**
-* The single per-run TerminationAccount (docs/07, 11.5): debit ONLY. No
+* The single per-run TerminationAccount: debit ONLY. No
 * credit operation exists by construction; reclaim never replenishes
-* anything (DEF-5 interaction, docs/07 7.3). Live: the engine debits the
+* anything (DEF-5 interaction). Live: the engine debits the
 * in-memory account, writes the carrying entry with the balance-after,
 * then applies effects. Resume state is rebuilt by TerminationFold from
 * the journal, never from live config.
@@ -3950,7 +3948,7 @@ var TerminationAccount = class {
 			phi: this.phi()
 		};
 	}
-	/** Phi = V + C * S + sum over live lineages (E + R) (docs/07, 11.4). */
+	/** Phi = V + C * S + sum over live lineages (E + R). */
 	phi() {
 		let phi = this.revisionUnits + lineageWeightOf(this.limits) * this.spawnUnits;
 		for (const state of this.lineages.values()) phi += state.escalationUnitsRemaining + state.rungsRemaining;
@@ -3968,7 +3966,7 @@ var TerminationAccount = class {
 		return this.revisionUnits;
 	}
 	/**
-	* The spawn-admission debit (docs/07, 11.3b): minus one spawnUnit for
+	* The spawn-admission debit: minus one spawnUnit for
 	* an admitted spawn of ANY origin; a NEW lineage receives E0 escalation
 	* units and (K_l - 1) rung transitions in the same atomic step, so the
 	* lemma's per-spawn decrease is C - (E0 + K_l - 1) = kMax - K_l + 1,
@@ -3996,7 +3994,7 @@ var TerminationAccount = class {
 		};
 	}
 	/**
-	* The plan_revise debit (docs/07, 11.3a and 11.7): minus one
+	* The plan_revise debit: minus one
 	* revisionUnit on EVERY journaled plan.revision, regardless of the op
 	* count, guard verdicts, or the auto-rebase outcome; conflict spam is
 	* never a free retry.
@@ -4013,7 +4011,7 @@ var TerminationAccount = class {
 		};
 	}
 	/**
-	* The escalation debit (docs/07, 11.3d): minus one escalationUnit of
+	* The escalation debit: minus one escalationUnit of
 	* the affected lineage, including EACH lineage of a class-level
 	* decision and timeout defaultDecisions. Conditioned on the
 	* countsAgainstLimit flag embedded in the decision entry by the caller.
@@ -4031,7 +4029,7 @@ var TerminationAccount = class {
 		};
 	}
 	/**
-	* The ladder-raise debit (docs/07, 11.3c): minus one rung of the
+	* The ladder-raise debit: minus one rung of the
 	* lineage; rungIndex is strictly monotone, there are no demotions and
 	* no runtime startTier promotion in v1.
 	*/
@@ -4050,7 +4048,7 @@ var TerminationAccount = class {
 		};
 	}
 	/**
-	* The docs/07 11.5 debit surface: attempts the named resource and, on
+	* The unified debit surface: attempts the named resource and, on
 	* underflow, writes `termination.denied` strictly BEFORE resolving with
 	* the typed failure (the caller surfaces the error only after this
 	* settles). Requires a deniedWriter; pure-fold contexts use the
@@ -4136,7 +4134,7 @@ var TerminationAccount = class {
 		return lineage;
 	}
 };
-/** The typed error code surfaced after a denied debit (docs/07, 11.3). */
+/** The typed error code surfaced after a denied debit. */
 function exhaustionCodeOf(resource) {
 	switch (resource) {
 		case "revisionUnits": return "revision_budget_exhausted";
@@ -4150,7 +4148,7 @@ function asRecord$1(value) {
 	return typeof value === "object" && value !== null ? value : void 0;
 }
 /**
-* The replay fold (docs/07, 11.6): rebuilds the account from
+* The replay fold: rebuilds the account from
 * termination.init and the debiting decision entries, asserting every
 * embedded balance-after against the recomputation. A divergence raises
 * the typed journal-integrity error at exactly the diverging entry;
@@ -4283,7 +4281,8 @@ function applySpawnDebit(account, entry, admission, assertBalance) {
 * Reuse-by-reference: SpawnKey dedup, donor rules, node.link, and the
 * abandoned-spend ledger (M7-T07, DEF-5).
 *
-* Owning spec: docs/03-journal-spec.md, section 9; docs/07, section 7.3.
+* Full contract: https://docs.rulvar.com/guide/journal and
+* https://docs.rulvar.com/guide/adaptive-orchestration.
 * Oscillation (cancel followed by a byte-identical re-add) no longer
 * means full repayment: completed work under an abandoned scope comes
 * back by reference, partially completed work grafts through a
@@ -4299,7 +4298,7 @@ function applySpawnDebit(account, entry, admission, assertBalance) {
 */
 const DEFAULT_MAX_OSCILLATIONS_PER_KEY = 2;
 /**
-* node.link identity (docs/03, 9.5): sha256 of {kind, spawnKey,
+* node.link identity: sha256 of {kind, spawnKey,
 * donorScope, targetNodeId}; targetNodeId is deterministic on replay
 * because NodeIds are assigned inside plan.revision.
 */
@@ -4433,7 +4432,7 @@ var DedupIndex = class DedupIndex {
 	allDonorsOf(spawnKey) {
 		return this.donors.get(spawnKey) ?? [];
 	}
-	/** Link count per key: the oscillation counter (docs/03, 9.7). */
+	/** Link count per key: the oscillation counter. */
 	oscillationCountOf(spawnKey) {
 		return this.links.get(spawnKey) ?? 0;
 	}
@@ -4446,7 +4445,7 @@ var DedupIndex = class DedupIndex {
 		};
 	}
 };
-/** A plan-node scope (docs/03, 2.1): its entries belong to one node. */
+/** A plan-node scope: its entries belong to one node. */
 function isPlanNodeScope(scope) {
 	return /(^|\/)plan\/[0-9A-Z]{26}$/.test(scope);
 }
@@ -4457,8 +4456,8 @@ function readIsolation(entry) {
 	return "none";
 }
 /**
-* The four-outcome verdict evaluation on a SpawnKey match (docs/03,
-* 9.4), computed once live at the fold head and embedded into the
+* The four-outcome verdict evaluation on a SpawnKey match, computed
+* once live at the fold head and embedded into the
 * deciding entry; replay never re-evaluates.
 */
 function evaluateReuse(index, spawnKey, config) {
@@ -4587,7 +4586,7 @@ function decodeCheckpoint(blob) {
 * The journal append JSON-serializability check (M1-T04): every journaled
 * value MUST be JSON-serializable; a violation raises a typed
 * NonSerializableValueError at the calling site without journaling
-* anything (docs/03, section "Serialization requirements").
+* anything.
 */
 function check(value, path) {
 	if (value === null) return;
@@ -4644,7 +4643,7 @@ const KNOWN_KINDS = /* @__PURE__ */ new Set([
 	"termination.init",
 	"termination.denied"
 ]);
-/** Legal stored statuses per kind (docs/03, section 5.3). */
+/** Legal stored statuses per kind. */
 const LEGAL_STATUSES = {
 	agent: [
 		"running",
@@ -4740,8 +4739,7 @@ function validateEntryShape(entry) {
 * resolution and abandon are appends of new entries plus a pure
 * deterministic fold; JournalStore stays exactly five methods.
 *
-* Owning spec: docs/03-journal-spec.md, sections "Suspension and
-* resolutions (DEF-4)" and "Abandon, derived skipped" (9.1).
+* Full contract: https://docs.rulvar.com/guide/durability
 */
 /**
 * The first-closing-wins fold over a loaded journal: one pass by seq,
@@ -4751,7 +4749,7 @@ function validateEntryShape(entry) {
 * schema-invalid offline resolution classifies invalid and does NOT close
 * the target. Abandon coverage is the target seq plus the transitive
 * child scope-prefix; the AbandonFold consumed by the replay predicate is
-* a projection of THIS fold (docs/03, section 6.2: not a separate pass).
+* a projection of THIS fold (not a separate pass).
 */
 var ResolutionFold = class {
 	targets = /* @__PURE__ */ new Map();
@@ -4891,8 +4889,8 @@ var ResolutionFold = class {
 	}
 };
 /**
-* Per-run, per-target FIFO serializer of resolution/abandon attempts
-* (docs/03, section 8.5): classification against the in-memory fold ->
+* Per-run, per-target FIFO serializer of resolution/abandon attempts:
+* classification against the in-memory fold ->
 * durable append -> settle exactly once; losing attempts are ALSO
 * appended and become journaled noops by fold classification. Winner
 * effects run strictly after the critical section (the caller's job).
@@ -4985,7 +4983,7 @@ var ResolutionArbiter = class {
 };
 //#endregion
 //#region src/journal/matching.ts
-/** Kinds excluded from forward-matching cursors (docs/03, section 8.2). */
+/** Kinds excluded from forward-matching cursors. */
 const REF_ENTRY_KINDS = /* @__PURE__ */ new Set(["resolution", "abandon"]);
 function currentOnlyKeyRing() {
 	return { keyFor(identity, hashVersion) {
@@ -5009,7 +5007,7 @@ var JournalMatcher = class {
 	keyRing;
 	disposition;
 	aliasDisposition;
-	/** Scope-prefix aliases (DEF-5, docs/03 9.5): donor prefix -> target prefix. */
+	/** Scope-prefix aliases (DEF-5): donor prefix -> target prefix. */
 	aliases = [];
 	keyCache = /* @__PURE__ */ new Map();
 	hitsInternal = 0;
@@ -5040,8 +5038,8 @@ var JournalMatcher = class {
 		this.disposition = disposition;
 	}
 	/**
-	* The disposition applied to alias-sourced candidates (DEF-5, docs/03
-	* 9.5): the skipped overlay from abandon is bypassed ONLY through the
+	* The disposition applied to alias-sourced candidates (DEF-5): the
+	* skipped overlay from abandon is bypassed ONLY through the
 	* alias, so entries regain their pre-abandon terminal status for
 	* matching in the NEW scope; the standalone old scope stays skipped.
 	*/
@@ -5097,7 +5095,7 @@ var JournalMatcher = class {
 	* Forward-matches one live call. A miss does not advance any cursor and
 	* does not extinguish future hits: the scan always starts at the scope
 	* head and skips consumed operations, so insertion stability holds by
-	* construction (docs/03, section 7.1).
+	* construction.
 	*/
 	match(scope, identity, mode) {
 		if (mode === "never") {
@@ -5208,19 +5206,17 @@ var JournalMatcher = class {
 * The journal kernel write path (M1-T04): two-phase entries, ordinal
 * assignment, the per-run serialized append queue with the JSON
 * serializability check, and the budget-ledger fold. Scoped
-* forward-matching and the replay predicate land with resume in M2
-* (docs/03, sections "Scoped forward-matching" and "Replay predicate");
+* forward-matching and the replay predicate land with resume in M2;
 * in M1 every lookup is live.
 *
-* Owning spec: docs/03-journal-spec.md, sections "JournalEntry form",
-* "Two-phase entries, dispatch, and the budget ledger"; component sketch
-* in docs/02-architecture.md, section "Journal Kernel".
+* Full contract: https://docs.rulvar.com/guide/journal; architecture
+* overview: https://docs.rulvar.com/guide/architecture.
 */
-/** docs/06 Appendix A: large-value soft warn threshold (committed for M2). */
+/** Large-value soft warn threshold (committed for M2). */
 const LARGE_VALUE_WARN_BYTES = 262144;
 /**
 * Per-run journal kernel front end. Everything is per instance: no module
-* state anywhere (docs/02, section "Dependency rules").
+* state anywhere.
 */
 var Replayer = class {
 	runId;
@@ -5266,8 +5262,8 @@ var Replayer = class {
 		}
 	}
 	/**
-	* Forward-matches one live call against the prior journal (docs/03,
-	* section 7). Fresh runs always miss; the M2-T06 predicate is injected
+	* Forward-matches one live call against the prior journal. Fresh
+	* runs always miss; the M2-T06 predicate is injected
 	* through setDisposition once folds are built.
 	*/
 	match(scope, identity, mode) {
@@ -5283,7 +5279,7 @@ var Replayer = class {
 		this.matcher.setDisposition(disposition);
 	}
 	/**
-	* The disposition for alias-sourced candidates (DEF-5, docs/03 9.5):
+	* The disposition for alias-sourced candidates (DEF-5):
 	* bypasses the abandon overlay so donor entries regain their
 	* pre-abandon terminal status when matched through the alias.
 	*/
@@ -5291,7 +5287,7 @@ var Replayer = class {
 		this.matcher.setAliasDisposition(disposition);
 	}
 	/**
-	* Registers a node.link scope-prefix rewrite (DEF-5, docs/03 9.5):
+	* Registers a node.link scope-prefix rewrite (DEF-5):
 	* donorPrefix forward-matches into targetPrefix at every nested level.
 	* Idempotent; the alias map is rebuilt by fold on resume.
 	*/
@@ -5299,9 +5295,9 @@ var Replayer = class {
 		this.matcher.registerAlias(donorPrefix, targetPrefix);
 	}
 	/**
-	* invalidate/retry (docs/03, section 6.5): explicit unpinning of a
+	* invalidate/retry: explicit unpinning of a
 	* memoized failure; the invalidated entry reruns on this resume. The
-	* safety boundary is an open question (docs/14).
+	* safety boundary is an open question.
 	*/
 	invalidate(seq) {
 		this.invalidated.add(seq);
@@ -5348,8 +5344,8 @@ var Replayer = class {
 		});
 	}
 	/**
-	* Submits a resolution attempt through the per-target FIFO arbiter
-	* (docs/03, section 8.7). Losing attempts are journaled noops.
+	* Submits a resolution attempt through the per-target FIFO arbiter.
+	* Losing attempts are journaled noops.
 	*/
 	resolveSuspended(target, attempt) {
 		const targetEntry = this.entries.find((entry) => entry.seq === target);
@@ -5361,12 +5357,12 @@ var Replayer = class {
 		if (targetEntry === void 0) throw new ConfigError(`abandonBranch: seq ${attempt.target} does not exist`);
 		return this.arbiter.submitAbandon(targetEntry.scope, targetEntry.spanId, attempt);
 	}
-	/** Pure fold view, snapshot-pinned (docs/03, section 8.7). */
+	/** Pure fold view, snapshot-pinned. */
 	suspensionState(target) {
 		return this.foldInternal.suspensionState(target);
 	}
 	/**
-	* Value size policy (docs/03, section "Normative payload schemas"):
+	* Value size policy:
 	* there is NO automatic offload in v1; oversized values warn and
 	* proceed. Large artifacts belong in TranscriptStore by reference.
 	*/
@@ -5393,7 +5389,7 @@ var Replayer = class {
 	* Two-phase dispatch: the running entry (kinds agent, step, child).
 	* `value` is legal on child dispatches only: the child payload
 	* `{ workflow, childScope }` lets the abandon fold compute the child's
-	* transitive scope coverage (docs/03, section 8.4; M6-T06). Values
+	* transitive scope coverage (M6-T06). Values
 	* never enter identity.
 	*/
 	appendRunning(input) {
@@ -5457,8 +5453,7 @@ var Replayer = class {
 		});
 	}
 	/**
-	* The budget ledger fold (docs/03, section "Budget ledger fold on
-	* resume"): usage sums over terminal entries exactly once; agentsSpawned
+	* The budget ledger fold: usage sums over terminal entries exactly once; agentsSpawned
 	* counts agent dispatches.
 	*/
 	ledger() {
@@ -5545,7 +5540,7 @@ var Replayer = class {
 * resolveExternal validates against the pinned schema BEFORE append on
 * the live path and settles the waiting promise in place without replay.
 *
-* Owning specs: docs/06, section 2.7; docs/03, section 8.
+* Full contract: https://docs.rulvar.com/guide/durability
 */
 /**
 * Normalizes a resolution value into an ApprovalDecision. Anything that
@@ -5562,7 +5557,7 @@ function toApprovalDecision(value) {
 * Per-run registry of open external suspensions plus the run's activity
 * counter: when every in-flight branch is blocked on suspensions
 * (activity zero, waiters open), the run quiesces into outcome
-* 'suspended' (docs/06, section 2.7).
+* 'suspended'.
 */
 var ExternalRegistry = class ExternalRegistry {
 	replayer;
@@ -5677,7 +5672,7 @@ var ExternalRegistry = class ExternalRegistry {
 		});
 	}
 	/**
-	* Tool-approval suspension (M3-T03; docs/08, section 3.6): journals (or
+	* Tool-approval suspension (M3-T03): journals (or
 	* re-matches) the suspended approval entry keyed by (toolName, input)
 	* in the agent's child scope and parks until a resolution closes it.
 	* The ask verdict is journaled together with the turn checkpoint; on
@@ -5735,7 +5730,7 @@ var ExternalRegistry = class ExternalRegistry {
 		});
 	}
 	/**
-	* Flavor B escalation suspension (M3-T07; docs/07, section 6.2): the
+	* Flavor B escalation suspension (M3-T07): the
 	* escalate tool suspends the agent on the SAME machinery as approvals
 	* (kind 'approval', toolName 'escalate') with a journaled deadlineAt so
 	* deadlines survive resume; the resolution VALUE is the raw
@@ -5812,7 +5807,7 @@ var ExternalRegistry = class ExternalRegistry {
 	/**
 	* RunHandle.resolveExternal: the live path validates BEFORE append and
 	* throws InvalidResolutionError without journaling; a winning attempt
-	* settles the waiting promise in place (docs/03, section 8.7).
+	* settles the waiting promise in place.
 	*/
 	async resolveExternal(key, value) {
 		const waiter = [...this.waiters.values()].find((candidate) => candidate.key === key);
@@ -5917,7 +5912,7 @@ var InMemoryTranscriptStore = class {
 * beside the journal and are replaced atomically, so listRuns never
 * parses payloads.
 *
-* Contract (docs/03, section "Storage SPI", DEF-4 tightening):
+* Contract (DEF-4 tightening):
 * - A1 atomicity: a torn trailing line (crash mid-append) is never
 *   visible in load; it is dropped and overwritten by the next append.
 * - A2 total per-run order: load returns append order, stable across
@@ -5928,7 +5923,7 @@ var InMemoryTranscriptStore = class {
 *
 * Leasing is NOT implemented here: LeasableStore ships with
 * @rulvar/store-sqlite (M5); JsonlFileStore is single-writer by
-* convention (docs/03, section "Shipped stores").
+* convention.
 */
 const JOURNAL_SUFFIX = ".jsonl";
 const META_SUFFIX = ".meta.json";
@@ -6012,7 +6007,7 @@ const TRANSCRIPT_SUFFIX = ".bin";
 /**
 * File-backed TranscriptStore (M6-T02): blobs (transcripts, checkpoints,
 * persisted CompiledWorkflow sources) as one file per ref under `dir`,
-* so compiled runs resume across processes (docs/06, 10.2). Refs follow
+* so compiled runs resume across processes. Refs follow
 * the `<runId>/<name>` convention; each path segment is checked
 * filesystem-safe and nested segments become directories.
 */
@@ -6073,7 +6068,7 @@ var FileTranscriptStore = class {
 //#endregion
 //#region src/engine/cost-report.ts
 /**
-* CostReport builders (M5-T03; docs/09, section "CostReport"). Two
+* CostReport builders (M5-T03). Two
 * sources, one shape:
 *
 * - `buildCostReport` folds the LIVE per-run attribution buckets (ctx
@@ -6087,8 +6082,7 @@ var FileTranscriptStore = class {
 *   facts that entries do not carry, so those buckets are empty here;
 *   byRole and the orchestrator block complete in M7 (DEF-7).
 *
-* Unpriced models surface in `unpriced`, never as a silent zero
-* (docs/04, section "Pricing").
+* Unpriced models surface in `unpriced`, never as a silent zero.
 */
 const ROLES = [
 	"orchestrate",
@@ -6172,8 +6166,8 @@ function costReportFromJournal(entries, priceUsd) {
 //#endregion
 //#region src/engine/run-profiles.ts
 /**
-* The shipped presets (docs/06, section 11: fast / standard / deep /
-* ultra "and similar"). Data only; a review-time assertion checks the
+* The shipped presets (fast / standard / deep / ultra "and similar").
+* Data only; a review-time assertion checks the
 * engine has zero behavioral branches keyed on these names.
 */
 const RUN_PROFILES = {
@@ -6240,7 +6234,7 @@ const TIER_ORDER = {
 /**
 * Strict-schema compatibility as both first-class providers define it:
 * every object node declares `additionalProperties: false` and lists every
-* property in `required` (docs/04, section 5.2). Boolean schemas and
+* property in `required`. Boolean schemas and
 * non-object shapes are trivially compatible.
 */
 function isStrictCompatibleSchema(schema) {
@@ -6280,10 +6274,10 @@ function isStrictCompatibleSchema(schema) {
 	return true;
 }
 /**
-* Tier selection (docs/04, section 8.4): the model's declared ceiling
+* Tier selection: the model's declared ceiling
 * bounds the tier; the native tier additionally requires a
-* strict-compatible canonical schema (docs/04, section 5.2: relying on
-* silent server-side fallback is forbidden), degrading to forced-tool.
+* strict-compatible canonical schema (relying on silent server-side
+* fallback is forbidden), degrading to forced-tool.
 * Prefill is not a tier.
 */
 function selectStructuredOutputTier(caps, canonicalSchema) {
@@ -6301,10 +6295,10 @@ function tierWithinCaps(tier, caps) {
 * Scheduler and concurrency (M1-T08): the per-run semaphore with a FIFO
 * queue (default 12 concurrent model calls). The engine lifetime spawn cap
 * is enforced by the budget layer at admission; parallel/pipeline
-* composition semantics live with ctx (docs/06, section "Scheduler").
+* composition semantics live with ctx.
 * Per-provider concurrency keys land with M4.
 */
-/** FIFO semaphore; default per-run width is 12 (docs/06, Appendix A). */
+/** FIFO semaphore; default per-run width is 12. */
 const DEFAULT_PER_RUN_CONCURRENCY = 12;
 var Semaphore = class {
 	limit;
@@ -6350,7 +6344,7 @@ var Semaphore = class {
 //#region src/model/concurrency.ts
 /**
 * Per-provider concurrency keys (M4-T07): a keyed limiter beside the
-* router, ENGINE-scoped (docs/06, section 4: keys constrain calls
+* router, ENGINE-scoped (keys constrain calls
 * across a single engine per adapter). The Appendix A default is
 * unlimited: an embeddable library must not surprise-throttle hosts, so
 * the per-run semaphore stays the only default bound and provider 429s
@@ -6359,7 +6353,7 @@ var Semaphore = class {
 *
 * There is deliberately NO distributed cross-process limiter: two
 * processes sharing one API key coordinate nothing here (a
-* process-global limiter is an open question, docs/14).
+* process-global limiter is an open question).
 */
 var KeyedLimiter = class {
 	semaphores = /* @__PURE__ */ new Map();
@@ -6382,7 +6376,7 @@ var KeyedLimiter = class {
 };
 //#endregion
 //#region src/model/failover.ts
-/** Normalizes the author-facing ModelChoice.fallbacks list (docs/04, 8.1). */
+/** Normalizes the author-facing ModelChoice.fallbacks list. */
 function normalizeFallbacks(refs) {
 	return (refs ?? []).map((model) => ({ model }));
 }
@@ -6407,8 +6401,8 @@ function nextFailover(targets, trigger, from) {
 	}
 }
 /**
-* Classifies a terminal agent outcome for the degenerate fallback
-* (docs/04, 11.3 as amended): schema-mismatch errors are
+* Classifies a terminal agent outcome for the degenerate fallback:
+* schema-mismatch errors are
 * 'schema-exhausted'; any other error is 'error'; limit terminals (the
 * no-progress abort included) are 'limit'; cancelled, escalated, and
 * skipped never trigger.
@@ -6428,11 +6422,11 @@ function resolvePricing(ref, table, capsPricing) {
 	return table?.models[ref] ?? capsPricing;
 }
 /**
-* Dollars from normalized usage against one pricing row (docs/04,
-* section 1.6: the adapter normalized the usage; inputTokens is the
+* Dollars from normalized usage against one pricing row (the adapter
+* normalized the usage; inputTokens is the
 * full prompt). Cache writes price at the 5m premium rate; the 1h rate
 * applies where a provider distinguishes it in usage, which the
-* canonical Usage does not yet carry (docs/04, section 10).
+* canonical Usage does not yet carry.
 */
 function priceUsdOf(pricing, usage) {
 	return usage.inputTokens / 1e6 * pricing.inputUsdPerMTok + usage.outputTokens / 1e6 * pricing.outputUsdPerMTok + usage.cacheReadTokens / 1e6 * (pricing.cacheReadUsdPerMTok ?? 0) + usage.cacheWriteTokens / 1e6 * (pricing.cacheWriteUsdPerMTok ?? 0);
@@ -6494,7 +6488,7 @@ function projectHistory(messages, targetProvider) {
 }
 /**
 * Lifts the adapter-shipped retention payload of one finished turn into
-* provider-raw parts (docs/04, section 2.3 retention transport). Reads
+* provider-raw parts (the retention transport). Reads
 * providerMetadata[<adapter id>].retainedParts and tags each block with
 * the adapter's provider family. Returns [] when the adapter shipped
 * nothing.
@@ -6532,9 +6526,8 @@ const DEFAULT_RETRY_POLICY = {
 /**
 * Classifies a WireError for the retry engine. Task-class failures are
 * never retryable by construction: adapters mark them retryable: false
-* and this returns undefined. The kind travels in WireError.data.kind
-* (docs/04, section 4.9); anything retryable without a specific kind is
-* transport.
+* and this returns undefined. The kind travels in WireError.data.kind;
+* anything retryable without a specific kind is transport.
 */
 function retryClassOf(error) {
 	if (!error.retryable) return;
@@ -6575,7 +6568,7 @@ function canRideLoopTurn(tier, toolsAvailable) {
 * to a different model OR the loop model's caps cannot serve the required
 * tier OR finalize is routed, in which case the schema never rides a loop
 * or synthesis turn). Otherwise the schema rides the last loop turn with
-* no extra call (docs/04, sections 8.3 and 8.4 as amended in M4-T01).
+* no extra call (as amended in M4-T01).
 */
 function needsSeparateExtract(input) {
 	if (!input.schemaSet) return false;
@@ -6586,7 +6579,7 @@ function needsSeparateExtract(input) {
 * map. This is the finalize TRIGGER: firing is decided by the presence of
 * a routing entry at any layer; the model it fires ON still resolves
 * through the full chain (a higher layer's all-roles `model` may override
-* the routed choice per docs/04, section 8.2).
+* the routed choice).
 */
 function roleConfiguredInRouting(role, layers) {
 	return layers.some((layer) => layer?.routing?.[role] !== void 0);
@@ -6594,8 +6587,8 @@ function roleConfiguredInRouting(role, layers) {
 /**
 * The finalize firing rule: only if configured in routing, and only after
 * tools stop, which presupposes a non-empty toolset. A no-tools agent's
-* single loop turn is already its synthesis (docs/04, section 8.4 as
-* amended in M4-T01). The caller additionally gates on the loop having
+* single loop turn is already its synthesis (as amended in M4-T01). The
+* caller additionally gates on the loop having
 * ended without an abort: a limit/error/cancelled/escalated loop never
 * reaches synthesis.
 */
@@ -6604,7 +6597,7 @@ function finalizeFires(options) {
 }
 /**
 * The summarize trigger: the compaction threshold on the context window
-* (docs/06, Appendix A: default 0.8). Pure predicate; the compaction
+* (default 0.8). Pure predicate; the compaction
 * pipeline that acts on it is M4-T03.
 */
 function atCompactionThreshold(usedTokens, contextWindow, threshold) {
@@ -6613,12 +6606,12 @@ function atCompactionThreshold(usedTokens, contextWindow, threshold) {
 }
 //#endregion
 //#region src/runtime/compaction.ts
-/** Appendix A: compaction threshold default, 0.8 of contextWindow. */
+/** Compaction threshold default, 0.8 of contextWindow. */
 const DEFAULT_COMPACTION_THRESHOLD = .8;
 /** Deterministic marker opening every compaction summary message. */
 const COMPACTION_SUMMARY_PREFIX = "Summary of the conversation so far:";
 /**
-* The threshold check (docs/06, M4-T03 committed semantics): the context
+* The threshold check (M4-T03 committed semantics): the context
 * estimate is the last loop turn's inputTokens + outputTokens; the Usage
 * invariant makes inputTokens the full prompt, and the turn's output
 * joins the next prompt.
@@ -6664,14 +6657,11 @@ function compactMessages(messages, summaryText) {
 * parsing, the per-invocation resolution chain, canonicalization into
 * CanonicalModelSpec, and caps scrubbing with visible scrub notes.
 *
-* Owning spec: docs/04-model-layer-spec.md, sections "Router and
-* resolution chain", "Canonical effort", and "Caps scrubbing and
-* structured-output tier selection".
+* Public contract: https://docs.rulvar.com/guide/model-routing.
 */
 /**
 * Per-engine adapter registry: strictly per engine, no global mutable
-* registry exists. A duplicate adapterId is a typed ConfigError
-* (docs/04, section "Registry and ModelRef").
+* registry exists. A duplicate adapterId is a typed ConfigError.
 */
 function buildAdapterRegistry(adapters) {
 	const registry = /* @__PURE__ */ new Map();
@@ -6695,12 +6685,10 @@ function parseModelRef(ref) {
 	};
 }
 /**
-* Role effort defaults (docs/04, section "Invocation roles and firing
-* protocol"): orchestrate and plan default to high; summarize and extract
+* Role effort defaults: orchestrate and plan default to high; summarize and extract
 * default to low. loop and finalize have NO role default: when the chain
 * resolves nothing, the wire omits effort and identity records the spec
-* with the effort member absent (docs/04, section "Router and resolution
-* chain", as amended).
+* with the effort member absent.
 */
 const ROLE_EFFORT_DEFAULTS = {
 	orchestrate: "high",
@@ -6755,7 +6743,7 @@ const SAMPLING_KEYS = [
 * Resolution runs on every model invocation, not once per agent: a layered
 * merge of { model, effort, providerOptions, fallbacks } in the order call
 * override > agent profile > workflow defaults > engine defaults, with the
-* invocation role attached as a tag (docs/04, section "Resolution chain").
+* invocation role attached as a tag.
 * After resolution the router reads ModelCaps and scrubs illegal
 * parameters visibly: unsupported effort is removed from the wire but
 * kept in identity; sampling params rejected by the model are removed
@@ -6839,7 +6827,7 @@ function resolveModelInvocation(options) {
 	if (merged.fallbacks !== void 0) resolved.fallbacks = merged.fallbacks;
 	return resolved;
 }
-/** The closed trigger vocabulary guard (docs/04, section 12). */
+/** The closed trigger vocabulary guard. */
 const TRIGGER_CLASSES = [
 	"error",
 	"limit",
@@ -6863,7 +6851,7 @@ function validateGate(gate, rungCount, index) {
 	if (!(gate.fraction > 0 && gate.fraction <= 1)) throw new ConfigError(`ladder acceptance gate ${String(index)}: a spot-check fraction lies in (0, 1], got ${String(gate.fraction)}`);
 }
 /**
-* Canonicalizes a declared LadderSpec (docs/04, section 12): validates the
+* Canonicalizes a declared LadderSpec: validates the
 * shape once (FR-119 judge declaration included) and resolves every rung's
 * effort to an explicit value. `chainEffort` is the effort the resolution
 * chain would contribute at the declaring layer; a rung that resolves no
@@ -6901,7 +6889,7 @@ function canonicalizeLadder(spec, options) {
 /**
 * The concrete ModelChoice of one rung attempt: each attempt is an
 * ordinary agent scope whose CanonicalModelSpec is that rung's
-* `{ kind: 'model' }` form (docs/04, section 8.2).
+* `{ kind: 'model' }` form.
 */
 function ladderRungChoice(ladder, index) {
 	const rung = ladder.rungs[index];
@@ -6917,7 +6905,7 @@ const DEFAULT_MAX_TURNS = 32;
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 12e4;
 /**
 * Limits merge per spawn: AgentOpts.limits over profile limits over engine
-* defaults.limits (docs/06, section "UsageLimits").
+* defaults.limits.
 */
 function mergeUsageLimits(call, profile, engine) {
 	const pick = (key) => call?.[key] ?? profile?.[key] ?? engine?.[key];
@@ -6945,13 +6933,13 @@ var ModelRetry = class extends Error {
 		if (opts?.data !== void 0) this.data = opts.data;
 	}
 };
-/** Bounded semantic retries per tool call chain (docs/06, Appendix A). */
+/** Bounded semantic retries per tool call chain. */
 const DEFAULT_MODEL_RETRY_ATTEMPTS = 2;
 //#endregion
 //#region src/runtime/escalation.ts
 const ESCALATE_TOOL_NAME = "escalate";
 /**
-* The exact tool schema of docs/07, section 4.9. costToDate and salvage
+* The escalate tool's exact request schema. costToDate and salvage
 * MUST NOT appear here: additionalProperties false rejects model-authored
 * values for them at argument validation.
 */
@@ -6995,7 +6983,7 @@ const ESCALATION_REQUEST_SCHEMA = {
 		}
 	}
 };
-/** The full-report schema applied BEFORE append (docs/03, section 5.4). */
+/** The full-report schema applied BEFORE append. */
 const ESCALATION_REPORT_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -7066,7 +7054,7 @@ const ESCALATION_REPORT_SCHEMA = {
 	}
 };
 /**
-* The engine opt-in tool (docs/08, section 6.6): registered through the
+* The engine opt-in tool: registered through the
 * same path as any tool under escalation opt-in of EITHER flavor (the
 * worker's only authoring channel for a report), never available without
 * opt-in, and dispatched through the same permission chain. The loop
@@ -7088,7 +7076,7 @@ async function validateEscalationReport(report) {
 	return validation.valid ? [] : validation.issues;
 }
 /**
-* countsAgainstLimit derivation (docs/07, section 6.3, XF-06): true iff
+* countsAgainstLimit derivation (XF-06): true iff
 * scope_bigger; scope_different and blocked_with_evidence are exempt and
 * never debit the escalation counter.
 */
@@ -7102,11 +7090,11 @@ function countsAgainstLimit(kind) {
 * journaled as a first-class terminal abort distinct from user
 * cancellation (a cancelled entry always reruns; a no-progress abort
 * must replay, or every resume would re-pay the stuck turns). The
-* interim heuristic is committed in docs/06 Appendix A: N consecutive
+* interim heuristic is committed: N consecutive
 * turns without tool calls or artifact deltas, N = 3; the broader
-* heuristic stays OQ-15 (docs/14), revisited on dogfood traces.
+* heuristic stays OQ-15, revisited on dogfood traces.
 *
-* Encoding (docs/03, sections 6.3 and 6.6): the abort is the agent's
+* Encoding: the abort is the agent's
 * terminal entry with status 'limit', an error payload carrying
 * abortClass 'no-progress', and memoizeOutcome stamped by the ENGINE on
 * the terminal entry, so the frozen memoize-limit rule replays it on
@@ -7114,7 +7102,7 @@ function countsAgainstLimit(kind) {
 * per-turn artifact channel, so the tool-call test subsumes artifact
 * deltas; per-turn artifact producers arrive with M4 compaction.
 */
-/** docs/06 Appendix A: the committed no-progress detector N. */
+/** The committed no-progress detector N. */
 const DEFAULT_NO_PROGRESS_TURNS = 3;
 /**
 * Counts consecutive progress-free turns. A turn with at least one tool
@@ -7154,14 +7142,14 @@ var NoProgressDetector = class {
 * allow: allow is only ever falling through to canUseTool or the
 * terminal default.
 *
-* Owning spec: docs/08-tools-permissions-spec.md, section "Permission
-* chain". Risk presets, the argv shell matcher, domain rules, and the
+* Full contract: https://docs.rulvar.com/guide/tools.
+* Risk presets, the argv shell matcher, domain rules, and the
 * audit/dry-run surface land in M5.
 */
 /**
 * Merges the engine-wide config and the profile config into one chain.
 * Layers concatenate engine-first; since rules only deny or ask, ordering
-* within a layer cannot change the verdict (docs/08, section 4.2). The
+* within a layer cannot change the verdict. The
 * profile's canUseTool wins over the engine's (a single slot by
 * construction). A declared preset compiles INTO the same layers, after
 * the host-authored rules, never as a fifth layer (M5-T05).
@@ -7189,7 +7177,7 @@ function compilePermissionChain(engine, profile) {
 		...canUseTool === void 0 ? {} : { canUseTool }
 	};
 }
-/** The command text an argv rule matches against (docs/08, section 5). */
+/** The command text an argv rule matches against. */
 function commandOf(input) {
 	if (typeof input === "string") return input;
 	if (typeof input === "object" && input !== null) {
@@ -7214,7 +7202,7 @@ function ruleMatches(rule, toolName, risk, input) {
 	return true;
 }
 /**
-* Advisory domain-rule matches for the audit payload (docs/08, 4.4):
+* Advisory domain-rule matches for the audit payload:
 * reported, never enforced outside first-party fetch.
 */
 function advisoryMatches(chain, toolName) {
@@ -7222,7 +7210,7 @@ function advisoryMatches(chain, toolName) {
 }
 /**
 * Unmatchable segments (command/process substitution, here-docs) yield
-* ask, ALWAYS, for any tool that has argv rules (docs/08, 5.2 step 3).
+* ask, ALWAYS, for any tool that has argv rules.
 */
 function argvUnmatchableAsk(chain, toolName, input) {
 	if (![...chain.deny, ...chain.ask].some((rule) => "argv" in rule && (Array.isArray(rule.tool) ? rule.tool : [rule.tool]).includes(toolName))) return false;
@@ -7230,7 +7218,7 @@ function argvUnmatchableAsk(chain, toolName, input) {
 	if (command === void 0) return true;
 	return lexShellCommand(command).some((segment) => segment.unmatchable);
 }
-/** A stub ToolContext for offline (dry-run) evaluations (docs/08, 4.5). */
+/** A stub ToolContext for offline (dry-run) evaluations. */
 function offlineContext(toolName) {
 	return {
 		runId: "dry-run",
@@ -7244,14 +7232,14 @@ function offlineContext(toolName) {
 }
 /**
 * Evaluates the chain for one dispatch, or OFFLINE against a
-* hypothetical call by tool name (the dry-run API of docs/08, section
-* 4.5: nothing executes; shells and tests read the verdict, the
+* hypothetical call by tool name (the dry-run API: nothing executes;
+* shells and tests read the verdict, the
 * deciding layer, and the matched rule). Hooks run in deterministic
 * registration order; { modifiedInput } substitutes the input and
 * continues; the first decisive verdict wins. The returned input is what
-* execute receives and what the approval identity hashes (docs/03,
-* section 1.2: post hook modification). Advisory domain-rule matches
-* ride every verdict for the audit payload (docs/08, 4.4).
+* execute receives and what the approval identity hashes (post hook
+* modification). Advisory domain-rule matches
+* ride every verdict for the audit payload.
 */
 async function evaluatePermission(chain, tool, input, ctx) {
 	const def = typeof tool === "string" ? {
@@ -7439,8 +7427,8 @@ function formatRePrompt(issues, attempt, maxAttempts) {
 * with M3/M4; the escalated status arrives in M3 as the flagged breaking
 * change.
 *
-* Owning specs: docs/06-execution-spec.md, section "Agent runtime
-* binding"; docs/04-model-layer-spec.md (roles, tiers, refusal).
+* Docs: https://docs.rulvar.com/guide/agents (agent runtime binding);
+* https://docs.rulvar.com/guide/model-routing (roles, tiers, refusal).
 */
 function isEscalated(r) {
 	return r.status === "escalated";
@@ -7466,8 +7454,7 @@ function addUsage(total, turn) {
 }
 /**
 * The Usage invariant is verified at the adapter boundary: inputTokens is
-* the FULL prompt including cache reads and writes (docs/04, section
-* "Usage invariant").
+* the FULL prompt including cache reads and writes.
 */
 function assertUsageInvariant(usage, adapterId) {
 	if (usage.inputTokens < usage.cacheReadTokens + usage.cacheWriteTokens) throw new Error(`adapter '${adapterId}' violated the Usage invariant: inputTokens (${usage.inputTokens}) < cacheReadTokens + cacheWriteTokens (${usage.cacheReadTokens} + ${usage.cacheWriteTokens})`);
@@ -7612,7 +7599,7 @@ function buildRequest(resolved, messages, limits, tools) {
 * parts go at the HEAD: on both first-class providers the retained
 * blocks (thinking blocks, reasoning items) precede the turn's text and
 * tool calls, and head placement reproduces that order on re-projection
-* (docs/04, section 2.3, M4-T02).
+* (M4-T02).
 */
 function assistantMsg(turn, retained = []) {
 	const parts = [...retained];
@@ -7636,8 +7623,7 @@ function assistantMsg(turn, retained = []) {
 * surfaced to the model as error tool results and never thrown past
 * policy: unknown names, argument-validation issues, ModelRetry (bounded
 * per tool call chain), NonSerializableValueError, and arbitrary execute
-* throws all land as { isError: true } results (docs/08, sections 1.1 and
-* 2.4; docs/06, section "ModelRetry").
+* throws all land as { isError: true } results.
 */
 async function executeToolCall(options) {
 	const { call, runtime } = options;
@@ -8581,7 +8567,7 @@ async function runAgent(options) {
 * ceiling severing live streams, with partial usage written usageApprox.
 * B0 is immutable after start: no API tops it up.
 *
-* The account tree (docs/06, section 5.4): the run root plus one
+* The account tree: the run root plus one
 * sub-account per admitted child workflow (and, from M7, the orchestrator
 * account and plan/NodeId accounts). A child's spend propagates to ALL
 * ancestors up to the run root; the root ceiling remains the true
@@ -8590,11 +8576,11 @@ async function runAgent(options) {
 * reserves are recovered from spawn-admission decision entries); the
 * per-account historical fold completes with DEF-7 in M7.
 *
-* Owning spec: docs/06-execution-spec.md, section "Three-layer budget".
+* Full contract: https://docs.rulvar.com/guide/budgets
 */
-/** Last resort of the admission reserve formula (docs/06, Appendix A). */
+/** Last resort of the admission reserve formula. */
 const DEFAULT_FLAT_RESERVE_USD = .5;
-/** The run-root account scope (docs/06, section 5.4 scope vocabulary). */
+/** The run-root account scope. */
 const ROOT_ACCOUNT = "run";
 const ZERO_USAGE = {
 	inputTokens: 0,
@@ -8603,8 +8589,7 @@ const ZERO_USAGE = {
 	cacheWriteTokens: 0
 };
 /**
-* The admission reserve for a spawn (docs/06, section "Layer 1: admission
-* before spawn"): opts.estCost, else profile.estCost, else
+* The admission reserve for a spawn: opts.estCost, else profile.estCost, else
 * price(countTokens(input) + caps.maxOutputTokens), else the engine flat
 * default.
 */
@@ -8670,7 +8655,7 @@ var RunBudget = class {
 		return chain;
 	}
 	/**
-	* Opens a child sub-account under `parentScope` (docs/06, section 5.4).
+	* Opens a child sub-account under `parentScope`.
 	* Re-opening an existing scope is the resume roll-forward path: the
 	* recorded ceiling wins once and the accumulated state is kept.
 	*/
@@ -8727,7 +8712,7 @@ var RunBudget = class {
 	/**
 	* Marks the run exhausted without a ceiling event: the orchestrator
 	* finalize fallback maps to outcome 'exhausted' with the synthesized
-	* partial value (DEF-7, docs/07 12.4; exhaustion is never null).
+	* partial value (DEF-7; exhaustion is never null).
 	*/
 	markExhausted() {
 		this.exhaustedInternal = true;
@@ -8744,7 +8729,7 @@ var RunBudget = class {
 	* Layer 1: admission before spawn. Blocks when spent + committedReserve
 	* has reached the ceiling on ANY account in the ancestor chain of
 	* `accountScope`, otherwise commits the reserve along the whole chain.
-	* Also enforces the engine lifetime spawn cap (docs/06, "Scheduler").
+	* Also enforces the engine lifetime spawn cap.
 	*/
 	admitSpawn(reserveUsd, accountScope = "run") {
 		if (this.agentsSpawnedInternal >= this.lifetimeSpawnCap) {
@@ -8768,7 +8753,7 @@ var RunBudget = class {
 	/**
 	* Resume roll-forward: commits a reserve recovered from a journaled
 	* spawn-admission decision entry without re-evaluating admission
-	* (docs/06, 5.1: reserves are recovered, never re-estimated).
+	* (reserves are recovered, never re-estimated).
 	*/
 	admitRecovered(reserveUsd, accountScope = "run") {
 		this.agentsSpawnedInternal += 1;
@@ -8776,7 +8761,7 @@ var RunBudget = class {
 		this.emitUpdate();
 	}
 	/**
-	* Registers the orchestrator finalize reserve (DEF-7, docs/07 12.2):
+	* Registers the orchestrator finalize reserve (DEF-7):
 	* absolute dollars set on the named account AND the run root, so
 	* admission never lets any spawn eat the finalization money even
 	* against whole-run exhaustion. Kept SEPARATE from committedReserveUsd
@@ -8852,7 +8837,7 @@ var RunBudget = class {
 			agentsSpawned: this.agentsSpawnedInternal
 		};
 	}
-	/** Null when the run has no USD ceiling (docs/06, section "Canonical Ctx interface"). */
+	/** Null when the run has no USD ceiling. */
 	remaining() {
 		const root = this.root;
 		if (root.ceilingUsd === void 0) return null;
@@ -8877,8 +8862,8 @@ var RunBudget = class {
 /**
 * AdmissionController v1 (M6-T06; DEF-2, DEF-3, DEF-5 substrate).
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, section
-* "AdmissionController". The single admission point for ALL spawns of any
+* Public contract: https://docs.rulvar.com/guide/adaptive-orchestration.
+* The single admission point for ALL spawns of any
 * origin: ctx.workflow, the orchestrator spawn tools (M6-T07), escalation
 * decomposition and rung respawns (M7). `admit(spec)` is called BEFORE
 * the carrying spawn-admission decision entry is journaled; the verdict
@@ -8941,8 +8926,8 @@ var AdmissionController = class {
 		return this.lineageLimits;
 	}
 	/**
-	* Binds the run's TerminationAccount (DEF-2; PlanRunner runs only,
-	* docs/07 section 1): from bind time on, every admitted spawn of any
+	* Binds the run's TerminationAccount (DEF-2; PlanRunner runs only):
+	* from bind time on, every admitted spawn of any
 	* origin debits one spawnUnit atomically with its decision entry, and
 	* a declared ladder longer than the frozen kMax rejects with
 	* ladder_exceeds_frozen. Non-PlanRunner runs never bind an account and
@@ -8957,7 +8942,7 @@ var AdmissionController = class {
 		return this.terminationAccount;
 	}
 	/**
-	* The lineage half of admission (DEF-3, docs/03 section 10.5): folds are
+	* The lineage half of admission (DEF-3): folds are
 	* computed live STRICTLY BEFORE the carrying decision entry is appended;
 	* the caller embeds the returned block in the entry and replay reads it
 	* back byte-exact. Enforces the single-live-attempt invariant
@@ -9170,7 +9155,7 @@ var AdmissionController = class {
 	* Resume roll-forward for a child that already SETTLED before the
 	* resume: re-registers the counters (maxChildrenPerNode, the lifetime
 	* cap, statsBefore fidelity) without committing any reserve; the spend
-	* itself sits in the root ledger seed (docs/03, 13.3).
+	* itself sits in the root ledger seed.
 	*/
 	recoverSettled(parentAccountScope) {
 		this.budget.admitRecovered(0, parentAccountScope);
@@ -9180,8 +9165,8 @@ var AdmissionController = class {
 	/**
 	* Resume roll-forward for an admission whose decision entry exists but
 	* whose child has NOT settled: re-applies the recorded reserve and
-	* counters without re-evaluating any limit (docs/07, 7.1: replay never
-	* re-evaluates admission; docs/06, 5.1: reserves are recovered, never
+	* counters without re-evaluating any limit (replay never
+	* re-evaluates admission; reserves are recovered, never
 	* re-estimated).
 	*/
 	recoverInFlight(parentAccountScope, verdict) {
@@ -9195,7 +9180,7 @@ var AdmissionController = class {
 //#endregion
 //#region src/orchestrator/handles.ts
 /**
-* The committed WakeDigest render budget (docs/06, Appendix A: 400
+* The committed WakeDigest render budget (Appendix A: 400
 * chars per outputSummary row, the character measure; committed at M10
 * entry by adopting the implemented distillation cap unchanged, the
 * value frozen into every cassette since M6). One value serves both
@@ -9205,8 +9190,8 @@ var AdmissionController = class {
 const WAKE_SUMMARY_RENDER_BUDGET_CHARS = 400;
 /**
 * The M6 outputSummary: a deterministic truncation of the child's
-* output (or error message), identical live and on replay (docs/07
-* section 2, clause 3: distillation lives with the child, ordered by
+* output (or error message), identical live and on replay (distillation
+* lives with the child, ordered by
 * spawn ordinal; the LLM distillation upgrade is M7 territory).
 */
 function summarizeOutput(result) {
@@ -9226,7 +9211,7 @@ function digestOf(record, result) {
 }
 //#endregion
 //#region src/orchestrator/wake.ts
-/** docs/07 4.8: the wait_for_events parameter schema (normative). */
+/** The wait_for_events parameter schema (normative). */
 const WAIT_FOR_EVENTS_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -9303,7 +9288,7 @@ function emptyDigestBlocks() {
 }
 //#endregion
 //#region src/orchestrator/spawn-tools.ts
-/** docs/07 4.2: the spawn_agent parameter schema (normative). */
+/** The spawn_agent parameter schema (normative). */
 const SPAWN_AGENT_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -9354,7 +9339,7 @@ const SPAWN_AGENT_SCHEMA = {
 		taskClass: { type: "string" }
 	}
 };
-/** docs/07 4.3: parallel_agents wraps the spawn_agent params. */
+/** parallel_agents wraps the spawn_agent params. */
 const PARALLEL_AGENTS_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -9366,7 +9351,7 @@ const PARALLEL_AGENTS_SCHEMA = {
 	} },
 	$defs: { spawnAgentParams: SPAWN_AGENT_SCHEMA }
 };
-/** docs/07 4.4: await_any and await_all share one parameter shape. */
+/** await_any and await_all share one parameter shape. */
 const AWAIT_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -9380,7 +9365,7 @@ const AWAIT_SCHEMA = {
 		}
 	} }
 };
-/** docs/07 4.5: cancel_agent. */
+/** The cancel_agent parameter schema. */
 const CANCEL_AGENT_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -9393,7 +9378,7 @@ const CANCEL_AGENT_SCHEMA = {
 		reason: { type: "string" }
 	}
 };
-/** docs/07 4.11: finish; result validates against the declared output schema. */
+/** finish; result validates against the declared output schema. */
 const FINISH_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -9407,7 +9392,7 @@ const FINISH_TOOL_NAME = "finish";
 /**
 * Builds the mode (c) toolset over the per-call runtime. profileCardText
 * rides the spawn tools' descriptions so both modes speak one agent
-* vocabulary (docs/06 9.3; M6-T04).
+* vocabulary (M6-T04).
 */
 function buildOrchestratorTools(runtime, profileCardText) {
 	return [
@@ -9508,15 +9493,13 @@ function runtimeOf(ctx) {
 * log, budget, and the deterministic shims; workflow/orchestrate/
 * awaitExternal/brief land with their milestones (M2/M6).
 *
-* Owning spec: docs/06-execution-spec.md, sections "Canonical Ctx
-* interface", "Error policy and dropped results", "Scheduler".
+* Public contract: https://docs.rulvar.com/guide/workflows.
 */
 /**
 * The rejection carrier of ctx.agent value-form calls: a real Error that
-* structurally satisfies the typed AgentError (docs/06, section "ctx.agent
-* and AgentOpts") and carries the full AgentResult for Settled mapping.
-* Deliberately not a RulvarError: AgentError is not in the closed code
-* registry (docs/02, section "Error taxonomy").
+* structurally satisfies the typed AgentError and carries the full
+* AgentResult for Settled mapping. Deliberately not a RulvarError:
+* AgentError is not in the closed code registry.
 */
 var AgentCallError = class extends Error {
 	kind;
@@ -9560,9 +9543,9 @@ function bump(map, key, usd) {
 }
 /**
 * Completes a model-authored escalation request into the full report:
-* costToDate and salvage are runtime-filled, never model-filled (docs/07,
-* section 6.3). The worktree patch ref lands after collect(); the
-* pre-dispose preview for flavor B decision-makers omits it.
+* costToDate and salvage are runtime-filled, never model-filled. The
+* worktree patch ref lands after collect(); the pre-dispose preview for
+* flavor B decision-makers omits it.
 */
 function buildEscalationReport(request, result, worktreePatchRef) {
 	return {
@@ -10528,7 +10511,7 @@ function createCtx(internals) {
 	}
 	/**
 	* Per-(scope, name) invocation ordinals of ctx.workflow, in execution
-	* order (docs/03, section 2.2: nested workflow scopes).
+	* order (nested workflow scopes).
 	*/
 	const workflowOrdinals = /* @__PURE__ */ new Map();
 	const nextWorkflowOrdinal = (scope, name) => {
@@ -10546,7 +10529,7 @@ function createCtx(internals) {
 		rebuilt.name = wire.code;
 		return rebuilt;
 	};
-	/** Maps an embedded admission rejection onto its typed error (docs/07, 7.3). */
+	/** Maps an embedded admission rejection onto its typed error. */
 	const rejectionError = (reason, name) => {
 		if (reason.code === "budget" || reason.code === "lifetime") return new BudgetExhaustedError(`admission rejected child workflow '${name}' (${reason.code})`, { data: { reason } });
 		return new AdmissionRejectedError(`admission rejected child workflow '${name}' (${reason.code}; maxDepth/maxChildrenPerNode are set via createEngine budgetDefaults)`, { data: { reason } });
@@ -10850,8 +10833,7 @@ async function executeWorkflow(internals, wf, args) {
 /**
 * The mode (c) dynamic orchestrator (M6-T07/T08).
 *
-* Owning spec: docs/06-execution-spec.md section 9.3 and
-* docs/07-adaptive-orchestration-spec.md sections 1 and 4. An ordinary
+* Full contract: https://docs.rulvar.com/guide/adaptive-orchestration. An ordinary
 * workflow whose agent (role 'orchestrate') holds the typed spawn tools;
 * both surfaces (top-level orchestrate() and ctx.orchestrate) share this
 * one implementation, the nested surface riding ctx.workflow so the
@@ -10862,7 +10844,7 @@ async function executeWorkflow(internals, wf, args) {
 * ordinary kind 'agent' entry; a crashed orchestrate() restores its
 * history from the checkpoint and finds child results by content keys,
 * WITHOUT regenerating spawn decisions and without re-paying children.
-* Non-PlanRunner applicability (docs/07 section 1): only the lifetime
+* Non-PlanRunner applicability: only the lifetime
 * cap, maxDepth, and the budget layers apply; no termination.init is
 * written; escalated children simply settle into their digests.
 */
@@ -10881,7 +10863,7 @@ function orchestratorPrompt(goal, maxSpawns, extensionLines) {
 }
 /**
 * Resolves per-spawn dispatch options against the engine registries
-* (docs/08: registered SchemaSpec and tool profile names; M7-T05). An
+* (registered SchemaSpec and tool profile names; M7-T05). An
 * unknown ref is a typed ConfigError, surfaced as a tool error to the
 * orchestrator and never a run failure.
 */
@@ -10928,7 +10910,15 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const admission = internals.admission;
 		const callingState = runtime.currentState();
 		const advertisedProfiles = filterProfiles(internals.defaults.profiles, opts?.profiles);
-		const cardText = profileCard(advertisedProfiles);
+		const spawnableProfiles = {};
+		const declaredLadderNames = [];
+		for (const [name, profile] of Object.entries(advertisedProfiles)) {
+			const spec = profile.model;
+			if (spec !== void 0 && typeof spec !== "string" && "ladder" in spec) declaredLadderNames.push(name);
+			else spawnableProfiles[name] = profile;
+		}
+		declaredLadderNames.sort();
+		const cardText = declaredLadderNames.length === 0 ? profileCard(advertisedProfiles) : `${profileCard(spawnableProfiles)}\nDeclared ladders (tier context for the knowledge card; NOT agentType values, never spawn them): ${declaredLadderNames.join(", ")}.`;
 		const extension = opts?.extension;
 		let orchestratorAccount;
 		let capState;
@@ -11156,7 +11146,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const forcedFinishController = new AbortController();
 		let capInFlight = false;
 		/**
-		* The at-cap freeze (docs/07, 12.4): EXACTLY one decision entry
+		* The at-cap freeze: EXACTLY one decision entry
 		* strictly before any effects; then the plan freezes for adaptation,
 		* wake triggers except quiescence disarm, and the orchestrator is
 		* driven to the reserved final wake. Crash between the entry and the
@@ -11203,7 +11193,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			}, callingState.spanId);
 			forcedFinishController.abort("rulvar:forced-finish");
 		};
-		/** Layer-1 soft boundary before delivering each wake (docs/07, 12.3). */
+		/** Layer-1 soft boundary before delivering each wake. */
 		const overSoftBoundary = () => {
 			if (capState === void 0 || orchestratorAccount === void 0 || extension === void 0) return false;
 			return (internals.budget.accountView(orchestratorAccount)?.spentUsd ?? 0) + capState.turnEstimateUsd > capState.effectiveCapUsd - capState.finalizeReserveUsd;
@@ -11281,6 +11271,8 @@ function makeOrchestratorWorkflow(goal, opts) {
 				if (opts?.maxSpawns !== void 0 && spawnOrdinal >= opts.maxSpawns) 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;
+				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`);
 				const decision = admission.admit({
 					origin: "spawn_agent",
 					name: params.agentType,
@@ -11453,7 +11445,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 				ladders,
 				...internals.floors === void 0 ? {} : { floors: internals.floors },
 				now: new Date(internals.now()).toISOString()
-			}), ladders);
+			}), ladders, { profiles: advertisedProfiles });
 			await internals.replayer.appendSinglePhase({
 				scope: callingState.scope,
 				key,
@@ -11510,6 +11502,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			role: "orchestrate",
 			result: "full",
 			tools: [...buildOrchestratorTools(orchestratorRuntime, fullCardText), ...extension?.tools(io) ?? []],
+			...capState === void 0 ? {} : { estCost: capState.effectiveCapUsd },
 			...opts?.model === void 0 ? {} : { model: opts.model },
 			...opts?.limits === void 0 ? {} : { limits: opts.limits },
 			[kOnRunning]: (seq) => {
@@ -11523,7 +11516,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 		if (orchestratorAccount !== void 0) orchestratorState.budgetScope = orchestratorAccount;
 		orchestratorState.signal = callingState.signal === void 0 ? forcedFinishController.signal : AbortSignal.any([callingState.signal, forcedFinishController.signal]);
 		/**
-		* The reserved final wake (docs/07, 12.4 d): a FRESH agent entry on
+		* The reserved final wake: a FRESH agent entry on
 		* the restricted single-tool toolset (a different toolsetHash), a
 		* prompt deterministically derived from the journaled cap decision
 		* and the pinned digest, and a finalizeTurns limit, paid from the
@@ -11541,6 +11534,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 				result: "full",
 				tools: finishOnly,
 				limits: { maxTurns: capState?.finalizeTurns ?? 2 },
+				...capState === void 0 ? {} : { estCost: capState.finalizeReserveUsd },
 				...opts?.model === void 0 ? {} : { model: opts.model },
 				[kTerminalTool]: { name: FINISH_TOOL_NAME }
 			};
@@ -11593,7 +11587,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 		return result.output;
 	});
 }
-/** Top-level surface: creates a run (docs/06 9.3). */
+/** Top-level surface: creates a run. */
 function orchestrate(engine, goal, opts) {
 	return engine.run(makeOrchestratorWorkflow(goal, opts), void 0);
 }
@@ -11603,16 +11597,13 @@ function orchestrate(engine, goal, opts) {
 * Per-run event machinery (M1-T10): the span registry (run > phase >
 * agent > tool > child hierarchy) and the event bus that stamps the
 * WorkflowEvent envelope, feeds RunHandle.events / on(), and fans out to
-* subscribers. EventSink is deliberately not an SPI (docs/02, section
-* "SPI seams and the 1.0 freeze").
+* subscribers. EventSink is deliberately not an SPI.
 *
-* Owning spec: docs/09-observability-testing-spec.md, section "Event
-* stream".
+* Full contract: https://docs.rulvar.com/guide/observability.
 */
 /**
 * Spans form a tree per run; spanId values are engine-minted opaque
-* strings, unique per run, pure telemetry, never identity (docs/09,
-* section "Span hierarchy").
+* strings, unique per run, pure telemetry, never identity.
 */
 var SpanRegistry = class {
 	parents = /* @__PURE__ */ new Map();
@@ -11777,15 +11768,14 @@ var InProcessRunner = class {
 * Engine entry points (M1-T11): createEngine and engine.run over the
 * InProcessRunner. Every registry hangs off the engine instance; nothing
 * is module-global, so two engines in one process are fully isolated and
-* ctx is created per run (docs/02, section "Engine anatomy"; docs/06,
-* section "Engine and ops API"). engine.resume lands with the journal
+* ctx is created per run. engine.resume lands with the journal
 * kernel in M2.
 */
-/** Content hash of an in-process workflow body (run-to-definition binding, docs/06 10.2). */
+/** 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");
 }
-/** Content hash of a compiled workflow source (run-to-definition binding, docs/06 10.2). */
+/** Content hash of a compiled workflow source (run-to-definition binding). */
 function hashWorkflowSource(source) {
 	return createHash("sha256").update(source, "utf8").digest("hex");
 }
@@ -12202,11 +12192,11 @@ function createEngine(options) {
 /**
 * The host half of the worker sandbox contract (M6-T02).
 *
-* Owning spec: docs/06-execution-spec.md, section 8.2. WorkerSandboxRunner
+* Full contract: https://docs.rulvar.com/guide/planner. WorkerSandboxRunner
 * (@rulvar/planner) owns the worker lifecycle and the MessagePort; this
 * core-owned bridge serves every sandbox primitive against the canonical
-* ctx of the run, so the runner builds exclusively from the public API
-* (docs/02, dependency rules). The boundary is journal-compatible JSON
+* ctx of the run, so the runner builds exclusively from the public API.
+* The boundary is journal-compatible JSON
 * validated on both sides; raw structured clone is NOT the contract.
 *
 * Responsibilities: