@rulvar/planner 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/compile-CfWgGVyz.js

@@ -0,0 +1,204 @@
+import { ScriptRejected } from "@rulvar/core";
+//#region src/compile.ts
+/**
+* The exact curated sandbox global set, in docs order (docs/06, 8.2).
+* The worker binds the ctx methods as bare globals under these names and
+* the API card teaches exactly this list.
+*/
+const SANDBOX_GLOBALS = [
+	"agent",
+	"parallel",
+	"pipeline",
+	"step",
+	"phase",
+	"log",
+	"budget",
+	"workflow",
+	"awaitExternal",
+	"now",
+	"random",
+	"uuid"
+];
+/** Marker reaching the AsyncFunction constructor; never invoked. */
+const asyncMarker = async () => void 0;
+/** The async-function constructor; building one compiles without running. */
+const AsyncFunctionCtor = Object.getPrototypeOf(asyncMarker).constructor;
+/**
+* Replaces string literals (single, double, template) and comments with
+* spaces of equal length so token scans never match inside them. Template
+* interpolations `${...}` are KEPT as code (a disallowed import inside an
+* interpolation must still be caught). Regex literals are not stripped:
+* a regex containing a banned word may false-positive, which errs on the
+* rejecting side for machine-generated source.
+*/
+function blankLiterals(source) {
+	const out = source.split("");
+	const blank = (index) => {
+		if (out[index] !== "\n") out[index] = " ";
+	};
+	const templateStack = [];
+	let i = 0;
+	let mode = "code";
+	while (i < source.length) {
+		const ch = source[i];
+		const next = source[i + 1];
+		if (mode === "code") {
+			if (ch === "'") {
+				mode = "single";
+				blank(i);
+			} else if (ch === "\"") {
+				mode = "double";
+				blank(i);
+			} else if (ch === "`") {
+				mode = "template";
+				blank(i);
+			} else if (ch === "/" && next === "/") {
+				mode = "line";
+				blank(i);
+			} else if (ch === "/" && next === "*") {
+				mode = "block";
+				blank(i);
+			} else if (ch === "}" && templateStack.length > 0) {
+				templateStack.pop();
+				mode = "template";
+				blank(i);
+			}
+		} else if (mode === "single" || mode === "double") {
+			if (ch === "\\") {
+				blank(i);
+				i += 1;
+				if (i < source.length) blank(i);
+				i += 1;
+				continue;
+			}
+			if (mode === "single" && ch === "'" || mode === "double" && ch === "\"") mode = "code";
+			blank(i);
+		} else if (mode === "template") {
+			if (ch === "\\") {
+				blank(i);
+				i += 1;
+				if (i < source.length) blank(i);
+				i += 1;
+				continue;
+			}
+			if (ch === "$" && next === "{") {
+				templateStack.push(true);
+				blank(i);
+				i += 1;
+				blank(i);
+				i += 1;
+				mode = "code";
+				continue;
+			}
+			if (ch === "`") mode = "code";
+			blank(i);
+		} else if (mode === "line") if (ch === "\n") mode = "code";
+		else blank(i);
+		else {
+			if (ch === "*" && next === "/") {
+				blank(i);
+				i += 1;
+				blank(i);
+				mode = "code";
+				i += 1;
+				continue;
+			}
+			blank(i);
+		}
+		i += 1;
+	}
+	return out.join("");
+}
+function positionAt(source, index) {
+	let line = 1;
+	let column = 1;
+	for (let i = 0; i < index && i < source.length; i += 1) if (source[i] === "\n") {
+		line += 1;
+		column = 1;
+	} else column += 1;
+	return {
+		line,
+		column
+	};
+}
+const DYNAMIC_IMPORT = /^import\s*\(\s*(['"`])([^'"`]*)\1\s*\)/;
+function scanImports(source, blanked, allowImports) {
+	const diagnostics = [];
+	const word = /\b(import|require|export)\b/g;
+	for (let match = word.exec(blanked); match !== null; match = word.exec(blanked)) {
+		const token = match[1];
+		const at = positionAt(source, match.index);
+		if (token === "require") {
+			const tail = blanked.slice(match.index + token.length);
+			if (/^\s*\(/.test(tail)) diagnostics.push({
+				ruleId: "no-require",
+				message: "require() is not available in the sandbox; the dialect has no module access",
+				...at
+			});
+			continue;
+		}
+		if (token === "export") {
+			diagnostics.push({
+				ruleId: "no-export",
+				message: "export declarations are not part of the sandbox dialect; return a value instead",
+				...at
+			});
+			continue;
+		}
+		const original = source.slice(match.index);
+		const dynamic = DYNAMIC_IMPORT.exec(original);
+		if (dynamic === null) {
+			diagnostics.push({
+				ruleId: "no-import",
+				message: "import is not available in the sandbox dialect (static imports, import.meta, and non-literal dynamic specifiers are always rejected)",
+				...at
+			});
+			continue;
+		}
+		const specifier = dynamic[2];
+		if (!allowImports.includes(specifier)) diagnostics.push({
+			ruleId: "disallowed-import",
+			message: `import('${specifier}') is not in allowImports (allowed: ${allowImports.length === 0 ? "none" : allowImports.join(", ")})`,
+			...at
+		});
+	}
+	return diagnostics;
+}
+/**
+* Validates and compiles planner-generated source into a CompiledWorkflow
+* (docs/06, 8.3). The source is an async function body over the sandbox
+* globals; its `return` value is the workflow result. The compiled form is
+* pure data (the source is evaluated only inside the worker sandbox);
+* machine scripts run under errorPolicy 'lenient' (docs/06, Appendix A).
+*/
+function compileScript(source, o) {
+	const allowImports = o?.allowImports ?? [];
+	const diagnostics = [];
+	if (typeof source !== "string" || source.trim() === "") throw new ScriptRejected("compileScript: source must be a non-empty string", { data: { diagnostics: [{
+		ruleId: "empty-source",
+		message: "source is empty"
+	}] } });
+	const blanked = blankLiterals(source);
+	diagnostics.push(...scanImports(source, blanked, allowImports));
+	try {
+		new AsyncFunctionCtor(...SANDBOX_GLOBALS, source);
+	} catch (error) {
+		diagnostics.push({
+			ruleId: "syntax",
+			message: error instanceof Error ? error.message : String(error)
+		});
+	}
+	if (diagnostics.length > 0) throw new ScriptRejected(`compileScript: source rejected with ${String(diagnostics.length)} diagnostic(s): ` + diagnostics.map((d) => d.ruleId).join(", "), { data: { diagnostics: diagnostics.map((d) => ({ ...d })) } });
+	return {
+		kind: "compiled-workflow",
+		name: "compiled",
+		source,
+		errorPolicy: "lenient"
+	};
+}
+/** Typed accessor for the diagnostics carried on a ScriptRejected. */
+function scriptDiagnosticsOf(error) {
+	return error.data?.diagnostics ?? [];
+}
+//#endregion
+export { compileScript as n, scriptDiagnosticsOf as r, SANDBOX_GLOBALS as t };

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+import { CompiledWorkflow, Ctx, Engine, InMemoryStore, JournalEntry, Json, ModelSpec, RunHandle, ScriptRejected, ScriptRunner } from "@rulvar/core";
+
+//#region src/compile.d.ts
+/**
+* The exact curated sandbox global set, in docs order (docs/06, 8.2).
+* The worker binds the ctx methods as bare globals under these names and
+* the API card teaches exactly this list.
+*/
+declare const SANDBOX_GLOBALS: readonly string[];
+/** One machine-readable compileScript diagnostic (docs/02, ScriptRejected row). */
+interface ScriptDiagnostic {
+  ruleId: string;
+  message: string;
+  line?: number;
+  column?: number;
+}
+interface CompileScriptOptions {
+  /** Dynamic-import specifiers permitted in the source; default [] (none). */
+  allowImports?: string[];
+}
+/**
+* Validates and compiles planner-generated source into a CompiledWorkflow
+* (docs/06, 8.3). The source is an async function body over the sandbox
+* globals; its `return` value is the workflow result. The compiled form is
+* pure data (the source is evaluated only inside the worker sandbox);
+* machine scripts run under errorPolicy 'lenient' (docs/06, Appendix A).
+*/
+declare function compileScript(source: string, o?: CompileScriptOptions): CompiledWorkflow;
+/** Typed accessor for the diagnostics carried on a ScriptRejected. */
+declare function scriptDiagnosticsOf(error: ScriptRejected): ScriptDiagnostic[];
+//#endregion
+//#region src/api-card.d.ts
+/** Renders the sandbox-dialect API card; pure and byte-stable. */
+declare function apiCard(): string;
+//#endregion
+//#region src/plan.d.ts
+/** One repair-loop diagnostic: lint and compile findings share the shape. */
+interface PlanDiagnostic {
+  ruleId: string;
+  message: string;
+  line?: number;
+  column?: number;
+  severity: "error" | "warning";
+}
+interface PlanOptions {
+  /** The planner model; otherwise the chain resolves role 'plan'. */
+  model?: ModelSpec;
+  /** Registered profile names to advertise; default: every profile. */
+  profiles?: string[];
+  /** Self-repair rounds from JSON diagnostics; default 3 (Appendix A). */
+  repairRounds?: number;
+}
+interface PlanResult {
+  source: string;
+  workflow: CompiledWorkflow;
+  /** Diagnostics of the ACCEPTED draft: advisories only, never errors. */
+  lint: PlanDiagnostic[];
+}
+/** The deterministic planner runId: one goal, one journal (docs/06, 9.2). */
+declare function planRunIdOf(goal: string): string;
+/**
+* The model may fence the script; the extractor takes the first fenced
+* block when one exists, else the whole reply, and is deterministic.
+*/
+declare function extractScript(reply: string): string;
+/**
+* Lints a script BODY with the workflows preset plus compileScript.
+* The body is wrapped in an async function for parsing (top-level
+* return/await are legal in the dialect); reported lines shift back so
+* they index into the body source.
+*/
+declare function lintScript(source: string): {
+  diagnostics: PlanDiagnostic[];
+  errors: PlanDiagnostic[];
+  workflow?: CompiledWorkflow;
+};
+declare function plan(engine: Engine, goal: string, o?: PlanOptions): Promise<PlanResult>;
+/**
+* plan-then-run in one call (docs/06, section 9; amended during M6-T05:
+* the composition is async because planning itself is a run).
+*/
+declare function runPlanned(engine: Engine, goal: string, args?: Json): Promise<RunHandle<unknown>>;
+//#endregion
+//#region src/cassettes.d.ts
+/** The M3-convention cassette normalization: wall clock and spans only. */
+declare function normalizeCassetteEntries(entries: readonly JournalEntry[]): JournalEntry[];
+declare const SANDBOX_DETERMINISM_RUN_ID = "m6-sandbox-determinism";
+/** A script exercising agents, parallel, step, and every seeded shim. */
+declare const SANDBOX_DETERMINISM_SOURCE: string;
+/**
+* One fresh sandbox-determinism run on a fresh store; two invocations
+* with the same worker produce byte-identical normalized journals (the
+* cassette assertion). The adapter factory keeps @rulvar/testing out of
+* the planner's dependency graph.
+*/
+declare function runSandboxDeterminism(options: {
+  workerUrl: URL;
+  makeAdapter: () => unknown;
+  modelRef: string;
+}): Promise<JournalEntry[]>;
+declare const SELF_REPAIR_GOAL = "m6 cassette: summarize the corpus";
+/** The failing first draft: bare Date.now trips rulvar/no-bare-date. */
+declare const SELF_REPAIR_BAD_DRAFT: string;
+/** The repaired draft the fake planner returns once diagnostics arrive. */
+declare const SELF_REPAIR_GOOD_DRAFT: string;
+declare const SELF_REPAIR_RUN_ID: string;
+/**
+* One planner-self-repair run: the first draft fails lint, the JSON
+* diagnostics ride the repair prompt, the second draft compiles. Returns
+* the normalized planning journal plus the plan result.
+*/
+declare function runPlannerSelfRepair(options: {
+  makeAdapter: () => unknown;
+  modelRef: string;
+  store?: InMemoryStore;
+  seedEntries?: JournalEntry[];
+}): Promise<{
+  entries: JournalEntry[];
+  planned: PlanResult;
+  engine: Engine;
+}>;
+/** The cassette file shape shared with the M3 sets. */
+interface M6CassetteFixture {
+  id: string;
+  note: string;
+  entries: JournalEntry[];
+  extra?: Json;
+}
+//#endregion
+//#region src/sandbox-runner.d.ts
+declare const DEFAULT_SANDBOX_TIMEOUT_MS = 3e5;
+declare const DEFAULT_SANDBOX_MEMORY_MB = 512;
+interface WorkerSandboxRunnerOptions {
+  /** Wall-clock ceiling for one execution; default 300000 (Appendix A). */
+  timeoutMs?: number;
+  /** Worker old-generation heap ceiling; default 512 (Appendix A). */
+  memoryMb?: number;
+  /**
+  * The worker entry module; defaults to the built sandbox-worker.js next
+  * to this module. Tests running from source point at the built dist.
+  */
+  workerUrl?: URL;
+}
+/** Accepts CompiledWorkflow ONLY: feeding a closure is a type error (docs/06, 8). */
+declare class WorkerSandboxRunner implements ScriptRunner {
+  private readonly timeoutMs;
+  private readonly memoryMb;
+  private readonly workerUrl;
+  constructor(options?: WorkerSandboxRunnerOptions);
+  execute<A, R>(wf: CompiledWorkflow, ctx: Ctx<never>, args: A): Promise<R>;
+}
+//#endregion
+export { type CompileScriptOptions, DEFAULT_SANDBOX_MEMORY_MB, DEFAULT_SANDBOX_TIMEOUT_MS, type M6CassetteFixture, type PlanDiagnostic, type PlanOptions, type PlanResult, SANDBOX_DETERMINISM_RUN_ID, SANDBOX_DETERMINISM_SOURCE, SANDBOX_GLOBALS, SELF_REPAIR_BAD_DRAFT, SELF_REPAIR_GOAL, SELF_REPAIR_GOOD_DRAFT, SELF_REPAIR_RUN_ID, type ScriptDiagnostic, WorkerSandboxRunner, type WorkerSandboxRunnerOptions, apiCard, compileScript, extractScript, lintScript, normalizeCassetteEntries, plan, planRunIdOf, runPlanned, runPlannerSelfRepair, runSandboxDeterminism, scriptDiagnosticsOf };

package/dist/index.js

@@ -0,0 +1,398 @@
+import { n as compileScript, r as scriptDiagnosticsOf, t as SANDBOX_GLOBALS } from "./compile-CfWgGVyz.js";
+import { ConfigError, InMemoryStore, SandboxError, ScriptRejected, createEngine, createSandboxBridge, defineWorkflow, toJournalValue } from "@rulvar/core";
+import { createHash } from "node:crypto";
+import { Linter } from "eslint";
+import { toJsonDiagnostics, workflowsConfig } from "eslint-plugin-rulvar";
+import { MessageChannel, Worker } from "node:worker_threads";
+//#region src/api-card.ts
+/**
+* The API card (M6-T04): teaches the planner model EXACTLY the sandbox
+* dialect and global set (docs/06, sections 8.2 and 8.3). The card is a
+* pure constant, byte-stable across runs; plan() (M6-T05) composes it
+* with profileCard(registry) and the goal. The usage examples are
+* distilled from the runnable examples/ corpus (M5-T09).
+*/
+const CARD = [
+	"You write ONE JavaScript async-function BODY (the workflow script).",
+	"It runs in a deterministic sandbox. The `return` value is the workflow result.",
+	"",
+	"Available globals (the COMPLETE list; nothing else exists):",
+	"- agent(prompt, opts?) -> Promise<value>: one subagent call.",
+	"  opts (JSON only): { agentType?, model?, effort?, schema?, tools?, onError?, label?, key?, estCost?, limits?, escalation?, fallback?, result? }",
+	"  - schema: a JSON Schema LITERAL (never a library value); the result is the validated object.",
+	"  - tools: an array of registered profile NAMES (strings only).",
+	"  - onError: 'throw' | 'null' (default 'null'; a failed call yields null and the loss is recorded).",
+	"  - model: a string; agentType: a registered profile name from the profile card.",
+	"- parallel(fns, opts?) -> Promise<values[]>: concurrent branches; fns is an array of async functions.",
+	"  opts: { settle?: true } returns settled outcomes instead of throwing on the first failure.",
+	"- pipeline(items, ...stageFns, opts?) -> Promise<results[]>: streams items through stages.",
+	"  opts: { onItemError?: 'drop' | 'throw' | 'collect' } (default 'drop').",
+	"- step(label, fn, opts?) -> Promise<json>: journals a computation so it never re-runs on resume.",
+	"  opts: { deps?: json[], key?: string }. fn must return JSON.",
+	"- phase(name, fn) -> Promise<value>: cosmetic grouping for progress and cost reports.",
+	"- log(level, msg, data?): telemetry; level is 'debug' | 'info' | 'warn' | 'error'.",
+	"- budget.spent() and budget.remaining(): ASYNC here; always `await budget.spent()`.",
+	"- workflow(name, args?, opts?) -> Promise<value>: runs a REGISTERED child workflow by name.",
+	"- awaitExternal(key, opts?) -> Promise<value>: suspends until an operator provides the value.",
+	"  opts: { schema?, prompt? }.",
+	"- now() -> number, random(key?) -> number, uuid() -> string: deterministic seeded shims.",
+	"",
+	"Hard rules:",
+	"- No import, require, or export. No fetch. No process. No Node APIs.",
+	"- Date.now() and Math.random() ARE the seeded shims; still prefer now() and random().",
+	"- Never put functions inside option objects; options are pure JSON.",
+	"- Policies are declarative JSON rule tables; ladders are JSON.",
+	"- Identical calls with identical arguments journal as ONE result; pass { key } to repeat deliberately.",
+	"",
+	"Patterns (from the runnable corpus):",
+	"- Adversarial panel:",
+	"  const votes = await parallel([() => agent('refute: ' + claim), () => agent('refute: ' + claim, { key: 'second-skeptic' })]);",
+	"- Judge over drafts:",
+	"  const drafts = await parallel(angles.map((a) => () => agent('draft from angle ' + a)));",
+	"  const winner = await agent('pick the best draft: ' + JSON.stringify(drafts), { schema: { type: 'object', properties: { index: { type: 'integer' } }, required: ['index'], additionalProperties: false } });",
+	"- Fold results without re-paying:",
+	"  const digest = await step('fold', () => drafts.join(' | '));"
+].join("\n");
+/** Renders the sandbox-dialect API card; pure and byte-stable. */
+function apiCard() {
+	return CARD;
+}
+//#endregion
+//#region src/plan.ts
+/**
+* The plan agent and the self-repair loop (M6-T05): mode (b), the
+* flagship hybrid (docs/06, section 9.2). plan() asks a planner model
+* (role 'plan') to write a script against the API card and the profile
+* card, lints it with eslint-plugin-rulvar, self-repairs up to
+* repairRounds rounds from the JSON diagnostics, and compiles the
+* accepted draft with compileScript. runPlanned composes plan-then-run.
+*
+* Determinism: the planner conversation itself is an ordinary journaled
+* run whose runId derives from the goal, so re-planning the same goal
+* against the same store REPLAYS the unchanged prefix for free
+* (invariant I1; the M6-T05 acceptance).
+*/
+/** The deterministic planner runId: one goal, one journal (docs/06, 9.2). */
+function planRunIdOf(goal) {
+	return `plan-${createHash("sha256").update(goal, "utf8").digest("hex").slice(0, 24)}`;
+}
+/**
+* The model may fence the script; the extractor takes the first fenced
+* block when one exists, else the whole reply, and is deterministic.
+*/
+function extractScript(reply) {
+	return (/```(?:[a-zA-Z]*)?\n([\s\S]*?)```/.exec(reply)?.[1] ?? reply).trim();
+}
+/**
+* Lints a script BODY with the workflows preset plus compileScript.
+* The body is wrapped in an async function for parsing (top-level
+* return/await are legal in the dialect); reported lines shift back so
+* they index into the body source.
+*/
+function lintScript(source) {
+	const diagnostics = [];
+	const linter = new Linter();
+	const wrapped = `async function rulvarWorkflowBody() {\n${source}\n}\n`;
+	const messages = linter.verify(wrapped, [{ languageOptions: {
+		ecmaVersion: 2024,
+		sourceType: "module"
+	} }, workflowsConfig], { filename: "workflow-body.js" });
+	for (const lint of toJsonDiagnostics(messages)) {
+		const diagnostic = {
+			ruleId: lint.ruleId,
+			message: lint.message,
+			severity: lint.severity,
+			line: Math.max(1, lint.line - 1),
+			column: lint.column
+		};
+		diagnostics.push(diagnostic);
+	}
+	let workflow;
+	try {
+		workflow = compileScript(source);
+	} catch (error) {
+		if (!(error instanceof ScriptRejected)) throw error;
+		for (const rejection of scriptDiagnosticsOf(error)) diagnostics.push({
+			ruleId: `compile/${rejection.ruleId}`,
+			message: rejection.message,
+			severity: "error",
+			...rejection.line === void 0 ? {} : { line: rejection.line },
+			...rejection.column === void 0 ? {} : { column: rejection.column }
+		});
+	}
+	const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+	const result = {
+		diagnostics,
+		errors
+	};
+	if (errors.length === 0 && workflow !== void 0) result.workflow = workflow;
+	return result;
+}
+function draftPrompt(goal, cards) {
+	return [
+		"Write the workflow script body for this goal.",
+		"",
+		`GOAL: ${goal}`,
+		"",
+		cards,
+		"",
+		"Reply with ONLY the script body (a fenced code block is accepted)."
+	].join("\n");
+}
+function repairPrompt(goal, source, diagnostics) {
+	return [
+		"Your previous workflow script was rejected by the linter.",
+		"",
+		`GOAL: ${goal}`,
+		"",
+		"PREVIOUS SCRIPT:",
+		source,
+		"",
+		"DIAGNOSTICS (JSON):",
+		JSON.stringify(diagnostics, null, 2),
+		"",
+		"Fix every error and reply with ONLY the corrected script body."
+	].join("\n");
+}
+/** The planner conversation as an ordinary journaled workflow. */
+const planWorkflow = defineWorkflow({ name: "rulvar-plan" }, async (ctx, args) => {
+	let source = "";
+	let lastDiagnostics = [];
+	for (let round = 0; round <= args.repairRounds; round += 1) {
+		const prompt = round === 0 ? draftPrompt(args.goal, args.cards) : repairPrompt(args.goal, source, lastDiagnostics);
+		const reply = await ctx.agent(prompt, {
+			role: "plan",
+			onError: "throw",
+			...args.model === void 0 ? {} : { model: args.model }
+		});
+		source = extractScript(String(reply));
+		const outcome = lintScript(source);
+		if (outcome.errors.length === 0) return {
+			source,
+			lint: outcome.diagnostics,
+			rounds: round + 1
+		};
+		lastDiagnostics = outcome.diagnostics;
+	}
+	throw new ScriptRejected(`plan: self-repair exhausted after ${String(args.repairRounds + 1)} drafts; the last diagnostics ride in data`, { data: { diagnostics: lastDiagnostics.map((d) => ({ ...d })) } });
+});
+async function plan(engine, goal, o) {
+	const repairRounds = o?.repairRounds ?? 3;
+	const args = {
+		goal,
+		cards: [
+			apiCard(),
+			"",
+			engine.profileCard(o?.profiles)
+		].join("\n"),
+		repairRounds,
+		...o?.model === void 0 ? {} : { model: o.model }
+	};
+	const outcome = await engine.resume(planRunIdOf(goal), planWorkflow, { args }).result;
+	if (outcome.status !== "ok" || outcome.value === void 0) {
+		const wire = outcome.error;
+		throw new ScriptRejected(`plan: the planner run settled '${outcome.status}'${wire === void 0 ? "" : `: ${wire.message}`}`, { data: {
+			status: outcome.status,
+			...wire === void 0 ? {} : { error: wire }
+		} });
+	}
+	const value = outcome.value;
+	const workflow = compileScript(value.source);
+	return {
+		source: value.source,
+		workflow,
+		lint: value.lint
+	};
+}
+/**
+* plan-then-run in one call (docs/06, section 9; amended during M6-T05:
+* the composition is async because planning itself is a run).
+*/
+async function runPlanned(engine, goal, args) {
+	const planned = await plan(engine, goal);
+	return engine.run(planned.workflow, args ?? null);
+}
+//#endregion
+//#region src/sandbox-runner.ts
+/**
+* WorkerSandboxRunner (M6-T02): the mandatory runner for machine-generated
+* scripts, mode (b). Owns the worker lifecycle and the dedicated
+* MessageChannel; every primitive call is served by the core sandbox
+* bridge against the canonical run ctx (docs/06, 8.2).
+*
+* Port lifecycle: one channel per run; the worker end rides the init
+* transfer list; the host end is referenced while the worker computes and
+* unreferenced while every worker frame is blocked on a host call, so a
+* suspended run lets the process exit (docs/06, 2.7) and a computing
+* worker keeps it alive. Breaching timeoutMs or memoryMb terminates the
+* worker and the run completes with outcome 'error' carrying the typed
+* SandboxError (docs/02, error taxonomy).
+*/
+const DEFAULT_SANDBOX_TIMEOUT_MS = 3e5;
+const DEFAULT_SANDBOX_MEMORY_MB = 512;
+/** Accepts CompiledWorkflow ONLY: feeding a closure is a type error (docs/06, 8). */
+var WorkerSandboxRunner = class {
+	timeoutMs;
+	memoryMb;
+	workerUrl;
+	constructor(options) {
+		this.timeoutMs = options?.timeoutMs ?? 3e5;
+		this.memoryMb = options?.memoryMb ?? 512;
+		this.workerUrl = options?.workerUrl ?? new URL("./sandbox-worker.js", import.meta.url);
+	}
+	async execute(wf, ctx, args) {
+		if (wf.kind !== "compiled-workflow") throw new ConfigError("WorkerSandboxRunner executes CompiledWorkflow values only; closures run in process (docs/06, section \"Script runners\")");
+		const argsJson = toJournalValue(args ?? null, "sandbox workflow args");
+		const channel = new MessageChannel();
+		const worker = new Worker(this.workerUrl, { resourceLimits: { maxOldGenerationSizeMb: this.memoryMb } });
+		const bridge = createSandboxBridge(ctx, { post: (message) => channel.port1.postMessage(message) });
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			const cleanup = () => {
+				clearTimeout(timer);
+				bridge.close();
+				channel.port1.close();
+				worker.terminate();
+			};
+			const settleOk = (value) => {
+				if (!settled) {
+					settled = true;
+					cleanup();
+					resolve(value);
+				}
+			};
+			const settleErr = (error) => {
+				if (!settled) {
+					settled = true;
+					cleanup();
+					reject(error);
+				}
+			};
+			const timer = setTimeout(() => {
+				settleErr(new SandboxError(`sandbox timeoutMs ${String(this.timeoutMs)} breached; the worker was terminated`, { data: {
+					reason: "timeout",
+					limit: this.timeoutMs
+				} }));
+			}, this.timeoutMs);
+			channel.port1.on("message", (message) => {
+				if (message.t === "done") {
+					settleOk(message.value);
+					return;
+				}
+				if (message.t === "fail") {
+					const wire = message.error;
+					const rebuilt = new Error(wire.message);
+					rebuilt.name = wire.code;
+					settleErr(rebuilt);
+					return;
+				}
+				if (message.t === "state") if (message.busy === true) channel.port1.ref();
+				else channel.port1.unref();
+				bridge.onMessage(message);
+			});
+			worker.on("error", (error) => {
+				if (error.code === "ERR_WORKER_OUT_OF_MEMORY") {
+					settleErr(new SandboxError(`sandbox memoryMb ${String(this.memoryMb)} breached; the worker was terminated`, { data: {
+						reason: "memory",
+						limit: this.memoryMb
+					} }));
+					return;
+				}
+				settleErr(error);
+			});
+			worker.on("exit", (code) => {
+				if (!settled) settleErr(new ConfigError(`sandbox worker exited unexpectedly with code ${String(code)}`));
+			});
+			worker.unref();
+			worker.postMessage({
+				t: "init",
+				port: channel.port2,
+				source: wf.source,
+				args: argsJson,
+				runId: bridge.runId
+			}, [channel.port2]);
+		});
+	}
+};
+//#endregion
+//#region src/cassettes.ts
+/** The M3-convention cassette normalization: wall clock and spans only. */
+function normalizeCassetteEntries(entries) {
+	return entries.map((entry) => ({
+		...entry,
+		spanId: "fixture-span",
+		startedAt: "2026-02-01T00:00:00.000Z",
+		...entry.endedAt === void 0 ? {} : { endedAt: "2026-02-01T00:00:00.000Z" }
+	}));
+}
+const SANDBOX_DETERMINISM_RUN_ID = "m6-sandbox-determinism";
+/** A script exercising agents, parallel, step, and every seeded shim. */
+const SANDBOX_DETERMINISM_SOURCE = [
+	"const first = await agent('probe alpha');",
+	"const both = await parallel([() => agent('branch zero'), () => agent('branch one')]);",
+	"const folded = await step('fold', () => [first, ...both].join(' | '), { deps: [now()] });",
+	"log('info', 'progress ' + random());",
+	"return { folded, id: uuid(), at: now() };"
+].join("\n");
+/**
+* One fresh sandbox-determinism run on a fresh store; two invocations
+* with the same worker produce byte-identical normalized journals (the
+* cassette assertion). The adapter factory keeps @rulvar/testing out of
+* the planner's dependency graph.
+*/
+async function runSandboxDeterminism(options) {
+	const store = new InMemoryStore();
+	const engine = createEngine({
+		adapters: [options.makeAdapter()],
+		stores: { journal: store },
+		defaults: { routing: {
+			loop: options.modelRef,
+			extract: options.modelRef
+		} },
+		runners: { sandbox: new WorkerSandboxRunner({ workerUrl: options.workerUrl }) }
+	});
+	const workflow = compileScript(SANDBOX_DETERMINISM_SOURCE);
+	const outcome = await engine.run(workflow, null, { runId: SANDBOX_DETERMINISM_RUN_ID }).result;
+	if (outcome.status !== "ok") throw new Error(`sandbox-determinism run settled '${outcome.status}'`);
+	return normalizeCassetteEntries(await store.load(SANDBOX_DETERMINISM_RUN_ID));
+}
+const SELF_REPAIR_GOAL = "m6 cassette: summarize the corpus";
+/** The failing first draft: bare Date.now trips rulvar/no-bare-date. */
+const SELF_REPAIR_BAD_DRAFT = [
+	"```js",
+	"const startedAt = Date.now();",
+	"const summary = await agent('summarize the corpus');",
+	"return { startedAt, summary };",
+	"```"
+].join("\n");
+/** The repaired draft the fake planner returns once diagnostics arrive. */
+const SELF_REPAIR_GOOD_DRAFT = [
+	"```js",
+	"const startedAt = now();",
+	"const summary = await agent('summarize the corpus');",
+	"return { startedAt, summary };",
+	"```"
+].join("\n");
+const SELF_REPAIR_RUN_ID = planRunIdOf(SELF_REPAIR_GOAL);
+/**
+* One planner-self-repair run: the first draft fails lint, the JSON
+* diagnostics ride the repair prompt, the second draft compiles. Returns
+* the normalized planning journal plus the plan result.
+*/
+async function runPlannerSelfRepair(options) {
+	const store = options.store ?? new InMemoryStore();
+	if (options.seedEntries !== void 0) for (const entry of options.seedEntries) await store.append(SELF_REPAIR_RUN_ID, entry);
+	const engine = createEngine({
+		adapters: [options.makeAdapter()],
+		stores: { journal: store },
+		defaults: { routing: { plan: options.modelRef } }
+	});
+	const planned = await plan(engine, SELF_REPAIR_GOAL);
+	return {
+		entries: normalizeCassetteEntries(await store.load(SELF_REPAIR_RUN_ID)),
+		planned,
+		engine
+	};
+}
+//#endregion
+export { DEFAULT_SANDBOX_MEMORY_MB, DEFAULT_SANDBOX_TIMEOUT_MS, SANDBOX_DETERMINISM_RUN_ID, SANDBOX_DETERMINISM_SOURCE, SANDBOX_GLOBALS, SELF_REPAIR_BAD_DRAFT, SELF_REPAIR_GOAL, SELF_REPAIR_GOOD_DRAFT, SELF_REPAIR_RUN_ID, WorkerSandboxRunner, apiCard, compileScript, extractScript, lintScript, normalizeCassetteEntries, plan, planRunIdOf, runPlanned, runPlannerSelfRepair, runSandboxDeterminism, scriptDiagnosticsOf };

package/dist/sandbox-worker.d.ts

@@ -0,0 +1,21 @@
+import { Json, WireError } from "@rulvar/core";
+
+//#region src/sandbox-worker.d.ts
+/** Runner-to-worker bootstrap message; the port rides the transfer list. */
+interface SandboxInitMessage {
+  t: "init";
+  port: unknown;
+  source: string;
+  args: Json;
+  runId: string;
+}
+/** Worker lifecycle messages the RUNNER consumes (the bridge never sees them). */
+type SandboxLifecycleMessage = {
+  t: "done";
+  value: Json;
+} | {
+  t: "fail";
+  error: WireError;
+};
+//#endregion
+export { SandboxInitMessage, SandboxLifecycleMessage };

package/dist/sandbox-worker.js

@@ -0,0 +1,295 @@
+import { t as SANDBOX_GLOBALS } from "./compile-CfWgGVyz.js";
+import { NonSerializableValueError, toJournalValue } from "@rulvar/core";
+import { createHash } from "node:crypto";
+import { parentPort } from "node:worker_threads";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/sandbox-worker.ts
+/**
+* The worker half of the sandbox contract (M6-T02): evaluates a
+* CompiledWorkflow source inside a worker_threads realm with the curated
+* global scope and proxies every primitive call as JSON-RPC over the
+* dedicated MessagePort to the host bridge (docs/06, 8.2).
+*
+* Determinism: now, random, uuid, and the Date.now/Math.random realm
+* replacements all draw from ONE seeded stream (seed = sha256(runId)), so
+* two runs with the same runId generate identical values; every generated
+* value is mirrored to the host and journaled as an ordinary kind 'rand'
+* entry (match-first on resume). import, fetch, and process are absent
+* from the scope; values crossing the boundary are validated
+* journal-compatible JSON, never raw structured clone.
+*/
+function wireOf(thrown) {
+	if (thrown instanceof NonSerializableValueError) return thrown.toWire();
+	if (thrown instanceof Error) return {
+		code: thrown.name !== "" && thrown.name !== "Error" ? thrown.name : "error",
+		message: thrown.message,
+		retryable: false
+	};
+	return {
+		code: "error",
+		message: String(thrown),
+		retryable: false
+	};
+}
+/** mulberry32 over the first four bytes of sha256(runId). */
+function seededStream(runId) {
+	const digest = createHash("sha256").update(runId, "utf8").digest();
+	let state = digest.readUInt32LE(0) ^ digest.readUInt32LE(4);
+	return () => {
+		state = state + 1831565813 | 0;
+		let t = state;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+function main(port, init) {
+	const next = seededStream(init.runId);
+	let logicalNow = 17e11 + Math.floor(next() * 1e9);
+	const frameToken = new AsyncLocalStorage();
+	const currentToken = () => frameToken.getStore() ?? 0;
+	let busyFrames = 0;
+	let lastReportedBusy;
+	const reportState = () => {
+		const busy = busyFrames > 0;
+		if (busy !== lastReportedBusy) {
+			lastReportedBusy = busy;
+			post({
+				t: "state",
+				busy
+			});
+		}
+	};
+	const enterFrame = () => {
+		busyFrames += 1;
+		reportState();
+	};
+	const exitFrame = () => {
+		busyFrames -= 1;
+		reportState();
+	};
+	function post(message) {
+		port.postMessage(message);
+	}
+	let nextCallId = 1;
+	const pendingCalls = /* @__PURE__ */ new Map();
+	function callHost(method, params) {
+		const validated = toJournalValue(params, `sandbox ${method} params`);
+		const id = nextCallId;
+		nextCallId += 1;
+		const token = currentToken();
+		return new Promise((resolve, reject) => {
+			pendingCalls.set(id, {
+				resolve,
+				reject
+			});
+			exitFrame();
+			post({
+				t: "call",
+				id,
+				token,
+				method,
+				params: validated
+			});
+		});
+	}
+	let nextFnId = 1;
+	const fns = /* @__PURE__ */ new Map();
+	const registerFns = (candidates, what) => candidates.map((candidate) => {
+		if (typeof candidate !== "function") throw new TypeError(`${what} accepts functions only`);
+		const fnId = nextFnId;
+		nextFnId += 1;
+		fns.set(fnId, candidate);
+		return fnId;
+	});
+	const mirrorRand = (subtype, value) => {
+		post({
+			t: "rand",
+			token: currentToken(),
+			subtype,
+			value
+		});
+	};
+	const shimNow = () => {
+		logicalNow += 1 + Math.floor(next() * 7);
+		const value = logicalNow;
+		mirrorRand("now", value);
+		return value;
+	};
+	const shimRandom = () => {
+		const value = next();
+		mirrorRand("random", value);
+		return value;
+	};
+	const shimUuid = () => {
+		const bytes = /* @__PURE__ */ new Uint8Array(16);
+		for (let i = 0; i < 16; i += 1) bytes[i] = Math.floor(next() * 256);
+		bytes[6] = bytes[6] & 15 | 64;
+		bytes[8] = bytes[8] & 63 | 128;
+		const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+		const value = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+		mirrorRand("uuid", value);
+		return value;
+	};
+	Date.now = shimNow;
+	Math.random = shimRandom;
+	Reflect.set(globalThis, "fetch", void 0);
+	Reflect.set(globalThis, "process", void 0);
+	const sandboxGlobals = {
+		agent: (prompt, opts) => callHost("agent", {
+			prompt,
+			...opts === void 0 ? {} : { opts }
+		}),
+		parallel: (tasks, opts) => {
+			if (!Array.isArray(tasks)) throw new TypeError("parallel takes an array of functions");
+			const fnIds = registerFns(tasks, "parallel");
+			return callHost("parallel", opts?.settle === true ? {
+				fnIds,
+				settle: true
+			} : { fnIds });
+		},
+		pipeline: (items, ...rest) => {
+			if (!Array.isArray(items)) throw new TypeError("pipeline takes an items array first");
+			const last = rest[rest.length - 1];
+			const hasOpts = typeof last === "object" && last !== null;
+			const stages = hasOpts ? rest.slice(0, -1) : rest;
+			const stageFnIds = registerFns(stages, "pipeline stages");
+			const onItemError = hasOpts ? last.onItemError : void 0;
+			return callHost("pipeline", {
+				items,
+				stageFnIds,
+				...onItemError === void 0 ? {} : { onItemError }
+			});
+		},
+		step: (label, fn, opts) => {
+			const [fnId] = registerFns([fn], "step");
+			const o = opts ?? {};
+			return callHost("step", {
+				label,
+				fnId,
+				...o.deps === void 0 ? {} : { deps: o.deps },
+				...o.key === void 0 ? {} : { key: o.key }
+			});
+		},
+		phase: (name, fn) => {
+			const [fnId] = registerFns([fn], "phase");
+			return callHost("phase", {
+				name,
+				fnId
+			});
+		},
+		log: (level, msg, data) => {
+			post({
+				t: "log",
+				token: currentToken(),
+				level,
+				msg: String(msg),
+				...data === void 0 ? {} : { data: toJournalValue(data, "sandbox log data") }
+			});
+		},
+		budget: {
+			spent: () => callHost("budget.spent", {}),
+			remaining: () => callHost("budget.remaining", {})
+		},
+		workflow: (name, args, opts) => callHost("workflow", {
+			name,
+			...args === void 0 ? {} : { args },
+			...opts?.key === void 0 ? {} : { key: opts.key }
+		}),
+		awaitExternal: (key, opts) => {
+			const o = opts ?? {};
+			return callHost("awaitExternal", {
+				key,
+				...o.schema === void 0 ? {} : { schema: o.schema },
+				...o.prompt === void 0 ? {} : { prompt: o.prompt }
+			});
+		},
+		now: shimNow,
+		random: (key) => {
+			if (key !== void 0 && typeof key !== "string") throw new TypeError("random(key) takes a string discriminator");
+			const value = next();
+			post({
+				t: "rand",
+				token: currentToken(),
+				subtype: "random",
+				value,
+				...key === void 0 ? {} : { key }
+			});
+			return value;
+		},
+		uuid: shimUuid
+	};
+	port.on("message", (raw) => {
+		switch (raw.t) {
+			case "result": {
+				const pending = pendingCalls.get(raw.id);
+				pendingCalls.delete(raw.id);
+				if (pending !== void 0) {
+					enterFrame();
+					pending.resolve(raw.value);
+				}
+				return;
+			}
+			case "error": {
+				const pending = pendingCalls.get(raw.id);
+				pendingCalls.delete(raw.id);
+				if (pending !== void 0) {
+					enterFrame();
+					const rebuilt = new Error(raw.error.message);
+					rebuilt.name = raw.error.code;
+					pending.reject(rebuilt);
+				}
+				return;
+			}
+			case "thunk:run": {
+				const fn = fns.get(raw.fnId);
+				enterFrame();
+				(async () => {
+					try {
+						if (fn === void 0) throw new Error(`unknown sandbox thunk ${String(raw.fnId)}`);
+						const value = await frameToken.run(raw.token, () => fn(...raw.args));
+						post({
+							t: "thunk:result",
+							id: raw.id,
+							value: toJournalValue(value ?? null, "sandbox thunk result")
+						});
+					} catch (thrown) {
+						post({
+							t: "thunk:error",
+							id: raw.id,
+							error: wireOf(thrown)
+						});
+					} finally {
+						exitFrame();
+					}
+				})();
+				return;
+			}
+			default: return;
+		}
+	});
+	const AsyncFunctionCtor = Object.getPrototypeOf(shimAsyncMarker).constructor;
+	enterFrame();
+	(async () => {
+		try {
+			post({
+				t: "done",
+				value: toJournalValue(await new AsyncFunctionCtor(...SANDBOX_GLOBALS, init.source)(...SANDBOX_GLOBALS.map((name) => sandboxGlobals[name])) ?? null, "sandbox script result")
+			});
+		} catch (thrown) {
+			post({
+				t: "fail",
+				error: wireOf(thrown)
+			});
+		} finally {
+			exitFrame();
+		}
+	})();
+}
+/** Marker reaching the AsyncFunction constructor; never invoked. */
+const shimAsyncMarker = async () => void 0;
+parentPort?.once("message", (init) => {
+	main(init.port, init);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@rulvar/planner",
+  "version": "1.0.0",
+  "description": "rulvar flagship hybrid mode: plan agent, compileScript, WorkerSandboxRunner, self-repair loop.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "eslint": "^9.39.4",
+    "@rulvar/core": "1.0.0",
+    "eslint-plugin-rulvar": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.22.3",
+    "typescript": "~6.0.3",
+    "@rulvar/testing": "1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/rulvar.git",
+    "directory": "packages/planner"
+  },
+  "homepage": "https://rulvar.com",
+  "bugs": {
+    "url": "https://github.com/o-stepper/rulvar/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "pack-check": "publint --pack pnpm && attw --pack . --profile esm-only"
+  }
+}