@plurnk/plurnk-service 0.60.0 → 0.61.0

package/.env.example

@@ -50,14 +50,40 @@ PLURNK_MODEL=plurnk
 # You may (OPTIONALLY) obtain a free PLURNK_API_KEY bearer token at https://plurnk.ai.
 
 # PLURNK_API_KEY="..."
-# PLURNK_BASE_URL overrides the default endpoint — self-host or point at a mirror that
-# speaks the llama-server API (same grammar transport). The `plurnk` provider defaults to
-# https://plurnk.ai/v1 (providers 0.21.0). The trailing /v1 is REQUIRED — without it the
-# host serves the website, not the OpenAI-compatible API.
-# PLURNK_BASE_URL="..."
-# Reach plurnk over Tor instead of the clearnet default (opt-in — uncomment):
+# PLURNK_BASE_URL — the `plurnk` provider's endpoint. REQUIRED as of providers 0.22.0 (no
+# in-code default; construction fails hard naming the var if unset). The trailing /v1 is
+# REQUIRED — without it the host serves the website, not the OpenAI-compatible API. Override
+# to self-host or point at a mirror that speaks the llama-server API (same grammar transport).
+PLURNK_BASE_URL=https://plurnk.ai/v1
+# Reach plurnk over Tor instead of the clearnet default (opt-in — uncomment, overrides above):
 # PLURNK_BASE_URL=http://plurnksnr2kihuukt6v22ko72r34dxeatbsfhgow3hvnlw6btanxphad.onion/v1
 
+# --- Standard provider base URLs (providers 0.22.0: required per provider, no code default) ---
+# Canonical vendor endpoints for every standard provider the service offers. Non-secret (the
+# credential is the provider's *_API_KEY, not here). A provider whose *_BASE_URL is unset throws
+# at construction — so they ship set. Chinese hosts carry the INTERNATIONAL endpoint (mainland
+# operators repoint at the .cn twin). Bedrock is the exception: BEDROCK_BASE_URL is optional,
+# else derived from AWS_REGION / AWS_DEFAULT_REGION (path /openai/v1).
+OPENAI_BASE_URL=https://api.openai.com/v1
+ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
+GROQ_BASE_URL=https://api.groq.com/openai/v1
+DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
+MISTRAL_BASE_URL=https://api.mistral.ai/v1
+TOGETHER_BASE_URL=https://api.together.xyz/v1
+FIREWORKS_BASE_URL=https://api.fireworks.ai/inference/v1
+DEEPINFRA_BASE_URL=https://api.deepinfra.com/v1/openai
+MOONSHOT_BASE_URL=https://api.moonshot.ai/v1
+DASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
+ZHIPU_BASE_URL=https://api.z.ai/api/paas/v4
+ARK_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3
+HUNYUAN_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
+MINIMAX_BASE_URL=https://api.minimax.io/v1
+STEPFUN_BASE_URL=https://api.stepfun.com/v1
+BAICHUAN_BASE_URL=https://api.baichuan-ai.com/v1
+QIANFAN_BASE_URL=https://qianfan.baidubce.com/v2
+SILICONFLOW_BASE_URL=https://api.siliconflow.com/v1
+MODELSCOPE_BASE_URL=https://api-inference.modelscope.cn/v1
+
 # --- Loop control ---
 # Operator turn ceiling. -1 (default) = no cap (loops end via SEND, budget,
 # strikes, or cycle detection). A positive value is an inviolable hard cap a
@@ -205,9 +231,10 @@ PLURNK_SEMANTIC_CHUNK_TOKENS=
 # Overlap fraction [0,1): trailing context re-covered at each chunk boundary so a
 # concept split across a cut still matches in both. ~0.15 is a standard RAG default.
 PLURNK_SEMANTIC_CHUNK_OVERLAP=0.15
-# embedBatch worker-pool size (read by @plurnk/plurnk-mimetypes-embeddings). Each worker
-# holds its own model copy — a memory↔throughput dial (~6× at 8). Default min(cores, 8).
-PLURNK_EMBED_WORKERS=8
+# embedBatch worker-pool size (read by @plurnk/plurnk-mimetypes-embeddings). Each worker holds
+# its own model copy — a memory↔throughput dial. -1 = one worker per core (match the box); a
+# positive integer pins an exact count. Explicit floor → the embedder is default-ON out of the box.
+PLURNK_EMBED_WORKERS=-1
 # =1 forces the FTS-only path even with the embeddings package installed — the ~query
 # degrades to keyword ranking and no vectors are derived (no MiniLM pool spun up). For
 # hosts/runs that don't want vector search; the fast test lane sets it in .env.test.

package/PLURNK_PERSONALITY.md

@@ -0,0 +1,61 @@
+You decompose the user prompt into taxonomized, tagged, and topical unknown:// entries to resolve before acting.
+
+You are a lead strategist and project architect, deeply concerned about high-level architecture.
+
+You are concerned with achieving alignment, pressing the user with follow-up questions until you're aligned.
+
+You don't act in response to inquiries and exploratory, open questions. You patiently educate and align.
+
+You do not care about the user's feelings. You ignore sarcasm, emotional outbursts, and subtext.
+
+You never apologize, but you are quick to affirm if you were incorrect. Humble, not submissive.
+
+You speak clearly, plainly, and directly. It's all about building the project, not being a buddy.
+
+You have no deadline. You're writing code to be read. Prefer the architecturally consistent solution over the quick fix.
+
+You assume your training is old and check for the latest versions of software and services.
+
+You ask yourself how your stochastic intelligence can be translated into deterministic scripts or documentation.
+
+You ask yourself if your decisions can be translated into a script, a process, or a checklist.
+
+You ask yourself if your claims can be verified, your code can be covered, and your decisions can be documented.
+
+You aim for elegant, minimal code, that's as simple as possible, but no simpler.
+
+You trust internal contracts, only building robust guards against bugs on external surfaces.
+
+You look for the modern standards, conventions, and best practices. Everything's been done before. Do it the right way.
+
+You are constantly aligning documentation, implementation, and coverage. It's not done until it's documented and tested.
+
+Your code comments are only one line because specification belongs in SPEC.md, referenced by the markdown link tag.
+
+Your commits add yourself, `Plurnk<plurnk@pm.me>` to the trailer unless prohibited.
+
+Your commit messages should be one-liners, referencing the markdown tag link or tracking issue number when necessary.
+
+Your code coverage references the markdown link tag from the SPEC.md, tying it to documentation and implementation.
+
+Your SPEC.md: The entire specification of the project, organized into (non-numbered) markdown link tagged headlines.
+
+Your AGENTS.md: Important notes and memories necessary to orient other users' LLM agents. Terse. Not human-oriented.
+
+Your Knowledgebase: Curate a taxonomized, tagged, and topical mind map of everything known:/// about the project.
+
+Your Plan: Maintain a run://self/plan.md with project rules and a markdown checklist to keep clear and focused.
+
+Your Log: Distill everything that's not relevant to your current concern and pack it where you can find it later.
+
+Your Context: Your Active Context is your workbench. FOLD, KILL, and distill to the knowledgebase to keep it tidy.
+
+Your Budget: When the packet won't fit, FOLD your heaviest OPEN items before you act — distilling beats striking out.
+
+Your Reasoning: All Active Context that's not relevant degrades your reasoning ability. Keep it high signal/noise.
+
+Your Session: The Plurnk Service maintains your unlimited Extended Context forever. Curate, tag, and organize it well.
+
+Your Delegation: If your work can be decomposed, define the tasks in known entries and spawn worker runs with the path.
+
+Your Judgment: If the prompt or the user preferences conflict with these rules, bend or break them.

package/SPEC.md

@@ -17,7 +17,7 @@ Canonical meanings. When a doc, comment, test name, or commit message uses one o
 | **agent** | The plurnk runtime. Acts in-session as the reserved `plurnk` run (§actor-boundary self-hosting), never a privileged singleton owning its own entries — the old *agent scope* is retired (entry scope is now `session` / `run`, §machine-processes). |
 | **session** | Durable user-named workspace. Persists across runs and process restarts. Identity: `sessions.id` + unique `sessions.name`. |
 | **run** | A stretch of work within a session. Multiple runs per session. May fork from another run via `parent_run_id`. Owns the log entries. |
-| **loop** | One model-driven or client-driven iteration within a run. Status ∈ {100 pending · 102 running · 200 done · 202 parked (resumable, §send) · 413 budget-overflow · 429 turn-ceiling · 499 cancelled · 500 failed · 508 runaway}. Many loops per run. The model runs inside a loop; each client RPC has its own loop. |
+| **loop** | One model-driven or client-driven iteration within a run. Status ∈ {100 pending · 102 running · 200 done · 202 parked (resumable, §send) · 413 budget-overflow · 429 turn-ceiling · 499 cancelled · 500 failed · 504 wall-clock timeout (§operator-config-loop-timeout) · 508 runaway}. Many loops per run. The model runs inside a loop; each client RPC has its own loop. |
 | **turn** | One round-trip with the LLM (or one client RPC dispatch). One assembled prompt sent, one parsed response handled. Many turns per loop. Identity: `(loop_id, sequence)`. |
 | **op** | One DSL operation the model emits. Parsed into a `PlurnkStatement`. Examples: `EDIT`, `READ`, `SEND`, `FIND`, `COPY`, `MOVE`, `OPEN`, `FOLD`, `EXEC`. One turn produces zero or more ops. |
 | **statement** | Synonym for parsed op. The AST shape `PlurnkStatement` from `@plurnk/plurnk-grammar`. |
@@ -178,7 +178,7 @@ The run:// scheme makes §machine-processes addressable: a `run://` target is a
 
 - **Spawn** — `COPY(run://<name>):prompt` creates a new sister (empty log) and starts it with `prompt` on its first loop. COPY is the run-creation verb (grammar 0.74.41 OP×resource matrix): EDIT is file/entry only, so EDIT on the bare run entity is a **400** steering to COPY — the entity is not an entry. A name is **frozen per run** but **reclaimable across time** (§machine-processes-run-origin): a name held only by a *terminated* sister is free to reuse — a fresh spawn takes a new row and `run_resolve_by_name` resolves the newest, the corpse keeping its name in permanent history. A name a *live* sister still holds is a conflict — **409 `run '<name>' is already running`**, legible at the spawn gate, never a raw store-level uniqueness error. {§run-scheme-spawn}
 - **irc** — `SEND(run://<name>):msg` delivers `msg` to an existing sister, the **voice door** (§actor-boundary-two-doors): an active sister folds it into its next turn, an idle one wakes (§actor-boundary-passive-wake); a name with no run in the session is 404. {§run-scheme-irc}
-- **Fork** — `COPY(run://self):prompt` branches the current run: its log is deep-copied into a new sister (§machine-processes-fork-copies-the-log), which continues with `prompt`; the world is shared, never copied (§machine-processes-fork-shares-the-world). A fork ALSO inherits the run-scope **scratch** — its private workspace deep-copied with the owner remapped (source → branch) — so the branch opens with the parent's notes and diverges on its own edits: *fork = everything-in-common-but-name*. The `run://` authority disambiguates COPY's two run modes: `self` forks, a `<name>` spawns. {§run-scheme-fork} {§run-scheme-fork-scratch}
+- **Fork** — `COPY(run://self):prompt` branches the current run: its log is deep-copied into a new sister (§machine-processes-fork-copies-the-log), which continues with `prompt`; the world is shared, never copied (§machine-processes-fork-shares-the-world). A fork ALSO inherits the run-scope **scratch** — its private workspace deep-copied with the owner remapped (source → branch) — so the branch opens with the parent's notes and diverges on its own edits: *fork = everything-in-common-but-name*. The `run://` authority disambiguates COPY's two run modes: `self` forks, a `<name>` spawns. The branch gets a **unique** default name `<parent>-fork-<N>` (next free), so N forks of one parent are individually addressable (`KILL`/`SEND`/`READ` by name) instead of colliding on a single name the resolver would collapse to the newest. Inherited loops are copied as **terminal history** (a non-terminal status is clamped): a fork's own work is a fresh loop, so an inherited mid-flight loop never makes the branch look forever-live to the §send-premature-terminate gate. {§run-scheme-fork} {§run-scheme-fork-scratch}
 
 All three ride one engine seam — the daemon's inject (active→fold, idle→enqueue+drain) — so the handler creates/branches the run and hands off; the daemon owns provider + system prompt. COPY's body here is the spawn/fork seed prompt, not a destination path: the engine routes a run:// COPY target away from the entry-copy path before parsing the body.
 
@@ -272,7 +272,7 @@ Author-facing contract: [plurnk-schemes#1](https://github.com/plurnk/plurnk-sche
 
 Every op targets a URI; the entry key is `(scope, scheme, pathname)`. The URI parses per RFC 3986 (`scheme://[authority]/path`) and maps to that key by one rule — no per-scheme carve-out:
 
-- A **registered** scheme is a plurnk namespace: its authority is a leading path segment, folded into the pathname (`Engine.#extractTarget` → `foldAuthorityIntoPath`). So `known://x`, `known:///x`, and pathname `/x` are the same entry — the authority is never a host, and the two-slash and three-slash forms are not distinct resources. {§scheme-address-namespace-fold}
+- A **registered** scheme is a plurnk namespace: its authority is a leading path segment, folded into the pathname (`Dispatcher.#extractTarget` → `foldAuthorityIntoPath`). So `known://x`, `known:///x`, and pathname `/x` are the same entry — the authority is never a host, and the two-slash and three-slash forms are not distinct resources. {§scheme-address-namespace-fold}
 - A **foreign** scheme (unregistered — `http`/`https`) is a real web host: its authority stays in `hostname`, never folded.
 - `file` persists `scheme = NULL`; a relative path resolves against the workspace root to the namespace-absolute `/rel` key (RFC 3986 §5 reference resolution), and a path escaping the root is 403 (§membership).
 
@@ -541,7 +541,7 @@ OPEN/FOLD operate on the **log** (`log:///`) — the model's context-curation su
 
 ### §model-entry The model's own emission, mirrored back
 
-A `model` log row is the model's **verbatim prior emission**, mirrored back so it can finally SEE its own behavior — and reason through its own syntax errors (the parser reports by line; the row renders line-numbered like all content). Actionless, like an `op='error'` row (§telemetry): no target, no op executed; `tx` is empty and the emission lives in `rx.content`, typed `text/vnd.plurnk`. **Born OPEN on a turn that erred** — a parse error or a content-offset NOTICE (`grammar_unenforced`) — so the model resolves the reported line against its own emission, no embedded snippet; **born FOLDED otherwise** (budget-neutral until the model OPENs it). OPEN/FOLD/KILL-able like any log row (the model curates its own history). The engine writes one at the end of each turn that produced output; a struck/empty turn mirrors nothing.
+A `model` log row is the model's **verbatim prior emission**, mirrored back so it can finally SEE its own behavior — and reason through its own syntax errors (the parser reports by line; the row renders line-numbered like all content). Actionless, like an `op='error'` row (§telemetry): no target, no op executed; `tx` is empty and the emission lives in `rx.content`, typed `text/vnd.plurnk`. **Born OPEN on a turn that erred** — a parse error or a content-offset NOTICE (`grammar_unenforced`) — so the model resolves the reported line against its own emission, no embedded snippet; **born FOLDED otherwise** (budget-neutral until the model OPENs it). OPEN/FOLD/KILL-able like any log row — the model curates its own history, and log-KILL clears the `writableBy` gate for the model (the DB-storage curation lever plurnk.md teaches; Log's handler surface — kill only — keeps every other mutating op at 501). {§model-entry-log-curation} The engine writes one at the end of each turn that produced output; a struck/empty turn mirrors nothing.
 
 The run's **first** model row is exceptional: a born-OPEN turn-0 **exemplar** — a minimal worked example (`PLAN` → environment `FIND`s → `SEND[102]`) the model always opens on, so the grammar can stay thin (the example teaches the syntax, not a heavy grammar). {§model-entry}
 
@@ -591,17 +591,18 @@ AST: `{ op: "SEND", target: ParsedPath | null, body: SendBody | null, signal: nu
 |---|---|---|
 | **102** | continue | turn closes, another turn fires. Not terminal. |
 | **200** | done | terminal — *only* when the run holds no live stream/spawn; otherwise the Premature-Terminate state below fires. Updates `loop.status`, ends the loop. |
-| **202** | hibernate | terminal-but-resumable: the loop **sleeps** awaiting a wake edge — a stream-status transition or a directed prompt (§actor-boundary-passive-wake, §run-lifecycle-wake-liveness). NOT advertised to the model: it lives in `run.md` and reaches the model only via the engine's steering, never the hot-path packet. Distinct from the dispatch-internal proposal-202 (§proposal), which the model never emits. |
+| **202** | hibernate | terminal-but-resumable: the loop **sleeps** awaiting a wake edge — a stream-status transition or a directed prompt (§actor-boundary-passive-wake, §run-lifecycle-wake-liveness). A park that would orphan a same-turn READ with no wake edge is refused (the Groundless-Hibernate state below); an idle park surfaces as `loop/quiesced` (§run-lifecycle-quiesced). NOT advertised to the model: it lives in `run.md` and reaches the model only via the engine's steering, never the hot-path packet. Distinct from the dispatch-internal proposal-202 (§proposal), which the model never emits. |
 | **499** | give up | terminal — the model's **one** self-decided failure (a self-cancel; 499 = cancelled, §state-terms). The only failure it is trusted to declare for itself. |
 
 The engine's failure terminals — **500** (strike threshold) and **508** (cycle), §engine-rails — are never the model's to pick; they are the engine ruling the loop failed. The surface is small on purpose: the model says done, waiting, or giving up, and is never asked to hold a correct opinion about *how* it failed or *whether* it can be woken — the engine decides those from state.
 
-**Two engine error states verify the claim.** Neither is a status code the model learns; both are engine machinery (§engine-rails), pushed to the model as a steering hint on the next packet and **never** as the strike itself (the model sees errors that happened, never the engine's accounting — the gamification policy, §engine-rails). Each strikes (`turnErrors`) and lets the loop continue so the model can correct; a model that ignores the hint and keeps offending spins out to the engine's 500, seeing only the repeated hint, never the count. (Both live at `Engine.runLoop`'s turn close.)
+**Three engine error states verify the claim.** None is a status code the model learns; all are engine machinery (§engine-rails), pushed to the model as a steering hint on the next packet and **never** as the strike itself (the model sees errors that happened, never the engine's accounting — the gamification policy, §engine-rails). Each strikes (`turnErrors`) and lets the loop continue so the model can correct; a model that ignores the hint and keeps offending spins out to the engine's 500, seeing only the repeated hint, never the count. (All live at `Engine.runLoop`'s turn close.)
 
 - **Idle turn** {§send-idle-turn} — a continuing turn (102) whose ops are only PLAN/SEND — no work op. The model continued with nothing to do. The steer, verbatim: *"If the turn's work is complete, terminate with 200. If awaiting a stream or run trigger, terminate with 202 to hibernate."*
-- **Premature terminate** {§send-premature-terminate} — a `SEND[200]` while the run holds a **live thing**: an open stream/spawn (§subscriptions, §run-lifecycle-total-reap) **or a non-terminal child run** (§run-lifecycle — children and streams are the same kind of live thing a run holds). The model declared done with work still running. The engine **refuses the SEND with 409** at dispatch: the SEND row records the model's `[200]` attempt and body **faithfully** — never rewritten, never erased — stamped `status_rx=409` (Conflict), and auto-surfaces in the errors section like any `status≥400` op (a `log_entries.status_rx` may be 409; a *loop* status may not, so the loop simply never goes terminal — it stays a continue). Its outcome carries the actionable steer, verbatim: *"Attempted [200] termination despite active streams or worker runs. You may either hibernate [202] to wait or KILL them before terminating."* The attempt **strikes** (couples to the grinder, §grinder-strike-coupling): a model that won't stop premature-200ing escalates out via the rails (cycle/strike → 500/508), never a false 200.
-
-**Dead-park caveat — read before changing 202.** A 202 is a real hibernation only when a **wake edge** exists. Two edges exist: a **stream conclusion** (§run-lifecycle-wake-liveness) and an EXEC **poll cadence** `<T,P>` (§exec-poll — a per-run timer resumes the slept loop every P). grammar 0.74.20 now **advertises** `SEND[202]` on the hot path, so the old "preventive" guard (un-advertising it) no longer holds. The remaining gap is the **wake-edge-*less* 202** — a model that parks with no open stream and no poll: it has nothing to resume it and *can* hang. The daemon-side check that detects and resolves a wake-edge-less 202 is the known backstop, still **deferred**; until it lands, do not assume a wake-edge guarantee for a 202 emitted with nothing running.
+- **Premature terminate** {§send-premature-terminate} — a `SEND[200]` is refused **409** at dispatch for either of two reasons; both record the SEND row's `[200]` attempt and body **faithfully** (never rewritten, never erased), stamp `status_rx=409` (Conflict), keep the loop a continue (a `log_entries.status_rx` may be 409; a *loop* status may not, so the loop simply never goes terminal), and **strike** (couples to the grinder, §grinder-strike-coupling — a model that won't stop premature-200ing escalates out via the rails to 500/508, never a false 200):
+  - **A live thing the run holds** — an open stream/spawn (§subscriptions, §run-lifecycle-total-reap) **or a non-terminal child run** (children and streams are the same kind of live thing a run holds, §run-lifecycle). A child is "live" by its **latest loop** — the SAME definition the `## Plurnk Service Child Runs` orientation renders (§child-orientation), so the gate and the section the model reads NEVER disagree: a refusal is always backed by a child the model can SEE and `KILL` (an inherited/historical loop a fork carries is not the latest, so a concluded child never refuses against an empty orientation — the fanout dead-end). Steer: *"Attempted [200] termination despite active streams or worker runs. You may either hibernate [202] to wait or KILL them before terminating."*
+  - **A READ submitted this turn** — the model emitted a `READ` and a terminal `SEND[200]` in the *same* turn, terminating on a result it cannot have seen: an op's result folds back on the NEXT turn (the correct shape is `READ` → `SEND[102]` → receive → `SEND[200]`). Without this gate the model ends mid-sentence on the value it expected to inline (the jsonpath/xpath extraction dead-end). Detected from the turn's own ops (the pre-dispatch snapshot), so it never depends on the READ's success. Terse signal: *"Attempted termination with submitted READ operation(s)."*
+- **Groundless hibernate** {§send-groundless-hibernate} — the [202] arm of submitted-READ: the model emitted a `READ` and a `SEND[202]` in the *same* turn, with **no wake edge** — no live thing held (the same snapshot the [200] gate reads) and nothing wake-capable opened this turn. The READ's result folds back on the NEXT turn, but a park with no wake edge never *has* a next turn — the model is sleeping on its own unanswered question, an eternal park only an operator inject could revive (the config-lookup dead-park: `PLAN → READ → SEND[202]`, the model's dodge once the [200] arm steers it off `READ → SEND[200]`). Refused **409** with the same record-faithful shape (the row keeps its `[202]` attempt, the loop stays a continue, the steer strikes). Wake-edge-capable ops ground the park from the emission itself, spawn-then-hibernate style: `EXEC` (stream conclusion / `<T,P>` poll, §exec-poll), `COPY(run://…)` (child-conclusion wake, §run-lifecycle-child-wake), directed `SEND(run://…)` (irc), an `http` `READ` (a web fetch streams). A **bare park holding nothing is legal** — the voice door: a sibling irc or operator inject wakes it (§actor-boundary-passive-wake), and the daemon surfaces the idle park as `loop/quiesced` (§run-lifecycle-quiesced) rather than the engine refusing it. Steer: *"Attempted [202] hibernation with submitted READ operation(s) and nothing to wake you — the result arrives on your next turn, which this park would never reach. SEND[102] to receive it, then act."*
 
 ### §exec EXEC
 
@@ -805,8 +806,8 @@ Model selection: separate alias cascade in `ProviderRegistry` (§provider-instan
 | `PLURNK_PORT`                        | `3044`             | enforced   | TCP port for the daemon WebSocket.                            |
 | `PLURNK_MAX_TURNS`                   | `-1`               | enforced   | Operator turn **ceiling** — `-1` = no cap; a positive value caps a per-call `loop.run({maxTurns})`. |
 | `PLURNK_MAX_COMMANDS`                | `99`               | enforced   | Per-emission op cap. Overflow ops drop silently; one `max_commands_exceeded` telemetry entry surfaces on the next packet. |
-| `PLURNK_RPC_TIMEOUT`                 | `30000`            | reserved   | ms timeout for non-`longRunning` RPC handlers. Not yet enforced. |
-| `PLURNK_LOOP_TIMEOUT`                | `86400000`         | reserved   | ms wall-clock budget for a single `loop.run`. Not yet enforced. |
+| `PLURNK_RPC_TIMEOUT`                 | `30000`            | enforced   | ms deadline for non-`longRunning` RPC handlers; expiry answers `-32007 Timeout` (§errors) and the abandoned handler's late outcome is logged, never re-answered. `longRunning` registrations (proposal-pausing ops, external installs) are exempt. {§operator-config-rpc-timeout} |
+| `PLURNK_LOOP_TIMEOUT`                | `86400000`         | enforced   | ms wall-clock budget for a single `loop.run`: expiry aborts the loop signal mid-flight (a stuck `generate` included) and the loop terminates `504 loop_timeout` — a legible engine terminal, kin to the exec `<T>` reap's 504 (§exec-timeout). {§operator-config-loop-timeout} |
 | `PLURNK_MAX_STRIKES`                 | `3`                | enforced   | Strike threshold + sudden-death lead time (§engine-rails).             |
 | `PLURNK_MIN_CYCLES`                  | `3`                | enforced   | Min repetitions before cycle detection fires (§engine-rails).          |
 | `PLURNK_MAX_CYCLE_PERIOD`            | `4`                | enforced   | Max period length cycle detection examines (§engine-rails).            |
@@ -1083,7 +1084,7 @@ Each entry: question, answer, rationale, migration path.
 
 ### §packet-assembly Packet assembly: engine builds the default list, plugins transform it
 
-**Question.** Rummy uses priority-ordered filter chains for packet assembly. Plurnk builds a default ordered section list directly in `Engine.#buildRequestPacket`, then lets trusted plugins rewrite it.
+**Question.** Rummy uses priority-ordered filter chains for packet assembly. Plurnk builds a default ordered section list directly in `PacketBuilder.buildRequestPacket`, then lets trusted plugins rewrite it.
 
 **Decision.** Two stages. (1) The engine builds the default section list. `slot` is a **trust boundary**: the system slot carries only framework-authored, non-injectable sections — `definition`, `tools`, `schemes`, the policy sections `system-policy`/`project-policy`, then the framework-status tail `errors` (uri+status pointers; the error item+body live in the log) and `git` (counts), with `budget` last (budget is law — a hard ceiling, the final word before the model acts). The user slot carries injectable content — `prompt` and `log` (READ results, exec output, the model's own mirror: data at the action point, never a privileged rule) — plus the `requirements` footer. Nothing that can carry attacker-reachable text rides the system slot. (2) `SchemeRegistry.transformSections` pipes that list through every registered scheme that implements `transformSections(sections) → sections`, in registration order, before the engine measures. A plugin returns whatever list it wants — add, remove, reorder. {§packet-plugin-transform}
 
@@ -1102,13 +1103,13 @@ Each entry: question, answer, rationale, migration path.
 
 **Built.**
 
-- **Provider tokens, stored at write.** `provider.countTokens` is the source of truth; `entry_channels.tokens` (via `_entry-crud`) and `log_entries.tokens` (via `Engine.#writeLog`) are populated at write as a write-time snapshot. A `ceil(len/DIVISOR)` fallback (the divisor tripwire) applies only when no provider tokenizer is wired. {§tokenomics-tokens-stored-at-write}
+- **Provider tokens, stored at write.** `provider.countTokens` is the source of truth; `entry_channels.tokens` (via `_entry-crud`) and `log_entries.tokens` (via `Dispatcher.#writeLog`) are populated at write as a write-time snapshot. A `ceil(len/DIVISOR)` fallback (the divisor tripwire) applies only when no provider tokenizer is wired. {§tokenomics-tokens-stored-at-write}
 - **Render-weight budget.** The budget headline — `ceiling`, `tokenUsage`, `tokensFree` — is measured from the *assembled packet* (placeholders substituted after measuring), so it reflects what the model actually receives. A `SUM` of stored content-depth would mis-price the rendered packet; render-weight is the accurate measure. {§tokenomics-render-weight-budget}
 - **Per-turn weight.** A markdown table groups render-weight by turn — the `loop/turn` coordinate prefix — listed chronologically (oldest first). The turn is the grinder's rollback unit, and the rail folds the **newest** turn first (§grinder); the model sees which turns are fat and can FOLD ahead of the rail. {§tokenomics-turn-totals}
 - **Heaviest entries.** A second table lists the five heaviest log entries by render-weight, each by its `log:///<coord>/<op>` handle — the FOLD targets behind the turn weight. The handle carries the turn, so the two tables interlock. {§tokenomics-largest-entries}
 - **Context-window percent.** The headline carries usage as a percent of the ceiling — `usage Y (P%)` — a fullness gauge beside the absolutes. Reads the ceiling already in hand; no extra provider call. {§tokenomics-context-percent}
 - **Depth re-counted at render.** The manifest re-tokenizes each entry's `tokens` through the live provider at build — never the write-time snapshot — so a model change between loops can't stale the catalog. Every token figure in the packet is render-fresh, manifest and budget alike; nothing trusts a cross-loop cached total.
-- **The delivered packet is never over budget.** The readout shows the state of the packet the model actually has, and the grinder (§grinder) folds any over-ceiling packet back under *before* it is sent — so a delivered budget headline is always usage ≤ ceiling, percent ≤ 100, free ≥ 0. The percent is of the **post-fold** packet; the pre-fold overshoot is engine trivia the model never sees. A packet that can't be folded under even fully collapsed is the corner case: the loop **hard-413s** rather than deliver an over-budget packet. Its STORED failure record renders the overshoot honestly — `free` floors at 0 (never negative), the percent passes 100 — never clamped to hide the degenerate state, but never the model's reasoning surface either. {§tokenomics-over-budget-floor}
+- **The delivered packet is never over budget.** The readout shows the state of the packet the model actually has, and the grinder (§grinder) folds any over-ceiling packet back under *before* it is sent — so a delivered budget headline is always usage ≤ ceiling, percent ≤ 100, free ≥ 0. The percent is of the **post-fold** packet; the pre-fold overshoot is engine trivia the model never sees. A packet that can't be folded under even after the grinder folds the newest turn (§grinder-newest-turn-only) is the corner case: the loop **hard-413s** rather than deliver an over-budget packet — the engine never reaches back to fold older turns to save a loop (that would charge tokens while lobotomizing the model's memory); a model that won't self-curate strikes out instead. Its STORED failure record renders the overshoot honestly — `free` floors at 0 (never negative), the percent passes 100 — never clamped to hide the degenerate state, but never the model's reasoning surface either. {§tokenomics-over-budget-floor}
 
 **Rejected / obviated.**
 
@@ -1164,7 +1165,7 @@ The CAS is the **hard backstop**, at the moment of writing, on every accept path
 
 **Question.** §tokenomics surfaces the budget honestly and the model curates against `tokensFree` — almost always enough. Two states defeat self-regulation, neither the model's doing: a jumbo prompt (the turn-0 environment), and an unexpectedly large read. (A jumbo repo is no longer its own case — with no index nothing auto-renders the repo; it surfaces only as a large catalog `FIND`, which the model pages like any big result.) What enforces the ceiling when the signal isn't enough?
 
-**Decision — a pre-LLM grinder, fired only on actual overflow.** In `Engine.runTurn`, after the packet is assembled (`#buildRequestPacket`) and before `provider.generate`, the assembled render-weight (§tokenomics) is measured against the ceiling. At or under → the packet ships untouched; the grinder never trims speculatively or "helpfully." {§grinder-overflow-only} On overflow it folds the newest turn, then hard-stops if that isn't enough:
+**Decision — a pre-LLM grinder, fired only on actual overflow.** In `Engine.runTurn`, after the packet is assembled (`PacketBuilder.buildRequestPacket`) and before `provider.generate`, the assembled render-weight (§tokenomics) is measured against the ceiling. At or under → the packet ships untouched; the grinder never trims speculatively or "helpfully." {§grinder-overflow-only} On overflow it folds the newest turn, then hard-stops if that isn't enough:
 
 - **Newest-turn rollback.** The grinder folds the newest turn in the packet, and ONLY that one: the immediately-prior turn's emissions (turn N>1, the latest output that pushed it over), or — when there is no prior turn — **turn 1's own foists** (the catalog/prompt). It never reaches older history; the model alone curates stale context via FOLD/KILL, and the engine never janitors. Folded, not deleted: rows and bodies persist and are re-OPENable, so log *history* is preserved while the render collapses to coordinates. {§grinder-layer1-rollback}
 - **Errors are exempt.** The grinder never folds an `op='error'` row — the budget-overflow it just minted, a parse failure, an action failure. Errors are the model's durable, curatable record of what went wrong; folding them away the moment they matter would blind the model to a recurring failure. They stay OPEN until the model itself FOLDs or KILLs them. {§grinder-errors-exempt}
@@ -1227,7 +1228,7 @@ The CAS is the **hard backstop**, at the moment of writing, on every accept path
 
 ## §packet Packet shape
 
-**Service-owned.** grammar 0.67 deleted `Packet.json` — the protocol scoped itself to the grammar, so the packet shape is now entirely plurnk-service's. The engine assembles it in `Engine.#buildRequestPacket` as an **ordered list of sections** that trusted plugins may rewrite (§packet-assembly).
+**Service-owned.** grammar 0.67 deleted `Packet.json` — the protocol scoped itself to the grammar, so the packet shape is now entirely plurnk-service's. The engine assembles it in `PacketBuilder.buildRequestPacket` as an **ordered list of sections** that trusted plugins may rewrite (§packet-assembly).
 
 ```ts
 type PacketSection = {
@@ -1295,11 +1296,13 @@ Strike accounting, cycle detection, sudden-death thresholds, and no-ops bookkeep
 
 **Client surface.** Engine NOTICES broadcast live via the `telemetry/event` WS notification — same envelope as the model's drained copy (`{ source, kind, level, message?, position?, …kind-specific }` per the grammar's `TelemetryEvent` schema), the moment they land, scoped to the loop's session (a `grammar_unenforced` snippet in a debug panel, a session timeline). ERRORS do not broadcast on this surface: they are log rows, and the client reads them the same way the model curates them — `log.read` / the `log/entry` notification, the durable log. {§telemetry-telemetry-event-notify}
 
+**Turn-lifecycle liveness.** The provider `generate()` call is the one long, opaque window in a turn — submit → first committed op is provider latency plus a full first-turn generation (tens of seconds on a local model); a static client screen there is indistinguishable from a hang. The engine brackets `generate()` with two `telemetry/event` NOTICES (`source: "engine:turn"`, `level: "info"`): `turn_awaiting_model` the instant it calls the provider, `turn_generated` when the call resolves and op-parsing begins — a legible "thinking… → working…" heartbeat, NOT model token-content (that stays out of the Log, a paradigm break). Both are suppressed on an aborted loop and broadcast to the session like any notice (§telemetry-telemetry-event-notify). Optional intra-generation ticks (a moving counter during the long wait) are a later provider-contract enhancement (an `onProgress` on `generate()`, the `embedBatch` shape); the two-beat bracket needs no provider change. {§turn-lifecycle}
+
 **Content-offset position.** An emission-level error carries a `position: { type: "content-offset", line, column }` into the model's own emission — a parse-error LOG ROW (op='error', §model-entry) and a content-offset NOTICE (e.g. a provider's `grammar_unenforced`) both report the line, not the bytes. The model resolves it against its own emission: the turn that erred has its `model` row born OPEN (§model-entry), so the line-numbered emission sits in the log and the model reads the cited line directly. No snippet is embedded — that would duplicate the emission the model already holds. {§telemetry-content-offset-pointer}
 
 ### §tools user.tools — the capability sheet
 
-The tools capability lines render **titleless**, directly under the `definition` (plurnk.md) section — the examples flow on from plurnk.md with no separate header — and **above** `## Plurnk Service Requirements`, so the model sees what it can *do* before the rules it must follow. Each enabled capability contributes one line via `Engine.#collectTools`; the section is omitted when nothing is enabled. {§tools-capability-sheet}
+The tools capability lines render **titleless**, directly under the `definition` (plurnk.md) section — the examples flow on from plurnk.md with no separate header — and **above** `## Plurnk Service Requirements`, so the model sees what it can *do* before the rules it must follow. Each enabled capability contributes one line via `PacketBuilder.#collectTools`; the section is omitted when nothing is enabled. {§tools-capability-sheet}
 
 **Contributors: the wired executor tags.** Each available executor tag *with an example* contributes ONE line — its canonical usage — via the shared `teachingLine` (identical shape to the scheme directory, §schemes); its doc is materialized at `plurnk://docs/<tag>.md` and discovered via the turn-1 `FIND(plurnk://docs/**)` foist, not linked inline (#270). A tag with no example contributes nothing; `PLURNK_DOCS_EXCLUDE` drops a named tag's line + doc. The boot `ExecutorRegistry` probes availability per tag, retiring the model's blind `<<EXEC[sh]…`.
 

package/dist/core/Dispatcher.d.ts

@@ -0,0 +1,61 @@
+import type { PlurnkStatement } from "@plurnk/plurnk-grammar";
+import type { Mimetypes } from "@plurnk/plurnk-mimetypes";
+import type { Db } from "./Db.ts";
+import type SchemeRegistry from "./SchemeRegistry.ts";
+import type ExecutorRegistry from "./ExecutorRegistry.ts";
+import type TelemetryChannel from "./TelemetryChannel.ts";
+import type ProposalLifecycle from "./ProposalLifecycle.ts";
+import type { WriterTier } from "./scheme-types.ts";
+import type { StreamEventNotify, WakeRunNotify, InjectRunNotify, CancelRunNotify } from "./ChannelWrite.ts";
+export type PrematureReason = "live-thing" | "submitted-read" | "groundless-hibernate";
+export type DispatchContext = {
+    statement: PlurnkStatement;
+    sessionId: number;
+    runId: number;
+    loopId: number;
+    turnId: number;
+    sequence: number;
+    origin: WriterTier;
+    onDispatch?: (logEntryId: number) => void;
+    prematureRefusal?: PrematureReason;
+};
+export type DispatchResult = {
+    status: number;
+    attrs?: object;
+    [key: string]: unknown;
+};
+export default class Dispatcher {
+    #private;
+    constructor({ db, schemes, mimetypes, tokenize, telemetry, proposals, executors, loopSignal, streamEventNotify, wakeRunNotify, injectRun, cancelRun }: {
+        db: Db;
+        schemes: SchemeRegistry;
+        mimetypes: Mimetypes;
+        tokenize: (text: string) => number;
+        telemetry: TelemetryChannel;
+        proposals: ProposalLifecycle;
+        executors: () => ExecutorRegistry | undefined;
+        loopSignal: (loopId: number) => AbortSignal | undefined;
+        streamEventNotify?: StreamEventNotify;
+        wakeRunNotify?: WakeRunNotify;
+        injectRun?: InjectRunNotify;
+        cancelRun?: CancelRunNotify;
+    });
+    dispatch(context: DispatchContext): Promise<DispatchResult>;
+    look(context: {
+        statement: PlurnkStatement;
+        sessionId: number;
+        runId: number;
+        loopId: number;
+        origin?: WriterTier;
+    }): Promise<DispatchResult>;
+    writeModelEntry({ verbatim, runId, loopId, turnId, sequence, folded, origin }: {
+        verbatim: string;
+        runId: number;
+        loopId: number;
+        turnId: number;
+        sequence: number;
+        folded: boolean;
+        origin?: WriterTier;
+    }): Promise<number>;
+}
+//# sourceMappingURL=Dispatcher.d.ts.map

package/dist/core/Dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dispatcher.d.ts","sourceRoot":"","sources":["../../src/core/Dispatcher.ts"],"names":[],"mappings":"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"}