@plurnk/plurnk-service 1.4.0 → 1.6.0

package/dist/core/Engine.sql

@@ -5,7 +5,7 @@ SELECT status FROM loops WHERE id = $loop_id;
 
 -- PREP: engine_worker_has_live_child
 -- A non-terminal child worker (worker:// spawn/fork set parent_worker_id) — a "live thing the worker holds",
--- like an open stream. A SEND[200] while one exists is a premature-terminate ({§send-premature-terminate}).
+-- like an open stream. A SEND signal 200 while one exists is a premature-terminate ({§send-premature-terminate}).
 -- Live = a child whose LATEST loop is still pending/running/parked (100/102/202) — the SAME definition
 -- engine_child_workers_live uses for the Active Child Workers orientation, so the 409 gate and the section the model
 -- reads NEVER disagree: a refused termination is always backed by a child the model can SEE and KILL
@@ -67,6 +67,7 @@ LIMIT 1;
 -- {§entry-owner} — one principal's entries (catalogRowsFor source for an owner-scoped FIND/foist):
 -- the commons, a worker's own space, or a named space — exactly one owner's rows, its perspective.
 SELECT e.id AS entry_id, e.scheme, e.pathname, ec.name AS channel, ec.content, ec.mimetype, ec.tokens AS tokens, e.deep_hash,
+    d.parse_issues,
     s.id AS subscription_id,
     CASE WHEN s.closed_at IS NULL
         THEN CAST(unixepoch('now') - unixepoch(s.opened_at) AS INTEGER)
@@ -75,6 +76,7 @@ SELECT e.id AS entry_id, e.scheme, e.pathname, ec.name AS channel, ec.content, e
     s.close_status
 FROM entries e
 JOIN entry_channels ec ON ec.entry_id = e.id
+LEFT JOIN derivations d ON d.deep_hash = e.deep_hash
 LEFT JOIN subscriptions s ON s.id = (
     SELECT latest.id
     FROM subscriptions latest
@@ -85,44 +87,28 @@ LEFT JOIN subscriptions s ON s.id = (
 WHERE e.workspace_id = $workspace_id AND e.owner_id = $owner_id
 ORDER BY e.updated_at ASC, e.id ASC, ec.name;
 
--- PREP: engine_list_owner_entry_tags
--- {§entry-owner} — (entry, tag) for one principal's entries (the owner-scoped catalog's tags field).
-SELECT et.entry_id, et.tag
-FROM entry_tags et
-JOIN entries e ON e.id = et.entry_id
-WHERE e.workspace_id = $workspace_id AND e.owner_id = $owner_id
-ORDER BY et.entry_id, et.tag;
-
 -- PREP: engine_next_turn_sequence
 SELECT COALESCE(MAX(sequence), 0) + 1 AS next FROM turns WHERE loop_id = $loop_id;
 
 -- PREP: engine_loop_usage
--- Per-loop usage totals and latest-turn gauge ({§tokenomics-client-gauge}),
--- surfaced on {§notifications-loop-terminated}. `context` is the latest
--- provider attempt on the latest turn, distinct from summed billed `prompt`.
-SELECT COALESCE(SUM(usage_prompt), 0)     AS prompt,
-       COALESCE(SUM(usage_completion), 0) AS completion,
-       CASE
-           WHEN COUNT(*) = 0 THEN 0
-           WHEN COUNT(usage_cost_usd) = COUNT(*) THEN SUM(usage_cost_usd)
-           ELSE NULL
-       END AS cost_usd,
-       COALESCE((
-           SELECT json_group_array(json(cost.value))
-           FROM turns charged, json_each(charged.usage_cost) AS cost
-           WHERE charged.loop_id = $loop_id
-       ), '[]') AS costs,
-       (
-           SELECT a.usage_prompt
-           FROM turn_attempts a
-           WHERE a.turn_id = (
+-- Latest-turn gauge ({§tokenomics-client-gauge}), surfaced beside the derived
+-- accounting projection on {§notifications-loop-terminated}. `context` is the
+-- latest settled physical request on the latest turn; an absent input count is
+-- unknown and does not fall back to older evidence.
+SELECT (
+           SELECT pr.usage_input
+           FROM provider_requests pr
+           JOIN model_calls mc ON mc.id = pr.model_call_id
+           WHERE mc.turn_id = (
                SELECT latest.id
                FROM turns latest
                WHERE latest.loop_id = $loop_id
                ORDER BY latest.sequence DESC
                LIMIT 1
            )
-           ORDER BY a.sequence DESC
+           AND mc.kind = 'emission'
+           AND pr.state = 'settled'
+           ORDER BY mc.sequence DESC, pr.sequence DESC
            LIMIT 1
        ) AS context,
        -- Latest turn's effective packet allowance; NULL when uncapped or unknown.
@@ -130,7 +116,23 @@ SELECT COALESCE(SUM(usage_prompt), 0)     AS prompt,
        (SELECT usage_prompt_budget FROM turns WHERE loop_id = $loop_id ORDER BY sequence DESC LIMIT 1) AS context_size,
        -- Latest turn's opaque provider metadata. {§meta-passthrough}
        (SELECT meta FROM turns WHERE loop_id = $loop_id ORDER BY sequence DESC LIMIT 1) AS meta
-FROM turns WHERE loop_id = $loop_id;
+FROM loops
+WHERE id = $loop_id;
+
+-- PREP: engine_loop_provider_requests
+-- Ordered cardinal accounting evidence. Aggregation belongs to the shared
+-- provider accounting contract, not SQLite arithmetic or denormalized rows.
+SELECT pr.provider, pr.model, pr.outcome, pr.status,
+       pr.usage_input, pr.usage_output, pr.usage_total,
+       pr.usage_input_no_cache, pr.usage_input_cache_read, pr.usage_input_cache_write,
+       pr.usage_output_text, pr.usage_output_reasoning,
+       pr.cost_kind, pr.cost_amount, pr.cost_currency, pr.cost_usd_equivalent,
+       pr.cost_source, pr.cost_reason
+FROM provider_requests pr
+JOIN model_calls mc ON mc.id = pr.model_call_id
+JOIN turns t ON t.id = mc.turn_id
+WHERE t.loop_id = $loop_id AND pr.state = 'settled'
+ORDER BY t.sequence, mc.sequence, pr.sequence;
 
 -- PREP: engine_loop_attributions
 -- {§attribution} — derive the loop projection from exact response-attempt
@@ -143,9 +145,9 @@ FROM (
     WHERE t.loop_id = $loop_id
     UNION
     SELECT value AS attribution
-    FROM turn_attempts a
-    JOIN turns t ON t.id = a.turn_id,
-         json_each(a.attributions)
+    FROM model_calls mc
+    JOIN turns t ON t.id = mc.turn_id,
+         json_each(mc.attributions)
     WHERE t.loop_id = $loop_id
 )
 ORDER BY attribution;
@@ -170,59 +172,80 @@ VALUES ($loop_id, $sequence, 102)
 RETURNING id;
 
 -- PREP: engine_close_turn
--- Updates the turn with the response packet, terminal status, and
--- provider usage stats once dispatch is complete. Paired with
--- engine_open_turn at runTurn boundaries.
+-- Updates the turn with the response packet and terminal metadata once dispatch
+-- is complete. Provider attempts own and materialize usage/cost above this path.
 UPDATE turns SET
     status = $status,
     packet = $packet,
-    usage_prompt = $usage_prompt,
-    usage_completion = $usage_completion,
-    usage_reasoning = $usage_reasoning,
-    usage_cached = $usage_cached,
-    usage_cost = $usage_cost,
-    usage_cost_usd = $usage_cost_usd,
     usage_prompt_budget = $usage_prompt_budget,
     finish_reason = $finish_reason,
     model = $model,
     meta = $meta
 WHERE id = $id;
 
--- PREP: engine_record_turn_attempt
--- One provider attempt carrying response evidence beneath a turn. Rejected or
--- interrupted attempts remain forensic evidence but never become packet history.
-INSERT INTO turn_attempts (
-    turn_id,
-    sequence,
-    accepted,
-    response,
-    parse_errors,
-    attributions,
-    usage_prompt,
-    usage_completion,
-    usage_reasoning,
-    usage_cached,
-    usage_cost,
-    usage_cost_usd,
-    finish_reason,
-    model
-)
-VALUES (
-    $turn_id,
-    $sequence,
-    $accepted,
-    $response,
-    $parse_errors,
-    $attributions,
-    $usage_prompt,
-    $usage_completion,
-    $usage_reasoning,
-    $usage_cached,
-    $usage_cost,
-    $usage_cost_usd,
-    $finish_reason,
-    $model
-);
+-- PREP: engine_open_model_call
+-- Logical identity and request attribution become durable before provider I/O.
+INSERT INTO model_calls (turn_id, sequence, kind, attributions, model)
+VALUES ($turn_id, $sequence, $kind, $attributions, $model)
+RETURNING id;
+
+-- PREP: engine_observe_model_call_response
+-- Preserve the logical response before call-specific interpretation. Physical
+-- request accounting has already settled through its cardinal observer path.
+UPDATE model_calls SET
+    state = 'response',
+    response = $response,
+    failure = $failure,
+    finish_reason = $finish_reason,
+    model = $model,
+    completed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+WHERE id = $id AND state = 'pending';
+
+-- PREP: engine_fail_model_call
+UPDATE model_calls SET
+    state = 'error',
+    failure = $failure,
+    completed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+WHERE id = $id AND state = 'pending';
+
+-- PREP: engine_open_turn_attempt
+INSERT INTO turn_attempts (model_call_id)
+VALUES ($model_call_id)
+RETURNING id;
+
+-- PREP: engine_classify_turn_attempt_response
+UPDATE turn_attempts SET
+    accepted = $accepted,
+    parse_errors = $parse_errors
+WHERE id = $id AND accepted IS NULL;
+
+-- PREP: engine_open_provider_request
+-- The provider calls this immediately before physical I/O.
+INSERT INTO provider_requests (model_call_id, sequence, provider, model)
+VALUES ($model_call_id, $sequence, $provider, $model)
+RETURNING id;
+
+-- PREP: engine_settle_provider_request
+UPDATE provider_requests SET
+    state = 'settled',
+    outcome = $outcome,
+    status = $status,
+    usage_input = $usage_input,
+    usage_output = $usage_output,
+    usage_total = $usage_total,
+    usage_input_no_cache = $usage_input_no_cache,
+    usage_input_cache_read = $usage_input_cache_read,
+    usage_input_cache_write = $usage_input_cache_write,
+    usage_output_text = $usage_output_text,
+    usage_output_reasoning = $usage_output_reasoning,
+    cost_kind = $cost_kind,
+    cost_amount = $cost_amount,
+    cost_currency = $cost_currency,
+    cost_usd_equivalent = $cost_usd_equivalent,
+    cost_source = $cost_source,
+    cost_reason = $cost_reason,
+    completed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+WHERE id = $id AND state = 'pending';
 
 -- PREP: engine_list_workspace_entries
 -- Every owner-held entry of a workspace — all schemes, all channels — for
@@ -298,8 +321,8 @@ WITH observation AS (
 SELECT o.cursor, o.boundary,
        ae.id AS event_id, ae.producer_worker_id, producer.name AS producer_worker_name,
        ae.kind, ae.source,
-       ae.op, ae.scheme, ae.hostname, ae.pathname, ae.rx, ae.attrs,
-       ae.status_rx, ae.prompt, ae.terminated_by
+       ae.op, ae.scheme, ae.hostname, ae.pathname, ae.rx, ae.attrs, ae.tags,
+       ae.status_rx, ae.terminated_by
 FROM observation o
 LEFT JOIN ambient_events ae
   ON ae.workspace_id = $workspace_id
@@ -325,6 +348,11 @@ INSERT INTO log_entries (
 ON CONFLICT(worker_id, ambient_event_id) WHERE ambient_event_id IS NOT NULL DO NOTHING
 RETURNING id;
 
+-- PREP: engine_ambient_delta_id
+-- Crash replay may find the observation row already inserted but its copied
+-- classifications incomplete. Resolve that row so idempotent tag writes can finish.
+SELECT id FROM log_entries WHERE worker_id = $worker_id AND ambient_event_id = $event_id;
+
 -- PREP: engine_advance_ambient_cursor
 -- Advance only from the snapshot that was actually materialized. A concurrent
 -- pull winning the CAS is safe; a loser replays idempotently on its next turn.
@@ -338,10 +366,11 @@ RETURNING ambient_event_cursor;
 
 -- PREP: engine_worker_stream_channels
 -- {§exec-stream} — every stream channel the worker owns (an EXEC's stdout/stderr live on the
--- runtime-tag entry), with content + state + coordinate, so the per-turn injector can emit the
--- channel's unshown byte-delta. Stays listed until its last delta is shown (cursor == content len).
+-- runtime-tag entry), with content + mimetype + state + coordinate, so the per-turn injector can
+-- publish the channel's next complete unit. Stays listed until its terminal observation is shown.
 SELECT s.id AS subscription_id, e.scheme AS runtime, e.pathname AS coord,
-    ec.name AS channel, ec.content AS content, ec.state AS state, s.close_status AS close_status,
+    ec.name AS channel, ec.content AS content, ec.mimetype AS mimetype,
+    ec.state AS state, s.close_status AS close_status,
     s.close_result AS close_result, s.published_channel AS published_channel
 FROM subscriptions s
 JOIN entries e ON e.id = s.entry_id
@@ -351,8 +380,8 @@ WHERE s.worker_id = $worker_id
 ORDER BY s.id, ec.name;
 
 -- PREP: engine_stream_cursor
--- {§exec-stream} — bytes of this channel already shown to the worker: the streamEnd recorded on its
--- latest foisted delta (the caller defaults to 0 when none exists yet).
+-- {§exec-stream} — content offset already shown to the worker: the streamEnd recorded on its latest
+-- foisted observation (the caller defaults to 0 when none exists yet).
 SELECT attrs
 FROM log_entries
 WHERE worker_id = $worker_id AND origin = 'plurnk' AND op = 'READ'
@@ -360,21 +389,18 @@ WHERE worker_id = $worker_id AND origin = 'plurnk' AND op = 'READ'
 ORDER BY id DESC LIMIT 1;
 
 -- PREP: engine_insert_stream_delta
--- {§exec-stream} / {§env-delta} — materialize a channel's unshown byte-delta as a
+-- {§exec-stream} / {§env-delta} — materialize a channel's next publishable content as a
 -- foisted READ row (the model READs the stream it never typed). origin=plurnk; fragment is
--- the channel; attrs.streamEnd is the next turn's cursor; expanded=1 when the channel has CLOSED
--- (the terminal delta auto-OPENs), 0 while it streams (ongoing deltas fold). {§exec-stream}
+-- the channel; attrs.streamEnd is the next turn's cursor; expanded=1 for a terminal
+-- observation, 0 for an ongoing observation. {§exec-stream}
 INSERT INTO log_entries (
-    worker_id, loop_id, turn_id, sequence, origin, source,
+    worker_id, loop_id, turn_id, sequence, origin, source, model_call_id,
     op, scheme, pathname, fragment, tx, mimetype_tx, rx, mimetype_rx, status_rx, attrs, expanded
 ) VALUES (
-    $worker_id, $loop_id, $turn_id, $sequence, 'plurnk', NULL,
+    $worker_id, $loop_id, $turn_id, $sequence, 'plurnk', NULL, NULL,
     'READ', $scheme, $pathname, $fragment, '', 'text/plain', $rx, 'application/json', $status, $attrs, $expanded
 );
 
--- PREP: engine_entry_tags
-SELECT tag FROM entry_tags WHERE entry_id = $entry_id ORDER BY tag;
-
 -- PREP: engine_child_workers_live
 -- The worker's LIVE child workers — latest loop non-terminal (100 pending / 102 processing / 202 parked).
 -- Powers the Active Child Workers orienting section ({§child-orientation}): terse `* <status> worker://<name>`
@@ -401,11 +427,10 @@ ORDER BY e.pathname;
 -- LogCoordinate pointers, forcing the model to confront failures instead of letting
 -- them rot in log:///. Window = the current turn AND the immediately-prior one
 -- (>= current_turn_seq - 1): prior-turn for action failures the model just caused,
--- current-turn so a same-turn engine error (the grinder's budget-overflow row, minted
--- pre-generate then re-derived) surfaces THIS turn rather than a turn late.
+-- current-turn so a pre-generate engine error surfaces THIS turn rather than a turn late.
 -- {§operation-result-uniform-error-channel}
 SELECT
-    le.op, le.sequence, le.status_rx, le.rx, le.mimetype_rx,
+    le.origin, le.op, le.attrs, le.sequence, le.status_rx, le.rx, le.mimetype_rx,
     le.scheme, le.pathname,
     t.sequence AS turn_seq, l.sequence AS loop_seq
 FROM log_entries le
@@ -420,21 +445,39 @@ ORDER BY t.sequence, le.sequence;
 
 -- TX: engine_grinder_fold_newest_turn
 -- {§grinder-layer1-rollback} — THE DOCTRINE: the log is the model's memory and the model ALONE
--- curates it (FOLD/KILL). The grinder never touches history — it only blocks NEW memories from
--- landing when there is no room: one set-op folds the still-open rows of the newest turn
--- boundary — the immediately-prior turn's emissions and the current turn's pre-model rows
--- (foists, wake surfaces). Turn 1 is the same rule (no prior turn; its foists are the newest).
+-- curates it (FOLD/KILL). The grinder rolls back only context introduced by the newest turn
+-- boundary: rows born in the immediately-prior/current turn plus exact older rows that a successful
+-- OPEN in the immediately-prior turn transitioned from folded to open. The durable effect relation
+-- owns that landed set; never re-run an authored glob/tag/matcher against later state. An OPEN no-op
+-- contributes no older row. Turn 1 is the same rule (no prior turn; its foists are the newest).
 -- Folded, never deleted; THREE exemptions ({§grinder-errors-exempt}): op='error',
 -- the user prompt, and PLAN. The temporary set captures the
 -- selection once so folding and additive `overflow` tagging cannot diverge.
 CREATE TEMP TABLE IF NOT EXISTS engine_grinder_fold_set (id INTEGER PRIMARY KEY);
 DELETE FROM engine_grinder_fold_set;
+WITH previous_turn AS (
+    SELECT MAX(id) AS id FROM turns WHERE loop_id = $loop_id AND id < $turn_id
+)
 INSERT INTO engine_grinder_fold_set (id)
-SELECT id FROM log_entries
-WHERE loop_id = $loop_id AND expanded = 1 AND op NOT IN ('error', 'PLAN')
-  AND COALESCE(scheme, '') != 'prompt'  -- the task frame ({§prompt-self-only}); NULL-safe: a model row's scheme is NULL
-  AND (turn_id = $turn_id
-       OR turn_id = (SELECT MAX(id) FROM turns WHERE loop_id = $loop_id AND id < $turn_id));
+SELECT boundary.id
+FROM log_entries boundary
+WHERE boundary.loop_id = $loop_id
+  AND boundary.expanded = 1
+  AND COALESCE(boundary.op, '') NOT IN ('error', 'PLAN')
+  AND COALESCE(boundary.scheme, '') != 'prompt'  -- the task frame ({§prompt-self-only}); NULL-safe: a model-emission row's scheme is NULL
+  AND (boundary.turn_id = $turn_id OR boundary.turn_id = (SELECT id FROM previous_turn))
+UNION
+SELECT target.id
+FROM log_curation_effects effect
+JOIN log_entries operation ON operation.id = effect.operation_log_entry_id
+JOIN log_entries target ON target.id = effect.target_log_entry_id
+WHERE operation.turn_id = (SELECT id FROM previous_turn)
+  AND operation.op = 'OPEN'
+  AND operation.status_rx < 400
+  AND effect.expanded_before = 0
+  AND target.expanded = 1
+  AND COALESCE(target.op, '') NOT IN ('error', 'PLAN')
+  AND COALESCE(target.scheme, '') != 'prompt';
 
 UPDATE log_entries SET expanded = 0
 WHERE id IN (SELECT id FROM engine_grinder_fold_set);
@@ -445,7 +488,7 @@ SELECT id, 'overflow' FROM engine_grinder_fold_set;
 DELETE FROM engine_grinder_fold_set;
 
 -- PREP: engine_fold_log_entry
--- Fold one known log row by id. Model mirror rows use this after insertion so
+-- Fold one known log row by id. Model-emission rows use this after insertion so
 -- the complete admitted emission remains available without opening by default.
 UPDATE log_entries SET expanded = 0 WHERE id = $id;
 
@@ -453,11 +496,12 @@ UPDATE log_entries SET expanded = 0 WHERE id = $id;
 -- Render-time log-section assembly ({§body-projection}).
 -- Yields log_entries for the whole worker — the conversation's working
 -- memory carries across loops within a worker, not just the
--- current loop. Coordinate is log:///<loop_seq>/<turn_seq>/<sequence>/<op>.
+-- current loop. Coordinates append /<op> only for rows that represent an operation.
 -- Status 202 entries in state='proposed' are model-invisible until resolved.
 -- `expanded = 0` rows are FOLDED — listed but collapsed to their coordinate
 -- (FOLD); the renderer elides the body. {§open-fold}: folded rows stay listed, re-OPENable.
 SELECT
+    le.id,
     l.sequence  AS loop_seq,
     t.sequence  AS turn_seq,
     le.sequence,
@@ -469,7 +513,13 @@ SELECT
     le.query, le.fragment,
     le.status_rx, le.rx, le.mimetype_rx,
     le.tx, le.mimetype_tx,
-    le.state, le.outcome, le.expanded, le.source, le.attrs
+    le.state, le.outcome, le.expanded, le.source, le.attrs,
+    COALESCE((
+        SELECT json_group_array(ordered.tag)
+        FROM (
+            SELECT tag FROM log_tags WHERE log_entry_id = le.id ORDER BY tag
+        ) ordered
+    ), '[]') AS tags
 FROM log_entries le
 JOIN turns t ON t.id = le.turn_id
 JOIN loops l ON l.id = le.loop_id
@@ -481,8 +531,8 @@ JOIN loops l ON l.id = le.loop_id
 -- {§operation-result-uniform-error-channel}.
 WHERE le.worker_id = $worker_id
   AND NOT (le.status_rx = 202 AND le.state = 'proposed')
-  AND NOT (le.op IN ('OPEN', 'FOLD') AND le.status_rx < 400)
-  AND NOT (le.op = 'KILL' AND le.scheme = 'log' AND le.status_rx < 400)
+  AND NOT (COALESCE(le.op, '') IN ('OPEN', 'FOLD') AND le.status_rx < 400)
+  AND NOT (COALESCE(le.op, '') = 'KILL' AND le.scheme = 'log' AND le.status_rx < 400)
 ORDER BY l.sequence, t.sequence, le.sequence;
 
 -- PREP: engine_insert_log_entry
@@ -491,14 +541,14 @@ ORDER BY l.sequence, t.sequence, le.sequence;
 -- triggers the proposal lifecycle (engine pauses dispatch; client resolves
 -- via proposal resolution; entry transitions through engine_resolve_log_entry).
 INSERT INTO log_entries (
-    worker_id, loop_id, turn_id, sequence, origin, source,
+    worker_id, loop_id, turn_id, sequence, origin, source, model_call_id,
     op, suffix, signal,
     scheme, username, password, hostname, port,
     pathname, query, fragment, lineMarker,
     tx, mimetype_tx, rx, mimetype_rx, status_rx, tokens,
     state, outcome, attrs
 ) VALUES (
-    $worker_id, $loop_id, $turn_id, $sequence, $origin, $source,
+    $worker_id, $loop_id, $turn_id, $sequence, $origin, $source, $model_call_id,
     $op, $suffix, $signal,
     $scheme, $username, $password, $hostname, $port,
     $pathname, $query, $fragment, $lineMarker,
@@ -533,12 +583,15 @@ SELECT l.sequence AS loop_seq,
   JOIN loops l ON l.id = le.loop_id
  WHERE le.id = $id;
 
--- PREP: engine_turn_retrievals
--- {§send-premature-terminate} — the pending set's retrieval leg: THIS turn's READ/FIND/OPEN rows,
--- whose results the model cannot have seen (they fold back next packet). A [200] over them is
--- discarding answers it asked for.
-SELECT id FROM log_entries
-WHERE turn_id = $turn_id AND origin = 'model' AND op IN ('READ', 'FIND', 'OPEN');
+-- PREP: engine_turn_packet_boundaries
+-- {§send-premature-terminate}/{§wait-obligation-matrix} — operations whose useful effect crosses
+-- into the next packet: READ/FIND/OPEN/BARE results, plus successful FOLD context curation. Retrievals
+-- block an explicit [200]; FOLD blocks only the empty-[202] inference because explicit final
+-- housekeeping remains valid.
+SELECT id, op FROM log_entries
+WHERE turn_id = $turn_id
+  AND origin = 'model'
+  AND (op IN ('READ', 'FIND', 'OPEN', 'BARE') OR (op = 'FOLD' AND status_rx < 400));
 
 -- PREP: engine_worker_has_undelivered_stream_term
 -- A stream may finish between its EXEC and a same-turn SEND. It is then no longer
@@ -568,8 +621,8 @@ LIMIT 1;
 -- errors the model cannot have seen (they land next packet). A [200] or already-drained [202] over
 -- them concludes blind past a failure — refused 409; [499] abandons regardless (declaring failure
 -- IS weighing it).
--- Actionless engine errors are excluded: the grinder's overflow row mints pre-packet, so the
--- recovery turn already saw it ({§grinder-hard-413-recovery}). A model-authored statement that
+-- Actionless engine errors are excluded because only model-authored failures can make
+-- the model's concluding disposition blind. A model-authored statement that
 -- failed grammar parsing is different: source='grammar' records a bounded operation failure
 -- from the accepted emission, unseen until the next packet, so it gates completion like every
 -- other failed model operation.
@@ -603,6 +656,22 @@ WITH RECURSIVE lineage(id, parent_worker_id) AS (
 )
 SELECT id FROM lineage WHERE parent_worker_id IS NULL;
 
+-- PREP: engine_worker_provider_identity
+-- Provider routing uses globally unique opaque identities, while all relational
+-- ownership and client coordinates retain the local integer worker id.
+-- {§worker-provider-identity} {§worker-primary}
+WITH RECURSIVE lineage(id, parent_worker_id, provider_identity) AS (
+    SELECT id, parent_worker_id, provider_identity FROM workers WHERE id = $worker_id
+    UNION ALL
+    SELECT w.id, w.parent_worker_id, w.provider_identity
+    FROM workers w JOIN lineage l ON w.id = l.parent_worker_id
+)
+SELECT current.provider_identity AS worker_id,
+       root.provider_identity AS primary_worker_id
+FROM workers current
+JOIN lineage root ON root.parent_worker_id IS NULL
+WHERE current.id = $worker_id;
+
 -- PREP: engine_worker_has_undelivered_child_term
 -- A child conclusion newer than the parent's observation cursor is complete but
 -- not delivered. This is the same durable boundary the next packet consumes,

package/dist/core/ExecutableTools.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeInvocationDecl } from "@plurnk/plurnk-execs";
+interface ExecutableTool {
+    readonly runtime: string;
+    readonly invocation: RuntimeInvocationDecl;
+}
+export default class ExecutableTools {
+    static render(tools: readonly ExecutableTool[]): string;
+}
+export {};
+//# sourceMappingURL=ExecutableTools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutableTools.d.ts","sourceRoot":"","sources":["../../src/core/ExecutableTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,UAAU,cAAc;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;CAC9C;AAqBD,MAAM,CAAC,OAAO,OAAO,eAAe;IAChC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAyBtD;CACJ"}

package/dist/core/ExecutableTools.js

@@ -0,0 +1,41 @@
+const escapeCell = (value) => value.replaceAll("|", "\\|");
+const bucket = (role, required, exclusive) => {
+    const marker = exclusive ? " ↔" : required ? "" : " ?";
+    return `${escapeCell(role)}${marker}`;
+};
+const code = (value) => {
+    const longest = Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
+    const fence = "`".repeat(longest + 1);
+    const padding = value.startsWith("`") || value.endsWith("`") ? " " : "";
+    return `${fence}${padding}${escapeCell(value)}${padding}${fence}`;
+};
+const example = (runtime, invocation) => {
+    const heading = `## EXEC0 [${runtime}]${invocation.example.target === undefined ? "" : ` (${invocation.example.target})`}`;
+    return [heading, invocation.example.body].filter((line) => line !== undefined).map((line) => code(line)).join("<br>");
+};
+export default class ExecutableTools {
+    static render(tools) {
+        if (tools.length === 0)
+            return "";
+        const rows = tools
+            .toSorted((left, right) => left.runtime.localeCompare(right.runtime))
+            .map(({ runtime, invocation }) => {
+            const exclusive = invocation.exclusive === true;
+            const target = invocation.target === undefined
+                ? "—"
+                : bucket(`${invocation.target.role}${invocation.target.directory === "cwd" ? " or local directory with body" : ""}`, invocation.target.required, exclusive);
+            const body = bucket(invocation.body.role, invocation.body.required, exclusive);
+            return `| \`[${runtime}]\` | ${target} | ${body} | ${example(runtime, invocation)} |`;
+        });
+        return [
+            "YOU SHOULD use purpose-built Plurnk OPs when possible; use EXEC for scripts only when necessary.",
+            "",
+            "`?` optional · `↔` choose one · `—` unavailable · `<timeout,poll>` optional",
+            "",
+            "| `[executor]` | `(target)` | body | example |",
+            "| --- | --- | --- | --- |",
+            ...rows,
+        ].join("\n");
+    }
+}
+//# sourceMappingURL=ExecutableTools.js.map

package/dist/core/ExecutableTools.js.map

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

package/dist/core/ExecutorRegistry.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelDecl, ExecArgs, ExecResult, Effect, RuntimeAvailability } from "@plurnk/plurnk-execs";
+import type { ChannelDecl, ExecArgs, ExecResult, Effect, RuntimeAvailability, RuntimeInvocationDecl } from "@plurnk/plurnk-execs";
 import { type PackageAttributions, type PluginAttribution, type PluginAttributionContext } from "@plurnk/plurnk-meta";
 import type { SchemeManifest } from "./types.ts";
 export interface Executor {
@@ -22,7 +22,7 @@ export interface RegistryEntry {
     readonly executor: Executor;
     readonly namespaceOwner: RuntimeNamespaceOwner;
     readonly glyph: string;
-    readonly example: string;
+    readonly invocation: RuntimeInvocationDecl;
     readonly documentation: string;
     readonly available: boolean;
     readonly detail: string | undefined;
@@ -41,7 +41,7 @@ export default class ExecutorRegistry {
             registry: ReadonlyMap<string, {
                 runtime: string;
                 glyph: string;
-                example?: string;
+                invocation: RuntimeInvocationDecl;
                 documentation?: string;
                 packageName: string;
             }>;

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

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

package/dist/core/ExecutorRegistry.js

@@ -76,7 +76,7 @@ export default class ExecutorRegistry {
         }
         // {§operator-config-git-ceiling} PLURNK_SERVICE_GIT_ALLOWED=0 must drop every
         // Git-capability executor entirely: a denied host neither dispatches
-        // EXEC[git]/EXEC[isogit] nor teaches them through the tools sheet.
+        // the Git/isogit EXEC runtimes nor teaches them through the tools sheet.
         const gitDenied = process.env.PLURNK_SERVICE_GIT_ALLOWED !== "1";
         const gitRuntimes = new Set(["git", "isogit"]);
         const infos = [...discovered.values()].filter((info) => !(gitDenied && gitRuntimes.has(info.runtime)));
@@ -95,7 +95,7 @@ export default class ExecutorRegistry {
                 executor,
                 namespaceOwner: { kind: "package", name: info.packageName },
                 glyph: info.glyph,
-                example: info.example ?? "",
+                invocation: info.invocation,
                 documentation: info.documentation ?? "",
                 available: availability.available,
                 detail: availability.detail,