@rulvar/plan 1.0.0 → 1.2.0

package/dist/index.js

@@ -5,8 +5,8 @@ import { CURRENT_HASH_VERSION, ConfigError, DedupIndex, InMemoryStore, LEGACY_LT
 * closed PlanNodeStatus machine, and the pure derivations the plan fold
 * consumes (readiness, cycle checks).
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, sections 3.1
-* (TaskPlan data model) and 3.2 (single applier and total order) (DEF-8).
+* Contract: https://docs.rulvar.com/guide/adaptive-orchestration
+* (TaskPlan data model; single applier and total order) (DEF-8).
 * Nodes carry NodeId ULIDs minted by the engine inside the plan.revision
 * entry that adds them, never by the model; dependencies form a DAG; the
 * status machine is closed and `done` is immutable. State is ALWAYS a pure
@@ -15,9 +15,9 @@ import { CURRENT_HASH_VERSION, ConfigError, DedupIndex, InMemoryStore, LEGACY_LT
 */
 /**
 * The single sequential scope holding every plan-mutating entry, inside
-* the orchestrator's run scope (docs/07, 3.2): total order = ordinal
+* the orchestrator's run scope: total order = ordinal
 * order = durable append order. Child node scopes are `plan/NodeId`
-* (core `planNodeScope`; grammar in docs/03, section 2.1).
+* (core `planNodeScope`).
 */
 const PLAN_SCOPE = "plan";
 /** The empty plan every fold starts from. */
@@ -30,7 +30,7 @@ function emptyPlan() {
 }
 /**
 * Terminal statuses: no transition ever leaves them. `done` is immutable
-* because its result is paid for (docs/07, 3.6: cancel_task on done drops
+* because its result is paid for (cancel_task on done drops
 * with node_already_done); failed, cancelled, and skipped are equally
 * final per the conflict table's terminal_status rows.
 */
@@ -46,18 +46,18 @@ function isTerminalPlanStatus(status) {
 /**
 * Asserts one status transition against the closed machine. Op-level
 * legality (which ops may request which transitions in which state) is
-* the rebase conflict table's job (docs/07, 3.6; M7-T04); the machine
+* the rebase conflict table's job (M7-T04); the machine
 * itself enforces exactly the structural rules:
 *
 * - nothing leaves a terminal status (`done` is immutable; failed,
 *   cancelled, skipped are final),
 * - `running` is entered only from `ready` (the engine schedules ready
-*   nodes; docs/07, 3.1),
+*   nodes),
 * - a transition never restates the current status (the engine writes no
 *   no-op set_node_status).
 *
 * A violation is an engine bug and raises the typed PlanInvariantError
-* (docs/07, 3.4: never a silent brick).
+* (never a silent brick).
 */
 function assertPlanTransition(node, to) {
 	if (isTerminalPlanStatus(node.status)) throw new PlanInvariantError(`plan node ${node.nodeId} is terminal '${node.status}' and cannot become '${to}' (docs/07, 3.1: the status machine is closed and 'done' is immutable)`, { data: {
@@ -77,8 +77,8 @@ function assertPlanTransition(node, to) {
 	} });
 }
 /**
-* Dependency satisfaction, derived purely in the fold and NEVER a record
-* (docs/07, 3.3): a dep is satisfied when waived or when its upstream
+* Dependency satisfaction, derived purely in the fold and NEVER a record:
+* a dep is satisfied when waived or when its upstream
 * node is `done`. Terminally unsuccessful upstreams (cancelled, failed)
 * keep blocking: such edges "remain blocking" per the rewire_deps row of
 * the conflict table, and waive_dep exists exactly to unblock them.
@@ -120,7 +120,7 @@ function recomputePlanReadiness(plan) {
 	} : plan;
 }
 /**
-* Cycle check for rewire_deps (docs/07, 3.6: a resulting cycle drops the
+* Cycle check for rewire_deps (a resulting cycle drops the
 * WHOLE op with dep_cycle; rewire_deps is atomic). Answers whether the
 * graph with `nodeId`'s deps replaced by `deps` contains a cycle
 * reachable from `nodeId`. add_task cannot create cycles (nothing depends
@@ -147,19 +147,19 @@ function wouldCreateDepCycle(plan, nodeId, deps) {
 * planHash (M7-T01): the canonical projection of a TaskPlan and its
 * sha256, plus the fold-head assertion the appenders use.
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, section 3.4
-* (DEF-8): planHash = sha256 of the canonical JSON of PlanState, nodes
-* sorted by NodeId, each node exactly the docs/07 3.1 record with `deps`
+* DEF-8: planHash = sha256 of the canonical JSON of PlanState, nodes
+* sorted by NodeId, each node exactly the canonicalNode record with `deps`
 * sorted in the hash, plus the guard fold counters revisionCount and
 * droppedRevisionStreak. Nothing wall-clock, nothing telemetric, enters
 * the hash. Canonicalization and digest ride the frozen hashVersion 2
 * deriver (RFC 8785 JCS + sha256), so the plan chain shares the identity
 * pipeline of the journal kernel; a future grammar change arrives as a
-* new deriver, never as an edit here (docs/03, section "hashVersion").
+* new deriver, never as an edit here
+* (https://docs.rulvar.com/guide/journal-compatibility).
 */
 /** The hashVersion whose profile computes planHash today. */
 const PLAN_HASH_VERSION = CURRENT_HASH_VERSION;
-/** The exact per-node projection entering the hash (docs/07, 3.1). */
+/** The exact per-node projection entering the hash. */
 function canonicalNode(node) {
 	const projected = {
 		nodeId: node.nodeId,
@@ -178,7 +178,7 @@ function canonicalNode(node) {
 }
 /**
 * The canonical JSON projection of PlanState: nodes sorted by NodeId plus
-* the guard fold counters, nothing else (docs/07, 3.4).
+* the guard fold counters, nothing else.
 */
 function canonicalPlanState(plan) {
 	return {
@@ -190,14 +190,14 @@ function canonicalPlanState(plan) {
 /**
 * planHash under one deriver profile (default: the current hashVersion 2
 * profile). Replay recomputes each entry's planHashAfter with the
-* predicate of that entry's OWN hashVersion (docs/07, 3.4), so the
+* predicate of that entry's OWN hashVersion, so the
 * deriver is a parameter, not an ambient.
 */
 function planHash(plan, deriver = deriverV2) {
 	return deriver.deriveKey(canonicalPlanState(plan));
 }
 /**
-* The append-time head assertion (docs/07, 3.4): planHashBefore of the
+* The append-time head assertion: planHashBefore of the
 * entry being appended MUST equal the current fold head. A failure is an
 * engine bug and raises the typed PlanInvariantError; the run finishes
 * with outcome error, never a silent brick.
@@ -218,11 +218,11 @@ function assertPlanHead(plan, expectedPlanHash, context) {
 * PlanWriteLock (M7-T01): the in-process FIFO mutex serializing live
 * appends to the sequential scope "plan".
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, section 3.2
+* Owning contract: https://docs.rulvar.com/guide/adaptive-orchestration
 * (DEF-8, XF-07). The lock serializes ONLY plan-scope appends (acquire,
 * read the fold head, evaluate, append, release); it MUST NOT substitute
 * for resolution arbitration, which is owned by the ResolutionArbiter
-* (docs/03, section "Suspension and resolutions (DEF-4)"). In queue mode
+* (DEF-4). In queue mode
 * the lease fencing epoch applies on top. Wall clock influences only
 * WHICH order gets recorded live; replay reads the recorded order and
 * never takes the lock.
@@ -259,14 +259,13 @@ var PlanWriteLock = class {
 * toolset, used by spawn_agent, parallel_agents, add_task, and
 * proposedDecomposition.
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, section 4.1. The
-* orchestrator never sees or names concrete models; model_hint.startTier
+* The orchestrator never sees or names concrete models; model_hint.startTier
 * is the ONLY model influence it has and is clamped to the declared
-* ladder (docs/07, section 10).
+* ladder.
 */
 /**
-* The deterministic spec digest entering PlanNode.promptSpecHash
-* (docs/07, 3.1): the canonical JSON of the full TaskSpec through the
+* The deterministic spec digest entering PlanNode.promptSpecHash:
+* the canonical JSON of the full TaskSpec through the
 * frozen hashVersion 2 canonicalization. A plan-internal digest, not a
 * kernel content key: the paid-call identity stays with the child's own
 * spawn entry.
@@ -289,8 +288,8 @@ function applyTaskSpecPatch(spec, patch) {
 * plan.revision and plan.decision entry payloads plus the single-applier
 * plan fold (M7-T04, DEF-8).
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, sections 3.2-3.4
-* and 3.9. There are several AUTHORS of plan mutations but exactly ONE
+* Full contract: https://docs.rulvar.com/guide/adaptive-orchestration.
+* There are several AUTHORS of plan mutations but exactly ONE
 * APPLIER: the fold below, consuming a totally ordered stream of
 * plan-mutating entries from the sequential scope "plan". Nothing mutates
 * PlanState directly; state is a pure fold of entries. Replay NEVER
@@ -301,7 +300,7 @@ function applyTaskSpecPatch(spec, patch) {
 * corrupting the journal further.
 */
 /**
-* Content keys (docs/07, 3.3): plan.revision keys over {kind, base,
+* Content keys: plan.revision keys over {kind, base,
 * requestedOps}; plan.decision over {kind, origin, ops, causeRef}.
 * Cosmetics (rationale) never enter a key; ordinal within scope "plan"
 * distinguishes repeats, so forward-matching works without kernel
@@ -330,7 +329,7 @@ function emptyPlanFold(plan) {
 		doneRefs: {}
 	};
 }
-/** The streak RevisionGuards consume (docs/07, 3.8). */
+/** The streak RevisionGuards consume. */
 function effectiveDroppedStreak(state) {
 	return state.plan.droppedRevisionStreak + state.badBaseStreak;
 }
@@ -372,7 +371,7 @@ function withNode(working, node, spec) {
 * recorded outcomes; op-level legality was decided at rebase time and is
 * never re-evaluated here. Exported for the rebase engine, which applies
 * each op of a revision against the state already changed by the earlier
-* applied ops of the same revision (docs/07, 3.5, step 3).
+* applied ops of the same revision.
 */
 function applyAppliedOp(working, op, context) {
 	switch (op.op) {
@@ -483,7 +482,7 @@ function readPlanDecision(entry) {
 	return value;
 }
 /**
-* THE single applier (docs/07, 3.2): folds one plan-scope entry into the
+* THE single applier: folds one plan-scope entry into the
 * state. Replay consumes recorded outcomes (the APPLIED diff), never
 * re-runs rebase, and timers do not run; hash verification runs under
 * the entry's own hashVersion profile.
@@ -544,7 +543,7 @@ function applyPlanEntry(state, entry, options) {
 }
 /**
 * The shared plan.decision applier core: engine authorship happens at
-* the fold head under PlanWriteLock (docs/07, 3.3), so the producer can
+* the fold head under PlanWriteLock, so the producer can
 * PREVIEW the resulting state (and its planHashAfter) before appending,
 * and the fold re-applies the recorded ops identically on replay.
 */
@@ -611,7 +610,7 @@ function lineageOfAdmission(admissions, opIndex) {
 	return verdict.lineage.logicalTaskId;
 }
 /**
-* The escalated node's fate under a resolve_escalation op (docs/07, 3.3):
+* The escalated node's fate under a resolve_escalation op:
 * retry re-opens the node for scheduling (pending; readiness decides),
 * cancel closes it, accept marks the paid partial result done, decompose
 * leaves the node escalated while its children (spawn_admitted in the
@@ -642,7 +641,7 @@ function resolveEscalatedNode(node, decision, escalationRef) {
 //#endregion
 //#region src/rebase.ts
 /**
-* Steps 2-4 of the committed algorithm (docs/07, 3.5): base validation,
+* Steps 2-4 of the committed algorithm: base validation,
 * sequential per-op conflict resolution against the mutating head, and
 * the post-revision counter update. Pure: the caller owns the lock, the
 * append, and every effect.
@@ -720,9 +719,8 @@ function dropped(requested, reason, blockingRef) {
 	};
 }
 /**
-* The complete per-op resolution table, op x node state at the fold head
-* (docs/07, 3.6). Normative and closed: every row below cites its table
-* row; nothing else exists.
+* The complete per-op resolution table, op x node state at the fold head.
+* Normative and closed: nothing outside the rows below exists.
 */
 function evaluateOp(op, opIndex, working, context, admissions, assignedNodeIds) {
 	if (context.frozen === true) return dropped(op, "plan_frozen");
@@ -898,7 +896,7 @@ function evaluateOp(op, opIndex, working, context, admissions, assignedNodeIds)
 	}
 }
 /**
-* The cancel cascade (docs/07, 3.6): the transitive BLOCKING dependents
+* The cancel cascade: the transitive BLOCKING dependents
 * of the cancelled node, computed at apply time. An edge is blocking
 * when not waived; `done` nodes never enter the cascade (done is
 * immutable), and running dependents (only reachable via waived or
@@ -927,7 +925,7 @@ function cascadeOf(plan, root) {
 //#region src/guards.ts
 /** Appendix A: osc_guard reject threshold per key (shared default). */
 const DEFAULT_MAX_OSCILLATIONS_PER_KEY = 2;
-/** The hard per-run stall replan bound (docs/07, 9.3). */
+/** The hard per-run stall replan bound. */
 const DEFAULT_STALL_REPLAN_CAP = 4;
 const DEFAULT_DROPPED_REVISION_LIMIT = 3;
 /**
@@ -1053,7 +1051,7 @@ const DEFAULT_MAX_PINNED_WORKTREES = 4;
 /**
 * The worktree pin ledger: a pure fold counting live pins from abandon
 * entries carrying `retainWorktree: true` (park pinning and DEF-5
-* retention share the cap by construction; docs/08).
+* retention share the cap by construction).
 */
 var PinLedger = class PinLedger {
 	pinnedTargets = /* @__PURE__ */ new Set();
@@ -1098,7 +1096,7 @@ function unparkPlacementOf(input) {
 * RunLedger (M7-T09): run-scoped, single-writer, journaled, strictly
 * advisory distilled state for recovery-context quality and replanning.
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, section 9. ONLY
+* Contract: https://docs.rulvar.com/guide/adaptive-orchestration. ONLY
 * the orchestrator scope writes; every authored write is a journaled
 * effect entry of kind `ledger.op`; the VIEW is a pure fold of those ops
 * joined to the journal's task table. The journal always wins on what is
@@ -1227,14 +1225,14 @@ function foldLedger(entries, options) {
 	return view;
 }
 /**
-* The committed ledger_read render budget (docs/06, Appendix A: 65536
+* The committed ledger_read render budget (Appendix A: 65536
 * chars over the serialized view, the character measure; OQ-04 closed
 * at M10 entry). The section caps stay the primary bound; under the
 * default termination limits this belt never engages.
 */
 const LEDGER_RENDER_BUDGET_CHARS = 65536;
 /**
-* Deterministic render bound (docs/07, 9.3): over budget, rows drop
+* Deterministic render bound: over budget, rows drop
 * oldest-first, auto-derived joins before authored sections, and the
 * mission brief slices last; every drop is a FLAGGED discrepancy line.
 * A pure function of (view, budget): a re-executed wake turn renders
@@ -1280,7 +1278,7 @@ function boundLedgerRender(view, budgetChars = LEDGER_RENDER_BUDGET_CHARS) {
 	}
 	return bounded;
 }
-/** Section-cap check for one authored op (docs/06, Appendix A). */
+/** Section-cap check for one authored op (Appendix A). */
 function ledgerCapViolation(view, op) {
 	if (op.op === "brief_set" && view.brief !== void 0) return "the mission brief is immutable (brief_set is once per run)";
 	if ((op.op === "fact_add" || op.op === "fact_supersede") && view.facts.length >= LEDGER_SECTION_CAPS.facts) return `the facts section is capped at ${String(LEDGER_SECTION_CAPS.facts)}`;
@@ -1288,7 +1286,7 @@ function ledgerCapViolation(view, op) {
 	if (op.op === "observation_add" && view.observations.length >= LEDGER_SECTION_CAPS.observations) return `the observations section is capped at ${String(LEDGER_SECTION_CAPS.observations)}`;
 }
 /**
-* Compaction sufficiency (docs/07, 9.3): the orchestrate role may
+* Compaction sufficiency: the orchestrate role may
 * compact aggressively only when the ledger measurably suffices (at
 * least one authored revision recorded and a minimum fact count);
 * otherwise the engine falls back to conservative summarize.
@@ -1311,9 +1309,8 @@ function exportLedger(view) {
 /**
 * ModelLadder runtime pieces (M7-T10).
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, section 10 (runtime
-* semantics); docs/04-model-layer-spec.md, section 12 (the type family and
-* canonicalization, declared once in core). This module is PURE: the
+* The ladder type family and canonicalization are declared once in
+* core. This module is PURE: the
 * PlanRunner drives it through the extension IO. Every ladder control-flow
 * verdict (trigger classification result, gate verdicts, spot-check
 * selection) journals as a decision entry computed once live and replayed
@@ -1321,8 +1318,8 @@ function exportLedger(view) {
 */
 /**
 * Extracts the declared ladder from an agent profile: the ModelSpec union
-* carries it (`model: { ladder }`), or the loop-role routing entry
-* (docs/04, section 12). The same declaration points feed ladderLengthOf
+* carries it (`model: { ladder }`), or the loop-role routing entry.
+* The same declaration points feed ladderLengthOf
 * and the frozen kMax, so admission and execution can never disagree on
 * the ladder length.
 */
@@ -1346,8 +1343,8 @@ function canonicalLadderOf(profile) {
 	return canonicalizeLadder(declared, chainEffort === void 0 ? void 0 : { chainEffort });
 }
 /**
-* Clamps the orchestrator's `model_hint.startTier` to the declared ladder
-* (docs/07, section 4.2): the hint is the ONLY model influence the
+* Clamps the orchestrator's `model_hint.startTier` to the declared ladder:
+* the hint is the ONLY model influence the
 * orchestrator has, and it never names a model.
 */
 function clampStartTier(ladder, hint) {
@@ -1357,14 +1354,14 @@ function clampStartTier(ladder, hint) {
 /**
 * The rung an attempt executes on: the clamped start tier plus the
 * journaled raise count, hard-clamped at the top rung. `rungIndex` per
-* lineage is strictly monotone; there are no demotions (docs/07, 10).
+* lineage is strictly monotone; there are no demotions.
 */
 function executingRungOf(ladder, startTier, raises) {
 	return Math.min(startTier + raises, ladder.rungs.length - 1);
 }
 /**
-* Classifies a settled attempt into the typed transition trigger
-* (docs/04, section 12): schema-mismatch errors are 'schema-exhausted';
+* Classifies a settled attempt into the typed transition trigger:
+* schema-mismatch errors are 'schema-exhausted';
 * the engine's no-progress abort is first-class 'no-progress' (it rides
 * status 'limit' with the dedicated abort class, distinct from user
 * cancellation by construction); cancelled, escalated, and skipped never
@@ -1390,7 +1387,7 @@ function ladderVerdictKey(attemptRef) {
 		attemptRef
 	});
 }
-/** The forced verdict schema of the judge gate (docs/07, section 10). */
+/** The forced verdict schema of the judge gate. */
 const JUDGE_VERDICT_SCHEMA = {
 	type: "object",
 	properties: {
@@ -1420,9 +1417,9 @@ function judgePrompt(input) {
 /**
 * EscalationProtocol completion (M7-T11).
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, section 6 (the
-* protocol), 3.3 (entry kinds), 3.7 (timer race); docs/03, section 8
-* (DEF-4 resolution family). The M3 producers (report, flavors, the
+* Full protocol: https://docs.rulvar.com/guide/adaptive-orchestration;
+* resolutions (the DEF-4 family): https://docs.rulvar.com/guide/durability.
+* The M3 producers (report, flavors, the
 * escalate tool, countsAgainstLimit derivation) live in core; this module
 * owns the DECISION side under PlanRunner: the authoritative
 * `escalation-decision` entries the lineage and termination folds consume,
@@ -1430,7 +1427,7 @@ function judgePrompt(input) {
 *
 * Channels, closed in v1:
 * - Live Flavor A: `cancel_task` on an escalated node transforms into an
-*   escalation resolution with verdict `cancel` (docs/07, 3.6 row); the
+*   escalation resolution with verdict `cancel`; the
 *   other verdicts on a TERMINAL report are engine territory.
 * - Flavor B: the suspended report resolves through the DEF-4 family
 *   (timeout `defaultDecision`, a live `onEscalation` decision, or a
@@ -1452,7 +1449,7 @@ function resolvedByOf(by) {
 	if (by === "class_decision") return "class";
 	return "live";
 }
-/** The plan.decision origin of one resolvedBy value (docs/07, 3.3). */
+/** The plan.decision origin of one resolvedBy value. */
 function decisionOriginOf(resolvedBy) {
 	if (resolvedBy === "default") return "escalation-default";
 	if (resolvedBy === "class") return "escalation-class";
@@ -1463,21 +1460,20 @@ function decisionOriginOf(resolvedBy) {
 /**
 * The PlanRunner toolset (M7-T05): plan_view and plan_revise.
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, sections 4.6 and
-* 4.7. The JSON Schemas below are NORMATIVE: they enter toolsetHash and
+* The JSON Schemas below are NORMATIVE: they enter toolsetHash and
 * therefore identity. plan_view is a pure fold pinned to the last
 * WakeDigest (never a live read; a re-executed wake turn reads its
 * original snapshot); plan_revise is the typed PlanOp diff with
 * auto-rebase (M7-T04), whose tool result renders deterministically from
 * the journaled entry.
 */
-/** docs/07, 4.6: plan_view takes no parameters. */
+/** plan_view takes no parameters. */
 const PLAN_VIEW_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
 	properties: {}
 };
-/** The taskSpec projection shared with spawn_agent (docs/07, 4.7 $defs). */
+/** The taskSpec projection shared with spawn_agent. */
 const TASK_SPEC_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -1506,7 +1502,7 @@ const TASK_SPEC_SCHEMA = {
 		taskClass: { type: "string" }
 	}
 };
-/** docs/07, 4.7: the plan_revise parameter schema (normative). */
+/** The plan_revise parameter schema (normative). */
 const PLAN_REVISE_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -1682,7 +1678,7 @@ const PLAN_VIEW_TOOL_NAME = "plan_view";
 const PLAN_REVISE_TOOL_NAME = "plan_revise";
 const LEDGER_APPEND_TOOL_NAME = "ledger_append";
 const LEDGER_READ_TOOL_NAME = "ledger_read";
-/** The closed authored op vocabulary as JSON Schema (docs/07, 9.2). */
+/** The closed authored op vocabulary as JSON Schema. */
 const LEDGER_APPEND_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -1811,7 +1807,7 @@ const LEDGER_APPEND_SCHEMA = {
 		}
 	] } }
 };
-/** docs/07: ledger_read takes no parameters and pins to the turn snapshot. */
+/** ledger_read takes no parameters and pins to the turn snapshot. */
 const LEDGER_READ_SCHEMA = {
 	type: "object",
 	additionalProperties: false,
@@ -1851,19 +1847,18 @@ function buildPlanTools(runtime) {
 /**
 * PlanRunner (M7-T05): the opt-in extension of mode (c).
 *
-* Owning spec: docs/07-adaptive-orchestration-spec.md, sections 1, 3, and
-* 4. The ENGINE, not the model, schedules ready nodes through the
+* Full contract: https://docs.rulvar.com/guide/adaptive-orchestration.
+* The ENGINE, not the model, schedules ready nodes through the
 * existing semaphore and budget admission; children run under
 * `plan/NodeId` scopes; every plan mutation is an entry in the single
 * sequential scope "plan"; the orchestrator sleeps between wakes and
 * revises the plan through typed diffs with auto-rebase. PlanRunner runs
-* write `termination.init` and carry the full adaptive machinery
-* (docs/07, section 1); the guards, reuse, park, ledger, ladder,
+* write `termination.init` and carry the full adaptive machinery;
+* the guards, reuse, park, ledger, ladder,
 * escalation, and budget-cap layers complete in M7-T06..T13.
 *
 * PlanRunner is built EXCLUSIVELY from the public core API through the
-* orchestrator extension seam (docs/02, section 4: the seam-sufficiency
-* rule).
+* orchestrator extension seam (the seam-sufficiency rule).
 */
 /** AgentResult terminal statuses mapped onto plan node statuses. */
 function nodeStatusOf(status) {
@@ -1879,7 +1874,7 @@ function nodeStatusOf(status) {
 const TERMINATION_INIT_KEY_KIND = "termination.init";
 const TERMINATION_DENIED_KEY_KIND = "termination.denied";
 /**
-* Builds the PlanRunner orchestrator extension (docs/07, section 3).
+* Builds the PlanRunner orchestrator extension.
 * Attach via `orchestrate(engine, goal, { extension: planRunner(o) })` or
 * the `orchestratePlanned` convenience surface.
 */
@@ -1930,8 +1925,8 @@ function planRunner(options) {
 		}
 	};
 	/**
-	* Appends fold-fired verdicts strictly BEFORE their effects (docs/07,
-	* 3.8); a verdict already journaled (replay absorb) never duplicates.
+	* Appends fold-fired verdicts strictly BEFORE their effects; a
+	* verdict already journaled (replay absorb) never duplicates.
 	*/
 	const drainGuardVerdicts = async () => {
 		while (pendingGuardVerdicts.length > 0) {
@@ -1971,7 +1966,7 @@ function planRunner(options) {
 	* SpawnKeys a byte-identical candidate would collide with: within one
 	* run, an identical TaskSpec resolves to the identical kernel content
 	* key, so donor discovery goes promptSpecHash -> prior nodes -> their
-	* root entry keys (docs/03, 9.2: strict byte equality, never fuzzy).
+	* root entry keys (strict byte equality, never fuzzy).
 	*/
 	const donorKeysOf = (spec) => {
 		const specHash = promptSpecHashOf(spec);
@@ -1985,7 +1980,7 @@ function planRunner(options) {
 	};
 	/**
 	* Re-issues the reuse effects recorded in one plan.revision entry
-	* (docs/03, 9.10: deciding entry, then node.link, then the child root,
+	* (deciding entry, then node.link, then the child root,
 	* then scheduling; a crash between any two is ordinary roll-forward).
 	* Idempotent: every append scans for its own identity first.
 	*/
@@ -2052,8 +2047,8 @@ function planRunner(options) {
 		}
 	};
 	/**
-	* Builds the reuse transform for one add_task at the fold head
-	* (docs/03, 9.4): the verdict, the donor descriptor, and the placement
+	* Builds the reuse transform for one add_task at the fold head:
+	* the verdict, the donor descriptor, and the placement
 	* embed into the revision entry; effects land after the append.
 	*/
 	const buildReuseTransform = (op, kind, donor) => {
@@ -2147,7 +2142,7 @@ function planRunner(options) {
 			}
 		};
 	};
-	/** Compiles applied cancels into severing abandons (docs/03, 9.1). */
+	/** Compiles applied cancels into severing abandons. */
 	const landCancelAbandons = async (value, authorizedBy) => {
 		for (const outcome of value.outcomes) {
 			if (outcome.kind === "dropped") continue;
@@ -2157,7 +2152,7 @@ function planRunner(options) {
 			for (const cascaded of applied.cascadeNodeIds ?? []) await abandonNode(cascaded, authorizedBy, "cancel_task cascade");
 		}
 	};
-	/** Severs a cancelled node's dispatched branch (docs/03, 9.1). */
+	/** Severs a cancelled node's dispatched branch. */
 	const abandonNode = async (nodeId, authorizedBy, reason) => {
 		const root = nodeRootOf(nodeId);
 		if (root === void 0) return;
@@ -2262,7 +2257,7 @@ function planRunner(options) {
 		return entry.seq;
 	};
 	/**
-	* The rung-resolved dispatch fields of a laddered node (docs/07, 10):
+	* The rung-resolved dispatch fields of a laddered node:
 	* the concrete ModelRef enters the attempt's identity hash, the rung
 	* caps bind as usage limits (maxTokens reads as the per-turn output
 	* cap, so maxTurns x maxTokens bounds the worst-case failed attempt),
@@ -2288,7 +2283,7 @@ function planRunner(options) {
 	};
 	/**
 	* Runs the acceptance gates of one settled ok attempt in declaration
-	* order, fail fast (docs/07, 10). Every evaluation is a decision entry
+	* order, fail fast. Every evaluation is a decision entry
 	* (kind 'decision', decisionType 'gate-verdict') computed once live and
 	* recovered by content key on re-execution; the spot-check draw is
 	* io.random (journaled ctx.random, never Math.random).
@@ -2374,7 +2369,7 @@ function planRunner(options) {
 		return { pass: true };
 	};
 	/**
-	* One judge invocation (docs/07, 10): a bounded child dispatch on the
+	* One judge invocation: a bounded child dispatch on the
 	* declared rung with the forced verdict schema. Identity is DERIVED
 	* (never minted live) so a re-executed turn replays the same judge by
 	* content match. A judge that itself errors fails CLOSED: acceptance
@@ -2420,7 +2415,7 @@ function planRunner(options) {
 		}
 	};
 	/**
-	* The ladder driver of one settled attempt (docs/07, 10; DEF-2/DEF-3).
+	* The ladder driver of one settled attempt (DEF-2/DEF-3).
 	* Returns 'raised' when the next rung attempt was authorized and
 	* dispatched (the node STAYS running under a new handle); 'none' when
 	* the ordinary terminal landing proceeds; or a forced terminal status
@@ -2604,7 +2599,7 @@ function planRunner(options) {
 		return (entry.value?.input ?? {}).kind;
 	};
 	/**
-	* Writes THE authoritative escalation-decision entry (docs/07, 6.5):
+	* Writes THE authoritative escalation-decision entry:
 	* idempotent by content key (decide-once per report); the counting
 	* debit is atomic with the append and a DENIED debit lands
 	* termination.denied strictly before, flipping the entry to
@@ -2666,7 +2661,7 @@ function planRunner(options) {
 		return entry;
 	};
 	/**
-	* Applies one decided escalation to the plan (docs/07, 3.3): the
+	* Applies one decided escalation to the plan: the
 	* resolve_escalation op (retry re-opens the node in place, accept
 	* closes it done, cancel closes it cancelled and severs the branch,
 	* decompose leaves it escalated while the admitted children carry the
@@ -2709,9 +2704,9 @@ function planRunner(options) {
 		await scheduleReady();
 	};
 	/**
-	* Decomposition admissions (docs/07, 11.3 b): each proposed child is an
-	* admitted spawn with a FRESH lineage minted inside the decision entry
-	* (docs/07, 8.1 rule 6); the spawn debits ride the decision.
+	* Decomposition admissions: each proposed child is an
+	* admitted spawn with a FRESH lineage minted inside the decision
+	* entry; the spawn debits ride the decision.
 	*/
 	const admitDecomposition = (children) => {
 		const rows = [];
@@ -2740,7 +2735,7 @@ function planRunner(options) {
 	};
 	/**
 	* Absorbs the DEF-4 winner of a Flavor B suspension into the
-	* authoritative decision (docs/07, 3.7: the resolution entry closes the
+	* authoritative decision (the resolution entry closes the
 	* suspension FIRST; the plan.decision references it strictly after).
 	* The timeout defaultDecision, a live onEscalation decision, and a
 	* class-level fan-out all land here through their journaled `by`.
@@ -2770,8 +2765,8 @@ function planRunner(options) {
 		return true;
 	};
 	/**
-	* Lands revision-transform escalation resolutions (docs/07, 3.6 row:
-	* cancel_task on an escalated node): the authoritative decision with
+	* Lands revision-transform escalation resolutions
+	* (cancel_task on an escalated node): the authoritative decision with
 	* verdict cancel, then the resolve_escalation plan.decision, then the
 	* severing abandon; all idempotent for the roll-forward path.
 	*/
@@ -2833,7 +2828,7 @@ function planRunner(options) {
 		}
 	};
 	/**
-	* The class-level decision (docs/07, 6.5): ONE entry resolving N
+	* The class-level decision: ONE entry resolving N
 	* same-kind reports, per-lineage debits embedded as `debits` rows,
 	* resolvedBy 'class'. Returns undefined when any counting debit would
 	* be denied (the caller degrades to single-target decisions).
@@ -2969,7 +2964,7 @@ function planRunner(options) {
 		}
 	};
 	/**
-	* A retry decision's amendments (docs/07, 6.3): amendedPrompt and
+	* A retry decision's amendments: amendedPrompt and
 	* startTier ride the journaled decision, so the re-dispatch is a pure
 	* function of the journal, identical live and on replay.
 	*/
@@ -3494,8 +3489,7 @@ function orchestratePlanned(engine, goal, opts) {
 //#endregion
 //#region src/cassettes.ts
 /**
-* M7 gating cassette runners (M7-T14; docs/09, section 6 catalog;
-* docs/11, section "Frozen journal fixtures").
+* M7 gating cassette runners (M7-T14).
 *
 * Every scenario runs fully offline on a scripted adapter over the
 * PUBLIC provider SPI and produces a NORMALIZED journal: wall clock,
@@ -3659,7 +3653,7 @@ async function settled(handle) {
 }
 /**
 * revise-mid-run: a plan revision arrives while a worker subtree is
-* mid-flight (docs/09 round-2). The first worker HANGS until the
+* mid-flight. The first worker HANGS until the
 * revision cancels it; the added replacement completes.
 */
 async function runReviseMidRun() {
@@ -3735,7 +3729,7 @@ function assignedNodeIn(req) {
 }
 /**
 * crash-during-revision: process death INSIDE the revision window, at
-* the pre-append kill point (docs/09 round-2): life 1 is truncated
+* the pre-append kill point: life 1 is truncated
 * strictly BEFORE the second plan.revision entry; life 2 re-issues the
 * revision live and rolls its effects forward.
 */
@@ -3804,7 +3798,7 @@ async function runCrashDuringRevision() {
 }
 /**
 * oscillation-freeze: the coarse-signature oscillation detector freezes
-* further re-adds under hysteresis (docs/09 round-2; distinct from the
+* further re-adds under hysteresis (distinct from the
 * per-key osc_guard reject).
 */
 async function runOscillationFreeze(options) {
@@ -3858,7 +3852,7 @@ async function runOscillationFreeze(options) {
 }
 /**
 * park-unpark: park of a running node with checkpoint retention, later
-* unpark and continuation (docs/09 round-2; docs/03 11.2). The worker
+* unpark and continuation. The worker
 * pays one tool turn, hangs in its second, parks at the boundary, and
 * the unparked continuation resumes from the retained checkpoint (the
 * booted history carries the paid turn).
@@ -4010,7 +4004,7 @@ function ladderScript(strongTurn) {
 /**
 * half-escalated-ladder: some rungs terminal, the active rung dangling
 * mid-attempt at the crash; resume continues the ladder without
-* repaying completed rungs (docs/09 round-2).
+* repaying completed rungs.
 */
 async function runHalfEscalatedLadder() {
 	const adapter = cassetteAdapter(ladderScript({ hangUntilAborted: true }));
@@ -4040,7 +4034,7 @@ async function runHalfEscalatedLadder() {
 /**
 * budget-denied-rung: the budget guard denies the rung respawn; the
 * denial journals as termination.denied strictly before the verdict and
-* the ladder takes its declared fallback path (docs/09 round-2).
+* the ladder takes its declared fallback path.
 */
 async function runBudgetDeniedRung() {
 	const adapter = cassetteAdapter(ladderScript({ text: "never reached" }));
@@ -4093,7 +4087,7 @@ function capScript(finalTurn) {
 * cap-freeze-then-finish (DEF-7): the soft boundary crossed with live
 * children; the cap decision precedes its effects; admitted nodes run to
 * completion; the final quiescence wake gets the finish-only toolset;
-* outcome ok with forcedFinish (docs/09).
+* outcome ok with forcedFinish.
 */
 async function runCapFreezeThenFinish() {
 	const adapter = cassetteAdapter(capScript(() => ({ toolCall: {
@@ -4276,7 +4270,7 @@ async function runRungRetryLineage() {
 /**
 * decompose-mints-children (DEF-3): an escalation decomposition mints
 * FRESH logical tasks inside the decision entry; the spawn debits ride
-* the same entry (docs/07, 8.1 rule 6, 11.3 b).
+* the same entry.
 */
 async function runDecomposeMintsChildren() {
 	let phase = 0;
@@ -4387,8 +4381,7 @@ async function runQueueFailoverDuringForcedFinish(deps) {
 //#region src/m9-cassettes.ts
 /**
 * M9 catalog completion runners: the DEF-2 and DEF-3 cassette rows that
-* were deferred at M7 (M9-T04; docs/09, sections 6.2 and 6.3; docs/10,
-* section "Gating cassette sets per milestone", M9 row).
+* were deferred at M7 (M9-T04).
 *
 * Same discipline as the M7 runners (cassettes.ts): every scenario runs
 * fully offline on the scripted adapter over the PUBLIC provider SPI,
@@ -5421,7 +5414,7 @@ async function runLegacyJournalResume() {
 * rungs burn their single turn on the echo tool (limit, raise) and whose
 * top rung is scriptable. Severing the node mid-top-rung leaves the two
 * completed rung attempts as ELIGIBLE PAID entries under the node's
-* coverage, which is exactly what a graft donor needs (docs/03, 9.4).
+* coverage, which is exactly what a graft donor needs.
 */
 function graftLadderProfile(isolation) {
 	return {
@@ -5491,7 +5484,7 @@ function linkEntriesOf(entries) {
 * reuse_full: the verdict is embedded in the plan.revision, the
 * node.link (mode full, claim shared) and the by-ref root are present,
 * the reused subtree costs zero live calls, and reclaimedUsdAtLink
-* equals the donor spend (docs/03, 9.4/9.5).
+* equals the donor spend.
 */
 async function runOscillationFullReuse() {
 	let phase = 0;
@@ -5568,7 +5561,7 @@ async function runOscillationFullReuse() {
 * mid-top-rung after two completed rung attempts; the byte-identical
 * re-add grafts (exclusive link), the completed rung attempts
 * forward-match through the scope alias, and only the interrupted rung
-* reruns live, exactly once (docs/03, 9.5).
+* reruns live, exactly once.
 */
 async function runGraftPartialSubtree() {
 	let phase = 0;
@@ -5653,7 +5646,7 @@ async function runGraftPartialSubtree() {
 * crash-between-link-and-root (DEF-5): the full-reuse scenario is cut
 * strictly AFTER the durable node.link and BEFORE the by-ref root; the
 * resume rolls forward: the link forward-matches, the root is re-issued,
-* and nothing is paid twice (docs/03, 9.10).
+* and nothing is paid twice.
 */
 async function runCrashBetweenLinkAndRoot() {
 	const script = (state) => {
@@ -5743,7 +5736,7 @@ async function runCrashBetweenLinkAndRoot() {
 * oscillation-guard-trip (DEF-5): the third re-add of one SpawnKey at
 * maxOscillationsPerKey 2 rejects osc_guard as a typed plan_revise
 * error; the run closes through the non-HITL path and the embedded
-* verdicts replay identically (docs/03, 9.4).
+* verdicts replay identically.
 */
 async function runOscillationGuardTrip() {
 	let phase = 0;
@@ -5817,8 +5810,8 @@ async function runOscillationGuardTrip() {
 * worktree-disposed-degrade (DEF-5): a worktree-isolated graft donor
 * whose tree was NOT retained degrades to a fresh admit with the
 * embedded DedupNote graft_unsafe; a second section verifies reuse_full
-* stays allowed for a worktree donor whose root is terminal (docs/03,
-* 9.4: the pin condition applies to grafts only).
+* stays allowed for a worktree donor whose root is terminal (the pin
+* condition applies to grafts only).
 */
 async function runWorktreeDisposedDegrade() {
 	let phase = 0;
@@ -5941,7 +5934,7 @@ async function runWorktreeDisposedDegrade() {
 * tasks; the first grafts (exclusive claim), the second admits fresh;
 * the grafted node is severed and the key added a third time: the link
 * points at the chain head and the drain is transitive, oldest first;
-* oscillationCount for the key reaches 2 (docs/03, 9.6).
+* oscillationCount for the key reaches 2.
 */
 async function runClaimExclusivityAndChain() {
 	let phase = 0;
@@ -6027,7 +6020,7 @@ async function runClaimExclusivityAndChain() {
 * done, a second node escalates, and a third completes; the wake
 * submits ONE stale-based revision {waive_dep, park_task, cancel_task}
 * whose trio drops with the exact reasons and the blockingRef pointing
-* at the defaultDecision resolution (docs/07, 3.5; docs/09, 6.8).
+* at the defaultDecision resolution.
 */
 async function runReviseRacingDefaultDecision() {
 	let phase = 0;
@@ -6144,7 +6137,7 @@ async function runReviseRacingDefaultDecision() {
 * crash-after-append-before-effects (DEF-8): the kill lands immediately
 * after the durable plan.revision carrying add_task x2 plus cancel_task
 * on a running node; the resume re-issues the effects: both children
-* spawn live exactly once and the cancel lands (docs/07, 3.9).
+* spawn live exactly once and the cancel lands.
 */
 async function runCrashAfterAppendBeforeEffects() {
 	const script = (state) => {
@@ -6225,7 +6218,7 @@ async function runCrashAfterAppendBeforeEffects() {
 * amend-vs-running-then-cancel-add (DEF-8): amend_task on a running node
 * drops node_running; the next revision cancels it and adds the amended
 * prompt as a NEW node continuing the SAME logical task; the abandon
-* covers the old branch and replay repays neither (docs/07, 4.7).
+* covers the old branch and replay repays neither.
 */
 async function runAmendVsRunningThenCancelAdd() {
 	let phase = 0;
@@ -6290,7 +6283,7 @@ async function runAmendVsRunningThenCancelAdd() {
 * intra-revision-self-conflict (DEF-8): one revision {cancel_task X,
 * amend_task X, rewire_deps with an edge onto X} resolves strictly in
 * submission order per the sequential intra-revision application
-* semantics (docs/07, 4.7 conflict table).
+* semantics.
 */
 async function runIntraRevisionSelfConflict() {
 	let phase = 0;
@@ -6365,7 +6358,7 @@ async function runIntraRevisionSelfConflict() {
 * bad-base-streak-terminates (DEF-8): three consecutive revisions with a
 * fabricated base.planHash land as all-dropped bad-base entries; the
 * dropped streak reaches its limit and the non-HITL RevisionGuards
-* fallback (finish-with-partial) closes the run (docs/07, 3.5/3.8).
+* fallback (finish-with-partial) closes the run.
 */
 async function runBadBaseStreakTerminates() {
 	let phase = 0;
@@ -6403,7 +6396,7 @@ async function runBadBaseStreakTerminates() {
 * park-races-child-completion (DEF-8): park_task lands on a running node
 * whose terminal appends moments later; parkRequested is extinguished by
 * the child-result transition, no checkpoint is written, and the node is
-* done (docs/07, 3.6).
+* done.
 */
 async function runParkRacesChildCompletion() {
 	let phase = 0;
@@ -6474,7 +6467,7 @@ async function runParkRacesChildCompletion() {
 * reserve-survives-run-exhaustion (DEF-7): cheap workers eat the run
 * ceiling until admission rejects the spawn that would invade the
 * committed finalize reserve; the final wake executes from the reserve
-* and the rejections forward-match on replay (docs/07, 12.4).
+* and the rejections forward-match on replay.
 */
 async function runReserveSurvivesRunExhaustion() {
 	let phase = 0;
@@ -6647,7 +6640,7 @@ function planScenario() {
 	};
 }
 /**
-* kb-pin-replay (docs/09, 6.11): the pin at admission and the repin at
+* kb-pin-replay: the pin at admission and the repin at
 * the wake, card bytes embedded, model names withheld.
 */
 async function runKbPinReplay() {
@@ -6672,7 +6665,7 @@ async function runKbPinReplay() {
 	return normalizeAdaptiveJournal(entries);
 }
 /**
-* kb-repin-expiry (docs/09, 6.11): the repin re-applies the docs/05
+* kb-repin-expiry: the repin re-applies the claim
 * filters against a FRESH read; a claim the store dropped between the
 * pin and the wake stops steering, while the boot pin's bytes stand.
 */