@plurnk/plurnk-service 3.1.0 → 3.2.0

package/dist/core/Dispatcher.js

@@ -3,10 +3,11 @@ import { parsePath } from "@plurnk/plurnk-parser";
 import { ConfigurationError, Knob } from "@plurnk/plurnk-meta";
 import { TurnDisposition, UNKNOWN_POSITION } from "@plurnk/plurnk-contracts";
 import Turn from "./Turn.js";
-import { foldAuthorityIntoPath, renderAddress, renderTarget, schemeNameOf } from "./plurnk-uri.js";
+import { entryAddress, foldAuthorityIntoPath, renderAddress, renderAuthoredTarget, renderTarget, schemeNameOf } from "./plurnk-uri.js";
 import WorkerName from "./WorkerName.js";
 import { PathSyntax } from "@plurnk/plurnk-contracts";
 import Namespace from "./namespace.js";
+import FileAddress from "./FileAddress.js";
 import CapabilityResolver from "./CapabilityResolver.js";
 import SchemeCtxImpl from "./caps/SchemeCtxImpl.js";
 import Results from "./results.js";
@@ -22,7 +23,7 @@ import BodyPreview from "../content/body-preview.js";
 import ReadResolve from "../content/read-resolve.js";
 import LogVisibility from "./LogVisibility.js";
 import PacketWire from "./packet-wire.js";
-import { resultPrefix, resultSize, unfitResult } from "./ContextFit.js";
+import { isContextReceipt, reserved, resultPrefix, resultSize, unfitResult } from "./ContextFit.js";
 import { TextCoordinates } from "@plurnk/plurnk-mimetypes";
 import EntryAddressBinding from "./EntryAddressBinding.js";
 import WorkerControlHandler from "./WorkerControlHandler.js";
@@ -91,7 +92,6 @@ class Dispatcher {
         this.#resourceSelector = new ResourceSelector({
             schemes,
             admitRead: (statement, ctx) => this.#checkCapabilities(statement, ctx),
-            canonicalFilePath: (pathname, workspaceId) => this.#canonicalFilePath(pathname, workspaceId),
             prepareDataRepresentation: (args) => this.#prepareDataRepresentation({
                 ...args,
                 handler: args.handler,
@@ -247,13 +247,10 @@ class Dispatcher {
         if (key !== null)
             target.pathname = key;
     }
-    async #canonicalFilePath(pathname, workspaceId) {
-        return Namespace.canonicalizeSpelling(pathname, await this.#workspaceRoot(workspaceId));
-    }
     async #editTargetIdentity(statement, workspaceId, _workerId) {
         const target = this.#extractTarget(statement.target, workspaceId);
         await this.#canonColumns(target, workspaceId);
-        return renderTarget(target);
+        return renderTarget(target, await this.#workspaceRoot(workspaceId));
     }
     // {§kill-scope-entry} — a scoped KILL on an entry-bearing scheme is one EDIT with an empty
     // body over the same marker: prepared, gated, and merged as an EDIT while its log row
@@ -295,9 +292,9 @@ class Dispatcher {
     async dispatch(context) {
         await this.#operationEvent(context, "started");
         await this.#noticeFilePaths(context);
-        const result = await this.#dispatch(context);
-        await this.#operationEvent(context, "settled", result);
-        return result;
+        const execution = await this.#dispatch(context);
+        await this.#operationEvent(context, "settled", execution.result);
+        return execution;
     }
     // {§file-path-normalization} Authored operands, once, before internal fan-out.
     async #noticeFilePaths({ statement, origin, workspaceId, workerId, loopId }) {
@@ -306,22 +303,29 @@ class Dispatcher {
         const targets = statement.op === "COPY" || statement.op === "MOVE"
             ? [statement.source.target, statement.destination.target]
             : [statement.target];
-        const absolute = targets.flatMap((target) => target === null || schemeNameOf(target) !== "file" ? []
-            : [PathSyntax.decodeParens(target.kind === "url" ? target.pathname : target.raw)])
-            .filter((pathname) => pathname.startsWith("/"));
-        if (absolute.length === 0)
+        const normalized = targets.flatMap((target) => {
+            if (target === null || schemeNameOf(target) !== "file")
+                return [];
+            const pathname = FileAddress.pathname(target);
+            return typeof pathname === "string" && (pathname.startsWith("/") || Namespace.isHomeRelative(pathname))
+                ? [{ target, pathname }] : [];
+        });
+        if (normalized.length === 0)
             return;
         const root = await this.#workspaceRoot(workspaceId);
         if (root === null || root === "/")
             return;
-        for (const pathname of absolute) {
+        for (const { target, pathname } of normalized) {
             const key = Namespace.canonicalizeSpelling(pathname, root);
             if (key === null)
                 continue;
+            const address = renderTarget({ scheme: null, pathname: key }, root, target);
+            if (address?.startsWith("file://"))
+                continue;
             this.#notices.push(workspaceId, workerId, loopId, {
                 source: "scheme:file", kind: "path_normalized", level: "warn",
                 directive: "YOU SHOULD address the resolved path.",
-                message: `Path resolved to '${key || "."}'.`,
+                message: `Path resolved to '${address || "."}'.`,
             });
         }
     }
@@ -336,11 +340,9 @@ class Dispatcher {
             ...(result === undefined ? {} : { result }),
         });
     }
-    async #dispatch(context) {
-        if (context.statement.op === "READ" && _a.#globTarget(context.statement.target)) {
-            return this.#fanOutRead(context, context.statement);
-        }
-        let result = await ResourceBindings.using(this.#schemes, this.#buildSchemeCtx(context), (ctx) => this.#dispatchOne(context, ctx));
+    async #dispatch(context, targetsResolved = false) {
+        const execution = await ResourceBindings.using(this.#schemes, this.#buildSchemeCtx(context), (ctx) => this.#dispatchOne(context, ctx, targetsResolved));
+        let { result } = execution;
         const edit = context.statement.op === "EDIT" ? context.statement : this.#scopedEntryEdits.get(context.statement);
         if (edit !== undefined) {
             // {§edit-batch-merges} — a proposal's apply result replaces the projected one; the
@@ -361,7 +363,7 @@ class Dispatcher {
             await ResourceBindings.using(this.#schemes, this.#buildSchemeCtx(noteContext), (ctx) => this.#dispatchOne(noteContext, ctx));
             result = Results.assert({ ...result, rowsWritten: (result.rowsWritten ?? 1) + 1 });
         }
-        return result;
+        return { ...execution, result };
     }
     // {§matcher-refusal} — a matcher the parser could not read refuses its one operation with the parser's
     // diagnostic and working form: the operation's own row, soft on the rail, never a contract strike.
@@ -380,57 +382,109 @@ class Dispatcher {
         return statement.body.trim() === "" ? null : statement.body;
     }
     static #globTarget(target) {
-        return target !== null && PathSyntax.hasGlob(target.kind === "url" ? target.pathname : target.raw);
+        if (target === null)
+            return false;
+        if (target.kind === "local")
+            return PathSyntax.hasGlob(target.raw);
+        // Authority-only worker addresses name actors, not their resource trees.
+        if (target.scheme === "worker" && (target.pathname === "" || target.pathname === "/"))
+            return false;
+        return PathSyntax.hasGlob(target.pathname) || PathSyntax.hasGlob(target.hostname ?? "");
     }
-    // {§read-fan-out} — a READ over a glob reads every matching path: the paths come from the
-    // ordinary FIND over the same target (unlogged; a matcher FIND when there is one, the catalog
-    // otherwise; its resource page bounds the fan-out), and each is read as an ordinary exact READ
-    // with the authored scope and matcher and its own receipt row, so every rendered line keeps its
-    // path, ordinal and anchor. No path: one 204 receipt on the authored glob.
-    async #fanOutRead(context, statement) {
-        const survey = {
-            op: "FIND", aside: statement.aside, target: statement.target, metadata: statement.metadata,
-            matcher: statement.matcher, lineMarker: null, body: null, position: statement.position,
-        };
-        const found = await ResourceBindings.using(this.#schemes, this.#buildSchemeCtx(context), (ctx) => this.#dataRun.run(schemeNameOf(statement.target), survey, ctx));
+    // {§bulk-resource-targeting} Selection and exact execution share the ordinary owners.
+    async #findTargets(survey, ctx) {
+        const found = await this.#dataRun.run(schemeNameOf(survey.target), survey, ctx);
+        if (found.status >= 400)
+            return { result: found };
         const paths = found.status < 300
             ? (found.results ?? []).flatMap((item) => Array.isArray(item) && !("items" in item[0]) ? [item[0].path] : [])
             : [];
-        if (paths.length === 0) {
-            const result = found.status >= 400 ? found : Results.assert(statement.matcher === null
-                ? { status: 204, detail: `No path matched ${statement.target.raw}.` }
-                : { status: 204, matched: 0, matcher: statement.matcher.raw, detail: `No line under ${statement.target.raw} matched the pattern.` });
-            const logEntryId = await this.#logWriter.writeLog({
-                statement, result, workspaceId: context.workspaceId, workerId: context.workerId, loopId: context.loopId,
-                turnId: context.turnId, sequence: context.sequence, origin: context.origin, curationPlan: null, modelCallId: null,
-            });
-            context.onDispatch?.(logEntryId);
-            await this.#notifySettled(context, logEntryId);
-            return result;
+        const matched = typeof found.matchingPathCount === "number" ? found.matchingPathCount : paths.length;
+        if (survey.lineMarker !== null && matched !== paths.length) {
+            throw new InvalidOperationResultError("Unbounded FIND did not return its complete resource selection.");
         }
-        const matchingPathCount = typeof found.matchingPathCount === "number" ? found.matchingPathCount : paths.length;
-        const results = [];
-        for (const [index, path] of paths.entries()) {
-            const target = parsePath(path);
+        const targets = paths.map((path) => {
+            const selected = survey.target?.fragment == null ? path : `${path.split("#")[0]}#${survey.target.fragment}`;
+            const target = parsePath(selected);
             if (target === null)
-                throw new InvalidOperationResultError(`FIND named an unparseable path: ${path}`);
-            const fanout = { target: statement.target.raw, matched: matchingPathCount, index, count: paths.length };
-            results.push(await this.#dispatch({ ...context, statement: { ...statement, target }, sequence: context.sequence + index, fanout }));
+                throw new InvalidOperationResultError(`FIND named an unparseable path: ${selected}`);
+            return target;
+        });
+        return { targets, matched };
+    }
+    async #selectTargets(statement, ctx) {
+        if (statement.op === "COPY" || statement.op === "MOVE") {
+            if (![statement.source, statement.destination].some(({ target }) => _a.#globTarget(target)))
+                return null;
+            let resolved = statement;
+            for (const operand of ["source", "destination"]) {
+                const selection = statement[operand];
+                if (!_a.#globTarget(selection.target))
+                    continue;
+                const found = await this.#findTargets({
+                    ...selection, op: "FIND", matcher: null, lineMarker: { marks: [1, -1] },
+                    aside: statement.aside, position: statement.position, body: null,
+                }, ctx);
+                if ("result" in found)
+                    return found;
+                if (found.targets.length !== 1)
+                    return { result: _a.#failure("target-cardinality", 400, `${statement.op} ${operand} matched ${found.matched} resources; expected one.`, {}, { operand, matchingPathCount: found.matched, recovery: "Name one source and one destination per pair.", retryable: false }) };
+                resolved = { ...resolved, [operand]: { ...selection, target: found.targets[0] } };
+            }
+            return { statements: [resolved] };
         }
-        if (matchingPathCount > paths.length) {
-            this.#notices.push(context.workspaceId, context.workerId, context.loopId, {
-                source: "engine:dispatcher",
-                kind: "read_fanout_bounded",
-                level: "warn",
+        if (!(statement.op === "READ" || statement.op === "EDIT" || statement.op === "KILL"))
+            return null;
+        if (!_a.#globTarget(statement.target) || (statement.op === "KILL" && schemeNameOf(statement.target) === "log"))
+            return null;
+        const found = await this.#findTargets({
+            op: "FIND", aside: statement.aside, target: statement.target, metadata: statement.metadata,
+            matcher: statement.op === "READ" ? statement.matcher : null,
+            lineMarker: statement.op === "READ" ? null : { marks: [1, -1] }, body: null, position: statement.position,
+        }, ctx);
+        if ("result" in found)
+            return found;
+        if (found.targets.length === 0)
+            return { result: Results.assert(statement.op === "READ" && statement.matcher !== null
+                    ? { status: 204, matched: 0, matcher: statement.matcher.raw, detail: `No line under ${statement.target.raw} matched the pattern.` }
+                    : { status: 204, detail: `No path matched ${statement.target.raw}.` }) };
+        if (statement.op === "READ" && found.matched > found.targets.length) {
+            this.#notices.push(ctx.workspaceId, ctx.workerId, ctx.loopId, {
+                source: "engine:dispatcher", kind: "read_fanout_bounded", level: "warn",
                 directive: "YOU SHOULD narrow the glob, or FIND first.",
-                message: `READ ${statement.target.raw} matched ${matchingPathCount} paths; the first ${paths.length} were read.`,
+                message: `READ ${statement.target.raw} matched ${found.matched} paths; the first ${found.targets.length} were selected.`,
             });
         }
-        return Results.assert({ ...(results.find(({ status }) => status >= 400) ?? results[results.length - 1]), rowsWritten: results.length });
+        return { statements: found.targets.map((target) => ({ ...statement, target })), fanout: { target: statement.target.raw, matched: found.matched } };
     }
-    async #dispatchOne(context, schemeCtx) {
+    async #dispatchSelection(context, selection) {
+        const admitted = selection.statements.slice(0, context.remainingCommands);
+        const results = [];
+        let rowsWritten = 0;
+        for (const [index, statement] of admitted.entries()) {
+            const { result } = await this.#dispatch({
+                ...context, statement, sequence: context.sequence + rowsWritten,
+                ...(selection.fanout === undefined ? {} : { fanout: { ...selection.fanout, index, count: admitted.length } }),
+                ...(context.fit === undefined ? {} : { fit: reserved(context.fit, admitted.length - index - 1) }),
+            }, true);
+            results.push(result);
+            rowsWritten += result.rowsWritten ?? 1;
+            if (context.failOnOperationError && result.status >= 400 && !isContextReceipt(result))
+                break;
+        }
+        if (results.length === 0)
+            throw new Error("Dispatch requires an admitted operation.");
+        return { result: { ...(results.find(({ status }) => status >= 400) ?? results.at(-1)), rowsWritten },
+            commandsExecuted: results.length, commandsOmitted: selection.statements.length - admitted.length };
+    }
+    // {§bulk-resource-targeting} Dispatch accounting is core-owned, never a scheme's extension data.
+    static #singleExecution(result) {
+        return { result, commandsExecuted: 1, commandsOmitted: 0 };
+    }
+    async #dispatchOne(context, schemeCtx, targetsResolved = false) {
         const { statement, workspaceId, workerId, loopId, turnId, sequence, origin, onDispatch, } = context;
         let result;
+        let resolved = null;
         let curationPlan = null;
         const denial = this.#checkWritable(statement, origin, workspaceId)
             ?? await this.#checkCapabilities(statement, schemeCtx)
@@ -445,7 +499,14 @@ class Dispatcher {
             // skips it. Logging failures (#writeLog throws) are NOT caught —
             // those are system failures.
             try {
-                if (statement.op === "EDIT") {
+                const selection = targetsResolved ? null : await this.#selectTargets(statement, schemeCtx);
+                if (selection !== null && !("result" in selection)) {
+                    resolved = selection;
+                }
+                else if (selection !== null) {
+                    result = selection.result;
+                }
+                else if (statement.op === "EDIT") {
                     result = await this.#resourceMutations.edit(statement, schemeCtx, context.editSequence);
                 }
                 else if (statement.op === "SEND" && statement.target === null) {
@@ -516,6 +577,12 @@ class Dispatcher {
                 }
             }
         }
+        // Child dispatch includes persistence and proposal settlement; their failures are
+        // internal, not exceptions from a scheme handler.
+        if (resolved !== null)
+            return this.#dispatchSelection(context, resolved);
+        if (result === undefined)
+            throw new Error("Operation dispatch produced neither targets nor a result.");
         result = await this.#fitResult(context, statement, result);
         // {§configuration-repair-path}: decide admission before persisting a proposed row.
         let autoAccept = false;
@@ -538,7 +605,7 @@ class Dispatcher {
                 }
             }
         }
-        // {§read-fan-out} — a row read on behalf of a glob names the statement it came from.
+        // {§bulk-resource-targeting} — a row on behalf of a glob names the statement it came from.
         if (context.fanout !== undefined) {
             const attrs = typeof result.attrs === "object" && result.attrs !== null ? result.attrs : {};
             result = { ...result, attrs: { ...attrs, fanout: context.fanout } };
@@ -569,6 +636,7 @@ class Dispatcher {
         // result the caller sees, so runTurn never branches on a pending state.
         if (_a.#isProposal(statement, result)) {
             if (autoAccept) {
+                await this.#proposals.recordDecision(logEntryId, { decision: "accept" });
                 const initialSettlement = await this.#proposals.workerApply(statement, result, { decision: "accept" }, { workspaceId, workerId, loopId, turnId, resources: schemeCtx.resources });
                 const effective = await this.#resourceMutations.settleProposal({
                     statement,
@@ -579,7 +647,7 @@ class Dispatcher {
                 });
                 const post = await this.#proposals.applyResolution(logEntryId, effective);
                 await this.#notifySettled(context, logEntryId);
-                return post;
+                return _a.#singleExecution(post);
             }
             // Register the resolution waiter SYNCHRONOUSLY before any await
             // yields. A same-tick resolveProposal() (e.g. from a test that
@@ -619,10 +687,10 @@ class Dispatcher {
             });
             const post = await this.#proposals.applyResolution(logEntryId, effective);
             await this.#notifySettled(context, logEntryId);
-            return post;
+            return _a.#singleExecution(post);
         }
         await this.#notifySettled(context, logEntryId);
-        return result;
+        return _a.#singleExecution(result);
     }
     // {§context-fit} — a result the model asked for arrives whole when it fits the remaining budget;
     // otherwise the row is its size and address — a READ of lines above the longest prefix of them that
@@ -724,11 +792,9 @@ class Dispatcher {
             return null;
         if (resolved.address === null)
             return null;
-        const rendered = target.kind === "url"
-            ? renderTarget({ ...target, fragment: null })
-            : renderTarget({ scheme: null, pathname: target.raw, fragment: null });
-        if (rendered === null)
-            throw new TypeError("Resolved entry target did not render.");
+        const rendered = resolved.address.scheme === "file"
+            ? entryAddress("file", "", resolved.address.pathname, await this.#workspaceRoot(workspaceId))
+            : renderAuthoredTarget({ ...target, fragment: null });
         return {
             scheme: resolved.address.scheme,
             authority: resolved.address.authority,
@@ -1317,7 +1383,14 @@ class Dispatcher {
         // `local` (bare path) carries no URL parts — store the raw text as the pathname for the log record, scheme=null.
         if (path.kind === "local")
             return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: PathSyntax.decodeParens(path.raw), query: null, fragment: path.fragment ?? null }; // {§path-parentheses} {§local-path-fragment}
-        const scheme = path.scheme === "file" ? null : path.scheme;
+        if (path.scheme === "file") {
+            const pathname = FileAddress.pathname(path);
+            // An invalid URL has no resolved identity; retain the refused input alongside its failure.
+            if (typeof pathname !== "string")
+                return { ...path };
+            return { scheme: null, username: null, password: null, hostname: null, port: null, pathname, query: null, fragment: path.fragment };
+        }
+        const scheme = path.scheme;
         // The registered scheme owns authority disposition. Namespace authority
         // is path syntax; resource and owner authorities remain explicit in the
         // durable operation evidence.