@plurnk/plurnk-service 1.3.11 → 1.4.0

package/dist/schemes/Exec.js

@@ -1,28 +1,31 @@
-import { parsePath } from "@plurnk/plurnk-grammar";
+import { parsePath } from "@plurnk/plurnk-contracts";
 import { Policy } from "@plurnk/plurnk-execs";
-import { WebFetcher } from "@plurnk/plurnk-schemes-http";
+import { WebFetcher, WebMaterializationError, } from "@plurnk/plurnk-schemes-http";
 import WorkspaceSettings from "../core/workspace-settings.js";
 import EffectPolicy from "./EffectPolicy.js";
 import EntryOps from "./_entry-ops.js";
 import EntryCrud from "./_entry-crud.js";
 import Owner from "../core/Owner.js";
-import { foldAuthorityIntoPath } from "../core/plurnk-uri.js";
-import { decodePathParens } from "../core/path-decode.js";
 import EntryFind from "./_entry-find.js";
 import ChannelWrite from "../core/ChannelWrite.js";
 import ExecEnv from "./exec-env.js";
 import ExecAbort from "./exec-abort.js";
-import { renderAddress } from "../core/plurnk-uri.js";
+import { entryPathnameOf, renderAddress } from "../core/plurnk-uri.js";
 import { writeFile, unlink, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { CoreSchemeAdapterBase } from "../core/CoreSchemeServices.js";
+import ErrorDetail from "../core/ErrorDetail.js";
+import Results, { OperationFailureError } from "../core/results.js";
+import { InvalidOperationResultError, NetworkAddress } from "@plurnk/plurnk-schemes";
+import DbProjectionCaps from "../core/caps/DbProjectionCaps.js";
+import WorkerControlAddress from "../core/WorkerControlAddress.js";
+import JournalTurn from "../core/JournalTurn.js";
 // Executors are discovered + probed at boot into ExecutorRegistry and reach
-// the scheme through ctx.executors (plurnk-service#181). Each runtime tag
+// the scheme through ctx.executors ({§exec-registry-resolves}). Each runtime tag
 // resolves to its sibling executor; the scheme itself stays runtime-agnostic.
-// The local path a subprocess EXEC's `(target)` slot names — a bare local path or a file:/// URL (both
-// decode to a filesystem path). Stat-routed at dispatch (#462): a directory becomes cwd, a file is the
-// program/data-source. A plurnk-scheme target is NOT local — schemeTargetOf handles that.
+// Extract the local arm of {§exec-target-routing}; non-file schemes are
+// classified separately by schemeSourceOf.
 const localPathFromTarget = (target) => {
     if (target === null)
         return null;
@@ -33,22 +36,31 @@ const localPathFromTarget = (target) => {
     }
     return null;
 };
-// #201 — a plurnk-scheme target (known/exec/log/…), distinct from file/local
-// (which localPathFromTarget handles as a path). Its content is resolved at apply-time;
-// executors stay scheme-blind (SPEC §5), so the scheme — not the executor — reads it.
-const schemeTargetOf = (target) => {
+// A non-file scheme target is distinct from the local path handled above. The
+// consumer resolves its content at apply time; executors stay scheme-blind
+// ({§executor-role}).
+const schemeSourceOf = (target) => {
     if (target === null || target.kind !== "url")
         return null;
     if (target.scheme === null || target.scheme === "file")
         return null;
-    return { scheme: target.scheme, pathname: target.pathname, fragment: target.fragment };
+    return target.raw;
 };
+// {§exec-target-routing} — effect classifies the invocation core is admitting,
+// before a scheme-backed source can be materialized. A scheme target with no
+// body becomes the command, so the executor has no target. With a body, the
+// scheme content becomes a target at run time; its authored address is the
+// stable, opaque target-present identity used only for the one effect call.
+const effectTargetOf = (authoredTarget, routedTarget, schemeSource, command) => schemeSource !== null && command.length > 0
+    ? authoredTarget?.raw ?? null
+    : routedTarget;
 // EXEC's pathname is <runtime>/<loop_seq>/<turn_seq>/<sequence> (stamped by
 // Dispatcher.#writeLog). Exec owns this convention, so it — not the client — turns
 // the pathname into the entry's coordinate, mirrored onto stream payloads so
-// waterfall clients read fields instead of parsing the URI (#224). The
+// clients read fields instead of parsing the URI. The
 // coordinate is the trailing three segments (runtime-agnostic); a pathname that
 // isn't a numeric triple yields undefined (no coordinate on the wire).
+// {§notifications-stream-event-on-channel-change}, {§notifications-stream-concluded}
 const coordinateFromPathname = (pathname) => {
     const seg = pathname.split("/").filter(Boolean);
     if (seg.length < 3)
@@ -61,7 +73,8 @@ const coordinateFromPathname = (pathname) => {
 // {§stream-owner-scoped} — resolve a stream statement's authority to the owning worker and hand
 // back the statement authority-stripped (the storage path is the bare loop coordinate; the owner
 // rides the owner_id column, never the pathname). Empty authority = the CALLING worker — your own
-// streams need no qualifier, so a fan-out sibling's identical coordinate can never be yours (#526).
+// streams need no qualifier, so a fan-out sibling's identical coordinate can never be yours
+// ({§stream-owner-scoped}).
 // A named authority = that worker's streams, ancestry-gated (reader must be the owner or an
 // ancestor); an unknown name or unpermitted reader resolves null → the face 404s, no existence leak.
 export const resolveStreamStatement = async (statement, ctx) => {
@@ -80,18 +93,17 @@ export default class Exec extends CoreSchemeAdapterBase {
         channels: { stdout: "text/stream", stderr: "text/stream" },
         defaultChannel: "stdout",
         category: "data",
-        scope: "workspace",
         writableBy: ["model", "client"],
         volatile: true,
         modelVisible: true,
         example: "<<EXEC[sqlite]:SELECT 22.0 / 7.0:EXEC",
-        documentation: "Runs a command in a runtime — `<<EXEC[runtime](cwd):command:EXEC` — output streams into the worker's `<runtime>:///<loop>/<turn>/<seq>` entry on the runtime's own channels (a subprocess → stdout/stderr; a computational runtime like sqlite/jq → a JSON `results` channel). A host-effecting command proposes for review before it runs; a read-only/pure one runs ungated. Either way you never fetch the output: the engine surfaces each turn's new stream bytes to you automatically — folded while the command runs, opened when it finishes.",
+        documentation: "Runs a command in a runtime — `<<EXEC[runtime](target):command:EXEC` — output streams into the worker's `<runtime>:///<loop>/<turn>/<seq>` entry on the runtime's own channels (a subprocess → stdout/stderr; a computational runtime like sqlite/jq → a JSON `results` channel). A host-effecting command proposes for review before it runs; a read-only/pure one runs ungated. Either way you never fetch the output: the engine surfaces each turn's new stream bytes to you automatically — folded while the command runs, opened when it finishes.",
         flags: {
             excludedInAsk: true,
         },
     };
-    // The web-fetch the entry sink calls on content:null (§exec-entry-sink / #455). Default = schemes-http's
-    // guarded WebFetcher over one warm-Chromium pool shared across this handler's
+    // The web-fetch the entry sink calls on content:null ({§exec-entry-sink}). Default = schemes-http's
+    // checked WebFetcher over one warm-Chromium pool shared across this handler's
     // fallback renders; injectable so tests substitute the network.
     #fetchWeb;
     #closeWebFetcher;
@@ -111,6 +123,11 @@ export default class Exec extends CoreSchemeAdapterBase {
     #activeSpawns = new Map();
     async idle() {
         await Promise.allSettled([...this.#activeSpawns.values()]);
+    }
+    // {§handler-lifecycle} — idle is the streaming drain barrier; the handler
+    // hook owns release of its separate checked-fetch browser pool.
+    async close() {
+        await this.idle();
         await this.#closeWebFetcher();
     }
     // Whether the worker has an in-flight spawn (a background exec). The daemon
@@ -123,23 +140,16 @@ export default class Exec extends CoreSchemeAdapterBase {
                 return true;
         return false;
     }
-    // §exec-hold-until-concluded — does the worker hold an in-flight spawn whose RUNTIME is in the
-    // operator's hold set? The turn-hold exception (owner ruling): for streams we know and
-    // control (the search family — one final JSON digest, seconds-bounded), the engine holds
-    // the next packet until conclusion instead of giving the model a turn it can only waste.
+    // {§exec-hold-until-concluded} — match active spawns against the
+    // operator's runtime or runtime:effect hold selectors.
     hasActiveHoldSpawns(workerId, holdSet) {
         for (const { workerId: r, runtime, effect } of this.#activeAborts.values())
             if (r === workerId && (holdSet.has(runtime) || holdSet.has(`${runtime}:${effect}`)))
                 return true;
         return false;
     }
-    // Process-KILL (plurnk-service#203). A running (host/background) exec is
-    // addressable by its coordinate pathname; KILL aborts that spawn's controller with
-    // the model's signal — KILL[code] → exactly that signal once (KILL[9] = SIGKILL), a
-    // bare KILL → the executor's SIGHUP default. The model owns escalation, so there
-    // is no auto-escalation here. The full #203 status matrix: 200 killed (in-flight) · 410
-    // killed-earlier (a prior abort closed the stream 499) · 304 already-exited (closed
-    // with any other terminal status) · 404 unknown (no subscription for that coordinate).
+    // {§stream-control} — active KILL routes through the live controller;
+    // terminal and missing outcomes resolve from the durable subscription.
     async kill(pathname, signal, ctx, scheme = "exec") {
         const core = this.coreContext(ctx);
         for (const entry of this.#activeAborts.values()) {
@@ -151,32 +161,44 @@ export default class Exec extends CoreSchemeAdapterBase {
         // Not running — settle the outcome from the closed subscription's status, scoped to the
         // caller's own subscription (coordinates duplicate across workers, {§stream-owner-scoped}).
         // The error answers in the model's OWN runtime-tag address (sh:///…), never the retired
-        // internal `exec` scheme (#527, {§fs-answer-in-canon}) — the model KILLs what it addressed.
-        const terminal = await ChannelWrite.execTerminalStatus(core.db, { workspaceId: core.workspaceId, workerId: core.workerId, pathname });
-        if (terminal === null)
-            return { status: 404, error: `no active stream at ${scheme}://${pathname}` };
-        if (terminal === 499)
-            return { status: 410, error: `${scheme}://${pathname} was killed earlier` };
-        return { status: 304 };
+        // internal `exec` machinery ({§fs-answer-in-canon}) — the model KILLs what it addressed.
+        const terminal = await ChannelWrite.execTerminalStatus(core.db, {
+            workspaceId: core.workspaceId,
+            workerId: core.workerId,
+            scheme,
+            pathname,
+        });
+        const target = renderAddress(scheme, pathname);
+        if (terminal === null) {
+            return Results.failure("scheme:exec", "stream-not-found", 404, `No stream exists at ${target}.`, {}, { target });
+        }
+        if (terminal === 499) {
+            return Results.failure("scheme:exec", "stream-already-killed", 410, `Stream ${target} was already killed.`, {}, {
+                target,
+                retryable: false,
+            });
+        }
+        return Results.failure("scheme:exec", "stream-already-terminal", 409, `${target} already concluded with status ${terminal}.`, {}, {
+            target,
+            terminalStatus: terminal,
+            retryable: false,
+        });
     }
     // EXEC op handler — the actual model-facing entry point per plurnk.md.
-    // `<<EXEC[runtime](cwd):command:EXEC` →
-    //   signal=runtime, target=cwd (ParsedPath local/file or null), body=command.
+    // `<<EXEC[runtime](target):command:EXEC` →
+    //   signal=runtime, target=optional source/program/cwd, body=command.
     //
     // Proposes (status=202) with attrs={runtime, cwd, command, pathname}.
     // applyResolution spawns the subprocess; output streams into the
     // coordinate-stamped <runtime>:///<pathname> entry's stdout/stderr channels
-    // (e.g. sh:///1/1/2, §exec/#240). The model READs that entry on a subsequent turn.
+    // (e.g. sh:///1/1/2, {§exec}). The model READs that entry on a subsequent turn.
     async exec(statement, ctx) {
         const core = this.coreContext(ctx);
         let command = statement.body ?? "";
-        // #201 — a plurnk-scheme target carries content the scheme resolves at
-        // apply-time; an empty body is then legal (the target IS the script).
-        const schemeTarget = schemeTargetOf(statement.target);
-        // #462 — stat-route the local (target): a DIRECTORY overrides cwd (run the body IN it); a FILE is
-        // the program/data-source the executor runs (body = stdin). A stat-miss falls to the file arm so the
-        // runtime reports its own not-found, never a dispatch 400. cwd otherwise = the workspace workspace
-        // (project_root) — the directory File writes to, and what a data-source target resolves against.
+        // Non-file data sources resolve after acceptance. {§exec-target-routing}
+        const schemeSource = schemeSourceOf(statement.target);
+        // A local directory overrides cwd; every other local path remains the
+        // executor target. {§exec-target-routing}
         const workspaceRow = await core.db.envelope_get_workspace.get({ id: core.workspaceId });
         const projectRoot = workspaceRow?.project_root ?? null;
         const localTarget = localPathFromTarget(statement.target);
@@ -190,75 +212,96 @@ export default class Exec extends CoreSchemeAdapterBase {
                     routedTarget = null;
                 }
             }
-            catch { /* stat-miss → file arm; the runtime reports its own not-found */ }
+            catch (cause) {
+                if (cause?.code !== "ENOENT") {
+                    console.error(`EXEC target classification failed for '${abs}':`, cause);
+                    return Results.failure("scheme:exec", "target-classification-failed", 500, `EXEC target '${localTarget}' could not be inspected: ${ErrorDetail.preview(cause)}`, {}, {
+                        target: localTarget,
+                        stage: "target-classification",
+                    });
+                }
+            }
         }
-        // Empty body is legal when the target IS the program: a #201 scheme target (the target is the
-        // script) or a #462 FILE target (run it, no stdin). Empty body with a directory target (nothing
-        // to run) or no target at all → 400.
-        if (command.length === 0 && schemeTarget === null && routedTarget === null) {
-            return { status: 400, error: "EXEC requires a command body (or a scheme target to run)" };
+        // An empty body requires a file/program or scheme command source.
+        // {§exec-target-routing}
+        if (command.length === 0 && schemeSource === null && routedTarget === null) {
+            return Results.failure("scheme:exec", "command-required", 400, "EXEC requires a command body or an executable target.", {}, {
+                recovery: "Provide a command body or executable target.",
+                retryable: false,
+            });
         }
         const requested = typeof statement.signal === "string" ? statement.signal : "";
-        let runtime = requested === "" ? "sh" : requested; // empty signal = default shell
+        const runtime = requested === "" ? "sh" : requested; // empty signal = default shell
         if (core.executors === undefined)
             throw new Error("exec dispatched without an executor registry");
-        // §exec-runtime-fallthrough (#350, the execs architect's resolution to the go-501 saga):
-        // an UNREGISTERED tag falls through to the shell with the tag as the command word —
-        // EXEC[go]:test ./... runs as sh: `go test ./...`. Per-tool runtimes (go/cargo/make/npm)
-        // never earn tags (owner, execs#21); this automates the principle. The output entry lands
-        // under sh:// (it ran on sh), telemetry records what models reach FOR (the promotion
-        // signal is data, not guesswork), and a typo'd tag becomes the shell's own clear 127.
-        // No new surface: anything expressible as EXEC[foo]:bar was expressible as EXEC[sh]:foo bar.
-        let fellThroughFrom = null;
-        if (requested !== "" && core.executors.entry(runtime) === undefined && core.executors.entry("sh") !== undefined) {
-            fellThroughFrom = runtime;
-            command = command.length > 0 ? `${runtime} ${command}` : runtime;
-            runtime = "sh";
-        }
-        // #328 — per-workspace client policy narrows the boot-registered set (subtractive). A tag the
-        // workspace's client layer disables is ABSENT for this workspace — refused like an unavailable
-        // runtime. Checked on the EFFECTIVE runtime: a fall-through rides sh's gate, so a workspace
-        // that disabled sh gets the refusal, never a side door.
         const workspaceExecs = (await WorkspaceSettings.read(core.db, core.workspaceId)).execs;
-        if (workspaceExecs !== null && !Policy.isEnabled(runtime, workspaceExecs)) {
-            return { status: 501, error: `\`${runtime}\` is disabled for this workspace by client policy (PLURNK_EXECS_*)` };
-        }
-        const resolved = core.executors.entry(runtime); // registry resolves the runtime tag; unknown/unavailable → 501 — §exec-registry-resolves
+        // {§exec-registry-resolves} — a non-empty tag selects exactly one registered executable
+        // tool. Unknown tags are not reinterpreted as shell command words: that would make the
+        // executed command differ from the authored body. Bare EXEC remains the default-shell form.
+        const resolved = core.executors.entry(runtime);
         if (resolved === undefined) {
-            return { status: 501, error: `\`${runtime}\` is not a configured runtime. available: ${core.executors.availableRuntimes().join(", ")}` };
+            const available = core.executors.availableRuntimes()
+                .filter((tag) => workspaceExecs === null || Policy.isEnabled(tag, workspaceExecs));
+            return Results.failure("scheme:exec", "runtime-not-registered", 501, `Executable tool '${runtime}' is not registered in this workspace.`, {}, {
+                requestedRuntime: runtime,
+                availableRuntimes: available,
+                ...(available.length > 0
+                    ? {
+                        recovery: available.includes("sh")
+                            ? `Use bare EXEC for a shell command or select a registered executable tool: ${available.join(", ")}.`
+                            : `Select a registered executable tool: ${available.join(", ")}.`,
+                    }
+                    : {}),
+                retryable: false,
+            });
         }
-        if (fellThroughFrom !== null) {
-            core.pushTelemetry?.({ source: "exec:dispatch", kind: "exec_runtime_fallthrough", message: `EXEC[${fellThroughFrom}] fell through to sh`, requested: fellThroughFrom, level: "info" });
+        // {§operator-config-workspace-execs} — the workspace layer only narrows
+        // the registered set. Bare EXEC resolves to sh before the same gate.
+        if (workspaceExecs !== null && !Policy.isEnabled(runtime, workspaceExecs)) {
+            const available = core.executors.availableRuntimes()
+                .filter((tag) => Policy.isEnabled(tag, workspaceExecs));
+            return Results.failure("scheme:exec", "runtime-disabled", 501, `Executable tool '${runtime}' is disabled by workspace policy.`, {}, {
+                requestedRuntime: runtime,
+                availableRuntimes: available,
+                recovery: available.length > 0
+                    ? `Use an enabled executable tool: ${available.join(", ")}.`
+                    : "Continue without executing a tool in this workspace.",
+                retryable: false,
+            });
         }
         if (!resolved.available) {
-            const why = resolved.detail === undefined ? "" : `: ${resolved.detail}`;
-            return { status: 501, error: `\`${runtime}\` is unavailable${why}` };
+            const why = resolved.detail === undefined ? "" : `: ${ErrorDetail.preview(resolved.detail)}`;
+            return Results.failure("scheme:exec", "runtime-unavailable", 501, `Executable tool '${runtime}' is unavailable${why}.`, {}, {
+                requestedRuntime: runtime,
+                retryable: false,
+            });
         }
-        // The (target) slot the executor receives — its DATA SOURCE / program (jq input, sqlite db, or a
-        // subprocess program run with the body as stdin; #15). A #462 directory target routed to cwd above
-        // leaves this null (the body is the command, run in that directory).
+        // The local (target) realization the executor receives — its data source
+        // or program. A directory routes to cwd and a scheme source is resolved
+        // only after acceptance, so either is null here.
         const target = routedTarget;
-        // Effect classifies by the target only, never by parsing the command (#289): host → propose,
-        // read/pure → auto-run inline (plurnk-service#182).
-        const policy = EffectPolicy.decide(resolved.executor.effect(target, command));
-        // cwd is the workspace WORKSPACE (project_root) — the directory File writes to and a relative
-        // data-source target resolves against (execs 0.4.26 §2) — UNLESS a #462 directory target overrode
-        // it above, in which case the body runs in that directory. A file/data-source target never moves cwd.
+        // Derive one effect from the canonical logical target before any policy
+        // consumes it, then preserve that fact with the invocation (#107,
+        // {§executor-effect}). Leaves never receive authored command text.
+        const effectTarget = effectTargetOf(statement.target, target, schemeSource, command);
+        const effect = resolved.executor.effect(effectTarget);
+        // cwd is the workspace project_root unless target routing selected a
+        // directory override. {§exec-target-routing}, {§executor-sinks}
         // Pathname is assigned by Dispatcher.#writeLog as <runtime>/<loop_seq>/
         // <turn_seq>/<sequence> (executor-domain + coordinate, e.g. sh/1/1/2).
         // `pathname` is stamped into attrs at log-write time; applyResolution
         // reads it back here.
         // EXEC repurposes the `<L>` slot as `<timeout, poll>` (seconds): mark[0] caps the spawn's
-        // lifetime, mark[1] sets the hibernation poll-wake cadence (§exec-poll). N>0 → deadline (504);
+        // lifetime, mark[1] sets the hibernation poll-wake cadence ({§exec-poll}). N>0 → deadline (504);
         // -1 / absent → unbounded (loop-life bounded); 0 → turn-scoped (reaped at the next pre-turn,
         // never surviving into the subsequent turn).
         const marks = statement.lineMarker?.marks;
         const timeoutSec = typeof marks?.[0] === "number" && marks[0] > 0 ? Math.floor(marks[0]) : undefined;
         const turnScoped = typeof marks?.[0] === "number" && marks[0] === 0;
-        const pollSec = typeof marks?.[1] === "number" && marks[1] > 0 ? Math.floor(marks[1]) : undefined;
+        const pollSec = typeof marks?.[1] === "number" && marks[1] >= 0 ? Math.floor(marks[1]) : undefined;
         const attrs = {
-            runtime, cwd, command, target, pathname: "", inline: policy === "auto",
-            ...(schemeTarget !== null ? { schemeTarget } : {}),
+            runtime, cwd, command, target, pathname: "", effect,
+            ...(schemeSource !== null ? { schemeSource } : {}),
             ...(timeoutSec !== undefined ? { timeoutSec } : {}),
             ...(turnScoped ? { turnScoped: true } : {}),
             ...(pollSec !== undefined ? { pollSec } : {}),
@@ -266,7 +309,7 @@ export default class Exec extends CoreSchemeAdapterBase {
         // Body shown to client during proposal review — `$ command` is the
         // most-readable summary regardless of runtime.
         const preview = runtime !== "" ? `[${runtime}] ${command}` : `$ ${command}`;
-        return { status: 202, body: preview, attrs }; // host runtime proposes with 202 — §exec-host-proposes
+        return { status: 202, body: preview, attrs }; // host runtime proposes with 202 — {§exec-host-proposes}
     }
     async applyResolution(args, ctx) {
         const core = this.coreContext(ctx);
@@ -276,25 +319,42 @@ export default class Exec extends CoreSchemeAdapterBase {
         const runtime = (typeof attrs.runtime === "string" && attrs.runtime !== "") ? attrs.runtime : "sh";
         const cwd = (typeof attrs.cwd === "string" && attrs.cwd.length > 0) ? attrs.cwd : null;
         let target = (typeof attrs.target === "string" && attrs.target.length > 0) ? attrs.target : null;
+        const effect = attrs.effect;
         if (typeof pathname !== "string" || pathname.length === 0) {
-            return { status: 500, outcome: "missing_pathname" };
+            throw new InvalidOperationResultError("The accepted EXEC proposal is missing its stream pathname.");
+        }
+        if (!EffectPolicy.isEffect(effect)) {
+            throw new InvalidOperationResultError("The accepted EXEC proposal is missing its canonical effect fact.");
         }
-        // #201 — resolve a scheme-URI target to content (executors stay scheme-blind).
-        // Empty body → the resolved content IS the command (run a stored script).
-        // Non-empty body → materialize the content to a temp file whose path becomes
-        // the runtime's data-source TARGET (the input for filters/sqlite/wasm).
+        // Resolve a scheme target after acceptance: empty body uses the content
+        // as the command; otherwise a temporary file becomes the data target.
+        // {§exec-target-routing}
         let tempPath = null;
-        if (attrs.schemeTarget !== undefined) {
-            const { scheme, pathname: tPath, fragment } = attrs.schemeTarget;
-            const read = await EntryCrud.readEntry(tPath, core, scheme);
-            if (read.entry === null)
-                return { status: 404, outcome: "scheme_target_not_found" };
-            const channels = read.entry.channels;
-            const channelName = fragment ?? (channels.body !== undefined ? "body" : Object.keys(channels)[0]);
-            const content = channelName === undefined ? undefined : channels[channelName]?.content;
-            // §channel-selection-unknown-channel-400 sibling fact — the miss names what exists.
-            if (content === undefined)
-                return { status: 404, outcome: "scheme_target_channel_not_found", error: `no channel #${channelName ?? fragment} at ${scheme}:///${tPath.replace(/^\//, "")}; channels: ${Object.keys(channels).join(", ")}` };
+        if (attrs.schemeSource !== undefined) {
+            const sourceTarget = parsePath(attrs.schemeSource);
+            if (sourceTarget?.kind !== "url" || sourceTarget.scheme === null || sourceTarget.scheme === "file") {
+                throw new InvalidOperationResultError("The accepted EXEC proposal has an invalid scheme source address.");
+            }
+            const read = await this.readExecSource({
+                op: "READ",
+                suffix: "",
+                signal: null,
+                target: sourceTarget,
+                lineMarker: null,
+                body: null,
+                position: { line: 0, column: 0 },
+            }, core);
+            if (read.status >= 400) {
+                return Results.assert({ ...read, outcome: "scheme_source_read_failed" });
+            }
+            const content = read.content;
+            if (typeof content !== "string") {
+                return Results.failure("scheme:exec", "source-content-unavailable", 422, `Scheme '${sourceTarget.scheme}' did not supply content for the EXEC source.`, { outcome: "scheme_source_content_unavailable" }, {
+                    scheme: sourceTarget.scheme,
+                    sourceStatus: read.status,
+                    retryable: false,
+                });
+            }
             if (command.length === 0) {
                 command = content;
             }
@@ -304,25 +364,26 @@ export default class Exec extends CoreSchemeAdapterBase {
                 target = tempPath;
             }
         }
-        // #500 — the accept-half mirrors the propose-half's #462 stat-route: an empty body with a
-        // LOCAL FILE target is legal (the target IS the program — the executor runs it as its script
-        // positional, transient exec per the owner ruling). Empty body with no target of any kind
-        // remains the contradiction.
+        // {§exec-target-routing} — a local file target is itself the program, so
+        // its body may be empty; no target and no command remains invalid.
         if (command.length === 0 && target === null) {
-            return { status: 500, outcome: "missing_command" };
+            if (attrs.schemeSource !== undefined) {
+                return Results.failure("scheme:exec", "source-command-empty", 422, "The EXEC source resolved to an empty command.", { outcome: "scheme_source_command_empty" }, { retryable: false });
+            }
+            throw new InvalidOperationResultError("The accepted EXEC proposal has neither a command nor a target.");
         }
         // Resolve the runtime's executor from the boot registry, then seed
-        // channels from its declared topology (Q1(b) in plurnk-service#174 —
-        // executor declares, scheme honors). Each executor declares its own
+        // channels from its declared topology ({§executor-channels}). Each executor declares its own
         // shape (subprocess → stdout/stderr; search → results; etc.).
-        if (core.executors === undefined)
-            return { status: 500, outcome: "no_executor_registry" };
+        if (core.executors === undefined) {
+            throw new InvalidOperationResultError("An accepted EXEC proposal has no executor registry.");
+        }
         const resolved = core.executors.entry(runtime);
-        if (resolved === undefined)
-            return { status: 500, outcome: "no_executor" };
-        // #485 — the per-tool effect (execs Effect: read/host/pure) rides the hold predicate so a
-        // suffixed PLURNK_SERVICE_EXEC_HOLD entry (`github:read`) can hold one tool-class and not another.
-        const effect = resolved.executor.effect(target, command);
+        if (resolved === undefined) {
+            throw new InvalidOperationResultError(`The '${runtime}' executor disappeared after its EXEC proposal.`);
+        }
+        // {§executor-effect}, {§exec-hold-until-concluded}, #107: the admitted
+        // effect fact rides the hold predicate unchanged through application.
         const seedChannels = {};
         for (const [name, decl] of Object.entries(resolved.executor.channels)) {
             seedChannels[name] = {
@@ -332,16 +393,23 @@ export default class Exec extends CoreSchemeAdapterBase {
             };
         }
         const seed = { channels: seedChannels, tags: [] };
-        // §exec — the stream entry's scheme IS the runtime tag (sh/node), so it addresses by
+        // {§exec} — the stream entry's scheme IS the runtime tag (sh/node), so it addresses by
         // tag authority (sh:///l/t/s). The engine registers each runtime tag → this handler.
         const { entryId } = await EntryCrud.writeEntry(pathname, seed, core, runtime, core.workerId);
-        if (entryId === null)
-            return { status: 500, outcome: "entry_write_failed" };
+        if (entryId === null) {
+            return Results.failure("scheme:exec", "stream-entry-write-failed", 500, `The ${runtime} stream entry could not be created.`, {
+                outcome: "entry_write_failed",
+            }, {
+                runtime,
+                stage: "stream-creation",
+                retryable: false,
+            });
+        }
         const subscriptionId = await ChannelWrite.openSubscription(core.db, {
             workerId: core.workerId, entryId, scheme: runtime,
             handle: runtime !== "" ? `${runtime}: ${command}` : command,
-            pollSeconds: typeof attrs.pollSec === "number" ? attrs.pollSec : null, // §exec-poll — hibernation wake cadence
-            turnScoped: attrs.turnScoped === true, // §exec-poll — `<0>` reaped at the next pre-turn
+            pollSeconds: typeof attrs.pollSec === "number" ? attrs.pollSec : null, // {§exec-poll} — hibernation wake cadence
+            turnScoped: attrs.turnScoped === true, // {§exec-poll} — `<0>` reaped at the next pre-turn
         });
         const controller = new AbortController();
         let unlink = () => { };
@@ -354,7 +422,7 @@ export default class Exec extends CoreSchemeAdapterBase {
             // then re-check `aborted`: a listener added to an already-aborted signal never
             // fires, so a check-then-attach order LOSES an abort that lands in the gap (R1's
             // TOCTOU leak). Attach-then-check closes it; controller.abort is idempotent, so a
-            // doubled fire is harmless. §exec-timeout
+            // doubled fire is harmless. {§exec-timeout}
             const onParentAbort = () => controller.abort(ExecAbort.teardownReason());
             parent.addEventListener("abort", onParentAbort, { once: true });
             unlink = () => parent.removeEventListener("abort", onParentAbort);
@@ -371,18 +439,19 @@ export default class Exec extends CoreSchemeAdapterBase {
             entryId, subscriptionId, signal: controller.signal, controller, tempPath,
             timeoutSec: typeof attrs.timeoutSec === "number" ? attrs.timeoutSec : null,
         });
-        // Every exec backgrounds + streams (§exec-stream): no same-turn receipt — the output
+        // Every exec backgrounds + streams ({§exec-stream}): no same-turn receipt — the output
         // surfaces as the environment-observation injector's delta on the next turn (folded while
-        // it runs, opened when it finishes). Pure/read commands still auto-accept (attrs.inline =
-        // no human gate); they just resolve a turn later, uniformly with host streams.
+        // it runs, opened when it finishes). Pure/read commands still auto-accept
+        // from the preserved effect fact; they resolve a turn later, uniformly
+        // with host streams.
         this.#activeSpawns.set(subscriptionId, tail);
         return { status: 200, outcome: "started" };
     }
     // Bridge the executor's sink-style contract (write/setState/emit)
     // onto plurnk-service's storage primitives (appendToChannel,
-    // setChannelState, ctx.pushTelemetry). Per plurnk-service#174 Q3,
-    // executor TelemetryEvents flow through the same engine path as
-    // grammar parse_errors — emit → buffer → next packet + live notify.
+    // setChannelState, ctx.pushNotice). Under {§executor-results},
+    // executor Notices flow through the same engine path as
+    // grammar parse advisories: emit, buffer, next packet, and live notify.
     //
     // write() and setState() callbacks must run in emission order:
     // appendToChannel reads channel state AFTER the append commits, so
@@ -392,7 +461,7 @@ export default class Exec extends CoreSchemeAdapterBase {
     async #runExecutor(opts) {
         const { executor, runtime, command, cwd, target, ctx, pathname, entryId, subscriptionId, signal, controller, timeoutSec, tempPath } = opts;
         const db = ctx.db;
-        const coordinate = coordinateFromPathname(pathname); // #224 — stamped on stream/event + stream/concluded
+        const coordinate = coordinateFromPathname(pathname);
         // grammar 0.74.20 EXEC `<T>` — kill the spawn after T seconds. unref'd so a pending timer never
         // holds the process open; cleared in finally so a spawn that finishes first leaves no timer.
         let timedOut = false;
@@ -404,216 +473,255 @@ export default class Exec extends CoreSchemeAdapterBase {
         const enqueue = (op) => {
             queue = queue.then(op, op);
         };
-        let closeStatus = 500;
-        let exitLabel = "spawn_failed";
+        let result = Results.failure("scheme:exec", "executor-did-not-conclude", 500, `The '${runtime}' executor did not produce a terminal result.`, {}, {
+            runtime,
+            stage: "execution",
+            retryable: false,
+        });
+        let exitLabel = "did not conclude";
         let stdoutLength = 0;
         let stderrLength = 0;
-        // §exec-entry-sink (#340) — the executor's entry() materialization request. The executor
-        // owns zero substrate: it hands us (path, content, {tags, mimetype}) and WE create/update
-        // the entry (writeEntry upsert; tags UNIONED — writeEntry alone replaces), then narrate ONE
-        // EDIT row in the reserved plurnk worker's log (the fs-fiction pattern, source = the calling
-        // run) — the existing env-delta ambience folds it into every worker's next packet. The row is a
-        // FULL fiction: tx carries the statement (body = the written content — the journal records
-        // the write, replay/fork-complete), rx carries the span (§edit-result-render, the whole
-        // content numbered — a wholesale write's span IS the content; no diff, which would be a
-        // pathological cost against a rewritten multi-MB page). Rendered folded by default, so no
-        // body rides a packet uninvited — the meta line carries the honest OPEN weight.
-        // Serialized: parallel entry() calls (allSettled) write in order; a rejection prunes that
-        // survivor executor-side without breaking the chain. Lazy narration context: one plurnk-run
-        // turn per spawn, not per entry.
+        // {§exec-entry-sink} {§env-delta-entry-materialization} — serialize
+        // executor entry() materializations and narrate them through the one
+        // reserved-worker turn owned by this spawn.
         let entryChain = Promise.resolve();
         let narration = null;
+        let callerSource;
+        const resolveCallerSource = async () => {
+            if (callerSource !== undefined)
+                return callerSource;
+            const caller = await db.worker_name_by_id.get({ worker_id: ctx.workerId });
+            if (caller === undefined)
+                throw new Error(`entry(): calling worker ${ctx.workerId} does not exist`);
+            callerSource = WorkerControlAddress.render(caller.name);
+            return callerSource;
+        };
         const entrySink = (path, content, opts) => {
             const parsed = parsePath(path);
-            if (parsed === null || parsed.kind !== "url" || parsed.scheme === null)
+            if (parsed === null || parsed.kind !== "url")
                 return Promise.reject(new Error(`entry(): '${path.slice(0, 80)}' is not a URL`));
             if (content !== null && opts.mimetype === undefined)
                 return Promise.reject(new Error("entry(): mimetype is required when content is provided"));
-            // §exec-entry-sink / #455 — content:null ⇒ core fetches the page through schemes-http's guarded
-            // primitive. The fetch STARTS HERE, OFF the write-serialization chain, so concurrent entry() calls
-            // fetch in PARALLEL (owner ruling: search fetches must not freeze the agent); only the entry WRITE
-            // serializes on entryChain (db-write ordering). A null fetch is dead (guard-refused / unreachable /
-            // non-2xx / non-textual / empty) and REJECTS, so the executor prunes that survivor. Non-null content
-            // is the materialize-given-body path — the caller already holds the bytes and states their mimetype.
-            const materialized = content === null
-                ? this.#fetchWeb(path, { signal })
-                : Promise.resolve({ body: content, mimetype: opts.mimetype });
+            const address = NetworkAddress.supports(parsed.scheme) ? NetworkAddress.from(parsed) : null;
+            if (address?.hasCredentials === true)
+                return Promise.reject(new Error("entry(): network URL userinfo is not allowed"));
+            const fetchAddress = address !== null && (address.scheme === "http" || address.scheme === "https")
+                ? address
+                : null;
+            const pathname = address?.pathname ?? entryPathnameOf(parsed);
+            const scheme = address?.scheme ?? parsed.scheme;
+            // {§exec-entry-sink}/{§web-search-retrieval} — start content:null
+            // acquisition before the write chain so fetches run in parallel;
+            // only durable entry writes serialize. A null result rejects the sink.
+            let materialized;
+            if (content === null) {
+                if (fetchAddress === null)
+                    return Promise.reject(new Error("entry(): content:null requires an http(s):// URL"));
+                materialized = this.#fetchWeb(fetchAddress.url, { signal });
+            }
+            else {
+                materialized = Promise.resolve({ body: content, mimetype: opts.mimetype });
+            }
             const op = async () => {
                 const fetched = await materialized;
                 if (fetched === null)
                     throw new Error(`entry(): '${path.slice(0, 80)}' is dead`);
-                let { body, mimetype } = fetched;
-                // External URLs arrive in transport-safe spelling, while entry identity uses
-                // the grammar's canonical resolved path. Store the decoded identity; renderers
-                // encode parentheses again when the address returns to the model.
-                const pathname = decodePathParens(foldAuthorityIntoPath(parsed.hostname, parsed.pathname));
-                const prior = await EntryCrud.readEntry(pathname, ctx, parsed.scheme);
-                const tags = [...new Set([...(prior.entry?.tags ?? []), ...opts.tags])];
-                // The web-fetch entry point: a fetched html page stores the handler's readable
-                // projection as the decisive `body` (text/markdown — what READ serves, FIND matches,
-                // FTS indexes, every weight reports) with the raw page under `html` (xpath + archive).
-                // Scoped HERE, not writeEntry: only auto-fetched web content projects; authored files
-                // stay verbatim (a `<user email=…>` roster's attribute data must survive a default READ).
-                let channels = { body: { content: body, mimetype } };
-                if (fetched.header !== undefined)
-                    channels.header = { content: fetched.header, mimetype: "text/plain" };
-                let decisive = body;
-                if (mimetype === "text/html") {
-                    if (ctx.mimetypes === undefined)
-                        throw new Error("entry(): HTML materialization requires the mimetype registry");
-                    let projected = (await ctx.mimetypes.process({ content: body, hint: "text/html" }, { channels: ["content"] })).content;
-                    if ((typeof projected !== "string" || projected.length === 0) && fetched.render !== undefined) {
-                        const rendered = await fetched.render();
-                        if (rendered !== null) {
-                            body = rendered.body;
-                            mimetype = rendered.mimetype;
-                            projected = (await ctx.mimetypes.process({ content: body, hint: "text/html" }, { channels: ["content"] })).content;
-                        }
-                    }
-                    if (typeof projected !== "string" || projected.length === 0) {
-                        throw new Error(`entry(): '${path.slice(0, 80)}' has no readable HTML projection`);
+                let web;
+                try {
+                    web = await WebFetcher.materialize(fetched, new DbProjectionCaps(ctx));
+                }
+                catch (error) {
+                    if (!signal.aborted && error instanceof WebMaterializationError) {
+                        console.error("entry() web materialization failed", { path, error });
                     }
-                    channels = {
-                        body: { content: projected, mimetype: "text/markdown" },
-                        html: { content: body, mimetype },
-                        ...(fetched.header === undefined ? {} : { header: { content: fetched.header, mimetype: "text/plain" } }),
-                    };
-                    decisive = projected;
+                    throw error;
                 }
-                const written = await EntryCrud.writeEntry(pathname, { channels, tags }, ctx, parsed.scheme);
+                if (web === null)
+                    throw new Error(`entry(): '${path.slice(0, 80)}' has no readable projection`);
+                const prior = await EntryCrud.readEntry(pathname, ctx, scheme);
+                const tags = [...new Set([...(prior.entry?.tags ?? []), ...opts.tags])];
+                // {§exec-entry-sink}/{§html-materialization} The shared
+                // materializer owns the decisive projection and its provenance.
+                const channels = {
+                    body: web.body,
+                    ...(web.html === undefined ? {} : { html: web.html }),
+                    ...(web.header === undefined ? {} : { header: { content: web.header, mimetype: "text/plain" } }),
+                };
+                const decisive = web.body.content;
+                const source = web.html?.content ?? decisive;
+                const causalSource = await resolveCallerSource();
+                const written = Results.assert(await EntryCrud.writeEntry(pathname, { channels, tags }, ctx, scheme));
                 if (narration === null) {
-                    const run = await db.envelope_get_worker_by_name.get({ workspace_id: ctx.workspaceId, name: "plurnk" })
+                    const worker = await db.envelope_get_worker_by_name.get({ workspace_id: ctx.workspaceId, name: "plurnk" })
                         ?? await db.envelope_insert_worker.get({ workspace_id: ctx.workspaceId, name: "plurnk", origin: "plurnk" });
-                    if (run === undefined)
+                    if (worker === undefined)
                         throw new Error("entry(): plurnk worker resolution returned no row");
-                    const loop = await db.envelope_insert_client_loop.get({ worker_id: run.id });
+                    const loop = await db.envelope_insert_client_loop.get({ worker_id: worker.id });
                     if (loop === undefined)
                         throw new Error("entry(): loop insert returned no row");
-                    const seqRow = await db.client_turn_next_sequence.get({ loop_id: loop.id });
-                    const turn = await db.client_turn_insert.get({ loop_id: loop.id, sequence: seqRow?.next ?? 1, packet: "{}" });
-                    if (turn === undefined)
-                        throw new Error("entry(): turn insert returned no row");
-                    narration = { workerId: run.id, loopId: loop.id, turnId: turn.id, seq: 1 };
+                    const turn = await JournalTurn.insert(db, loop.id);
+                    narration = {
+                        workerId: worker.id,
+                        loopId: loop.id,
+                        loopSeq: loop.sequence,
+                        turnId: turn.id,
+                        turnSeq: turn.sequence,
+                        seq: 1,
+                    };
+                }
+                const sequence = narration.seq++;
+                if (written.problem !== undefined) {
+                    Results.attachInstance(written, `log:///${narration.loopSeq}/${narration.turnSeq}/${sequence}/EDIT`);
                 }
                 await db.engine_insert_log_entry.get({
-                    worker_id: narration.workerId, loop_id: narration.loopId, turn_id: narration.turnId, sequence: narration.seq++,
+                    worker_id: narration.workerId, loop_id: narration.loopId, turn_id: narration.turnId, sequence,
                     // signal carries the tags — the SAME slot a model's EDIT[tags] uses, so the
                     // ambient row renders its tags natively everywhere (packet meta line, digest).
-                    origin: "plurnk", source: String(ctx.workerId), op: "EDIT", suffix: "", signal: JSON.stringify(tags),
-                    scheme: parsed.scheme, username: null, password: null, hostname: null, port: null,
-                    pathname, params: null, fragment: null, lineMarker: null,
-                    tx: JSON.stringify({ op: "EDIT", body }), mimetype_tx: "application/json",
-                    rx: JSON.stringify({
-                        status: written.status, entryId: written.entryId, tags,
-                        span: decisive.split("\n").map((l, n) => `${n + 1}:${l}`).join("\n"),
-                    }), mimetype_rx: "application/json",
+                    origin: "plurnk", source: causalSource, op: "EDIT", suffix: "", signal: JSON.stringify(tags),
+                    scheme, username: null, password: null, hostname: null, port: null,
+                    pathname, query: null, fragment: null, lineMarker: null,
+                    tx: JSON.stringify({ op: "EDIT", body: source }), mimetype_tx: "application/json",
+                    rx: JSON.stringify(written.problem === undefined
+                        ? {
+                            ...written,
+                            tags,
+                            span: decisive.split("\n").map((l, n) => `${n + 1}:${l}`).join("\n"),
+                        }
+                        : written),
+                    mimetype_rx: "application/json",
                     status_rx: written.status, tokens: ctx.tokenize?.(decisive) ?? 0, state: "resolved", outcome: null,
                     // Durable provenance for clients/forensics. This is machine
                     // ambience, not a human/model action waterfall item.
                     attrs: JSON.stringify({ tags, kind: "entry_materialized" }),
                 });
-                return renderAddress(parsed.scheme, pathname);
+                if (written.problem !== undefined)
+                    throw new OperationFailureError(written);
+                return renderAddress(scheme, pathname);
             };
             const run = entryChain.then(op, op);
             entryChain = run.then(() => undefined, () => undefined);
             return run;
         };
         try {
-            let result = null;
             try {
-                result = await executor.run({
+                const reported = await executor.run({
                     runtime, command, cwd, target, signal,
                     entry: entrySink,
-                    env: ExecEnv.scoped(), // SPEC §exec {§exec-env-scoped} — never plurnk's own secrets
+                    env: ExecEnv.scoped(), // SPEC {§exec} {§exec-env-scoped} — never plurnk's own secrets
                     write: (channel, chunk) => enqueue(() => ChannelWrite.appendToChannel(db, {
                         entryId, channel, chunk, notify: ctx.streamEventNotify, coordinate,
                     })),
                     setState: (channel, state) => enqueue(() => ChannelWrite.setChannelState(db, {
                         entryId, channel, state, notify: ctx.streamEventNotify, coordinate,
                     })),
-                    emit: (event) => {
-                        // The executor plugin's TelemetryEvent predates grammar's required `level`;
-                        // inject a default (forwarding the producer's own severity when it supplies one). #276
-                        const level = event.level ?? "info";
-                        ctx.pushTelemetry?.({ ...event, level });
-                    },
+                    emit: (event) => ctx.pushNotice?.(event),
                 });
                 // Drain the queue so the subscription doesn't close before
                 // final chunk events / state transitions have committed.
                 await queue;
+                try {
+                    result = Results.assert(reported);
+                }
+                catch (cause) {
+                    console.error(`Executor '${runtime}' returned an invalid operation result:`, cause);
+                    result = Results.failure("scheme:exec", "executor-invalid-result", 500, `The '${runtime}' executor returned an invalid operation result.`, {}, {
+                        runtime,
+                        stage: "result-validation",
+                        retryable: false,
+                    });
+                }
             }
             catch (cause) {
                 // A rejecting driver must still CONCLUDE its stream — uncaught, the subscription sat
                 // open forever and the floating spawn promise was an unhandled rejection.
-                exitLabel = `driver_crashed: ${cause instanceof Error ? cause.message : String(cause)}`;
+                console.error(`Executor '${runtime}' threw outside its operation result contract:`, cause);
+                result = Results.failure("scheme:exec", "executor-threw", 500, `The '${runtime}' executor failed outside its operation result contract.`, {}, {
+                    runtime,
+                    stage: "execution",
+                    retryable: false,
+                });
             }
-            if (result !== null) {
-                const exitCode = result.exitCode ?? -1;
-                closeStatus = result.status;
-                // A timeout aborts the spawn → the executor reports 499; restamp it 504 so the model
-                // sees "ran out of time" distinct from a deliberate kill/cancel (§exec-timeout).
-                if (timedOut && closeStatus === 499)
-                    closeStatus = 504;
-                // The service's own abort knowledge outranks a driver's claim: a spawn we reaped
-                // (teardown/kill/cancel) did not succeed, whatever status it resolved under abort.
-                if (signal.aborted && !timedOut && closeStatus < 400) {
-                    closeStatus = 499;
-                    exitLabel = "reaped";
-                }
-                else
-                    exitLabel = closeStatus === 504 ? `timed out after ${timeoutSec}s`
-                        : closeStatus === 499 ? "aborted"
-                            : closeStatus === 500 && exitCode === -1 ? "spawn_failed"
-                                : `exit ${exitCode}`;
+            const exitCode = typeof result.exitCode === "number" ? result.exitCode : null;
+            // A timeout aborts the spawn → the executor reports 499; replace the
+            // complete result so status and Problem remain one valid truth.
+            if (timedOut) {
+                result = Results.failure("scheme:exec", "execution-timeout", 504, `Execution of '${runtime}' exceeded its ${timeoutSec}-second deadline.`, exitCode === null ? {} : { exitCode }, {
+                    runtime,
+                    timeoutSeconds: timeoutSec,
+                    stage: "execution",
+                    retryable: false,
+                });
+                // The service's own abort knowledge outranks a driver's claim: a
+                // spawn we reaped did not succeed, whatever it resolved under abort.
             }
-            await ChannelWrite.closeSubscription(db, { subscriptionId, status: closeStatus });
+            else if (signal.aborted && result.status < 400) {
+                result = Results.failure("scheme:exec", "execution-cancelled", 499, `Execution of '${runtime}' was cancelled by the service.`, exitCode === null ? {} : { exitCode }, {
+                    runtime,
+                    stage: "execution",
+                    retryable: false,
+                });
+            }
+            exitLabel = timedOut
+                ? `timed out after ${timeoutSec}s`
+                : result.status === 499
+                    ? "aborted"
+                    : exitCode !== null
+                        ? `exit ${exitCode}`
+                        : result.problem?.title.toLowerCase() ?? "completed";
+            await ChannelWrite.closeSubscription(db, { subscriptionId, result });
             const stdoutMeta = await db.channel_meta.get({ entry_id: entryId, channel: "stdout" });
             const stderrMeta = await db.channel_meta.get({ entry_id: entryId, channel: "stderr" });
             stdoutLength = stdoutMeta?.contentLength ?? 0;
             stderrLength = stderrMeta?.contentLength ?? 0;
         }
         finally {
-            // §exec-entry-sink — drain the entry()/narration writes so the tail (hence idle()) is a
-            // COMPLETE quiescence barrier: a consumer woken below, or a teardown awaiting idle(), must
-            // not race an in-flight entry() write into a closing db (#432 teardown race). Each op is
-            // enqueued as `.then(op, op)`, so entryChain never rejects — awaiting it in finally is safe.
+            // {§exec-entry-sink} — the spawn tail owns every serialized entry/narration write.
             await entryChain;
             if (timeoutTimer !== null)
                 clearTimeout(timeoutTimer); // a finished spawn leaves no pending timer
-            // #201 — a materialized data-source temp file outlives the spawn it fed;
-            // unlink it once the worker settles (open-unlink is safe on Linux).
-            if (tempPath !== null)
-                await unlink(tempPath).catch(() => { });
+            // {§exec-source-temporary} — cleanup cannot rewrite the settled
+            // executor result, but an exceptional failure remains observable.
+            if (tempPath !== null) {
+                await unlink(tempPath).catch((cause) => {
+                    console.error(`EXEC source temporary cleanup failed for '${tempPath}':`, cause);
+                });
+            }
             this.#activeAborts.get(subscriptionId)?.unlink();
             this.#activeAborts.delete(subscriptionId);
             this.liveSubscriptions().unregister(subscriptionId);
             this.#activeSpawns.delete(subscriptionId);
-            // Every worker backgrounds now (§exec-stream) — wake a parked loop on completion so the
-            // run resumes to the turn where the stream's terminal delta surfaces.
+            // Every worker backgrounds now ({§exec-stream}) — wake a parked loop on completion so the
+            // worker resumes to the turn where the stream's terminal delta surfaces.
             if (ctx.wakeWorkerNotify !== undefined) {
                 ctx.wakeWorkerNotify({
                     workspaceId: ctx.workspaceId, workerId: ctx.workerId,
-                    entryId, target: `${runtime}://${pathname}`, subscriptionId, closeStatus,
+                    entryId, target: `${runtime}://${pathname}`, subscriptionId, result,
                     scheme: runtime,
                     summary: `${runtime}://${pathname} completed (${exitLabel}); stdout=${stdoutLength} bytes, stderr=${stderrLength} bytes`,
                     ...coordinate,
                 });
             }
         }
-        return closeStatus;
+        return result;
     }
     async read(statement, ctx) {
         const core = this.coreContext(ctx);
         const owner = await resolveStreamStatement(statement, core);
-        if (owner === null)
-            return { status: 404, content: null, mimetype: null, channel: null };
+        if (owner === null) {
+            return Results.failure("scheme:exec", "stream-not-found", 404, "No visible stream exists at the requested address.", {
+                content: null, mimetype: null, channel: null,
+            });
+        }
         return EntryOps.readWorkspaceEntry(owner.statement, core, Exec.manifest, owner.ownerId);
     }
     async find(statement, ctx) {
         const core = this.coreContext(ctx);
         const owner = await resolveStreamStatement(statement, core);
-        if (owner === null)
-            return { status: 404, content: null, mimetype: null, results: [], itemsTokenTotal: 0, pathnames: [], matches: [] };
+        if (owner === null) {
+            return Results.failure("scheme:exec", "stream-not-found", 404, "No visible stream exists at the requested address.", {
+                content: null, mimetype: null, results: [], itemsTokenTotal: 0, pathnames: [], matches: [],
+            });
+        }
         return EntryFind.findWorkspaceEntries(owner.statement, core, Exec.manifest, owner.ownerId);
     }
     async readEntry(pathname, ctx) {