@plurnk/plurnk-service 0.28.0 → 0.34.0

package/dist/core/Engine.js

@@ -5,6 +5,7 @@ import EntryCrud from "../schemes/_entry-crud.js";
 import EntryManifest from "../schemes/_entry-manifest.js";
 import GitMembership from "./git-membership.js";
 import GitState from "./git-state.js";
+import Fork from "./fork.js";
 import { DEFAULT_LOOP_FLAGS } from "./scheme-types.js";
 import { LineMarkerOps, MimetypeBinary, editedSpan } from "../content/index.js";
 import { readFile } from "node:fs/promises";
@@ -90,7 +91,7 @@ const pathnameFromPath = (path) => {
 // loop terminal). No strike, no telemetry.
 const TURN_STATUS_IMPLICIT_CONTINUE = 102;
 // Status assigned to a turn that emitted NO ops at all. Strike-worthy; the
-// action routes through telemetry.errors[] (§telemetry).
+// action routes through telemetry.errors[] (§telemetry, §telemetry-no-error-scheme — never an error:// scheme).
 const TURN_STATUS_NO_OPS = 422;
 // Rail #38: action-entry statuses that DON'T accumulate strikes. Model adapted
 // to a finding (not_found, op_not_supported); no penalty. Rummy parallel:
@@ -127,7 +128,7 @@ const fingerprintOp = (stmt) => {
         }
         const lm = stmt.lineMarker;
         if (lm !== null && lm !== undefined)
-            parts.push(`L:${lm.first},${lm.last ?? ""}`);
+            parts.push(`L:${lm.marks.join(",")}`);
         return parts.length > 0 ? `|${parts.join("|")}` : "";
     };
     if (path === null) {
@@ -239,6 +240,7 @@ class Engine {
     #loopAborts = new Map();
     #streamEventNotify;
     #wakeRunNotify;
+    #injectRun;
     // Telemetry event fan-out: every TelemetryEvent pushed to the loop's
     // buffer is also broadcast live to the connected client(s) on the
     // session. Without this, the client sees `loop/terminated` with a
@@ -247,11 +249,12 @@ class Engine {
     #telemetryEventNotify;
     // Cached plurnk GBNF — read once on the first constrained generate (#189).
     #gbnfCache = null;
-    constructor({ db, schemes, mimetypes, streamEventNotify, wakeRunNotify, telemetryEventNotify, tokenize }) {
+    constructor({ db, schemes, mimetypes, streamEventNotify, wakeRunNotify, injectRun, telemetryEventNotify, tokenize }) {
         this.#db = db;
         this.#schemes = schemes;
         this.#streamEventNotify = streamEventNotify;
         this.#wakeRunNotify = wakeRunNotify;
+        this.#injectRun = injectRun;
         this.#telemetryEventNotify = telemetryEventNotify;
         // Default to empty discovery — standalone Engine construction (in
         // tests) gets no handlers, and content flows through the framework's
@@ -315,6 +318,7 @@ class Engine {
         // both sides per the grammar 0.17.0 TelemetryEvent protocol.
         this.#telemetryEventNotify?.(sessionId, { loopId, event });
     }
+    // Telemetry drains as it's read into the packet — each event surfaces once. §telemetry-drain-on-read
     #drainTelemetry(loopId) {
         const buf = this.#telemetryBuffer.get(loopId);
         if (buf === undefined)
@@ -343,7 +347,7 @@ class Engine {
         }
         return slice.join("\n");
     }
-    async runLoop({ provider, messages, persona = "", requirements = "", sessionId, runId, loopId, maxTurns = 50, maxStrikes = readMaxStrikes(), minCycles = readPositiveInt("PLURNK_MIN_CYCLES", DEFAULT_MIN_CYCLES), maxCyclePeriod = readPositiveInt("PLURNK_MAX_CYCLE_PERIOD", DEFAULT_MAX_CYCLE_PERIOD), origin = "model", signal, onDispatch, }) {
+    async runLoop({ provider, messages, requirements = "", sessionId, runId, loopId, maxTurns = 50, maxStrikes = readMaxStrikes(), minCycles = readPositiveInt("PLURNK_MIN_CYCLES", DEFAULT_MIN_CYCLES), maxCyclePeriod = readPositiveInt("PLURNK_MAX_CYCLE_PERIOD", DEFAULT_MAX_CYCLE_PERIOD), origin = "model", signal, onDispatch, }) {
         const turnIds = [];
         const suddenDeathThreshold = maxTurns - maxStrikes;
         // Per-loop AbortController for scheme-side cancellation propagation.
@@ -400,7 +404,7 @@ class Engine {
                     await delay(execWaitMs, undefined, { signal });
             }
             const turn = await this.runTurn({
-                provider, messages, persona, requirements, sessionId, runId, loopId, origin, signal, onDispatch,
+                provider, messages, requirements, sessionId, runId, loopId, origin, signal, onDispatch,
                 turnNumber: turnIds.length + 1, maxTurns,
             });
             turnIds.push(turn.turnId);
@@ -425,7 +429,7 @@ class Engine {
                 state.turnErrors++;
             // SPEC §grinder: a non-soft grinder fire counts toward the strike streak.
             if (turn.budgetStruck)
-                state.turnErrors++;
+                state.turnErrors++; // a grinder fire bumps the strike streak — §grinder-strike-coupling
             this.#strikeState.set(loopId, state);
             // Rail #38: strike accounting. Three sources strike a turn:
             //  1. recordedFailed — any action-entry at hard failure status
@@ -465,7 +469,7 @@ class Engine {
             }
         }
     }
-    async runTurn({ provider, messages, persona = "", requirements = "", sessionId, runId, loopId, origin = "model", signal, onDispatch, turnNumber = 1, maxTurns = 50, }) {
+    async runTurn({ provider, messages, requirements = "", sessionId, runId, loopId, origin = "model", signal, onDispatch, turnNumber = 1, maxTurns = 50, }) {
         // === Turn-as-container model ===
         //
         // Turn rows are created at runTurn OPEN (status=102, placeholder
@@ -497,7 +501,7 @@ class Engine {
         // otherwise.
         let nextActionIndex = 1;
         if (seq === 1) {
-            // Operator doc READs (PLURNK_MD_<ALIAS>). The docs were materialized
+            // Operator doc READs (PLURNK_MD_<ALIAS>, §actor-boundary-doc-injection). The docs were materialized
             // as plurnk:///<entry> entries by the plurnk run (loop_run, via the
             // §actor-boundary keystone); foist a READ of each into THIS turn-0 so the model
             // reads them inline. It sees only the READ — the materializing EDIT
@@ -531,10 +535,17 @@ class Engine {
                     target: promptPath, lineMarker: null,
                     body: promptRow.prompt, position: { line: 1, column: 1 },
                 };
+                let promptLogId;
                 await this.dispatch({
                     statement: promptStmt, sessionId, runId, loopId, turnId,
-                    sequence: nextActionIndex, origin: "plurnk", onDispatch,
+                    sequence: nextActionIndex, origin: "plurnk",
+                    onDispatch: (id) => { promptLogId = id; onDispatch?.(id); },
                 });
+                // §prompt-fold (User Note 6): the prompt EDIT duplicates
+                // packet.user.prompt (its own section), so fold it — logged for
+                // forensics, collapsed in the model's log, re-OPENable.
+                if (promptLogId !== undefined)
+                    await this.#db.engine_fold_log_entry.run({ id: promptLogId });
                 nextActionIndex++;
             }
         }
@@ -604,14 +615,14 @@ class Engine {
         // queries log_entries scoped to the run — the prompt entry just
         // written (if turn 1) is part of that query result.
         let requestPacket = await this.#buildRequestPacket({
-            initialMessages: messages, persona, requirements, runId, loopId,
+            initialMessages: messages, requirements, runId, loopId,
             currentTurnSeq: seq, provider, gitStatus,
         });
         // SPEC §grinder — budget grinder, pre-LLM: reclaim window on actual overflow.
         const enforced = await this.#enforceBudget({
             packet: requestPacket, provider, runId, loopId, turnId, sessionId, turnNumber,
             rebuild: (telemetryErrors) => this.#buildRequestPacket({
-                initialMessages: messages, persona, requirements, runId, loopId,
+                initialMessages: messages, requirements, runId, loopId,
                 currentTurnSeq: seq, provider, telemetryErrors, gitStatus,
             }),
         });
@@ -632,14 +643,14 @@ class Engine {
         // The 0.28.0 EOS-forcing root terminates the turn at the status SEND, but a
         // grammar can't bound degeneration *inside* a statement body — this caps the
         // decode at the free window so a runaway can't reach the context wall.
-        const genCeiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling);
+        const genCeiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling); // provider.contextSize, the immutable identity, read by the budget — §provider-surface-identity
         const maxTokens = genCeiling === null ? undefined : Math.max(1, genCeiling - requestPacket.system.tokens - requestPacket.user.tokens);
-        const response = await provider.generate({ messages: modelMessages, runId: String(runId), signal, grammar: await this.#grammarConstraint(), maxTokens });
+        const response = await provider.generate({ messages: modelMessages, runId: String(runId), signal, grammar: await this.#grammarConstraint(), maxTokens }); // §provider-surface-generate §provider-guarantees-single-call §provider-guarantees-signal-wired
         // Engine splits wire-level response: emission (content, reasoning,
         // parsed ops) → packet.assistant per Packet.json §assistant;
         // call-metadata (usage, finishReason, model) → Turn columns per
         // Turn.json. Mixing the two on packet.assistant was the wrong layer.
-        const { packetAssistant, callMetadata, parseErrors } = this.#splitResponse(response);
+        const { packetAssistant, callMetadata, parseErrors } = this.#splitResponse(response); // raw assistant content is opaque — split, never interpreted — §provider-guarantees-assistantraw-opaque
         // Surface parse errors to the model's NEXT packet so it can self-
         // correct. Without this, malformed emissions (e.g. a READ matcher
         // body starting with `//` being interpreted as xpath) silently
@@ -685,7 +696,7 @@ class Engine {
             usage_prompt: usage.prompt,
             usage_completion: usage.completion,
             usage_cached: usage.cached,
-            usage_cost_pico: provider.costFor(usage),
+            usage_cost_pico: provider.costFor(usage), // §provider-surface-costfor
             finish_reason: finishReason,
             model,
         });
@@ -820,9 +831,12 @@ class Engine {
     // and §user) BEFORE the provider call. The same packet object is then
     // completed with assistant + assistantRaw after the model responds, so
     // the stored packet and the wire payload share one source of truth.
-    async #buildRequestPacket({ initialMessages, persona: defaultPersona, requirements, runId, loopId, currentTurnSeq, provider, gitStatus, telemetryErrors: presetTelemetry, }) {
+    async #buildRequestPacket({ initialMessages, requirements, runId, loopId, currentTurnSeq, provider, gitStatus, telemetryErrors: presetTelemetry, }) {
         const byRole = (role) => initialMessages.filter((m) => m.role === role).map((m) => m.content).join("\n\n");
-        const system_definition = byRole("system");
+        // plurnk.md (grammar/dialects) THEN the scheme catalogue: grammar 0.49+ is
+        // scheme-agnostic, so the service teaches what schemes exist + what they do
+        // at packet-time (grammar#239 item 7). SchemeRegistry.teach() assembles it.
+        const system_definition = `${byRole("system")}\n\n${this.#schemes.teach()}`;
         // user.prompt sources from the loop's most recent prompt entry first
         // (plurnk:///prompt/<loop_id>/<N> for the highest N written to date).
         // This is what inject + the turn-1 foist write into. Falls back to
@@ -832,13 +846,8 @@ class Engine {
         const prompt = (latestPromptRow !== undefined && typeof latestPromptRow.content === "string" && latestPromptRow.content.length > 0)
             ? latestPromptRow.content
             : byRole("user");
-        // Resolve persona cascade: loops.persona > runs.persona >
-        // sessions.persona > caller-supplied default. SQL coalesces in one
-        // query; null result means no DB override exists, use the default.
-        const row = await this.#db.engine_resolve_persona.get({ loop_id: loopId });
-        const persona = (row?.persona !== undefined && row?.persona !== null) ? row.persona : defaultPersona;
         // Requirements is engine-sourced, NOT threaded from callers — that threading is
-        // exactly how it went missing (loop_run/Daemon read sysprompt + persona but never
+        // exactly how it went missing (callers read the sysprompt but never the
         // requirements). Read Paths.defaultRequirements (PLURNK_REQUIREMENTS env →
         // requirements.md) fresh each build so edits take effect; a non-empty param wins.
         const requirementsText = requirements.length > 0 ? requirements : await readFile(Paths.defaultRequirements, "utf8");
@@ -849,7 +858,7 @@ class Engine {
         // form — wire-payload tokens may differ slightly because chat-
         // template scaffolding adds bytes, but the subtotal tracks "what
         // the model has to process" closely enough for budget diagnostics.
-        const countTokens = (t) => provider.countTokens(t);
+        const countTokens = (t) => provider.countTokens(t); // §provider-surface-counttokens
         // Budget readout (SPEC.md §tokenomics). Two-pass: measure the wire-rendered
         // index/log sections (budget-independent), install the readout with a
         // tokensFree placeholder, measure the assembled total, resolve free,
@@ -859,21 +868,21 @@ class Engine {
         // headline omitted, section lines still shown).
         const ceiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling);
         const scratch = {
-            system: { system_definition, persona, log },
+            system: { system_definition, log },
             user: { prompt, telemetry: { budget: "", errors: telemetryErrors, git: gitStatus }, tools: this.#collectTools(), system_requirements: requirementsText },
         };
         const sections = PacketWire.measureBudgetSections(scratch, countTokens);
         scratch.user.telemetry.budget = this.#renderBudget(sections, ceiling);
         const total = countTokens(PacketWire.renderSystemContent(scratch.system)) + countTokens(PacketWire.renderUserContent(scratch.user));
-        const tokensFree = ceiling === null ? null : Math.max(0, ceiling - total);
-        const percent = ceiling === null ? null : Math.round((total / ceiling) * 100);
+        const tokensFree = ceiling === null ? null : Math.max(0, ceiling - total); // free floors at 0 on overshoot — §tokenomics-over-budget-floor
+        const percent = ceiling === null ? null : Math.round((total / ceiling) * 100); // usage as % of the ceiling — §tokenomics-context-percent
         const budget = tokensFree === null
             ? scratch.user.telemetry.budget
             : scratch.user.telemetry.budget
                 .replace(TOKEN_USAGE_PLACEHOLDER, String(total))
                 .replace(TOKEN_PERCENT_PLACEHOLDER, String(percent))
                 .replace(TOKENS_FREE_PLACEHOLDER, String(tokensFree));
-        const system = { tokens: 0, system_definition, persona, log };
+        const system = { tokens: 0, system_definition, log };
         const user = { tokens: 0, prompt, telemetry: { budget, errors: telemetryErrors, git: gitStatus }, tools: scratch.user.tools, system_requirements: requirementsText };
         system.tokens = countTokens(PacketWire.renderSystemContent(system));
         user.tokens = countTokens(PacketWire.renderUserContent(user));
@@ -912,10 +921,11 @@ class Engine {
     // contributor (gated by PLURNK_PLAN); each available executor tag then
     // contributes its self-documenting example (plurnk-execs#7), retiring the
     // blind EXEC.
+    // The capability sheet — the live tool surface (PLAN + wired executor tags). §tools-capability-sheet
     #collectTools() {
         const tools = [];
-        if (process.env.PLURNK_PLAN === "1") {
-            tools.push("* Begin every response with <<PLAN:{planning and reasoning}:PLAN");
+        if (process.env.PLURNK_PLAN === "1") { // <<PLAN advertised only when PLAN is enabled — §tools-plan-gated
+            tools.push("* Begin every response with <<PLAN:...:PLAN");
         }
         // Each available runtime tag contributes its self-documenting example —
         // the example carries syntax + purpose, so there's no prose line. Tags
@@ -937,6 +947,7 @@ class Engine {
     // passes, re-measuring between. Folds (never deletes) — the prior turn's logs,
     // then the catalog except the manifest lifeline. The strike it raises and the
     // hard-stop it can signal are returned to runLoop, which owns abandonment.
+    // §grinder-overflow-only — fires only on actual overflow, never speculatively
     async #enforceBudget({ packet, provider, runId, loopId, turnId, sessionId, turnNumber, rebuild }) {
         const ceiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling);
         const measure = (p) => p.system.tokens + p.user.tokens;
@@ -946,7 +957,7 @@ class Engine {
         const note = (scheme) => { folded.set(scheme, (folded.get(scheme) ?? 0) + 1); };
         // Pass 1 — prior-turn rollback: fold the latest emissions (the ones that
         // pushed it over). No prior turn (turn 1, env overflow) → no-op → pass 2.
-        const priorLogs = await this.#db.engine_grinder_prior_turn_logs.all({ loop_id: loopId, turn_id: turnId });
+        const priorLogs = await this.#db.engine_grinder_prior_turn_logs.all({ loop_id: loopId, turn_id: turnId }); // prior-turn rollback folds the latest emissions — §grinder-layer1-rollback
         for (const le of priorLogs)
             note(le.scheme ?? "log");
         if (priorLogs.length > 0)
@@ -955,17 +966,18 @@ class Engine {
         let current = priorLogs.length > 0 ? await rebuild(errors) : packet;
         if (measure(current) <= ceiling) {
             this.#emitBudgetOverflow(sessionId, loopId, folded);
-            return { packet: current, fit: true, struck: turnNumber > 1 };
+            return { packet: current, fit: true, struck: turnNumber > 1 }; // turn 0/1 overflow is the environment, never a strike — §grinder-soft-turn-0-1
         }
         // Prior-turn rollback is the only budget lever now: entries don't render
         // (no index), so there is no catalog to collapse. If pass 1 didn't fit,
-        // the packet is over and the caller hard-413s.
+        // the packet is over and the caller hard-413s. §grinder-hard-413-abort
         this.#emitBudgetOverflow(sessionId, loopId, folded);
         return { packet: current, fit: measure(current) <= ceiling, struck: turnNumber > 1 };
     }
     // The model-facing budget event (SPEC §grinder, §telemetry): which entries left the
     // window, by scheme — the model's own terms, no mechanism vocabulary. The
     // strike this overflow triggers stays engine-internal (gamification policy).
+    // §grinder-event-model-terms — model-facing terms only; the strike stays engine-internal
     #emitBudgetOverflow(sessionId, loopId, folded) {
         if (folded.size === 0)
             return;
@@ -1061,7 +1073,7 @@ class Engine {
             source: r.source,
         }));
     }
-    // §env-delta — at pre-turn build, surface what changed in the shared world since this
+    // §env-delta (§actor-boundary-no-mutex: runs share without locks; a conflict surfaces as a delta, never prevented) — at pre-turn build, surface what changed in the shared world since this
     // run last looked. No per-run snapshot (§machine-processes "a run is its log"): every
     // edit is already a span-carrying log row, so PULL other actors' EDITs on shared
     // entries since this run's prior turn — real cross-run edits and the plurnk run's
@@ -1092,11 +1104,12 @@ class Engine {
     // world changed," so the fiction keeps its perspective aligned with what its tooling
     // would show. The fiction lives in the plurnk run's log; every other run pulls it
     // through the one delta path, exactly like a sibling's real edit.
+    // §membership-emi-divergence-signal — disk divergences logged as the plurnk run's source=file EDIT fictions
     async #logFsFictions(sessionId, divergences) {
         if (divergences.length === 0)
             return;
         const run = await this.#db.envelope_get_run_by_name.get({ session_id: sessionId, name: "plurnk" })
-            ?? await this.#db.envelope_insert_run.get({ session_id: sessionId, name: "plurnk", persona: null, origin: "plurnk" });
+            ?? await this.#db.envelope_insert_run.get({ session_id: sessionId, name: "plurnk", origin: "plurnk" });
         if (run === undefined)
             throw new Error("logFsFictions: plurnk run resolution returned no row");
         const loop = await this.#db.envelope_insert_client_loop.get({ run_id: run.id });
@@ -1129,6 +1142,7 @@ class Engine {
             signal: this.#loopAborts.get(loopId)?.signal,
             streamEventNotify: this.#streamEventNotify,
             wakeRunNotify: this.#wakeRunNotify,
+            injectRun: this.#injectRun,
             mimetypes: this.#mimetypes,
             tokenize: this.#tokenize,
             pushTelemetry: (event) => this.#pushTelemetry(sessionId, loopId, event),
@@ -1171,10 +1185,10 @@ class Engine {
                     result = await this.#run("exec", statement, schemeCtx);
                 }
                 else {
-                    result = await this.#run(this.#schemeNameOf(statement.target), statement, schemeCtx);
+                    result = await this.#run(this.#schemeNameOf(statement.target), statement, schemeCtx); // §op-methods-op-dispatch
                 }
             }
-            catch (err) {
+            catch (err) { // a scheme exception becomes the op's 500 outcome — §scheme-surface-exception-500
                 result = {
                     status: 500,
                     error: err instanceof Error ? err.message : String(err),
@@ -1183,7 +1197,7 @@ class Engine {
         }
         const logEntryId = await this.#writeLog({ statement, result, runId, loopId, turnId, sequence, origin });
         onDispatch?.(logEntryId);
-        // Proposal lifecycle (SPEC.md §engine-rails + §methods loop.resolve). When a
+        // Proposal lifecycle (SPEC.md §engine-rails + §methods loop.resolve; §proposal-202-pauses). When a
         // scheme returns status 202, the entry is written as state='proposed';
         // dispatch then PAUSES on a per-entry waiter until resolution
         // arrives via Engine.resolveProposal (from the loop/resolve RPC,
@@ -1208,7 +1222,7 @@ class Engine {
             // YOLO listener auto-resolves) BEFORE awaiting — they may
             // resolve synchronously inside their handlers.
             const target = this.#extractTarget(statement.target);
-            const flags = await this.#loadLoopFlags(loopId);
+            const flags = await this.#loadLoopFlags(loopId); // the loop/proposal notification carries flags (yolo) — §dual-yolo-proposal-carries-flags
             const event = {
                 logEntryId, sessionId, runId, loopId, turnId,
                 op: statement.op,
@@ -1245,6 +1259,7 @@ class Engine {
         }
         return result;
     }
+    // On accept, run the scheme's applyResolution — File writes disk, Exec spawns. §proposal-accept-applies
     async #runApplyResolution(statement, originalResult, resolution, ids) {
         const { sessionId, runId, loopId, turnId } = ids;
         if (resolution.decision !== "accept")
@@ -1406,7 +1421,7 @@ class Engine {
                 // transitions to cancelled with outcome='timeout'.
                 if (this.#pendingProposals.has(logEntryId)) {
                     this.#pendingProposals.delete(logEntryId);
-                    resolve({ decision: "cancel", outcome: "timeout" });
+                    resolve({ decision: "cancel", outcome: "timeout" }); // §proposal-timeout-cancels
                 }
             }, timeoutMs);
             this.#pendingProposals.set(logEntryId, { resolve, timeoutHandle });
@@ -1415,8 +1430,8 @@ class Engine {
     async #applyResolution(logEntryId, resolution) {
         // Map decision → terminal state + HTTP-aligned status:
         //   accept  → state='resolved', status=200
-        //   reject  → state='failed',   status=400, outcome='rejected' (default)
-        //   cancel  → state='cancelled',status=499, outcome='loop_aborted' (default)
+        //   reject  → state='failed',   status=400, outcome='rejected' (default) §proposal-reject-fails
+        //   cancel  → state='cancelled',status=499, outcome='loop_aborted' (default) §proposal-cancel-aborts
         // resolution.outcome wins over the default when supplied; this is how
         // veto filters (Phase E.2 proposal.accepting) can specify a more
         // precise outcome string like 'policy_veto' or 'timeout'.
@@ -1462,6 +1477,11 @@ class Engine {
         if (statement.op === "EXEC") {
             return this.#denyIfDisallowed("exec", origin);
         }
+        // A run-fork (COPY src=run://) is gated by run://'s writableBy — its body
+        // is a fork prompt, not a dst path, so the entry-COPY dst-parse below
+        // doesn't apply. §machine-processes
+        if (this.#isRunFork(statement))
+            return this.#denyIfDisallowed("run", origin);
         if (statement.op === "COPY" || statement.op === "MOVE") {
             const dst = statement.op === "COPY" ? (statement.body === null ? null : parsePath(statement.body)) : statement.body;
             const dstScheme = this.#schemeNameOf(dst);
@@ -1492,7 +1512,7 @@ class Engine {
             return null;
         if (manifest.writableBy.includes(origin))
             return null;
-        return { status: 403, error: `writer '${origin}' is not in writableBy for scheme '${schemeName}'` };
+        return { status: 403, error: `writer '${origin}' is not in writableBy for scheme '${schemeName}'` }; // §scheme-surface-writableby-403
     }
     // Per-loop flag gating. Schemes self-declare their flag affinity in
     // their manifest (excludedInAsk / requiresWeb /
@@ -1516,14 +1536,47 @@ class Engine {
                 return null;
             return { status: 403, error: `scheme '${scheme}' is inactive under current loop flags` };
         };
+        if (this.#isRunFork(statement))
+            return check(statement.target); // body is a fork prompt, not a dst path
         if (statement.op === "COPY" || statement.op === "MOVE") {
             return check(statement.target) ?? check(statement.op === "COPY" ? (statement.body === null ? null : parsePath(statement.body)) : statement.body);
         }
         return check(statement.target);
     }
+    // A COPY whose SOURCE is run:// is a run-fork, not an entry-copy — its body
+    // is the fork's seed prompt, not a destination path. The COPY gates and
+    // #handleCopy branch on this so they never parse the prompt as a dst path.
+    #isRunFork(statement) {
+        return statement.op === "COPY" && this.#schemeNameOf(statement.target) === "run";
+    }
+    // COPY(run:///<src>):prompt — fork: deep-copy the source run's log into a new
+    // run (Fork), then start it with the prompt (ctx.injectRun). Source "."/"" =
+    // self (ctx.runId); a name resolves within the session (404 if absent).
+    // §machine-processes-fork-copies-the-log
+    async #handleRunFork(statement, ctx) {
+        const target = statement.target;
+        if (target === null)
+            return { status: 400, error: "run:// fork requires a source run" };
+        const name = pathnameFromPath(target).replace(/^\/+/, "");
+        let srcRunId = ctx.runId;
+        if (name !== "" && name !== ".") {
+            const row = await this.#db.run_resolve_by_name.get({ session_id: ctx.sessionId, name });
+            if (row === undefined)
+                return { status: 404, error: `run:///${name} not found in this session` };
+            srcRunId = row.id;
+        }
+        if (ctx.injectRun === undefined)
+            throw new Error("run fork: injectRun capability absent");
+        const branchRunId = await Fork.fork(this.#db, srcRunId);
+        const branch = await this.#db.fork_get_run.get({ id: branchRunId });
+        await ctx.injectRun({ sessionId: ctx.sessionId, runId: branchRunId, prompt: typeof statement.body === "string" ? statement.body : "" });
+        return { status: 200, body: branch?.name ?? "" };
+    }
     async #handleCopy(statement, ctx) {
         if (statement.op !== "COPY")
             throw new Error("unreachable");
+        if (this.#isRunFork(statement))
+            return await this.#handleRunFork(statement, ctx);
         const srcPath = statement.target;
         // COPY's body is an opaque raw string (grammar §COPY: a dest path OR a run-fork
         // prompt); parse it to the dest path. Non-path bodies (run:// fork prompts) are
@@ -1542,17 +1595,17 @@ class Engine {
         const dstPath = statement.body;
         if (srcPath === null)
             return { status: 400, error: "MOVE requires source path" };
-        // MOVE is relocation only — deletion is KILL's job (§move). The /dev/null
+        // MOVE is relocation only — deletion is KILL's job (§move, §move-dev-null-not-special). The /dev/null
         // and null-body delete-by-MOVE back-compat is retired: no silent debt.
         if (dstPath === null)
-            return { status: 400, error: "MOVE requires a destination; use KILL to delete" };
+            return { status: 400, error: "MOVE requires a destination; use KILL to delete" }; // §move-null-body-400
         const srcSchemeName = this.#schemeNameOf(srcPath);
         if (srcSchemeName === null)
             return { status: 400, error: "MOVE source must be a URL path with a scheme" };
         const srcHandler = this.#schemes.get(srcSchemeName);
         if (srcHandler === undefined || typeof srcHandler.deleteEntry !== "function")
             return { status: 501 };
-        // Relocation: COPY then DELETE source.
+        // Relocation: COPY then DELETE source (§move-relocation-deletes-source).
         const copyResult = await this.#copyOrchestration({ statement, srcPath, dstPath, ctx });
         if (copyResult.status >= 400)
             return copyResult;
@@ -1612,6 +1665,7 @@ class Engine {
             throw new Error("unreachable");
         return { status: 200 };
     }
+    // Same- and cross-scheme COPY share one orchestrator — §copy-cross-scheme-copy §move-cross-scheme-move
     async #copyOrchestration({ statement, srcPath, dstPath, ctx }) {
         const srcSchemeName = this.#schemeNameOf(srcPath);
         const dstSchemeName = this.#schemeNameOf(dstPath);
@@ -1627,7 +1681,7 @@ class Engine {
         const dstPathname = pathnameFromPath(dstPath);
         const srcResult = await srcHandler.readEntry(srcPathname, ctx);
         if (srcResult.status !== 200 || srcResult.entry === null)
-            return { status: 404, error: `COPY/MOVE source not found: ${srcSchemeName}://${srcPathname}` };
+            return { status: 404, error: `COPY/MOVE source not found: ${srcSchemeName}://${srcPathname}` }; // §copy-missing-source-404 §move-missing-source-404
         const entry = srcResult.entry;
         // Destination read — the conflict/no-op verdict is deferred until the
         // to-be-written content is known (after <L> slice + tag resolution below),
@@ -1641,7 +1695,7 @@ class Engine {
         for (const [channelName, channelData] of Object.entries(entry.channels)) {
             const expectedMimetype = dstChannels[channelName];
             if (expectedMimetype !== undefined && expectedMimetype !== channelData.mimetype) {
-                return { status: 415, error: `mimetype mismatch on channel '${channelName}': ${channelData.mimetype} vs ${expectedMimetype}` };
+                return { status: 415, error: `mimetype mismatch on channel '${channelName}': ${channelData.mimetype} vs ${expectedMimetype}` }; // cross-mimetype COPY/MOVE → 415, never coerce — §channel-mimetype-cross-mimetype-415
             }
         }
         // `<L>` source range slicing per SPEC.md §op-invariants (symmetric with READ
@@ -1663,7 +1717,7 @@ class Engine {
             }
             channels = sliced;
         }
-        // Tag resolution: signal = replace; absent/empty = carry from source
+        // Tag resolution: signal = replace (§copy-signal-replaces-source-tags); absent/empty = carry from source (§copy-no-signal-carries-source-tags)
         const tags = (Array.isArray(statement.signal) && statement.signal.length > 0)
             ? statement.signal
             : entry.tags;
@@ -1679,8 +1733,8 @@ class Engine {
                 && writeNames.every((n, i) => n === dstNames[i] && (channels[n]?.content ?? "") === (dstChannels[n]?.content ?? ""));
             const sameTags = [...tags].sort().join("") === [...dstExisting.entry.tags].sort().join("");
             if (sameContent && sameTags)
-                return { status: 304 };
-            return { status: 409, error: `COPY/MOVE destination exists: ${dstSchemeName}://${dstPathname}` };
+                return { status: 304 }; // identical → §copy-noop-304
+            return { status: 409, error: `COPY/MOVE destination exists: ${dstSchemeName}://${dstPathname}` }; // §copy-conflict-409
         }
         const writeResult = await dstHandler.writeEntry(dstPathname, { channels, tags }, ctx);
         // A file dest returns 202 (disk write → §membership review): propagate the
@@ -1817,7 +1871,8 @@ class Engine {
     #extractTarget(path) {
         if (path === null)
             return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: null, params: null, fragment: null };
-        if (path.kind === "local")
+        // `local` (bare path) and `regex` (grammar 0.46 `#pattern#flags` target) carry no URL parts — store the raw text as the pathname for the log record, scheme=null.
+        if (path.kind === "local" || path.kind === "regex")
             return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: path.raw, params: null, fragment: null };
         const scheme = path.scheme === "file" ? null : path.scheme;
         return {