@genroc/eval-node 0.0.1

package/README.md

@@ -0,0 +1,302 @@
+# @genroc/eval-node
+
+Script tasks for Node. Two halves with different jobs:
+
+* **the bundler** (`genroc-import`) — an author-time resolver genctl runs on every apply and
+  every edit, turning `$import: ./x.ts` into a bundled, typechecked string
+* **the worker** (`genroc-eval-node`) — claims parked `external` script tasks off genroc's queue
+  and evaluates each in its own realm
+
+## Setting up a project
+
+    npm i -D @genroc/eval-node
+
+Then register the resolver in a `genroc.yaml` beside your definitions — discovery walks up from
+the file, so nothing depends on the cwd:
+
+    resolvers:
+      import:
+        phase: code
+        ext: .ts
+        command: [npx, genroc-import]
+
+`genctl apply` and `genctl types` now resolve `$import` directives. Typechecking is the
+resolver's exit code, so a stored definition cannot hold code that failed to typecheck.
+
+## Running the worker
+
+    docker run -e GENROC_SERVER=http://host:8448 ghcr.io/genroc/eval-node:preview
+
+or locally, if you already have Node:
+
+    GENROC_SERVER=http://localhost:8448 npx genroc-eval-node
+
+Add `GENROC_TOKEN` once the server has auth on; `worker` is the only permission it needs.
+
+**The bundler cannot be the image.** It runs per edit and must resolve your project's own
+`node_modules`, so a container start per invocation would break the editor loop.
+
+Design record: [specs/external-task-queue.md](../specs/external-task-queue.md) for the queue,
+[specs/script-tasks.md](../specs/script-tasks.md) for the runtime.
+
+    GENROC_SERVER=http://localhost:8448 node eval-node/worker.ts
+
+Against a server started with `--auth token`, mint a scoped credential first:
+
+    TOKEN=$(genctl token create --perms worker --label evaluator -q)
+    GENROC_SERVER=http://localhost:8448 GENROC_TOKEN=$TOKEN node eval-node/worker.ts
+
+`worker` reaches the four queue verbs and `GET /api/objects/{ref}` — enough to claim, fetch an
+externalized input and answer, and nothing else. This is the credential most likely to end up on
+a machine you trust least, so it is worth scoping rather than reusing an admin token: a leaked
+one cannot read a definition, list an instance, or mint another token.
+
+A credential problem **exits the worker** rather than being retried. Polling through a 401 looks
+like a healthy worker that never picks anything up, which is the worst shape to debug.
+
+It needs **Node 24 or newer**: the sources are TypeScript and are run as-is, by Node's own
+type stripping.
+
+| env | default | |
+|---|---|---|
+| `GENROC_SERVER` | `http://localhost:8448` | where to claim from |
+| `GENROC_TOKEN` | *(none)* | credential, when the server runs with `--auth token`. Needs the **`worker`** permission and nothing more |
+| `WORKER_ID` | `evaluator-<pid>` | the claim holder; renewals are scoped to it |
+| `CONCURRENCY` | `4` | how many scripts run at once — **this worker's** decision |
+| `LEASE_MS` | `30000` | visibility timeout; renewed at a third of it while working |
+| `POLL_MS` | `250` | idle poll interval; a non-empty claim polls again immediately |
+| `PROCESS` / `TASK` | unset | claim only this process / task id |
+
+**The worker calls genroc, not the other way round.** That is the whole reason this is a
+queue worker rather than the HTTP sidecar it used to be:
+
+- **Concurrency is the worker's to set.** Under the old `fetch` shape genroc decided how many
+  scripts ran at once (`--max-concurrent`, default 200) and the evaluator accepted every one.
+  A backlog is now a queue, not 200 threads fighting over a core.
+- **No engine worker is held.** A `fetch` occupies one of genroc's advance slots for its whole
+  duration, so a slow evaluator starved unrelated tasks. An `external` task parks.
+- **The connection direction inverts.** `/eval` was unauthenticated arbitrary code execution
+  that genroc had to be able to reach. A worker only needs outbound access, so it can live
+  anywhere — behind NAT, in another trust zone.
+
+## The task input
+
+The `input` of the external task IS the evaluation request:
+
+```jsonc
+{
+  "code": "return { fee: input.amount * 0.1 };",  // required — an async function body
+  "input": { "amount": 250 },                     // optional — bound as `input`
+  "timeout_ms": 5000                              // optional — default 5000
+}
+```
+
+`code` is the **body of an async function**, so `await` works and the value reaches genroc
+through `return`. It is compiled with `input` and `require` as parameters, under
+`"use strict"` — `require` is what a bundled `import` of a node builtin lands on.
+
+## The answer — the failure kind IS the error code
+
+genroc's `on_error` matches error codes, and an external task's `raises` declares the closed
+set a worker may send. So the classification lives in the **code**, where a rule can match it,
+rather than in a body a `switch` has to read.
+
+| outcome | the worker submits | |
+|---|---|---|
+| the script returned | `result: <the return value>` | `return;` sends nothing, which genroc reads as `null` |
+| the script faulted | `error: {code, message, data}` | `code` is the kind, below |
+| the **evaluator** faulted | *nothing* — it releases the claim | the task returns to the queue for another worker |
+
+The five kinds, every one of them **permanent** — a retry re-runs the same code on the same
+input and fails identically:
+
+`compile_error` · `threw` · `timeout` · `nonserializable` · `exited`
+
+`data` carries `{name, stack?}`: `name` is what a script sets to tell one refusal from another
+(`e.name = 'LimitExceeded'`), and `stack` is renumbered to the lines the author wrote and
+trimmed to 2 KiB.
+
+**The retryable class has no code on purpose.** A runner that faults releases its claim, which
+is how a queue spells "try this somewhere else" — it puts the task in front of a different
+worker instead of spending the definition's `on_error` budget on this one's bad day. There is
+no retry policy to write.
+
+## The genroc side
+
+```yaml
+- id: price
+  action:
+    type: external
+    input:
+      code: |
+        if (input.amount > 100) {
+          const e = new Error('amount over the limit');
+          e.name = 'LimitExceeded';
+          throw e;
+        }
+        return { fee: input.amount * 0.1 };
+      input: "$: input"
+    result_schema: { type: object, properties: { fee: { type: number } }, required: [fee] }
+    raises:
+      threw:           { $ref: "#/$defs/script_error" }
+      timeout:         { $ref: "#/$defs/script_error" }
+      compile_error:   { $ref: "#/$defs/script_error" }
+      nonserializable: { $ref: "#/$defs/script_error" }
+      exited:          { $ref: "#/$defs/script_error" }
+  timeout: 30s
+  on_error:
+    - code: [threw]
+      goto: $script_failed
+    - code: [compile_error, nonserializable, exited]
+      panic: { code: script_broken, message: "the script did not run: ${error.code}" }
+  switch: [{ goto: end }]
+
+- id: script_failed
+  switch:
+    - case: 'error.data.name == "LimitExceeded"'
+      raise: { code: limit_exceeded, message: "the script rejected the amount" }
+    - raise: { code: script_failed, message: "the script failed" }
+```
+
+**A script cannot name a genroc error code.** `raise`/`panic` codes are literals, never
+expressions, so the mapping from a thrown error to an authored code is this `switch` — one
+task the definition owns, reading `error.data`. That is the whole error protocol: the worker
+classifies into a code, the definition names the outcome.
+
+Set the task `timeout` **above** `timeout_ms`. If the task's deadline fires first the code is
+`external.timeout`, which is in `errcode.Unknowable()` — permanently unretryable on an
+`only_once` task, and indistinguishable from no evaluator running at all.
+
+`only_once` is worth considering if your scripts have side effects: without it a worker that
+dies mid-script has its task re-claimed and the script runs again. With it the task is never
+handed out twice, and the instance gets a catchable `external.lost` instead.
+
+## `${` must be escaped as `$${` — when the code is inline
+
+An external task's `input` is a Shape, so `${…}` is genroc's interpolation marker and a JS
+template literal inside `code` is read by genroc rather than passed through. Write `` `<$${x}>` ``.
+A leading `$:` on the code string needs `$$:` for the same reason. See
+[specs/typed-values.md](../specs/typed-values.md). Moving the code into a `.ts` file
+removes this entirely — see the next section.
+
+## `import.ts` — the author-time half
+
+`import.ts` is the **code-phase resolver** genctl runs before a definition is applied. It
+never touches the queue and the worker never runs it; the two halves share this package only
+because they share a calling convention, which is exactly the coupling that breaks silently
+if they version apart.
+
+Register it in the project's `genroc.yaml`:
+
+```yaml
+resolvers:
+  import: { phase: code, ext: .ts, command: [node, ../eval-node/import.ts] }
+```
+
+then write the script as a module and name it from the definition:
+
+```yaml
+body:
+  code: "$import: ./fee.ts"
+  input: "$: input"
+```
+
+```ts
+import type { Input, Output } from "./fee.genroc";
+
+export default async function (input: Input): Promise<Output> {
+  return { fee: input.amount * 0.1 };
+}
+```
+
+`genctl types -f process.yaml` writes `fee.genroc.d.ts` beside the script — named for the
+**script's path**, not the task, so renaming a task cannot break the import line. `Input` is
+the inferred type of what the definition passes; `Output` is what it declares
+(`responses.200`, or `result_schema` on a child). `genctl apply` regenerates them, runs
+`tsc --noEmit`, and bundles — so **a type error is a failed apply**, and a stored definition
+cannot hold code that failed to typecheck.
+
+The bundle is emitted as CJS and wrapped as a function body, so the evaluator needs to know
+nothing about modules. Imports resolve through TypeScript under the same config the check
+ran with, so a `paths` alias that typechecks also bundles. They are inlined at build time, so the string a
+definition version stores is self-contained forever — with one exception: **node builtins
+stay as `require` calls**, which the realm satisfies. A package is frozen into the
+definition; `node:fs` is resolved by whatever runner executes it.
+
+### Your tsconfig, your types
+
+The generated project config `extends` **the nearest `tsconfig.json` above the script** —
+the one your editor already reads, so the two cannot disagree. Two scripts under two
+different configs are two `tsc` runs.
+
+Of that config, three keys are the toolchain's and the rest are yours:
+
+| key | owner | why |
+|---|---|---|
+| `lib` | the toolchain | Describes the realm. A worker thread has no `document`, whatever a config claims. |
+| `include` | the toolchain | Forced to `[]`. A base `include` survives beside our `files` and would drag your whole tree in to be checked as scripts. |
+| `types` | **you** | How a script opts into the node globals. The realm has them, so refusing the declarations would only lie. With no tsconfig at all the default is `[]`. |
+
+```jsonc
+// tsconfig.json beside your scripts
+{ "compilerOptions": { "types": ["node"] } }  // now `import { appendFile } from "node:fs/promises"` typechecks
+```
+
+**This is what removes the `$${` escaping above** — a template literal in a `.ts` file is
+never read by genroc, because genctl doubles every `$` on splice.
+
+## The realm — one Worker per execution
+
+`evaluate()` starts a Worker (`realm.ts`), posts the code into it, and races the reply against the budget;
+`terminate()` runs on every path. That thread is what the contract rests on, and it buys
+exactly three things the previous in-process evaluator could not:
+
+- **The budget is enforced, not merely reported.** A synchronous `while(true){}` never
+  yields, so no in-process timer can interrupt it — the old evaluator hung forever on that
+  input, and said so in this file. Killing the thread is the only bound. Measured on Node
+  24: `terminate()` stops a spinning worker, and the CPU it was burning goes with it.
+- **A fresh global object per execution.** One script cannot configure the next. It is also
+  why there is no compile cache any more: a cache inside a discarded realm can never be hit.
+- **The script's mistakes stay the script's.** An uncaught throw, and `process.exit()`, end
+  the realm and come back as a `422` — neither reaches the runner.
+
+It costs about **50ms per execution** end to end for a trivial script (Node 24, M-series
+laptop), a 200 KiB body about 63ms. Roughly 19ms of that is Node re-stripping `worker.ts`'s
+types on every realm — precompiling it to JavaScript would buy that back, and is deliberately
+not done: a build artefact that goes stale against its source fails silently, and this file
+is the one where a wrong line number is invisible.
+
+That also changes an old trade-off. A subprocess per execution measures ~48ms here — within
+noise of the thread — where on the previous runtime it was ten times the thread's cost. The
+thread no longer wins on price, and a subprocess contains the two things a thread cannot
+(below), so it is the live upgrade path rather than a theoretical one.
+
+## What this is not
+
+- **Not deterministic.** A script reads the real clock and the real RNG, and a retry
+  re-executes — so attempt two can differ from attempt one. An earlier version injected a
+  pinned `Date` and a seeded `Math`; nothing could supply a stable `now` (the expression
+  environment has no clock), so the pin was the wall clock under another name, and the `ctx`
+  it needed was surface with nothing behind it. A value that must survive a retry belongs in
+  the definition, passed through `input`.
+- **Not a sandbox.** The realm isolates *execution*, not *authority*: a script gets the
+  worker's filesystem, network and environment, and `require` of any node builtin. That is
+  deliberate — a script task is meant to do real work — but the trust boundary stays the
+  same-trust-domain one (your genroc, your worker host). It is not the multi-tenant story, and
+  nothing here should be mistaken for one. Pulling does move the boundary in one useful way:
+  the worker needs no inbound reachability, so nothing but the worker can ask it to run code.
+- **A thread does not contain memory or a native crash.** A worker shares the process
+  address space, so a script that exhausts memory takes the runner with it — and so does a
+  fault in the runtime itself, which is not hypothetical: the previous one segfaulted on
+  resume from laptop sleep, taking the in-flight evaluation with it. Containing that is what
+  the subprocess strategy is for — `eval.ts` keeps HTTP out precisely so it can be swapped
+  underneath.
+- **Concurrency is capped by this worker, not by genroc.** Each evaluation is a thread, and
+  `CONCURRENCY` is how many it will claim at once. Raising it past what the host can run turns
+  a queue back into threads fighting over a core.
+- **Not where imports and type checking happen.** The evaluator still takes one
+  self-contained function body and knows nothing about TypeScript; `import.ts` is what turns
+  a module into that body, at author time. See above.
+- **`eval.ts` and `realm.ts` know nothing about genroc.** `worker.ts` is the entire
+  queue-facing half, which is what keeps the containment strategy swappable — and what lets
+  the realm's own properties be tested by calling `evaluate()` directly.

package/bin/import.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// npm `bin` entries need a shebang and a stable extension; Node's type stripping handles the
+// .ts behind it. genroc.yaml points here: command: [npx, genroc-import]
+import "../import.ts";

package/bin/worker.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../worker.ts";

package/eval.ts

@@ -0,0 +1,98 @@
+// Evaluation core: run a code string in its OWN realm and classify every outcome into one of
+// the failure kinds in README.md. Nothing here knows about genroc — worker.ts is the only
+// thing that talks to the queue — so this stays testable and the containment stays swappable.
+//
+// The containment is a Worker per execution (realm.ts). It is what makes the budget real:
+// a synchronous busy loop never yields, so no in-process timer can interrupt it, and only a
+// thread the host can kill bounds it.
+
+import { Worker } from "node:worker_threads";
+
+export type EvalRequest = {
+  code: string;
+  input?: unknown;
+  timeout_ms?: number;
+};
+
+/** Every kind here is PERMANENT: a retry re-runs the same code on the same input and fails
+ *  identically. The retryable class has no kind because it is not an outcome — a runner that
+ *  faults releases its claim and lets another worker take the task. */
+export type FailureKind = "compile_error" | "threw" | "timeout" | "nonserializable" | "exited";
+
+export type EvalFailure = {
+  kind: FailureKind;
+  name: string;
+  message: string;
+  stack?: string;
+};
+
+/** `body` is JSON TEXT, not a value: serialising in the realm is what makes a nonserializable
+ *  return a script fault rather than a 500 thrown out of the response path. It is also what
+ *  crosses the worker boundary — structured clone would refuse a different set of values. */
+export type EvalResult =
+  | { ok: true; body: string }
+  | { ok: false; failure: EvalFailure };
+
+/** The message the host posts into the realm, and the only reply it accepts back. */
+export type WorkerRequest = { code: string; input?: unknown };
+export type WorkerReply = EvalResult;
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const REALM_URL = new URL("./realm.ts", import.meta.url);
+
+/** Thrown, not returned: a realm that fails to start is the RUNNER faulting, which worker.ts
+ *  answers by releasing the claim rather than by reporting an outcome. A script fault is a
+ *  return value. */
+class RealmFault extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RealmFault";
+  }
+}
+
+export async function evaluate(req: EvalRequest): Promise<EvalResult> {
+  const budget = typeof req.timeout_ms === "number" ? req.timeout_ms : DEFAULT_TIMEOUT_MS;
+
+  const worker = new Worker(REALM_URL);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await new Promise<EvalResult>((resolve, reject) => {
+      timer = setTimeout(() => resolve(timedOut(budget)), budget);
+      worker.once("message", (reply: WorkerReply) => resolve(reply));
+      // A script may end its own realm (`process.exit()`), which is not a throw and would
+      // otherwise present as a hang until the budget expired. Our own terminate() raises
+      // this too, by which time the promise has settled and the first result stands.
+      worker.once("exit", (code: number) => resolve(exited(code)));
+      worker.once("error", (err: Error) => reject(new RealmFault(errorText(err))));
+      worker.postMessage({ code: req.code, input: req.input } satisfies WorkerRequest);
+    });
+  } finally {
+    clearTimeout(timer);
+    // Awaited, and the whole point: on the timeout path a thread is still burning a core, and
+    // resolving before it is gone would report an evaluation the machine is still running.
+    await worker.terminate();
+  }
+}
+
+function timedOut(ms: number): EvalResult {
+  return {
+    ok: false,
+    failure: { kind: "timeout", name: "TimeoutError", message: `script exceeded its ${ms}ms budget` },
+  };
+}
+
+function exited(code: number): EvalResult {
+  return {
+    ok: false,
+    failure: {
+      kind: "exited",
+      name: "RealmExited",
+      message: `the script ended its own realm with code ${code} instead of returning`,
+    },
+  };
+}
+
+function errorText(e: unknown): string {
+  const message = (e as { message?: unknown } | null)?.message;
+  return typeof message === "string" && message !== "" ? message : "the evaluation realm failed to start";
+}

package/import.ts

@@ -0,0 +1,395 @@
+// The code-phase resolver: manifest on stdin, `{"code": [...]}` on stdout, non-zero exit
+// with the diagnostic on stderr. genctl never parses TypeScript and this never parses YAML
+// — the manifest is the whole contract. See specs/source-resolution.md.
+//
+// Two modes, one binary: "types" writes the declarations an editor needs and returns no
+// code; "build" typechecks and bundles. A separate types hook would mean a second `tsc`
+// over the same project.
+
+import { spawn } from "node:child_process";
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { builtinModules } from "node:module";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import commonjs from "@rollup/plugin-commonjs";
+import json from "@rollup/plugin-json";
+import { nodeResolve } from "@rollup/plugin-node-resolve";
+import { rollup, type Plugin } from "rollup";
+import ts from "typescript";
+
+type Schema = Record<string, any>;
+
+type Site = {
+  resolver: string;
+  process: string;
+  task?: string;
+  pointer: string;
+  path: string;
+  input?: Schema;
+  output?: Schema;
+};
+
+type Manifest = {
+  mode: "types" | "build";
+  root: string;
+  schemas: Record<string, Schema>;
+  sites: Site[];
+};
+
+function die(message: string): never {
+  console.error(message);
+  process.exit(1);
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Creates the parent directory, which `.genroc/` relies on: nothing else makes it. */
+async function write(path: string, content: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content);
+}
+
+// ── JSON Schema → TypeScript ───────────────────────────────────────────────────
+
+/** Only genroc's keyword set is handled; anything else its strict decoder would have
+ *  refused before this ran (internal/schema, allowedKeywords). */
+function tsType(s: Schema | undefined, used: Set<string>): string {
+  if (s === undefined || s === null) return "unknown";
+  if (typeof s.$ref === "string") {
+    const name = s.$ref.replace(/^#\/\$defs\//, "");
+    used.add(name);
+    return identifier(name);
+  }
+  if (Array.isArray(s.enum)) {
+    return s.enum.map((v: unknown) => JSON.stringify(v)).join(" | ") || "never";
+  }
+  if (Array.isArray(s.anyOf)) return union(s.anyOf.map((a: Schema) => tsType(a, used)));
+  if (Array.isArray(s.oneOf)) return union(s.oneOf.map((a: Schema) => tsType(a, used)));
+  if (Array.isArray(s.allOf)) {
+    return s.allOf.map((a: Schema) => tsType(a, used)).join(" & ") || "unknown";
+  }
+
+  const types: string[] = s.type === undefined ? [] : Array.isArray(s.type) ? s.type : [s.type];
+  if (types.length === 0) {
+    // The top type: `{}` means unknown, not "an empty object". specs/unknown-type.md.
+    return s.properties ? objectType(s, used) : "unknown";
+  }
+  return union(types.map((t) => scalarType(t, s, used)));
+}
+
+function scalarType(t: string, s: Schema, used: Set<string>): string {
+  switch (t) {
+    case "object":
+      return objectType(s, used);
+    case "array":
+      return s.items ? `Array<${tsType(s.items, used)}>` : "unknown[]";
+    case "string":
+      return "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    default:
+      return "unknown";
+  }
+}
+
+function objectType(s: Schema, used: Set<string>): string {
+  const props: Record<string, Schema> = s.properties ?? {};
+  const required = new Set<string>(s.required ?? []);
+  const lines: string[] = [];
+  for (const [key, sub] of Object.entries(props)) {
+    const doc = typeof sub.description === "string" ? `  /** ${sub.description} */\n` : "";
+    lines.push(`${doc}  ${propKey(key)}${required.has(key) ? "" : "?"}: ${tsType(sub, used)};`);
+  }
+  if (s.additionalProperties && typeof s.additionalProperties === "object") {
+    lines.push(`  [key: string]: ${tsType(s.additionalProperties, used)};`);
+  }
+  if (lines.length === 0) return "Record<string, unknown>";
+  return `{\n${lines.join("\n")}\n}`;
+}
+
+function union(parts: string[]): string {
+  const seen = [...new Set(parts)];
+  return seen.length === 0 ? "unknown" : seen.join(" | ");
+}
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const propKey = (k: string) => (IDENT.test(k) ? k : JSON.stringify(k));
+const identifier = (n: string) => (IDENT.test(n) ? n : `Def_${n.replace(/[^A-Za-z0-9_$]/g, "_")}`);
+
+function deref(s: Schema | undefined, defs: Record<string, Schema>): Schema | undefined {
+  let cur = s;
+  for (let i = 0; cur && typeof cur.$ref === "string" && i < 16; i++) {
+    cur = defs[cur.$ref.replace(/^#\/\$defs\//, "")];
+  }
+  return cur;
+}
+
+/** The manifest's `input` is the type of the whole ACTION input — for /eval that is
+ *  `{code, input, timeout_ms, …}`, and only its `input` field is bound as the script's
+ *  parameter. genroc cannot know that; this file owns the evaluator's wire contract, so
+ *  the navigation belongs here rather than in genctl. */
+function scriptInput(site: Site, defs: Record<string, Schema>): Schema | undefined {
+  const action = deref(site.input, defs);
+  const bound = action?.properties?.input;
+  return bound ?? site.input;
+}
+
+/** Emits one named type per reachable $def rather than inlining: a task output may
+ *  reference itself (specs/recursive-type-inference.md) and inlining would not terminate. */
+function declarations(site: Site, defs: Record<string, Schema>): string {
+  const used = new Set<string>();
+  const input = tsType(scriptInput(site, defs), used);
+  const output = tsType(site.output, used);
+
+  const emitted: string[] = [];
+  const done = new Set<string>();
+  while (true) {
+    const next = [...used].find((n) => !done.has(n));
+    if (next === undefined) break;
+    done.add(next);
+    const body = tsType(defs[next], used);
+    emitted.push(`export type ${identifier(next)} = ${body};`);
+  }
+
+  return [
+    "// Generated by genroc. Do not edit - regenerate with `genctl types`.",
+    `// ${site.process}${site.task ? ` / ${site.task}` : ""}  (${site.pointer})`,
+    "",
+    ...emitted,
+    emitted.length ? "" : "",
+    `export type Input = ${input};`,
+    "",
+    `export type Output = ${output};`,
+    "",
+  ].join("\n");
+}
+
+/** Keyed by the script's PATH, not the task id: keyed by task, renaming a task would break
+ *  the author's `import type` line with the error landing nowhere near the rename. */
+function typesPathFor(scriptPath: string): string {
+  return scriptPath.replace(/\.[^.\/]+$/, "") + ".genroc.d.ts";
+}
+
+// ── typecheck ──────────────────────────────────────────────────────────────────
+
+/** The nearest tsconfig above the script — the one the author's editor already reads. Two
+ *  different configs mean a red editor over a clean apply, or the reverse. The walk stops at
+ *  the project root: above it is not this project. */
+async function nearestTsconfig(from: string, root: string): Promise<string | null> {
+  for (let dir = from; ; dir = dirname(dir)) {
+    const candidate = join(dir, "tsconfig.json");
+    if (await exists(candidate)) return candidate;
+    if (dir === root || dirname(dir) === dir) return null;
+  }
+}
+
+async function typecheck(root: string, sites: Site[]): Promise<void> {
+  const dir = join(root, ".genroc");
+  await write(join(dir, ".gitignore"), "*\n");
+
+  // One tsc per distinct base config: `extends` takes a single base, so merging two would
+  // check each script under the other author's options.
+  const groups = new Map<string, Site[]>();
+  for (const site of sites) {
+    const base = (await nearestTsconfig(dirname(site.path), root)) ?? "";
+    const group = groups.get(base);
+    if (group) group.push(site);
+    else groups.set(base, [site]);
+  }
+
+  let n = 0;
+  for (const [base, group] of groups) {
+    const config: Record<string, unknown> = {
+      ...(base ? { extends: relative(dir, base) } : {}),
+      compilerOptions: {
+        noEmit: true,
+        strict: true,
+        skipLibCheck: true,
+        moduleDetection: "force",
+        module: "preserve",
+        target: "esnext",
+        // `lib` DESCRIBES the realm and is written after `extends` so a base cannot widen it:
+        // a worker thread has no document, whatever an author's config claims.
+        lib: ["esnext", "webworker"],
+        // `types` is the author's, and it is how a script opts into the node globals —
+        // the worker realm has them, so refusing the declarations would only lie. With no
+        // base config there is nothing to opt in with, so the default stays none.
+        ...(base ? {} : { types: [] }),
+      },
+      files: group.flatMap((s) => [relative(dir, s.path), relative(dir, typesPathFor(s.path))]),
+      // `files` overrides the base's, but a base `include` survives beside it and would
+      // drag the author's whole tree in, to be checked under the worker lib.
+      include: [],
+    };
+    const configPath = join(dir, groups.size === 1 ? "tsconfig.json" : `tsconfig.${n++}.json`);
+    await write(configPath, JSON.stringify(config, null, 2));
+    await runTsc(root, configPath);
+  }
+}
+
+async function runTsc(root: string, configPath: string): Promise<void> {
+  const tsc = fileURLToPath(import.meta.resolve("typescript/bin/tsc"));
+  const proc = spawn(process.execPath, [tsc, "--noEmit", "-p", configPath], {
+    cwd: root,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let out = "";
+  let err = "";
+  proc.stdout.on("data", (c: Buffer) => (out += c));
+  proc.stderr.on("data", (c: Buffer) => (err += c));
+  const code = await new Promise<number>((resolve, reject) => {
+    proc.on("error", reject);
+    proc.on("close", (c) => resolve(c ?? 1));
+  });
+  if (code !== 0) {
+    // tsc reports on stdout; the exit code IS the type check, so this is the diagnostic
+    // genctl surfaces and the reason a failed import never produces a string.
+    die([out, err].filter(Boolean).join("\n").trimEnd());
+  }
+}
+
+// ── bundle ─────────────────────────────────────────────────────────────────────
+
+/** Transpiles only. The typecheck above already ran over the author's OWN tsconfig, and a
+ *  second opinion from a config they do not control could fail a build they cannot fix. */
+const transpile: Plugin = {
+  name: "genroc-transpile",
+  transform(code, id) {
+    if (!id.endsWith(".ts") && !id.endsWith(".tsx")) return null;
+    const out = ts.transpileModule(code, {
+      fileName: id,
+      compilerOptions: {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        verbatimModuleSyntax: false,
+        jsx: id.endsWith(".tsx") ? ts.JsxEmit.ReactJSX : undefined,
+      },
+    });
+    return { code: out.outputText, map: out.sourceMapText ?? null };
+  },
+};
+
+const BUILTIN = new Set([...builtinModules, ...builtinModules.map((m) => `node:${m}`)]);
+
+/** Resolves imports through TYPESCRIPT, using the same config the typecheck ran under, so a
+ *  `paths` alias that compiles also bundles. Reimplementing `paths` here would be a second
+ *  resolver to keep in agreement with tsc; this one cannot disagree.
+ *  A package resolving to a `.d.ts` is declined — that is a type, not the implementation —
+ *  which leaves node_modules to nodeResolve. */
+function tsResolve(configPath: string | null): Plugin {
+  let options: ts.CompilerOptions = {};
+  if (configPath) {
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    options = ts.parseJsonConfigFileContent(read.config ?? {}, ts.sys, dirname(configPath)).options;
+  }
+  return {
+    name: "genroc-ts-resolve",
+    resolveId(source, importer) {
+      if (!importer || BUILTIN.has(source)) return null;
+      const { resolvedModule } = ts.resolveModuleName(source, importer, options, ts.sys);
+      if (!resolvedModule || resolvedModule.isExternalLibraryImport) return null;
+      return resolvedModule.resolvedFileName.endsWith(".d.ts") ? null : resolvedModule.resolvedFileName;
+    },
+  };
+}
+
+/** Bundles to CJS and wraps it as an async function BODY, which is what /eval compiles.
+ *  The runtime stays unchanged: bundling is entirely the importer's job, and the string it
+ *  produces is self-contained, so a definition version pins its code forever. */
+async function bundle(site: Site, root: string): Promise<string> {
+  // Builtins are EXTERNALISED as `require` calls that worker.ts satisfies. Anything else
+  // unresolved is a REFUSAL, not an external: rollup's default is to leave it as a require
+  // of a module that will not be there, which bundles clean and fails at runtime.
+  const built = await rollup({
+    input: site.path,
+    external: (id) => BUILTIN.has(id),
+    plugins: [
+      tsResolve(await nearestTsconfig(dirname(site.path), root)),
+      nodeResolve({ extensions: [".ts", ".tsx", ".mjs", ".js", ".json"] }),
+      commonjs(),
+      // A `.json` import is a data file inlined at build time, which the previous bundler
+      // did natively; without it rollup hands the JSON to the JS parser.
+      json(),
+      transpile,
+    ],
+    onwarn(warning) {
+      if (warning.code === "UNRESOLVED_IMPORT") {
+        die(`${site.path}: cannot resolve ${warning.exporter ?? "an import"} — is it installed?`);
+      }
+    },
+  }).catch((e: unknown) => die(`${site.path}: ${e instanceof Error ? e.message : String(e)}`));
+
+  const { output } = await built.generate({ format: "cjs", exports: "auto", inlineDynamicImports: true });
+  await built.close();
+  const cjs = output[0].code;
+  return [
+    "var module = { exports: {} }, exports = module.exports;",
+    cjs,
+    "var __genroc_main = module.exports.default ?? module.exports;",
+    'if (typeof __genroc_main !== "function") {',
+    `  throw new Error(${JSON.stringify(`${site.path} has no default export function`)});`,
+    "}",
+    "return await __genroc_main(input);",
+  ].join("\n");
+}
+
+// ── main ───────────────────────────────────────────────────────────────────────
+
+const stdin: string = await new Promise((resolve, reject) => {
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => (raw += c));
+  process.stdin.on("end", () => resolve(raw));
+  process.stdin.on("error", reject);
+});
+const manifest = JSON.parse(stdin) as Manifest;
+if (!manifest || !Array.isArray(manifest.sites)) die("stdin is not a genroc resolver manifest");
+
+// One script at two sites with different input types is a refusal, not a union: the union
+// is sound and would typecheck a body that is wrong at one of the sites.
+const byPath = new Map<string, Site>();
+for (const site of manifest.sites) {
+  const seen = byPath.get(site.path);
+  const defsOf = (x: Site) => (manifest.schemas[x.process]?.$defs ?? {}) as Record<string, Schema>;
+  if (
+    seen &&
+    JSON.stringify(scriptInput(seen, defsOf(seen))) !==
+      JSON.stringify(scriptInput(site, defsOf(site)))
+  ) {
+    die(
+      `${site.path} is imported at ${seen.pointer} and ${site.pointer} with different input types.\n` +
+        "Split it into two scripts, or make the two call sites pass the same shape.",
+    );
+  }
+  byPath.set(site.path, site);
+}
+
+for (const site of byPath.values()) {
+  const defs = (manifest.schemas[site.process]?.$defs ?? {}) as Record<string, Schema>;
+  await write(typesPathFor(site.path), declarations(site, defs));
+}
+
+if (manifest.mode === "types") {
+  process.exit(0);
+}
+
+await typecheck(manifest.root, [...byPath.values()]);
+
+const code: string[] = [];
+for (const site of manifest.sites) {
+  code.push(await bundle(site, manifest.root));
+}
+process.stdout.write(JSON.stringify({ code }));

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@genroc/eval-node",
+  "version": "0.0.1",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "work": "node worker.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "rollup": "^4.52.4",
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2"
+  },
+  "description": "genroc script tasks for Node: the author-time bundler and the queue worker",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/genroc/genroc.git",
+    "directory": "eval-node"
+  },
+  "homepage": "https://genroc.org",
+  "bin": {
+    "genroc-import": "bin/import.mjs",
+    "genroc-eval-node": "bin/worker.mjs"
+  },
+  "files": [
+    "bin",
+    "*.ts",
+    "tsconfig.json",
+    "README.md"
+  ]
+}

package/realm.ts

@@ -0,0 +1,132 @@
+// The evaluation realm. One Worker per execution: a fresh global object per script, and a
+// thread the host can kill mid-loop — the only thing that bounds a synchronous busy loop.
+// eval.ts owns the budget and does the killing; nothing here knows about time.
+//
+// Everything that touches the script's VALUE lives on this side of the boundary — compiling,
+// classifying, serialising — because this is the only realm the value exists in.
+
+import { createRequire } from "node:module";
+import { parentPort } from "node:worker_threads";
+
+import type { EvalFailure, FailureKind, WorkerReply, WorkerRequest } from "./eval.ts";
+
+const AsyncFunction = async function () {}.constructor as new (
+  ...args: string[]
+) => (...args: unknown[]) => Promise<unknown>;
+
+const STRICT = '"use strict";\n';
+
+// Bundled `node:*` imports survive as `require` calls — the importer externalises builtins and
+// inlines everything else — and a function built by the AsyncFunction constructor has no
+// `require` in scope. Passing one in is what makes an import of a builtin work at runtime rather than at
+// typecheck only. Resolution is anchored here, which is right: only builtins reach it.
+const scriptRequire = createRequire(import.meta.url);
+const STACK_BYTES = 2_048;
+
+/**
+ * Line offset the AsyncFunction preamble adds, measured rather than assumed: the generated
+ * wrapper's shape is engine-specific, and a hardcoded number silently misreports every
+ * script's error location the day it changes.
+ */
+const lineOffset: Promise<number> = (async () => {
+  // Same parameter list as a real compile: the preamble is what is being measured.
+  const probe = new AsyncFunction("input", "require", STRICT + "throw new Error('probe');");
+  try {
+    await probe();
+    return 0;
+  } catch (err) {
+    return reportedLine(err) - 1;
+  }
+})();
+
+// V8 marks a frame compiled by the AsyncFunction constructor with the site that CALLED the
+// constructor, then the script's OWN position:
+//   at inner (eval at run (file:///…/worker.ts:107:10), <anonymous>:6:9)
+// `eval at` is therefore what separates script frames from runner plumbing — matched without
+// the function name, which is whatever encloses the `new AsyncFunction` below. The LAST such
+// frame is the body's top level: frames interleave, since a script can throw inside a native
+// callback.
+const SCRIPT_FRAME = /\(eval at /;
+// The trailing `<anonymous>:LINE:COL` — the script's position, after the host file's own.
+const POSITION = /<anonymous>:(\d+):(\d+)\)?\s*$/;
+// `    at name (` — absent on the top-level frame, which V8 names `eval`.
+const FRAME_NAME = /^\s*at\s+(?:async\s+)?([^\s(]+)\s*\(/;
+
+/** Line number of the throw as the engine reported it, or 1 if the stack is unreadable. */
+function reportedLine(err: unknown): number {
+  const stack = err instanceof Error && typeof err.stack === "string" ? err.stack : "";
+  const frame = stack.split("\n").find((l) => SCRIPT_FRAME.test(l)) ?? "";
+  const m = frame.match(POSITION);
+  return m ? Number(m[1]) : 1;
+}
+
+/** Renumbers each script frame to the line the AUTHOR wrote and drops the runner's own.
+ *  Rewriting the whole location is also what keeps the runner's path out of a script's
+ *  stack — V8 puts it inside every compiled frame. */
+function scriptStack(err: unknown, offset: number): string | undefined {
+  if (!(err instanceof Error) || typeof err.stack !== "string") return undefined;
+  const lines = err.stack.split("\n");
+  let boundary = -1;
+  for (let i = 0; i < lines.length; i++) if (SCRIPT_FRAME.test(lines[i]!)) boundary = i;
+  const frames = (boundary >= 0 ? lines.slice(0, boundary + 1) : lines.slice(0, 1))
+    .map((line) => {
+      const pos = line.match(POSITION);
+      if (!pos) return line; // the `Error: message` header and native frames, kept as-is
+      const name = line.match(FRAME_NAME)?.[1];
+      const at = name && name !== "eval" && name !== "anonymous" ? `at ${name} ` : "at ";
+      const indent = line.match(/^\s*/)![0];
+      return `${indent}${at}(script:${Math.max(1, Number(pos[1]) - offset)}:${pos[2]})`;
+    })
+    .join("\n");
+  return frames.length > STACK_BYTES ? frames.slice(0, STACK_BYTES) : frames;
+}
+
+function describe(err: unknown, kind: FailureKind, offset: number): EvalFailure {
+  if (err instanceof Error) {
+    return { kind, name: err.name, message: err.message, stack: scriptStack(err, offset) };
+  }
+  // A script may throw a non-Error (`throw {code: "x"}`), so name/message must not assume one.
+  return { kind, name: "Thrown", message: safeText(err) };
+}
+
+function safeText(v: unknown): string {
+  try {
+    return typeof v === "string" ? v : JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}
+
+async function run(req: WorkerRequest): Promise<WorkerReply> {
+  const offset = await lineOffset;
+
+  let fn: (...args: unknown[]) => Promise<unknown>;
+  try {
+    // No compile cache: the realm is discarded after this execution, so a cache in it could
+    // never be hit. Repeated compilation is the price of the fresh global object.
+    fn = new AsyncFunction("input", "require", STRICT + req.code);
+  } catch (err) {
+    return { ok: false, failure: describe(err, "compile_error", offset) };
+  }
+
+  let value: unknown;
+  try {
+    value = await fn(req.input, scriptRequire);
+  } catch (err) {
+    return { ok: false, failure: describe(err, "threw", offset) };
+  }
+
+  try {
+    // undefined stringifies to undefined, not "undefined"; an empty body is how genroc
+    // spells null, which is the right reading of a script that returned nothing.
+    return { ok: true, body: value === undefined ? "" : JSON.stringify(value) ?? "" };
+  } catch (err) {
+    return { ok: false, failure: describe(err, "nonserializable", offset) };
+  }
+}
+
+// Non-null because this module only ever runs as a worker entry point; a null port here
+// would mean eval.ts loaded it as a plain module, which nothing does.
+parentPort!.on("message", async (req: WorkerRequest) => {
+  parentPort!.postMessage(await run(req));
+});

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext"
+    ],
+    "types": [
+      "node"
+    ],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "**/*.ts"
+  ]
+}

package/worker.ts

@@ -0,0 +1,300 @@
+// The queue worker: claims parked `external` script tasks from genroc, evaluates each in its
+// own realm, and answers. This is the whole genroc-facing half — eval.ts and realm.ts know
+// nothing about the queue, which is what keeps the containment strategy swappable.
+//
+// See README.md for the contract, and specs/external-task-queue.md for the queue itself.
+
+import { evaluate, type EvalRequest, type FailureKind } from "./eval.ts";
+
+const SERVER = (process.env.GENROC_SERVER ?? "http://localhost:8448").replace(/\/$/, "");
+const WORKER_ID = process.env.WORKER_ID ?? `evaluator-${process.pid}`;
+// The credential, when the server runs with --auth token. A worker needs exactly the `worker`
+// permission — the four queue verbs plus GET /api/objects — so mint it scoped rather than
+// handing a worker an admin token: this is the credential most likely to sit on a machine you
+// trust least. specs/api-auth.md §5.
+//
+// Sent as a header rather than in the URL because Node's fetch REFUSES a URL carrying
+// credentials ("Request cannot be constructed from a URL that includes credentials"), so the
+// basic-auth-in-the-URL trick that works for genctl is not available here.
+const TOKEN = process.env.GENROC_TOKEN ?? "";
+const authHeaders: Record<string, string> = TOKEN ? { authorization: `Bearer ${TOKEN}` } : {};
+// Concurrency is the worker's to set, and that is the point of pulling: under the old fetch
+// shape genroc decided how many scripts ran at once (--max-concurrent, default 200) and the
+// evaluator accepted every one of them. Here it claims what it can run and no more, so a
+// backlog is a queue rather than 200 threads fighting over a core.
+const CONCURRENCY = Number(process.env.CONCURRENCY ?? 4);
+const POLL_MS = Number(process.env.POLL_MS ?? 250);
+// The visibility timeout. Short, and renewed while work is in flight: a worker that dies
+// should return its task quickly rather than holding it for the whole budget.
+const LEASE_MS = Number(process.env.LEASE_MS ?? 30_000);
+const RENEW_MS = Math.max(1_000, Math.floor(LEASE_MS / 3));
+const PROCESS_FILTER = process.env.PROCESS ?? "";
+const TASK_FILTER = process.env.TASK ?? "";
+
+type ObjectEntry = { path: (string | number)[]; ref: string; size: number };
+
+type QueueTask = {
+  token: string;
+  process: string;
+  task_id: string;
+  input: unknown;
+  objects?: ObjectEntry[];
+  raises?: Record<string, unknown>;
+};
+
+// Values too large to ship inline are listed rather than carried, and a bundle is exactly that:
+// one object shared by every instance of a definition version, fetched once instead of copied
+// into each task. A ref is a content hash, so it is immutable — the cache never invalidates.
+const objectCache = new Map<string, unknown>();
+
+async function fetchObject(ref: string): Promise<unknown> {
+  const cached = objectCache.get(ref);
+  if (cached !== undefined) return cached;
+  // Left to throw on purpose: this runs while a task is IN FLIGHT, and a task whose input
+  // cannot be fetched must fail rather than silently run against a missing value. The caller
+  // releases the claim, so the task returns to the queue.
+  const res = await fetch(`${SERVER}/api/objects/${encodeURIComponent(ref)}`, { headers: authHeaders });
+  if (!res.ok) throw new Error(`fetch object ${ref}: HTTP ${res.status}`);
+  const { data } = (await res.json()) as { data: string };
+  let value: unknown;
+  try {
+    value = JSON.parse(data);
+  } catch {
+    value = data;
+  }
+  objectCache.set(ref, value);
+  return value;
+}
+
+/** Put each listed value back where its path says it belongs. Paths are arrays of keys, so this
+ *  needs no parser: the whole reason they are not JSON Pointer strings. */
+async function resolveObjects(job: QueueTask): Promise<unknown> {
+  let input: any = job.input;
+  for (const e of job.objects ?? []) {
+    const value = await fetchObject(e.ref);
+    if (e.path.length === 0) {
+      input = value;
+      continue;
+    }
+    // The path is rooted at the entry and starts with "input", which is the value being rebuilt.
+    const rest = e.path[0] === "input" ? e.path.slice(1) : e.path;
+    if (rest.length === 0) {
+      input = value;
+      continue;
+    }
+    let cur: any = input;
+    for (let i = 0; i < rest.length - 1; i++) cur = cur?.[rest[i]!];
+    if (cur) cur[rest[rest.length - 1]!] = value;
+  }
+  return input;
+}
+
+async function call(path: string, body: unknown): Promise<{ ok: boolean; status: number; data: any }> {
+  // A network error is a REPLY, not a throw. A worker outlives the server it polls — a
+  // restart, a rolling deploy, a container coming up before genroc is listening — and an
+  // unhandled rejection here kills it for a condition the next poll would clear. Status 0
+  // says "never reached the server", which is distinct from anything genroc answers.
+  let res: Response;
+  try {
+    res = await fetch(SERVER + path, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    return { ok: false, status: 0, data: { error: `${SERVER} unreachable: ${(err as Error).message}` } };
+  }
+  const text = await res.text();
+  let data: any = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { error: text };
+  }
+  return { ok: res.ok, status: res.status, data };
+}
+
+/** The task input IS an EvalRequest: `code` required, `input` and `timeout_ms` optional. A task
+ *  whose input is not that shape is the definition's fault, not the script's, and is reported
+ *  as a compile_error — the nearest permanent kind, since no retry can fix the definition. */
+function asEvalRequest(input: unknown): EvalRequest | string {
+  if (typeof input !== "object" || input === null) return "the task input is not an object";
+  const r = input as Record<string, unknown>;
+  if (typeof r.code !== "string") return "the task input has no `code` string";
+  return {
+    code: r.code,
+    input: r.input,
+    timeout_ms: typeof r.timeout_ms === "number" ? r.timeout_ms : undefined,
+  };
+}
+
+const inFlight = new Map<string, QueueTask>();
+let running = true;
+
+// Whether the last claim reached genroc. A worker polls several times a second, so an
+// unreachable server would otherwise emit a line per poll — thousands during a restart, which
+// buries the one line that mattered. Announce the TRANSITIONS instead: going away, and coming
+// back. Silence in between is the report that nothing changed.
+let serverReachable = true;
+
+async function claim(n: number): Promise<QueueTask[]> {
+  const { ok, status, data } = await call("/api/external-tasks/claim", {
+    worker_id: WORKER_ID,
+    limit: n,
+    lease_ms: LEASE_MS,
+    ...(PROCESS_FILTER ? { process: PROCESS_FILTER } : {}),
+    ...(TASK_FILTER ? { task: TASK_FILTER } : {}),
+  });
+  if (!ok) {
+    // A credential problem is not transient, and polling through it looks like a healthy
+    // worker that never picks anything up — the worst shape for an operator to debug. Exit
+    // instead, so a supervisor restarts it and the failure is visible where it happened.
+    if (status === 401 || status === 403) {
+      console.error(
+        `claim rejected (${status}): ${JSON.stringify(data)}\n` +
+          `The server requires authentication. Set GENROC_TOKEN to a token with the 'worker' ` +
+          `permission — mint one with: genctl token create --perms worker --label evaluator -q`,
+      );
+      process.exit(1);
+    }
+    // status 0 is "never reached the server" (see call): a restart, a rolling deploy, a
+    // network blip. Not an error to act on — the next poll clears it — so it is reported once
+    // and then waited out.
+    if (status === 0) {
+      if (serverReachable) {
+        serverReachable = false;
+        console.error(
+          `genroc at ${SERVER} is unreachable — ${(data as { error?: string })?.error ?? ""}. ` +
+            `Still polling every ${POLL_MS}ms; work resumes when it comes back.`,
+        );
+      }
+      return [];
+    }
+    console.error(`claim failed: ${JSON.stringify(data)}`);
+    return [];
+  }
+  if (!serverReachable) {
+    serverReachable = true;
+    console.error(`genroc at ${SERVER} is reachable again — resuming.`);
+  }
+  return (data?.items ?? []) as QueueTask[];
+}
+
+async function release(token: string): Promise<void> {
+  const { ok, data } = await call("/api/external-tasks/release", { token });
+  if (!ok) console.error(`release failed: ${JSON.stringify(data)}`);
+}
+
+/** answer submits the outcome. A refusal is NOT retried with a different one: the definition
+ *  declared a contract this worker does not satisfy (an undeclared code, a payload that does
+ *  not fit `raises`), and guessing again would only pick a second wrong answer. Release it, so
+ *  the task returns to the queue and an operator sees it waiting rather than silently gone. */
+async function answer(token: string, outcome: Record<string, unknown>): Promise<void> {
+  const { ok, data } = await call("/api/external-tasks/resolve", { token, ...outcome });
+  if (ok) return;
+  console.error(`genroc refused the outcome for ${token}: ${JSON.stringify(data)}`);
+  await release(token);
+}
+
+async function run(job: QueueTask): Promise<void> {
+  let resolved: unknown;
+  try {
+    resolved = await resolveObjects(job);
+  } catch (err) {
+    // The values are there or they are not; this is the runner failing to read them, not the
+    // script failing, so hand the task back for someone else rather than reporting an outcome.
+    console.error(`resolving objects for ${job.token}: ${err instanceof Error ? err.message : String(err)}`);
+    await release(job.token);
+    return;
+  }
+  const req = asEvalRequest(resolved);
+  if (typeof req === "string") {
+    await answer(job.token, {
+      error: { code: "compile_error", message: req, data: { name: "BadTaskInput" } },
+    });
+    return;
+  }
+
+  let result;
+  try {
+    result = await evaluate(req);
+  } catch (err) {
+    // The RUNNER faulted, not the script — the one class where a retry can help. There is no
+    // error code for it on purpose: releasing the claim is how a queue spells "retryable", and
+    // it puts the task in front of a different worker instead of burning the definition's
+    // on_error budget on this one's bad day.
+    console.error(`evaluator fault on ${job.token}: ${err instanceof Error ? err.message : String(err)}`);
+    await release(job.token);
+    return;
+  }
+
+  if (result.ok) {
+    // `body` is JSON text produced inside the realm; an empty body is a script that returned
+    // nothing, which genroc reads as null.
+    await answer(job.token, { result: result.body === "" ? null : JSON.parse(result.body) });
+    return;
+  }
+  const f = result.failure;
+  await answer(job.token, {
+    error: {
+      // The failure KIND is the code, so an on_error rule branches on what went wrong without
+      // reading a payload. Every kind is permanent; see eval.ts.
+      code: f.kind satisfies FailureKind,
+      message: f.message,
+      data: { name: f.name, ...(f.stack ? { stack: f.stack } : {}) },
+    },
+  });
+}
+
+async function renewLoop(): Promise<void> {
+  while (running) {
+    await new Promise((r) => setTimeout(r, RENEW_MS));
+    const tokens = [...inFlight.keys()];
+    if (!tokens.length) continue;
+    const { ok, data } = await call("/api/external-tasks/renew", {
+      worker_id: WORKER_ID,
+      tokens,
+      lease_ms: LEASE_MS,
+    });
+    // A short count means a claim lapsed and was taken over. Nothing to do about it — the work
+    // continues and its answer will be refused — but say so, because it is the signal that
+    // LEASE_MS is too short for what these scripts actually take.
+    if (ok && data?.renewed < tokens.length) {
+      console.error(`renewed ${data.renewed}/${tokens.length} claims; a lease lapsed under load`);
+    }
+  }
+}
+
+async function pollLoop(): Promise<void> {
+  while (running) {
+    const free = CONCURRENCY - inFlight.size;
+    const jobs = free > 0 ? await claim(free) : [];
+    for (const job of jobs) {
+      inFlight.set(job.token, job);
+      void run(job).finally(() => inFlight.delete(job.token));
+    }
+    // Only idle when there was nothing to take: a full queue should be drained at the speed the
+    // realms allow, not at the poll interval.
+    if (jobs.length === 0) await new Promise((r) => setTimeout(r, POLL_MS));
+  }
+}
+
+async function shutdown(signal: string): Promise<void> {
+  if (!running) return;
+  running = false;
+  const tokens = [...inFlight.keys()];
+  console.log(`${signal}: releasing ${tokens.length} claim(s)`);
+  // Hand work back rather than letting it sit out its lease. The evaluations still running are
+  // abandoned, which is exactly what the release says: nobody answered.
+  await Promise.all(tokens.map(release));
+  process.exit(0);
+}
+
+process.on("SIGINT", () => void shutdown("SIGINT"));
+process.on("SIGTERM", () => void shutdown("SIGTERM"));
+
+console.log(
+  `evaluator worker ${WORKER_ID} polling ${SERVER} (concurrency=${CONCURRENCY}, lease=${LEASE_MS}ms)`,
+);
+void renewLoop();
+void pollLoop();