@rulvar/plan 1.3.0 → 1.3.2

package/README.md

@@ -0,0 +1,32 @@
+# @rulvar/plan
+
+The adaptive orchestration extension for dynamic rulvar runs:
+`PlanRunner` treats the task plan as typed, engine-owned data with
+journaled revisions, reuse, escalations, and model ladders. Built
+entirely on the public core API. Exports `planRunner`,
+`orchestratePlanned`, and `buildPlanTools`.
+
+The one-line mnemonic against its sibling: `@rulvar/planner` plans
+before the run (it writes the script); `@rulvar/plan` replans during the
+run (it revises the task plan).
+
+Part of [rulvar](https://rulvar.com), an embeddable TypeScript engine
+for durable, budget-bounded multi-agent LLM workflows, where a completed
+LLM call is never paid for twice. Full documentation:
+[docs.rulvar.com](https://docs.rulvar.com).
+
+## Install
+
+```bash
+pnpm add @rulvar/core @rulvar/plan
+```
+
+## Documentation
+
+- [Adaptive orchestration](https://docs.rulvar.com/guide/adaptive-orchestration)
+- [Orchestration modes](https://docs.rulvar.com/guide/orchestration-modes)
+- [API reference](https://docs.rulvar.com/api/%40rulvar/plan/)
+
+## License
+
+[Apache-2.0](https://github.com/o-stepper/rulvar/blob/main/LICENSE)

package/dist/index.js

@@ -60,7 +60,7 @@ function isTerminalPlanStatus(status) {
 * (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: {
+	if (isTerminalPlanStatus(node.status)) throw new PlanInvariantError(`plan node ${node.nodeId} is terminal '${node.status}' and cannot become '${to}' (the status machine is closed and 'done' is immutable)`, { data: {
 		nodeId: node.nodeId,
 		from: node.status,
 		to
@@ -70,7 +70,7 @@ function assertPlanTransition(node, to) {
 		from: node.status,
 		to
 	} });
-	if (to === "running" && node.status !== "ready") throw new PlanInvariantError(`plan node ${node.nodeId} cannot start running from '${node.status}' (the engine schedules ready nodes only; docs/07, 3.1)`, { data: {
+	if (to === "running" && node.status !== "ready") throw new PlanInvariantError(`plan node ${node.nodeId} cannot start running from '${node.status}' (the engine schedules ready nodes only)`, { data: {
 		nodeId: node.nodeId,
 		from: node.status,
 		to
@@ -335,7 +335,7 @@ function effectiveDroppedStreak(state) {
 }
 function verifyHash(entry, which, expected, plan, deriverFor) {
 	const actual = planHash(plan, deriverFor?.(entry.hashVersion) ?? deriverV2);
-	if (actual !== expected) throw new ReplayPlanHashMismatch(`plan fold ${which} mismatch at seq ${String(entry.seq)}: recomputed ${actual}, entry carries ${expected} (hashVersion ${String(entry.hashVersion)}); the resume is rejected without corrupting the journal (docs/07, 3.4)`, { data: {
+	if (actual !== expected) throw new ReplayPlanHashMismatch(`plan fold ${which} mismatch at seq ${String(entry.seq)}: recomputed ${actual}, entry carries ${expected} (hashVersion ${String(entry.hashVersion)}); the resume is rejected without corrupting the journal`, { data: {
 		entryRef: entry.seq,
 		expected,
 		actual,
@@ -1267,11 +1267,11 @@ function boundLedgerRender(view, budgetChars = LEDGER_RENDER_BUDGET_CHARS) {
 			bounded[section].shift();
 			droppedRows += 1;
 		}
-		if (droppedRows > 0) bounded.discrepancies.push(`renderBudget: dropped the ${String(droppedRows)} oldest ${section} rows (docs/06, Appendix A)`);
+		if (droppedRows > 0) bounded.discrepancies.push(`renderBudget: dropped the ${String(droppedRows)} oldest ${section} rows `);
 		if (size(bounded) <= budgetChars) return bounded;
 	}
 	if (bounded.brief !== void 0 && size(bounded) > budgetChars) {
-		bounded.discrepancies.push("renderBudget: the mission brief was sliced (docs/06, Appendix A)");
+		bounded.discrepancies.push("renderBudget: the mission brief was sliced");
 		const over = size(bounded) - budgetChars;
 		const keep = Math.max(0, bounded.brief.text.length - over);
 		bounded.brief = {
@@ -2139,7 +2139,7 @@ function planRunner(options) {
 				logicalTaskId,
 				isNew: false
 			});
-			if (!debited.ok) throw new ConfigError("termination_exhausted: maxTotalSpawns reached at a reuse link (docs/07, 11.3)");
+			if (!debited.ok) throw new ConfigError("termination_exhausted: maxTotalSpawns reached at a reuse link");
 			decision = {
 				verdict: {
 					kind: "reuse_full",
@@ -2336,7 +2336,7 @@ function planRunner(options) {
 	* against the per-engine registry BEFORE paying for the attempt.
 	*/
 	const ladderDispatchFields = (node, spec, ladder) => {
-		for (const gate of ladder.acceptance ?? []) if (gate.kind === "mechanical" && io.gates[gate.profile] === void 0) throw new ConfigError(`mechanical gate profile '${gate.profile}' is not registered under defaults.gates (docs/07, section 10)`);
+		for (const gate of ladder.acceptance ?? []) if (gate.kind === "mechanical" && io.gates[gate.profile] === void 0) throw new ConfigError(`mechanical gate profile '${gate.profile}' is not registered under defaults.gates `);
 		const rungIndex = executingRungOf(ladder, clampStartTier(ladder, spec.model_hint?.startTier), requireAccount().rungIndexOf(node.logicalTaskId));
 		const rung = ladder.rungs[rungIndex];
 		if (rung === void 0) throw new ConfigError(`ladder rung ${String(rungIndex)} is undeclared`);
@@ -3178,10 +3178,10 @@ function planRunner(options) {
 				ledgerScope: rootScope,
 				planScope
 			}), op);
-			if (violation !== void 0) throw new ConfigError(`ledger_append rejected: ${violation} (docs/06, Appendix A)`);
+			if (violation !== void 0) throw new ConfigError(`ledger_append rejected: ${violation}`);
 			if (op.op === "lesson_add") {
 				const stats = io.admission.lineage()?.statsOf(op.key.logicalTaskId);
-				if (!(stats !== void 0 && stats.attemptsUsed > 0 && stats.approaches.some((approach) => approach.approachSig === op.key.approachSig))) throw new ConfigError("lesson_add rejected: the key matches no journaled attempt of that logical task (docs/07, 9.2)");
+				if (!(stats !== void 0 && stats.attemptsUsed > 0 && stats.approaches.some((approach) => approach.approachSig === op.key.approachSig))) throw new ConfigError("lesson_add rejected: the key matches no journaled attempt of that logical task ");
 			}
 			const entry = await io.append({
 				scope: rootScope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/plan",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "rulvar adaptive orchestration extension: PlanRunner, RunLedger, escalation extensions, ModelLadder configuration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.3.0"
+    "@rulvar/core": "1.3.2"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-sqlite": "1.3.0"
+    "@rulvar/store-sqlite": "1.3.2"
   },
   "repository": {
     "type": "git",