@plurnk/plurnk-service 1.0.4 → 1.0.6

package/dist/core/PacketBuilder.js

@@ -1,8 +1,9 @@
 var _a;
 import { renderAddress, promptLoopPrefix } from "./plurnk-uri.js";
-import { teachingLine, docsExcludeSet } from "./teaching.js";
+import { rulerCount } from "./token-ruler.js";
+import { docsExcludeSet } from "./teaching.js";
 import { Policy } from "@plurnk/plurnk-execs";
-import SessionSettings from "./session-settings.js";
+import WorkspaceSettings from "./workspace-settings.js";
 import { DEFAULT_LOOP_FLAGS } from "./scheme-types.js";
 import { readPacketInject, readSystemPolicy, readProjectPolicy } from "./packet-inject.js";
 import { readFile } from "node:fs/promises";
@@ -19,6 +20,7 @@ import ProviderInstantiate from "./ProviderInstantiate.js";
 const TOKENS_FREE_PLACEHOLDER = "{{tokensFree}}";
 const TOKEN_USAGE_PLACEHOLDER = "{{tokenUsage}}";
 const TOKEN_PERCENT_PLACEHOLDER = "{{tokenPercent}}";
+const SYSTEM_CTX_PLACEHOLDER = "{{systemCtx}}"; // #440 — treemap's non-turn overhead = total − Σturns, known only post-assembly
 // §tokenomics-window-partition — the four partition numbers. REQUIRED (fail-hard, the
 // providers-env convention): the ceiling is DERIVED from these, never set directly
 // (PLURNK_BUDGET_CEILING is retired — a settable ceiling let policy contradict physics).
@@ -58,14 +60,21 @@ class PacketBuilder {
     // scopeEnvToAlias resolves PLURNK_SERVICE_*_<alias> over the bare fallback with providers' own
     // battle-tested suffix parser. Cached per alias; the boot-global case falls back to the active
     // alias when a provider carries no side-table entry (a test Mock).
-    static #KNOBS = ["PLURNK_SERVICE_CTX", "PLURNK_SERVICE_REASONING", "PLURNK_SERVICE_ASSISTANT", "PLURNK_SERVICE_SAFETY"];
+    static #KNOBS = ["PLURNK_SERVICE_CONTEXT_WINDOW", "PLURNK_SERVICE_REASONING", "PLURNK_SERVICE_COMPLETION", "PLURNK_SERVICE_SAFETY"];
     #partitions = new Map();
     #resolvePartition(alias) {
+        // #472 hard shed (OpenAI lexicon ruling) — the retired llama.cpp-speak names fail LOUD at the
+        // read boundary; a stale operator .env must never silently lose its ceiling to a rename.
+        for (const k of Object.keys(process.env)) {
+            const m = /^PLURNK_SERVICE_(CTX|ASSISTANT)(_.*)?$/.exec(k);
+            if (m !== null)
+                throw new Error(`${k} is retired (#472): the knob is PLURNK_SERVICE_${m[1] === "CTX" ? "CONTEXT_WINDOW" : "COMPLETION"}${m[2] ?? ""}.`);
+        }
         const view = scopeEnvToAlias(process.env, alias, _a.#KNOBS);
         return {
-            ctx: readPartitionIntFrom(view, "PLURNK_SERVICE_CTX", 1),
+            contextWindow: readPartitionIntFrom(view, "PLURNK_SERVICE_CONTEXT_WINDOW", 1),
             reasoning: readPartitionIntFrom(view, "PLURNK_SERVICE_REASONING", 0),
-            assistant: readPartitionIntFrom(view, "PLURNK_SERVICE_ASSISTANT", 0),
+            completion: readPartitionIntFrom(view, "PLURNK_SERVICE_COMPLETION", 0),
             safety: readPartitionIntFrom(view, "PLURNK_SERVICE_SAFETY", 0),
         };
     }
@@ -88,20 +97,20 @@ class PacketBuilder {
         }
         return false;
     }
+    // #421 — §tokenomics-window-unpollable-deliberate: an unpollable window (provider.contextWindow null
+    // after env/probe/catalog all miss) with NO per-alias knob is genuinely-unknown — nobody chose an
+    // envelope. The budget/ceiling short-circuit that window to NO-CAP (#isUnboundedWindow) rather than
+    // substitute a stand-in the operator never chose; the bare partition still feeds maxTokensFor's
+    // generation reserves, which the backend clamps. A per-alias CONTEXT_WINDOW knob makes the window DELIBERATE
+    // and it flows bounded, normally.
+    #isUnboundedWindow(provider) {
+        if (provider.contextWindow !== null)
+            return false;
+        const alias = ProviderInstantiate.aliasOf(provider) ?? resolveActiveAlias(process.env)?.alias ?? "";
+        return !_a.#hasAliasKnob(alias);
+    }
     #partitionFor(provider) {
         const alias = ProviderInstantiate.aliasOf(provider) ?? resolveActiveAlias(process.env)?.alias ?? "";
-        // #377 — §tokenomics-window-unpollable-deliberate: "CTX stands in for unknown physics" is
-        // only honest when the CTX is the operator's DELIBERATE policy for THIS alias. An unpollable
-        // window (provider.contextSize null — the provider's machine signal after env/probe/catalog
-        // all miss) riding BARE partition numbers is nobody's policy: numbers tuned for some other
-        // model silently applied, surfacing later as truncation/overflow telemetry (#352's failure
-        // mode recurring for every unpollable model). Fail loud at first use, naming both remedies.
-        if (provider.contextSize === null && !_a.#hasAliasKnob(alias)) {
-            // BEFORE the cache lookup — the constructor pre-primes the boot alias's partition, and a
-            // cache hit must never bypass this refusal (the check keys on the PROVIDER's null window,
-            // which the cached partition knows nothing about).
-            throw new Error(`window unpollable for alias '${alias || "<active>"}' and its partition rides bare numbers — nobody chose this envelope for this model. Either set PLURNK_PROVIDERS_CONTEXT_SIZE_${alias || "<alias>"} (so the window is known) or set the per-alias partition (PLURNK_SERVICE_{CTX,REASONING,ASSISTANT,SAFETY}_${alias || "<alias>"}) so the numbers are deliberate.`);
-        }
         const hit = this.#partitions.get(alias);
         if (hit !== undefined)
             return hit;
@@ -109,15 +118,15 @@ class PacketBuilder {
         this.#partitions.set(alias, part);
         return part;
     }
-    // The generation envelope — REASONING + ASSISTANT, one undifferentiated pool, passed on
+    // The generation envelope — REASONING + COMPLETION, one undifferentiated pool, passed on
     // every generate({maxTokens}): no decode is unbounded (§tokenomics-window-partition). Per
     // alias (#352): gemma's measured envelope; a cloud alias's generous default the backend clamps.
-    decodeBudget(provider) {
-        const { reasoning, assistant } = this.#partitionFor(provider);
-        return reasoning + assistant;
+    maxTokensFor(provider) {
+        const { reasoning, completion } = this.#partitionFor(provider);
+        return reasoning + completion;
     }
-    // §tokenomics-window-partition ÷ §tokenomics-ceiling-calibrates-to-usage — the prompt ceiling
-    // is DERIVED, never set: effectiveWindow = min(CTX, provider window; CTX alone when the
+    // §tokenomics-window-partition — the prompt ceiling
+    // is DERIVED, never set: effectiveWindow = min(CONTEXT_WINDOW, provider window; CONTEXT_WINDOW alone when the
     // provider reports none) minus the reserves, divided by the loop's observed real/measured
     // token ratio (usage.prompt is ground truth; a heuristic ruler shipped a 65k-real packet into
     // a 49k window, #311). A fractional ceiling also budgeted the prompt against the window and
@@ -128,31 +137,34 @@ class PacketBuilder {
     // space (usage.prompt, the numerator, is real; the calibration ratio maps measured→real and
     // has no business here). The raw n_ctx overstates usable room by the reserve total.
     promptBudgetFor(provider) {
-        const { ctx, reasoning, assistant, safety } = this.#partitionFor(provider);
-        const effectiveWindow = provider.contextSize === null ? ctx : Math.min(ctx, provider.contextSize);
-        return Math.max(0, effectiveWindow - reasoning - assistant - safety);
+        if (this.#isUnboundedWindow(provider))
+            return null; // #421 — no cap: an unknown window has no denominator
+        const { contextWindow, reasoning, completion, safety } = this.#partitionFor(provider);
+        const effectiveWindow = provider.contextWindow === null ? contextWindow : Math.min(contextWindow, provider.contextWindow);
+        return Math.max(0, effectiveWindow - reasoning - completion - safety);
     }
-    // tokenRatio is real/measured, calibrated by Engine per loop (§tokenomics-ceiling-calibrates-to-usage).
-    // BELOW 1 is legitimate: a certified upper-bound ruler (no exact tokenizer)
-    // overmeasures, and the ceiling expands to observed truth — Engine applies the floor for
-    // exact rulers; this method trusts its input (run24: the floor-at-1 halved gbuild's window).
-    ceilingFor(provider, tokenRatio = 1) {
-        if (tokenRatio <= 0)
-            throw new Error(`ceilingFor: tokenRatio must be > 0, got ${tokenRatio}`);
-        const { ctx, reasoning, assistant, safety } = this.#partitionFor(provider);
-        const effectiveWindow = provider.contextSize === null ? ctx : Math.min(ctx, provider.contextSize);
-        const promptBudget = effectiveWindow - reasoning - assistant - safety;
+    // §tokenomics-agnostic-ruler — the ceiling is the real window partition (window − reserves),
+    // NO calibration ratio: the model-facing measure is the chars/2 ruler (an over-count for
+    // typical text), so comparing ruler-weight to the real-token ceiling is itself the conservative
+    // bias — the model curates against less room than it has and never overflows for typical
+    // content; the exact provider count guards the pathological tail at the materialization gate.
+    ceilingFor(provider) {
+        if (this.#isUnboundedWindow(provider))
+            return null; // #421 — no cap: the gauge headline is omitted
+        const { contextWindow, reasoning, completion, safety } = this.#partitionFor(provider);
+        const effectiveWindow = provider.contextWindow === null ? contextWindow : Math.min(contextWindow, provider.contextWindow);
+        const promptBudget = effectiveWindow - reasoning - completion - safety;
         if (promptBudget <= 0) {
             const alias = ProviderInstantiate.aliasOf(provider) ?? resolveActiveAlias(process.env)?.alias ?? "";
-            throw new Error(`window partition contradiction for alias '${alias}': effective window ${effectiveWindow} <= reserves ${reasoning}+${assistant}+${safety}. A local (llama-server) alias needs its OWN measured envelope — set PLURNK_SERVICE_{CTX,REASONING,ASSISTANT,SAFETY}_${alias || "<alias>"} (the bare defaults are cloud-generous; #352).`);
+            throw new Error(`window partition contradiction for alias '${alias}': effective window ${effectiveWindow} <= reserves ${reasoning}+${completion}+${safety}. A local (llama-server) alias needs its OWN measured envelope — set PLURNK_SERVICE_{CONTEXT_WINDOW,REASONING,COMPLETION,SAFETY}_${alias || "<alias>"} (the bare defaults are cloud-generous; #352).`);
         }
-        return Math.floor(promptBudget / tokenRatio);
+        return promptBudget;
     }
     // Assemble the request half of the spec'd packet (Packet.json system
     // and §user) BEFORE the provider call. The same packet object is then
     // completed with assistant + assistantRaw after the model responds, so
     // the stored packet and the wire payload share one source of truth.
-    async buildRequestPacket({ initialMessages, requirements, sessionId, runId, loopId, currentTurnSeq, provider, gitStatus, tokenRatio = 1, telemetryErrors: presetTelemetry, }) {
+    async buildRequestPacket({ initialMessages, requirements, workspaceId, workerId, loopId, currentTurnSeq, provider, gitStatus, telemetryErrors: presetTelemetry, }) {
         const byRole = (role) => initialMessages.filter((m) => m.role === role).map((m) => m.content).join("\n\n");
         // plurnk.md (grammar/dialects) ONLY — the definition is the hot-path grammar.
         // The scheme catalogue is its own `schemes` section below tools (§schemes-directory),
@@ -165,7 +177,7 @@ class PacketBuilder {
         // the runLoop caller's messages.user for tests that bypass the
         // foist mechanism entirely.
         const loopSeqRow = await this.#db.engine_loop_sequence.get({ loop_id: loopId });
-        const promptRows = (await this.#db.drain_get_all_prompt_bodies_for_loop.all({ pattern: `${promptLoopPrefix(runId, loopSeqRow?.sequence ?? loopId)}%` }))
+        const promptRows = (await this.#db.drain_get_all_prompt_bodies_for_loop.all({ pattern: `${promptLoopPrefix(workerId, loopSeqRow?.sequence ?? loopId)}%` }))
             .filter((r) => typeof r.content === "string" && r.content.length > 0);
         // §prompt-auto-read (owner): the section is a PATHS list (the errors shape — no bodies);
         // each prompt's content reaches the model through its foisted auto-READ in the log, and
@@ -184,14 +196,14 @@ class PacketBuilder {
         // leads requirements.md, so a third copy here was pure duplication in the model's packet. PLAN
         // is mandated unconditionally by plurnk.md §Imperatives (grammar 0.70 requires every turn to
         // lead with PLAN), so the service injects no separate plan directive either.
-        const log = await this.#buildLog(runId);
+        const log = await this.#buildLog(workerId);
         const telemetryErrors = presetTelemetry ?? await this.buildTelemetryErrors(loopId, currentTurnSeq);
-        const countTokens = (t) => provider.countTokens(t); // §provider-surface-counttokens
-        // #367 — the capability sheet must reflect the LOOP MODE, not just session-enablement: an
+        const countTokens = rulerCount; // §tokenomics-agnostic-ruler — the ONE model-facing ruler (chars/2), not the provider
+        // #367 — the capability sheet must reflect the LOOP MODE, not just workspace-enablement: an
         // ask-mode loop advertises only what its dispatch gate (resolveForLoop) will accept, so the
         // model is never taught a tag it'll then be 403'd on (the taught→emitted→rejected→508 spiral).
         const activeSchemes = this.#schemes.resolveForLoop(await this.#loadLoopFlags(loopId));
-        const tools = this.#collectTools(await this.#sessionEnabled(sessionId), await SessionSettings.questionsEnabled(this.#db, sessionId), activeSchemes);
+        const tools = this.#collectTools(await this.#workspaceEnabled(workspaceId), await WorkspaceSettings.questionsEnabled(this.#db, workspaceId), activeSchemes);
         // Budget readout (SPEC.md §tokenomics). Two-pass: render the budget from
         // the structured log's subtotals with a {{tokensFree}} placeholder, build
         // the section list, measure the assembled total, resolve free, substitute.
@@ -199,8 +211,9 @@ class PacketBuilder {
         // a serialized approximation. ceiling is the provider's window ×
         // PLURNK_BUDGET_CEILING (null when no window is reported → headline
         // omitted, section lines still shown). §tokenomics-render-weight-budget
-        const ceiling = this.ceilingFor(provider, tokenRatio);
-        const budgetReadout = this.#renderBudget(PacketWire.measureLogBudget(log, countTokens), ceiling);
+        const ceiling = this.ceilingFor(provider);
+        const logBudget = PacketWire.measureLogBudget(log, countTokens);
+        const budgetReadout = this.#renderBudget(logBudget, ceiling);
         // The default packet: an ordered list of addressable sections (§packet-assembly).
         // `slot` is a TRUST boundary (and the prompt-cache boundary): system holds only
         // framework-authored, non-injectable sections — the static head (definition/tools/
@@ -209,24 +222,24 @@ class PacketBuilder {
         // the requirements footer. The budget section carries its {{tokensFree}} placeholders
         // here; they resolve below once the assembled total is known.
         const inject = await readPacketInject(); // #240 — operator section, per-turn, fail-hard on a broken path
-        const sessionRoot = (await this.#db.envelope_get_session.get({ id: sessionId }))?.project_root ?? null;
+        const workspaceRoot = (await this.#db.envelope_get_workspace.get({ id: workspaceId }))?.project_root ?? null;
         const systemPolicy = await readSystemPolicy(); // ~/.plurnk/AGENTS.md (or PLURNK_SERVICE_POLICY)
-        const projectPolicy = await readProjectPolicy(sessionRoot); // <projectRoot>/AGENTS.md (or PLURNK_SERVICE_PROJECT)
+        const projectPolicy = await readProjectPolicy(workspaceRoot); // <projectRoot>/AGENTS.md (or PLURNK_SERVICE_PROJECT)
         // Child-orientation (§child-orientation): the live things THIS run holds — open streams +
-        // unconcluded child runs — surfaced every turn as terse `* <status> <path>` pointers (same shape
+        // unconcluded child workers — surfaced every turn as terse `* <status> <path>` pointers (same shape
         // as errors) just above the errors section. Orienting STATE so the model never loses track of
         // what it's holding (the premature-terminate trap), never advice on what to do. Empty → omitted.
-        const childStreams = (await this.#db.engine_child_streams_open.all({ run_id: runId }))
+        const childStreams = (await this.#db.engine_child_streams_open.all({ worker_id: workerId }))
             .map((s) => ({ status: "active", path: renderAddress(s.scheme, s.pathname) }));
-        const childRuns = (await this.#db.engine_child_runs_live.all({ run_id: runId }))
-            .map((r) => ({ status: r.status, path: `run://${r.name}` }));
+        const childWorkers = (await this.#db.engine_child_workers_live.all({ worker_id: workerId }))
+            .map((r) => ({ status: r.status, path: `worker://${r.name}` }));
         const defaults = [
             { name: "definition", slot: "system", header: null, content: system_definition, tokens: 0 },
-            { name: "tools", slot: "system", header: null, content: tools.join("\n"), tokens: 0 }, // titleless — the examples flow on from plurnk.md (definition) directly above
-            { name: "schemes", slot: "system", header: "Plurnk Service Schemes", content: this.#schemes.teach(), tokens: 0 },
-            ...(inject !== null ? [{ name: "inject", slot: "system", header: "Plurnk Operator Notes", content: inject, tokens: 0 }] : []),
+            { name: "tools", slot: "system", header: null, content: tools, tokens: 0 }, // titleless — the fenced op catalog flows on from plurnk.md (definition) directly above
+            { name: "schemes", slot: "system", header: "Schemes", content: this.#schemes.teach(), tokens: 0 },
+            ...(inject !== null ? [{ name: "inject", slot: "system", header: "Operator Notes", content: inject, tokens: 0 }] : []),
             // policy: the client's privileged rules — ~/.plurnk/AGENTS.md (system) then <root>/AGENTS.md (project) — below grammar/tools/schemes, above budget-the-law. AGENTS is POLICY here, never a curatable READable entry. Empty content ⇒ section omitted.
-            { name: "system-policy", slot: "system", header: "Plurnk Service Policy", content: systemPolicy ?? "", tokens: 0 },
+            { name: "system-policy", slot: "system", header: "Policy", content: systemPolicy ?? "", tokens: 0 },
             { name: "project-policy", slot: "system", header: "Project Policy", content: projectPolicy ?? "", tokens: 0 },
             // The packet split is a TRUST boundary: system carries only framework-authored, non-injectable
             // sections; anything that could carry attacker-reachable text (a READ result, exec output, the
@@ -235,19 +248,19 @@ class PacketBuilder {
             // neither is an injection surface; both sit at the bottom of system, just above budget-the-law.
             // child-orientation: what THIS run holds live — streams then runs — just above errors. Terse
             // pointers (the path is the actionable address the model READs/OPENs/KILLs), never advice. §child-orientation
-            { name: "child-streams", slot: "system", header: "Plurnk Service Child Streams", content: PacketWire.renderChildPointers(childStreams), tokens: 0 },
-            { name: "child-runs", slot: "system", header: "Plurnk Service Active Child Worker Runs", content: PacketWire.renderChildPointers(childRuns), tokens: 0 },
-            { name: "errors", slot: "system", header: "Plurnk Service Errors", content: PacketWire.renderErrors(telemetryErrors), tokens: 0 },
-            { name: "git", slot: "system", header: "Plurnk Service Git Status", content: PacketWire.renderGit(gitStatus), tokens: 0 },
+            { name: "child-streams", slot: "system", header: "Child Streams", content: PacketWire.renderChildPointers(childStreams), tokens: 0 },
+            { name: "child-workers", slot: "system", header: "Active Child Workers", content: PacketWire.renderChildPointers(childWorkers), tokens: 0 },
+            { name: "errors", slot: "system", header: "Errors", content: PacketWire.renderErrors(telemetryErrors), tokens: 0 },
+            { name: "git", slot: "system", header: "Git Status", content: PacketWire.renderGit(gitStatus), tokens: 0 },
             // budget — LAW (a hard ceiling the model must obey).
-            { name: "budget", slot: "system", header: "Plurnk Service Budget", content: budgetReadout, tokens: 0 },
+            { name: "budget", slot: "system", header: "Budget", content: budgetReadout, tokens: 0 },
             // §prompt-auto-read (owner): the prompts section is the system slot's very bottom —
             // a paths-only list (the errors shape); bodies arrive via the foisted auto-READ.
-            { name: "prompt", slot: "system", header: "Plurnk Service User Prompts", content: prompt, tokens: 0 },
+            { name: "prompt", slot: "system", header: "User Prompts", content: prompt, tokens: 0 },
             // log in the user slot: injectable content (READ results, exec output, the model's own mirror) — data, never rules — kept at the action point so the model consults its history.
-            { name: "log", slot: "user", header: "Plurnk Service Log", content: PacketWire.renderLog(log, countTokens), tokens: 0 },
+            { name: "log", slot: "user", header: "Log", content: PacketWire.renderLog(log, countTokens), tokens: 0 },
             // requirements renders LAST — the user-slot footer, the syntax contract closest to the model's turn (a recency carve-out for weak models).
-            { name: "requirements", slot: "user", header: "Plurnk Service Requirements", content: baseRequirements, tokens: 0 },
+            { name: "requirements", slot: "user", header: "Recap", content: baseRequirements, tokens: 0 },
         ];
         // Plugin packet control (§packet-assembly): trusted schemes rewrite the
         // default list — add, remove, reorder — in-process, before measurement.
@@ -257,14 +270,18 @@ class PacketBuilder {
         let total = countTokens(PacketWire.renderSlot(sections, "system")) + countTokens(PacketWire.renderSlot(sections, "user"));
         {
             const budgetSec = sections.find((s) => s.name === "budget"); // a plugin may have removed it
-            if (budgetSec) {
+            // A null ceiling (#421 — unbounded window) has no headline to calibrate: no truncation, no
+            // percent/free substitution. #renderBudget already omitted the headline, so nothing to do.
+            if (budgetSec && ceiling !== null) {
                 // Curation pressure gates on OCCUPANCY (§tokenomics-pressure-gates-on-occupancy, #308):
                 // the Turns/Heaviest tables are a standing FOLD-target list, and a high-headroom model
                 // reads them as a todo — burning turns on token hygiene at 3% of a 64k window. Under
                 // half-full, the headline's numbers stand alone (truncate at the first blank line) and
                 // the total RE-measures — the substituted figures must reconcile with what ships.
                 // A null ceiling can't calibrate, so the full readout stays.
-                if ((total / ceiling) * 100 < 50) {
+                // A mermaid budget (#440) self-scales to pressure, so it is never truncated — the calm
+                // low-usage view IS the point; only the tabular readout collapses under half-full.
+                if (!budgetSec.content.includes("```mermaid") && (total / ceiling) * 100 < 50) {
                     const cut = budgetSec.content.indexOf("\n\n");
                     if (cut !== -1) {
                         budgetSec.content = budgetSec.content.slice(0, cut);
@@ -273,12 +290,17 @@ class PacketBuilder {
                 }
                 const tokensFree = Math.max(0, ceiling - total); // free floors at 0 on overshoot — §tokenomics-over-budget-floor
                 const percent = (total / ceiling) * 100; // usage as % of the ceiling — §tokenomics-context-percent
+                const sumTurns = logBudget.byTurn.reduce((s, t) => s + t.tokens, 0); // #440 — treemap non-turn box = total − Σturns
+                const systemCtx = Math.max(0, total - sumTurns);
+                // replaceAll: a mermaid budget recurs free/used across the headline + treemap + pie, so a
+                // single .replace would leave the diagrams carrying literal {{…}} placeholders.
                 budgetSec.content = budgetSec.content
-                    .replace(TOKEN_USAGE_PLACEHOLDER, String(total))
+                    .replaceAll(TOKEN_USAGE_PLACEHOLDER, String(total))
                     // Any nonzero usage under 1% is "<1" — Math.round alone claimed "1%" from 0.51%,
                     // overstating a near-empty window.
-                    .replace(TOKEN_PERCENT_PLACEHOLDER, total > 0 && percent < 1 ? "<1" : String(Math.round(percent)))
-                    .replace(TOKENS_FREE_PLACEHOLDER, String(tokensFree));
+                    .replaceAll(TOKEN_PERCENT_PLACEHOLDER, total > 0 && percent < 1 ? "<1" : String(Math.round(percent)))
+                    .replaceAll(TOKENS_FREE_PLACEHOLDER, String(tokensFree))
+                    .replaceAll(SYSTEM_CTX_PLACEHOLDER, String(systemCtx));
             }
         }
         // Pass 2: per-section render-weight + the assembled packet total (post
@@ -294,7 +316,23 @@ class PacketBuilder {
     // placeholder here — buildRequestPacket substitutes it after measuring the packet.
     #renderBudget(log, ceiling) {
         const lines = [];
-        lines.push(`Token Ceiling ${ceiling} · Token Usage ${TOKEN_USAGE_PLACEHOLDER} (${TOKEN_PERCENT_PLACEHOLDER}%) · Tokens Free ${TOKENS_FREE_PLACEHOLDER}`);
+        // #421 — no ceiling (unbounded window): omit the headline entirely; the section lines below
+        // stay so the model keeps its FOLD-target surface, just with no percent it can't compute.
+        if (ceiling !== null)
+            lines.push(`Token Ceiling ${ceiling} · Token Usage ${TOKEN_USAGE_PLACEHOLDER} (${TOKEN_PERCENT_PLACEHOLDER}%) · Tokens Free ${TOKENS_FREE_PLACEHOLDER}`);
+        // #440 {§budget-mermaid} — the enriched visual Budget (default on). With a ceiling to scale
+        // against, the treemap REPLACES the Turns table (per-turn composition) + a pie gauge; the
+        // heaviest-items list stays a table (#450). Self-scaled to pressure (calm→urgent), never <50%-truncated.
+        // Set PLURNK_SERVICE_BUDGET_MERMAID=off to A/B against the tabular baseline (#440's before/after).
+        if (process.env.PLURNK_SERVICE_BUDGET_MERMAID !== "off" && ceiling !== null && log.entries > 0) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push(_a.#renderBudgetMermaid(log, ceiling));
+            // #450 — the heaviest items stay a plain ranked list (a ranking isn't a composition, no
+            // treemap; two mermaid diagrams are enough visual examples) — the same table as the tabular budget.
+            lines.push(..._a.#heaviestItemsLines(log.largest));
+            return lines.join("\n");
+        }
         if (log.entries > 0) {
             if (lines.length > 0)
                 lines.push("");
@@ -306,23 +344,54 @@ class PacketBuilder {
                 for (const t of log.byTurn)
                     lines.push(`| ${t.turn} | ${t.tokens} |`);
             }
-            // The heaviest individual log items — the FOLD targets behind the weight
-            // (§tokenomics {§tokenomics-largest-entries}). "items", not "entries": the readout
-            // lists log:/// rows (log items), distinct from catalog entries (plurnk.md: "EDIT
-            // is only for entries. Do not attempt to edit log items.").
-            if (log.largest.length > 0) {
-                lines.push("", "Heaviest items (FOLD targets — folding reclaims their tokens):", "| item | tokens |", "|---|--:|");
-                for (const e of log.largest)
-                    lines.push(`| ${e.path} | ${e.tokens} |`);
-            }
+            lines.push(..._a.#heaviestItemsLines(log.largest));
         }
         return lines.join("\n");
     }
-    // #328 — the per-session client execs policy narrows what the packet ADVERTISES, matching what
-    // dispatch refuses: a session-disabled tag is absent from the capability sheet and the doc set,
+    // The heaviest individual log items — the FOLD targets behind the weight, a ranked LIST in both the
+    // mermaid and tabular budgets (#450: a ranking isn't a composition, so it's never a chart). "items",
+    // not "entries": log:/// rows, distinct from catalog entries (plurnk.md: "EDIT is only for entries").
+    // {§tokenomics-largest-entries}
+    static #heaviestItemsLines(largest) {
+        if (largest.length === 0)
+            return [];
+        return ["", "Heaviest items (FOLD targets — folding reclaims their tokens):", "| item | tokens |", "|---|--:|",
+            ...largest.map((e) => `| ${e.path} | ${e.tokens} |`)];
+    }
+    // #440 {§budget-mermaid} — the Budget as two budget-scaled mermaid diagrams (validated to render on
+    // GitHub; syntax: plurnk-plurnkdown/demo/budget-mermaid.md). Both scaled to the CEILING, so salience
+    // tracks pressure: `free` dominates at low usage (calm), turn boxes fill as it climbs (urgent).
+    // free/used/system+context are placeholders — the post-assembly total resolves them. (#450 cut the xychart.)
+    static #renderBudgetMermaid(log, ceiling) {
+        // Turn composition → treemap: turn boxes + system+context + free compose the whole ceiling —
+        // the per-turn FOLD surface (which turns are heavy, labeled `turn L/T`) the headline can't give.
+        const treemap = [
+            "```mermaid",
+            "treemap-beta",
+            `"Budget — ceiling ${ceiling}"`,
+            `    "free": ${TOKENS_FREE_PLACEHOLDER}`,
+            `    "system + context": ${SYSTEM_CTX_PLACEHOLDER}`,
+            ...log.byTurn.map((t) => `    "turn ${t.turn}": ${t.tokens}`),
+            "```",
+        ].join("\n");
+        // Gauge → pie: used vs free, budget-scaled (used + free = ceiling); also a visual exemplar for
+        // the model's own user-facing SENDs. (#450 cut the heaviest-items xychart — its bare-coordinate
+        // labels a floor model can't decode, and the treemap already surfaces per-turn heaviness.)
+        const pie = [
+            "```mermaid",
+            "pie showData",
+            `    title Budget — used vs free (ceiling ${ceiling})`,
+            `    "used" : ${TOKEN_USAGE_PLACEHOLDER}`,
+            `    "free" : ${TOKENS_FREE_PLACEHOLDER}`,
+            "```",
+        ].join("\n");
+        return [treemap, pie].join("\n\n");
+    }
+    // #328 — the per-workspace client execs policy narrows what the packet ADVERTISES, matching what
+    // dispatch refuses: a workspace-disabled tag is absent from the capability sheet and the doc set,
     // never taught-then-refused. No policy (execs unset) → everything boot-registered shows.
-    async #sessionEnabled(sessionId) {
-        const { execs } = await SessionSettings.read(this.#db, sessionId);
+    async #workspaceEnabled(workspaceId) {
+        const { execs } = await WorkspaceSettings.read(this.#db, workspaceId);
         if (execs === null)
             return () => true;
         return (tag) => Policy.isEnabled(tag, execs);
@@ -344,58 +413,55 @@ class PacketBuilder {
             return DEFAULT_LOOP_FLAGS;
         }
     }
-    #collectTools(sessionEnabled, questionsOn = false, activeSchemes) {
-        const tools = [];
+    #collectTools(workspaceEnabled, questionsOn = false, activeSchemes) {
+        // §PACKET Tools (#441) — the capability sheet's OP examples ride a `plurnk` fence, matching the
+        // Schemes catalog (one packet, one shape for op-example sheets). Prose notices (EXEC-disabled)
+        // stay prose beside the fence — a prose line isn't an op for the op-fence gate to validate.
+        const ops = [];
+        const notices = [];
         // §send-300-choices — the one-liner rides ONLY where questions are enabled (allowed +
         // client-requested); the fuller questions.md doc injects through docEntries the same way.
         if (questionsOn)
-            tools.push(teachingLine("<<SEND[300]:Deploy where?;staging;production:SEND"));
-        // Each available runtime tag contributes its self-documenting example —
-        // the example carries syntax + purpose, so there's no prose line. Tags
-        // with no example (sh/node, covered by the core prompt) contribute
-        // nothing; available-only, so the model never sees an unusable tag. `* `
-        // bullets + bare op forms match the packet's list/op rendering (no `- `,
-        // no backticks — see packet-wire.ts).
+            ops.push("<<SEND[300]:Deploy where?;staging;production:SEND");
         const executors = this.#executors();
         if (executors !== undefined) {
             const excluded = docsExcludeSet();
             const runtimes = executors.availableRuntimes();
-            // execs#24 (operator design, via the client) + the #367 filter CORRECTED: the per-tag
-            // runtime schemes are READ faces (reading sh:// history is legitimate in ask mode), so
-            // keying the sheet on activeSchemes.has(tag) filtered NOTHING — the untested corner of
-            // be8a77c. The sheet's lines are EXEC-usage examples, so the key is the 'exec' scheme
-            // (the op face, excludedInAsk). When it's inactive, say so POSITIVELY: plurnk.md still
-            // teaches EXEC as language, and silent absence measurably invites confabulated runtimes
-            // (the client's 5-probe: 500×3). Core speaks the line — only core knows the gate closed.
+            // execs#24 / #367: the sheet's lines are EXEC-usage examples, keyed on the 'exec' scheme
+            // (the op face, excludedInAsk). When inactive, say so POSITIVELY (a prose notice): plurnk.md
+            // still teaches EXEC as language, and silent absence measurably invites confabulated runtimes.
             const execActive = activeSchemes === undefined || activeSchemes.has("exec");
             if (runtimes.length > 0 && !execActive) {
-                tools.push(teachingLine("EXEC operations are disabled for this loop — do not run commands; answer or advise directly"));
-                return tools;
+                notices.push("EXEC operations are disabled for this loop — do not run commands; answer or advise directly");
             }
-            for (const tag of runtimes) {
-                if (excluded.has(tag))
-                    continue; // #240 — PLURNK_SERVICE_DOCS_EXCLUDE drops the oneliner + the doc
-                if (!sessionEnabled(tag))
-                    continue; // #328 — session-disabled tags aren't advertised
-                const entry = executors.entry(tag);
-                // #240 — identical treatment with the scheme directory: the example IS the oneliner,
-                // the fuller doc (materialized at plurnk://docs/<tag>.md) rides an inline link whose
-                // token cost lives on that manifest entry. No example → no line (like a provisional scheme).
-                if (entry?.example)
-                    tools.push(teachingLine(entry.example));
+            else {
+                for (const tag of runtimes) {
+                    if (excluded.has(tag))
+                        continue; // #240 — PLURNK_SERVICE_DOCS_EXCLUDE drops the oneliner + the doc
+                    if (!workspaceEnabled(tag))
+                        continue; // #328 — workspace-disabled tags aren't advertised
+                    const entry = executors.entry(tag);
+                    // #240 — the example IS the oneliner (a bare op, fenced below); the fuller doc
+                    // materializes at plurnk://docs/<tag>.md. No example → no line.
+                    if (entry?.example)
+                        ops.push(entry.example);
+                }
             }
         }
-        return tools;
+        const parts = [...notices];
+        if (ops.length > 0)
+            parts.push(`\`\`\`plurnk\n${ops.join("\n")}\n\`\`\``);
+        return parts.join("\n\n");
     }
     // #note12 — the daughter-provided reference docs (schemes' + execs' `documentation`),
     // materialized at plurnk:///docs/<name>.md by loop_run (like operator docs) so the
     // catalogue's doc-links READ and the manifest carries each doc's token cost.
-    async docEntries(sessionId) {
+    async docEntries(workspaceId) {
         const out = this.#schemes.docs(); // scheme docs already drop PLURNK_SERVICE_DOCS_EXCLUDE names
         // §send-300-choices — the conditional teaching: questions.md (from the docs corpus)
-        // materializes ONLY for enabled sessions — the same conditional-doc mechanism as the EXEC
-        // plugin docs below. An un-enabled session is never taught the op it can't use.
-        if (await SessionSettings.questionsEnabled(this.#db, sessionId)) {
+        // materializes ONLY for enabled workspaces — the same conditional-doc mechanism as the EXEC
+        // plugin docs below. An un-enabled workspace is never taught the op it can't use.
+        if (await WorkspaceSettings.questionsEnabled(this.#db, workspaceId)) {
             try {
                 const q = await readFile(resolvePath(Paths.schemeDocs, "questions.md"), "utf8");
                 if (q.length > 0)
@@ -406,11 +472,11 @@ class PacketBuilder {
         const executors = this.#executors();
         if (executors !== undefined) {
             const excluded = docsExcludeSet();
-            const sessionEnabled = await this.#sessionEnabled(sessionId); // #328 — no doc for a disabled tag
+            const workspaceEnabled = await this.#workspaceEnabled(workspaceId); // #328 — no doc for a disabled tag
             for (const tag of executors.availableRuntimes()) {
                 if (excluded.has(tag))
                     continue; // #240 — exec docs honor the same exclude
-                if (!sessionEnabled(tag))
+                if (!workspaceEnabled(tag))
                     continue;
                 const doc = executors.entry(tag)?.documentation;
                 if (doc !== undefined && doc.length > 0)
@@ -425,10 +491,12 @@ class PacketBuilder {
     // strike, rebuild, re-measure. Folds (never deletes). The strike it raises and
     // the hard-stop it can signal are returned to runLoop, which owns abandonment.
     // §grinder-overflow-only — fires only on actual overflow, never speculatively
-    async enforceBudget({ packet, provider, runId, loopId, turnId, mintSequence, tokenRatio = 1, rebuild }) {
-        const ceiling = this.ceilingFor(provider, tokenRatio);
+    async enforceBudget({ packet, provider, workerId, loopId, turnId, mintSequence, rebuild }) {
+        const ceiling = this.ceilingFor(provider);
         const measure = (p) => p.tokens;
-        if (measure(packet) <= ceiling)
+        // #421 — a null ceiling is an unbounded window: always fit, never fold or strike (the backend
+        // clamps; this mirrors Engine's physicallySendable, which treats a null contextWindow as sendable).
+        if (ceiling === null || measure(packet) <= ceiling)
             return { packet, fit: true, struck: false };
         // ONE rule, every turn — turn 1 and turn 101 alike (§grinder-layer1-rollback): fold the
         // NEWEST turn boundary's still-open rows (the prior turn's emissions + this turn's
@@ -442,15 +510,23 @@ class PacketBuilder {
         // turn late. The row is grinder-exempt, so it stacks into a visible recurrence trail. It
         // sits at the turn's reserved running sequence (mintSequence) so it never collides with the
         // post-generate dispatch rows. §telemetry-uniform-error-channel, §grinder-overflow-error-row
-        await this.#telemetry.mintEngineError("budget_overflow", { runId, loopId, turnId, sequence: mintSequence });
+        await this.#telemetry.mintEngineError("budget_overflow", { workerId, loopId, turnId, sequence: mintSequence });
         await this.#db.engine_grinder_fold_newest_turn.run({ loop_id: loopId, turn_id: turnId });
         const current = await rebuild();
         return { packet: current, fit: measure(current) <= ceiling, struck: true };
     }
+    // §tokenomics-agnostic-ruler — the EXACT materialization measure: the provider's own token
+    // count of the assembled packet, the ONE place per-model exactness is used (once per turn, at
+    // the fit-gate). The model-facing render-weight (packet.tokens) stays the ruler; this is the
+    // physics check that the real bytes fit the real window.
+    exactPacketTokens(packet, provider) {
+        return provider.countTokens(PacketWire.renderSlot(packet.sections, "system"))
+            + provider.countTokens(PacketWire.renderSlot(packet.sections, "user"));
+    }
     // Complete the packet by adding the model's response. After this the
     // packet matches Packet.json fully and is ready for storage.
     completePacket(requestPacket, assistant, assistantRaw, provider) {
-        const assistantTokens = provider.countTokens(assistant.content);
+        const assistantTokens = rulerCount(assistant.content); // §tokenomics-agnostic-ruler — render-weight in ruler units (usage_* keep the provider's real count)
         return {
             tokens: requestPacket.tokens + assistantTokens,
             sections: requestPacket.sections,
@@ -484,16 +560,16 @@ class PacketBuilder {
     // Snapshot is taken at packet build (pre-dispatch this turn), so it
     // reflects "what has happened before this turn." Each row carries a
     // log:///<loop_seq>/<turn_seq>/<sequence> coordinate the model can READ.
-    async #buildLog(runId) {
-        // SPEC §packet-terms: runs own log entries — log is the run's history,
-        // not the loop's. Span all loops in the run so the model sees
+    async #buildLog(workerId) {
+        // SPEC §packet-terms: runs own log entries — log is the worker's history,
+        // not the loop's. Span all loops in the worker so the model sees
         // earlier loops' work as conversational memory.
         //
         // User prompts are first-class log entries: runTurn writes a
         // client-origin SEND[200] row at sequence=0 of each new
         // turn-1. Prompts thus surface naturally in this query — no
         // synthetic / shim layer.
-        const rows = await this.#db.engine_render_log.all({ run_id: runId });
+        const rows = await this.#db.engine_render_log.all({ worker_id: workerId });
         return rows.map((r) => ({
             coordinate: `${r.loop_seq}/${r.turn_seq}/${r.sequence}`,
             origin: r.origin,