@plurnk/plurnk-contracts 1.16.4 → 1.17.0

package/dist/src/AstBuilder.js

@@ -2,13 +2,14 @@
 import { ParserRuleContext, TerminalNode } from "antlr4ng";
 import * as xpath from "xpath";
 import { JSONPathEnvironment } from "json-p3/dist/json-p3.esm.js";
-import { BodyContext, LineMarkerContext, MetadataContext, MidSendContext, PlanStatementContext, SendStatementContext, TargetContext, } from "./generated/plurnkParser.js";
+import { BodyContext, LineMarkerContext, MetadataContext, DispositionStatementContext, SendStatementContext, TargetContext, } from "./generated/plurnkParser.js";
 import { plurnkLexer } from "./generated/plurnkLexer.js";
 import PlurnkParseError from "./PlurnkParseError.js";
 import PathSyntax from "./PathSyntax.js";
 import PlanValue from "./PlanValue.js";
+import TurnDisposition from "./TurnDisposition.js";
 export default class AstBuilder {
-    // {§misplaced-annotation-advisory} — advisories raised while building one statement; the
+    // {§misplaced-aside-advisory} — advisories raised while building one statement; the
     // parser drains them right after the statement so the model sees WHAT it did on the first try.
     static #advisories = [];
     static takeAdvisories() {
@@ -17,32 +18,165 @@ export default class AstBuilder {
         return taken;
     }
     // A body that is solely an HTML comment can never be a matcher. Preserve it
-    // as the operation annotation and report only that deterministic normalization.
-    static #annotationBody(op, delimiter, annotation, raw, position) {
+    // as the operation aside and report only that deterministic normalization.
+    static #asideBody(op, aside, raw, position) {
         if (raw === null)
-            return { annotation, raw };
+            return { aside, raw };
         const comment = /^\s*<!--([\s\S]*?)-->\s*$/u.exec(raw);
         if (comment === null)
-            return { annotation, raw };
-        AstBuilder.#advisories.push(new PlurnkParseError(position.line, position.column, "parser", `The ${op} body contained only an HTML comment; it was applied as the operation annotation.`, "warning"));
-        return { annotation: annotation ?? (comment[1] ?? "").trim(), raw: null };
+            return { aside, raw };
+        AstBuilder.#advisories.push(new PlurnkParseError(position.line, position.column, "parser", `The ${op} body contained only an HTML comment; it was applied as the operation aside.`, "warning"));
+        return { aside: aside ?? (comment[1] ?? "").trim(), raw: null };
+    }
+    // {§matcher-option} — `pattern` is the language's key inside `[metadata]`: lifted into the
+    // statement's `matcher`, classified exactly as a body matcher was ({§matcher-prefix-claims}).
+    // A block that carries only `pattern` leaves no metadata for the owner; beside other keys the
+    // block stays for the owner, whose reader skips the reserved key. The block's shape stays the
+    // owner's business ({§scheme-metadata-modifier}): a second block or malformed JSON lifts
+    // nothing and reaches the owner's 400 untouched; only a present `pattern` that is not a
+    // string, or a malformed matcher, is the language's own positioned diagnostic.
+    // {§naked-pattern} — one line of matcher text, its trailing aside split back out. A sigil
+    // (`/`, `//`, `$`, `~`, `&`, `^`) is a matcher wherever it stands; a sigil-less glob or literal
+    // is one only on the heading line of FIND, READ or KILL, where the text can mean nothing else.
+    // {§trailing-slots} — the slots after the matcher peel off the right end of the heading text,
+    // aside, scope and option block in any order, until what remains is the matcher.
+    static #bareMatcher(raw, op, inline, position, carried = { scope: false, metadata: false }) {
+        if (raw === null)
+            return null;
+        let text = raw.trim();
+        if (text === "" || text.includes("\n"))
+            return null;
+        let aside = null;
+        let scope = null;
+        let metadata = null;
+        // A slot the heading already carries is not peeled: a second one is trailing text.
+        let scopeFree = !carried.scope;
+        let metadataFree = !carried.metadata;
+        const scopeTail = op === "FIND" ? AstBuilder.#TAIL_POSITIONS : AstBuilder.#TAIL_TEXT_SCOPE;
+        for (;;) {
+            const trailingAside = /\s*<!--([\s\S]*?)-->\s*$/u.exec(text);
+            if (trailingAside !== null && aside === null) {
+                aside = (trailingAside[1] ?? "").trim();
+                text = text.slice(0, trailingAside.index).trim();
+                continue;
+            }
+            const trailingScope = scopeTail.exec(text);
+            if (trailingScope !== null && scopeFree && trailingScope.index > 0) {
+                scope = trailingScope[1];
+                scopeFree = false;
+                text = text.slice(0, trailingScope.index).trim();
+                AstBuilder.#adviseTrailing(position, `\`${scope}\` after the pattern was read as the scope; the scope goes before the pattern.`);
+                continue;
+            }
+            const trailingBlock = /\s*\[(\{[\s\S]*\})\]\s*$/u.exec(text);
+            if (trailingBlock !== null && metadataFree && trailingBlock.index > 0 && AstBuilder.#isJsonArrayOfObjects(trailingBlock[1])) {
+                metadata = trailingBlock[1];
+                metadataFree = false;
+                text = text.slice(0, trailingBlock.index).trim();
+                AstBuilder.#adviseTrailing(position, `\`[${metadata}]\` after the pattern was read as the option block; options go before the pattern.`);
+                continue;
+            }
+            break;
+        }
+        if (text === "")
+            return null;
+        if (AstBuilder.#SIGIL.test(text))
+            return { text, aside, scope, metadata };
+        if (!inline || (op !== "FIND" && op !== "READ" && op !== "KILL"))
+            return null;
+        return { text, aside, scope, metadata };
+    }
+    static #adviseTrailing(position, message) {
+        if (position === undefined)
+            return;
+        AstBuilder.#advisories.push(new PlurnkParseError(position.line, position.column, "parser", message, "warning"));
+    }
+    static #isJsonArrayOfObjects(inner) {
+        try {
+            const parsed = JSON.parse(`[${inner}]`);
+            return Array.isArray(parsed) && parsed.every((element) => typeof element === "object" && element !== null && !Array.isArray(element));
+        }
+        catch {
+            return false;
+        }
+    }
+    static #SIGIL = /^(\/|\$|~|&|\^)/u;
+    // The scope shapes the lexer admits, matched at the right end of the heading text.
+    static #TAIL_POSITIONS = /\s*(<-?[0-9]+(?:\.[0-9]+)?(?:(?:,\s?|-)-?[0-9]+(?:\.[0-9]+)?)*>)\s*$/u;
+    static #TAIL_TEXT_SCOPE = /\s*(<(?:-?[0-9]+(?:\.[0-9]+)?|@[0-9A-Za-z]{5}(?:[: ][1-9][0-9]*)?|@[0-9]{1,4})(?:(?:,\s?|-)(?:-?[0-9]+(?:\.[0-9]+)?|@[0-9A-Za-z]{5}(?:[: ][1-9][0-9]*)?|@[0-9]{1,4}))*>)\s*$/u;
+    // The body text that opened on the heading line itself, split from the lines beneath it.
+    static #splitInlineBody(ctx, position) {
+        const text = AstBuilder.#bodyTextOf(ctx);
+        if (text === null)
+            return { inline: null, below: null };
+        const body = AstBuilder.#findFirst(ctx, BodyContext);
+        if (body?.start === null || body?.start === undefined || body.start.line !== position.line)
+            return { inline: null, below: text };
+        const eol = text.search(/\r?\n/u);
+        if (eol === -1)
+            return { inline: text, below: null };
+        const below = text.slice(eol).replace(/^\r?\n/u, "");
+        return { inline: text.slice(0, eol), below: below === "" ? null : below };
+    }
+    static #liftMatcher(op, metadata, position, raw = null, inline = false, carriedScope = false) {
+        if (metadata === null || metadata.length !== 1) {
+            const bare = AstBuilder.#bareMatcher(raw, op, inline, position, { scope: carriedScope, metadata: metadata !== null });
+            return bare === null
+                ? { matcher: null, metadata, aside: null, scope: null }
+                : {
+                    matcher: AstBuilder.#parseMatcherBody(bare.text, position),
+                    metadata: metadata ?? (bare.metadata === null ? null : [bare.metadata]),
+                    aside: bare.aside,
+                    scope: bare.scope,
+                };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(`[${metadata[0]}]`);
+        }
+        catch (cause) {
+            if (!(cause instanceof SyntaxError))
+                throw cause;
+            return { matcher: null, metadata, aside: null, scope: null };
+        }
+        const elements = parsed;
+        if (elements.some((element) => typeof element !== "object" || element === null || Array.isArray(element))) {
+            return { matcher: null, metadata, aside: null, scope: null };
+        }
+        const options = Object.assign({}, ...elements);
+        if (!Object.hasOwn(options, "pattern"))
+            return { matcher: null, metadata, aside: null, scope: null };
+        const pattern = options.pattern;
+        if (typeof pattern !== "string") {
+            throw new PlurnkParseError(position.line, position.column, "visitor", `${op} "pattern" must be a string matcher, e.g. [{"pattern": "/needle/i"}].`);
+        }
+        const matcher = AstBuilder.#parseMatcherBody(pattern, position);
+        const others = Object.keys(options).filter((key) => key !== "pattern");
+        return { matcher, metadata: others.length === 0 ? null : metadata, aside: null, scope: null };
+    }
+    // {§matcher-option} — a text or log operation's body is never a matcher; it is ignored with one
+    // advisory naming the option form, and the operation still runs (operator, 2026-09-12: warn, never
+    // strike, over a body the model was taught not to write).
+    static #adviseBody(op, raw, position) {
+        if (raw === null || raw.trim() === "")
+            return;
+        if (AstBuilder.#bareMatcher(raw, op, false) !== null)
+            return;
+        AstBuilder.#advisories.push(new PlurnkParseError(position.line, position.column, "parser", `${op} takes no body; the body was ignored. A pattern belongs on the opening fence line after the path.`, "warning"));
     }
     static #SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
     // Compile-only RFC 9535 admission using the runtime's JSONPath engine. {§matcher-prefix-claims}
     static #JSONPATH = new JSONPathEnvironment();
     static #GRAPH_MATCHER = /^&[<>]?[^\s<>]\S*$/u;
     static build(ctx) {
-        // The strict turn root attaches the leading PLAN and the terminal SEND as direct
-        // children (not wrapped in `statement`), so dispatch those by type first.
-        if (ctx instanceof PlanStatementContext)
-            return AstBuilder.#buildPlan(ctx);
+        // Disposition and SEND contexts can arrive without a statement wrapper.
+        if (ctx instanceof DispositionStatementContext)
+            return AstBuilder.#buildDisposition(ctx);
         if (ctx instanceof SendStatementContext)
             return AstBuilder.#buildSend(ctx);
-        if (ctx instanceof MidSendContext)
-            return AstBuilder.#buildMidSend(ctx);
-        const midSend = ctx.midSend();
-        if (midSend)
-            return AstBuilder.#buildMidSend(midSend);
+        const send = ctx.sendStatement();
+        if (send)
+            return AstBuilder.#buildSend(send);
         const find = ctx.findStatement();
         if (find)
             return AstBuilder.#buildFind(find);
@@ -73,32 +207,32 @@ export default class AstBuilder {
         const kill = ctx.killStatement();
         if (kill)
             return AstBuilder.#buildKill(kill);
-        // `midStatement` has no planStatement alternative (PLAN is never a mid-op); only the
-        // full `statement` rule does.
-        if ("planStatement" in ctx) {
-            const plan = ctx.planStatement();
-            if (plan)
-                return AstBuilder.#buildPlan(plan);
-            const send = ctx.sendStatement();
-            if (send)
-                return AstBuilder.#buildSend(send);
+        if ("dispositionStatement" in ctx) {
+            const disposition = ctx.dispositionStatement();
+            if (disposition)
+                return AstBuilder.#buildDisposition(disposition);
         }
         throw new Error("statement context has no recognized alternative");
     }
     static #buildFind(ctx) {
-        const positionForBody = AstBuilder.#positionOf(ctx);
-        const bodied = AstBuilder.#annotationBody("FIND", AstBuilder.#splitDelimiter(ctx.OPEN_FIND().getText(), "FIND"), AstBuilder.#annotationOf(ctx), AstBuilder.#bodyTextOf(ctx), positionForBody);
-        return AstBuilder.#buildFindFrom(ctx, bodied.annotation, bodied.raw);
+        const position = AstBuilder.#positionOf(ctx);
+        const split = AstBuilder.#splitInlineBody(ctx, position);
+        const bodied = AstBuilder.#asideBody("FIND", AstBuilder.#asideOf(ctx), split.below, position);
+        return AstBuilder.#buildFindFrom(ctx, bodied.aside, split.inline, bodied.raw);
     }
-    static #buildFindFrom(ctx, annotation, raw) {
+    static #buildFindFrom(ctx, aside, inline, below) {
         const position = AstBuilder.#positionOf(ctx);
         const slots = AstBuilder.#extractSlots(ctx.slotModifiers(), position);
+        AstBuilder.#adviseBody("FIND", below, position);
+        const lifted = AstBuilder.#liftMatcher("FIND", slots.metadata, position, inline ?? below, inline !== null, slots.lineMarker !== null);
         return {
             op: "FIND",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_FIND().getText(), "FIND"),
-            annotation,
+            aside: aside ?? lifted.aside,
             ...slots,
-            body: raw !== null ? AstBuilder.#parseMatcherBody(raw, position) : null,
+            lineMarker: slots.lineMarker ?? (lifted.scope === null ? null : AstBuilder.#parseLineMarker(lifted.scope)),
+            metadata: lifted.metadata,
+            matcher: lifted.matcher,
+            body: null,
             position,
         };
     }
@@ -113,34 +247,17 @@ export default class AstBuilder {
         const look = ctx.lookStatement();
         if (look)
             return AstBuilder.#buildLook(look);
-        const buff = ctx.buffStatement();
-        if (buff)
-            return AstBuilder.#buildBuff(buff);
         throw new Error("clientStatement context has no recognized alternative");
     }
-    // LOOK / BUFF are client-tier matcher observations. They share the tag slots
-    // and parse matcher bodies directly for their client-owned lifecycles.
+    // LOOK is the client-tier matcher observation. It shares the tag slots and parses
+    // its matcher body directly for its client-owned lifecycle.
     static #buildLook(ctx) {
         const position = AstBuilder.#positionOf(ctx);
         const slots = AstBuilder.#extractTextSlots(ctx.slotModifiers(), position);
         const raw = AstBuilder.#bodyTextOf(ctx);
         return {
             op: "LOOK",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_LOOK().getText(), "LOOK"),
-            annotation: AstBuilder.#annotationOf(ctx),
-            ...slots,
-            body: raw !== null ? AstBuilder.#parseMatcherBody(raw, position) : null,
-            position,
-        };
-    }
-    static #buildBuff(ctx) {
-        const position = AstBuilder.#positionOf(ctx);
-        const slots = AstBuilder.#extractSlots(ctx.slotModifiers(), position);
-        const raw = AstBuilder.#bodyTextOf(ctx);
-        return {
-            op: "BUFF",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_BUFF().getText(), "BUFF"),
-            annotation: AstBuilder.#annotationOf(ctx),
+            aside: AstBuilder.#asideOf(ctx),
             ...slots,
             body: raw !== null ? AstBuilder.#parseMatcherBody(raw, position) : null,
             position,
@@ -149,33 +266,20 @@ export default class AstBuilder {
     static #buildRead(ctx) {
         const position = AstBuilder.#positionOf(ctx);
         const slots = AstBuilder.#extractTextSlots(ctx.slotModifiers(), position);
-        const delimiter = AstBuilder.#splitDelimiter(ctx.OPEN_READ().getText(), "READ");
-        const bodied = AstBuilder.#annotationBody("READ", delimiter, AstBuilder.#annotationOf(ctx), AstBuilder.#bodyTextOf(ctx), position);
-        const annotation = bodied.annotation;
-        const raw = bodied.raw;
-        const targetPath = slots.target?.kind === "url"
-            ? slots.target.pathname
-            : slots.target?.raw;
-        const hasMatcher = raw !== null && raw.trim() !== "";
-        if (hasMatcher || (targetPath !== undefined && PathSyntax.hasGlob(targetPath))) {
-            if (slots.lineMarker?.marks.some((mark) => typeof mark === "string") === true) {
-                throw new PlurnkParseError(position.line, position.column, "visitor", "line anchors require an exact READ target; FIND result positions are numeric");
-            }
-            const findSlots = slots;
-            return {
-                op: "FIND",
-                delimiter,
-                annotation,
-                ...findSlots,
-                body: hasMatcher ? AstBuilder.#parseMatcherBody(raw, position) : null,
-                position,
-            };
-        }
+        const split = AstBuilder.#splitInlineBody(ctx, position);
+        const bodied = AstBuilder.#asideBody("READ", AstBuilder.#asideOf(ctx), split.below, position);
+        AstBuilder.#adviseBody("READ", bodied.raw, position);
+        const lifted = AstBuilder.#liftMatcher("READ", slots.metadata, position, split.inline ?? bodied.raw, split.inline !== null, slots.lineMarker !== null);
+        const aside = bodied.aside ?? lifted.aside;
+        // {§read-find-normalization} — a READ is never rewritten: a glob target is the runtime's
+        // fan-out over every matching path, with or without a matcher (core {§read-fan-out}).
         return {
             op: "READ",
-            delimiter,
-            annotation,
+            aside,
             ...slots,
+            lineMarker: slots.lineMarker ?? (lifted.scope === null ? null : AstBuilder.#parseTextLineMarker(lifted.scope, position)),
+            metadata: lifted.metadata,
+            matcher: lifted.matcher,
             body: null,
             position,
         };
@@ -183,12 +287,18 @@ export default class AstBuilder {
     static #buildEdit(ctx) {
         const position = AstBuilder.#positionOf(ctx);
         const slots = AstBuilder.#extractTextSlots(ctx.slotModifiers(), position);
+        // {§naked-pattern} — a sigil on the heading line is the matcher; the lines beneath are the
+        // replacement (none deletes each match). Any other heading-line text is the body it always was.
+        const split = AstBuilder.#splitInlineBody(ctx, position);
+        const lifted = AstBuilder.#liftMatcher("EDIT", slots.metadata, position, split.inline, true, slots.lineMarker !== null);
         return {
             op: "EDIT",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_EDIT().getText(), "EDIT"),
-            annotation: AstBuilder.#annotationOf(ctx),
+            aside: AstBuilder.#asideOf(ctx) ?? lifted.aside,
             ...slots,
-            body: AstBuilder.#bodyTextOf(ctx),
+            lineMarker: slots.lineMarker ?? (lifted.scope === null ? null : AstBuilder.#parseTextLineMarker(lifted.scope, position)),
+            metadata: lifted.metadata,
+            matcher: lifted.matcher,
+            body: lifted.matcher === null || split.inline === null ? AstBuilder.#bodyTextOf(ctx) : split.below,
             position,
         };
     }
@@ -200,8 +310,7 @@ export default class AstBuilder {
             throw new Error("COPY grammar did not produce two resource selections");
         return {
             op: "COPY",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_COPY().getText(), "COPY"),
-            annotation: AstBuilder.#annotationOf(ctx),
+            aside: AstBuilder.#asideOf(ctx),
             source: AstBuilder.#resourceSelectionFromCtx(selections[0], position),
             destination: AstBuilder.#resourceSelectionFromCtx(selections[1], position),
             position,
@@ -215,128 +324,96 @@ export default class AstBuilder {
             throw new Error("MOVE grammar did not produce two resource selections");
         return {
             op: "MOVE",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_MOVE().getText(), "MOVE"),
-            annotation: AstBuilder.#annotationOf(ctx),
+            aside: AstBuilder.#asideOf(ctx),
             source: AstBuilder.#resourceSelectionFromCtx(selections[0], position),
             destination: AstBuilder.#resourceSelectionFromCtx(selections[1], position),
             position,
         };
     }
-    // {§send-label} — a disposition label makes the SEND terminal and names no recipient.
-    static #SEND_LABELS = Object.freeze({ NEXT: 102, WAIT: 202, TERM: 200, FAIL: 499 });
-    static #buildSend(ctx) {
+    static #buildDisposition(ctx) {
         const position = AstBuilder.#positionOf(ctx);
-        const label = ctx.SEND_LABEL().getText().slice(1, -1);
-        const status = AstBuilder.#SEND_LABELS[label];
-        if (status === undefined)
-            throw new Error(`the lexer admitted an unknown SEND label: ${label}`);
-        const raw = AstBuilder.#bodyTextOf(ctx);
+        const op = (ctx.start?.text ?? "").replace(/^`+[0-9]*/, "");
+        if (!TurnDisposition.isOp(op))
+            throw new Error(`Unknown disposition operation: ${op}`);
+        // {§one-line-turn} — an inventory written as a block on the heading line is the body when
+        // nothing sits beneath the heading, with one advisory naming where it belongs.
+        const below = AstBuilder.#bodyTextOf(ctx);
+        const inline = ctx.metadata()?.getText() ?? null;
+        if (inline !== null && (below === null || below.trim() === "")) {
+            AstBuilder.#advisories.push(new PlurnkParseError(position.line, position.column, "parser", `${op}'s inventory was read from the heading line; it belongs in the body.`, "warning"));
+        }
+        const raw = below !== null && below.trim() !== "" ? below : inline;
         return {
-            op: "SEND",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_SEND().getText(), "SEND"),
-            annotation: AstBuilder.#annotationOf(ctx),
-            status,
+            op,
+            aside: AstBuilder.#asideOf(ctx),
             target: null,
             metadata: null,
-            // A WAIT keeps its scope ({§send-wait-scope}); the dispatcher owns what it accepts.
             lineMarker: AstBuilder.#lineMarkerFromCtx(ctx.lineMarker()),
-            body: raw !== null ? AstBuilder.#parseSendBody(raw) : null,
+            body: PlanValue.admit(raw ?? "", (message) => AstBuilder.#advisories.push(new PlurnkParseError(position.line, position.column, "visitor", message, "warning"))),
             position,
         };
     }
     // A mid-turn SEND is a message to its recipient path, or to the user when it names none.
-    static #buildMidSend(ctx) {
+    static #buildSend(ctx) {
         const position = AstBuilder.#positionOf(ctx);
-        const slots = AstBuilder.#extractBranchSlots(ctx.targetWithMetadata(), position);
+        const slots = AstBuilder.#extractSlots(ctx.resourceSelection(), position);
         const raw = AstBuilder.#bodyTextOf(ctx);
         return {
             op: "SEND",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_SEND().getText(), "SEND"),
-            annotation: AstBuilder.#annotationOf(ctx),
-            status: null,
-            target: slots.target,
-            metadata: slots.metadata,
-            lineMarker: null,
+            aside: AstBuilder.#asideOf(ctx),
+            ...slots,
             body: raw !== null ? AstBuilder.#parseSendBody(raw) : null,
             position,
         };
     }
     static #buildExec(ctx) {
         const position = AstBuilder.#positionOf(ctx);
-        const slots = AstBuilder.#extractExecSlots(ctx.execModifiers(), position);
+        const slots = AstBuilder.#extractExecSlots(ctx.execModifiers(), position, AstBuilder.#executorOf(ctx) ?? "sh");
         return {
             op: "EXEC",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_EXEC().getText(), "EXEC"),
-            annotation: AstBuilder.#annotationOf(ctx),
-            executor: AstBuilder.#executorOf(ctx, position),
+            aside: AstBuilder.#asideOf(ctx),
+            executor: AstBuilder.#executorOf(ctx),
             ...slots,
             body: AstBuilder.#bodyTextOf(ctx),
             position,
         };
     }
-    // {§exec-executor-slot} — the executor may lead the heading or trail the path (once, unambiguous:
-    // no other slot after a path uses `[...]`); two executors are the one rejected shape.
-    static #executorOf(ctx, pos) {
-        const found = ctx.EXECUTOR();
-        const list = Array.isArray(found) ? found : found === null || found === undefined ? [] : [found];
-        if (list.length > 1) {
-            throw new PlurnkParseError(pos.line, pos.column, "visitor", "`### EXEC0` accepts one `[executor]`");
-        }
-        return list[0]?.getText().slice(1, -1) ?? null;
+    // {§executor-case} — the AST carries the registered spelling; the tag may be written in any case.
+    static executorSpellings = new Map();
+    static #executorOf(ctx) {
+        const name = ctx.OPEN_EXEC().getText().replace(/^`+[0-9]*/, "");
+        if (name === "EXEC")
+            return null;
+        return AstBuilder.executorSpellings.get(name.toLowerCase()) ?? name;
     }
     static #buildBare(ctx) {
         const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractBranchSlots(ctx.targetWithMetadata(), position);
         return {
             op: "BARE",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_BARE().getText(), "BARE"),
-            annotation: AstBuilder.#annotationOf(ctx),
-            target: null,
-            metadata: null,
+            aside: AstBuilder.#asideOf(ctx),
+            target: slots.target,
+            metadata: slots.metadata,
             lineMarker: null,
             body: AstBuilder.#requiredBodyTextOf(ctx),
             position,
         };
     }
-    static #buildPlan(ctx) {
-        const position = AstBuilder.#positionOf(ctx);
-        const slots = AstBuilder.#extractSlots(ctx.slotModifiers(), position);
-        const rejected = [
-            slots.target !== null ? "(path)" : null,
-            slots.metadata !== null ? "{metadata}" : null,
-            slots.lineMarker !== null ? "<scope>" : null,
-        ].filter((slot) => slot !== null);
-        if (rejected.length > 0) {
-            throw new PlurnkParseError(position.line, position.column, "visitor", `PLAN does not accept ${AstBuilder.#joinTerms(rejected)}.`);
-        }
-        return {
-            op: "PLAN",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_PLAN().getText(), "PLAN"),
-            annotation: AstBuilder.#annotationOf(ctx),
-            target: null,
-            metadata: null,
-            lineMarker: null,
-            body: PlanValue.admit(AstBuilder.#requiredBodyTextOf(ctx)),
-            position,
-        };
-    }
-    static #joinTerms(terms) {
-        if (terms.length < 2)
-            return terms[0] ?? "";
-        if (terms.length === 2)
-            return `${terms[0]} and ${terms[1]}`;
-        return `${terms.slice(0, -1).join(", ")}, and ${terms.at(-1)}`;
-    }
     static #buildKill(ctx) {
         const position = AstBuilder.#positionOf(ctx);
         // {§kill-scope} — the scope names lines of a log body or of an entry; null kills the whole target.
         const slots = AstBuilder.#extractTextSlots(ctx.slotModifiers(), position);
-        const raw = AstBuilder.#bodyTextOf(ctx);
+        const split = AstBuilder.#splitInlineBody(ctx, position);
+        AstBuilder.#adviseBody("KILL", split.below, position);
+        const lifted = AstBuilder.#liftMatcher("KILL", slots.metadata, position, split.inline ?? split.below, split.inline !== null, slots.lineMarker !== null);
         return {
             op: "KILL",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_KILL().getText(), "KILL"),
-            annotation: AstBuilder.#annotationOf(ctx),
+            aside: AstBuilder.#asideOf(ctx) ?? lifted.aside,
             ...slots,
-            body: raw !== null ? AstBuilder.#parseMatcherBody(raw, position) : null,
+            lineMarker: slots.lineMarker ?? (lifted.scope === null ? null : AstBuilder.#parseTextLineMarker(lifted.scope, position)),
+            metadata: lifted.metadata,
+            matcher: lifted.matcher,
+            body: null,
             position,
         };
     }
@@ -345,8 +422,7 @@ export default class AstBuilder {
         const slots = AstBuilder.#extractBranchSlots(ctx.targetWithMetadata(), position);
         return {
             op: "WORK",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_WORK().getText(), "WORK"),
-            annotation: AstBuilder.#annotationOf(ctx),
+            aside: AstBuilder.#asideOf(ctx),
             ...slots,
             lineMarker: null,
             body: AstBuilder.#requiredBodyTextOf(ctx),
@@ -358,8 +434,7 @@ export default class AstBuilder {
         const slots = AstBuilder.#extractBranchSlots(ctx.targetWithMetadata(), position);
         return {
             op: "FORK",
-            delimiter: AstBuilder.#splitDelimiter(ctx.OPEN_FORK().getText(), "FORK"),
-            annotation: AstBuilder.#annotationOf(ctx),
+            aside: AstBuilder.#asideOf(ctx),
             ...slots,
             lineMarker: null,
             body: AstBuilder.#requiredBodyTextOf(ctx),
@@ -372,22 +447,27 @@ export default class AstBuilder {
             metadata: AstBuilder.#metadataFromCtx(ctx),
         };
     }
+    static #singleMarker(ctx, pos) {
+        const found = AstBuilder.#findAll(ctx, LineMarkerContext);
+        if (found.length > 1)
+            throw new PlurnkParseError(pos.line, pos.column, "visitor", "A resource selection takes at most one scope.");
+        return found[0] ?? null;
+    }
     static #extractSlots(modCtx, pos) {
         return {
             target: AstBuilder.#targetFromCtx(AstBuilder.#findFirst(modCtx, TargetContext), pos),
             metadata: AstBuilder.#metadataFromCtx(modCtx),
-            lineMarker: AstBuilder.#lineMarkerFromCtx(AstBuilder.#findFirst(modCtx, LineMarkerContext)),
+            lineMarker: AstBuilder.#lineMarkerFromCtx(AstBuilder.#singleMarker(modCtx, pos)),
         };
     }
     static #extractTextSlots(modCtx, pos) {
         return {
             target: AstBuilder.#targetFromCtx(AstBuilder.#findFirst(modCtx, TargetContext), pos),
             metadata: AstBuilder.#metadataFromCtx(modCtx),
-            lineMarker: AstBuilder.#textLineMarkerFromCtx(AstBuilder.#findFirst(modCtx, LineMarkerContext)),
+            lineMarker: AstBuilder.#textLineMarkerFromCtx(AstBuilder.#singleMarker(modCtx, pos)),
         };
     }
     // Depth-first search for the first terminal of `tokenType`; returns its text or null.
-    // Lets the SEND/KILL signal read work regardless of which signal rule wrapped it.
     static #findToken(root, tokenType) {
         if (root === null)
             return null;
@@ -402,12 +482,12 @@ export default class AstBuilder {
         }
         return null;
     }
-    static #extractExecSlots(modCtx, pos) {
+    static #extractExecSlots(modCtx, pos, executor) {
         // {§exec-executor-slot} — every slot at most once; the grammar admits any order.
         const once = (type, slot) => {
             const found = AstBuilder.#findAll(modCtx, type);
             if (found.length > 1) {
-                throw new PlurnkParseError(pos.line, pos.column, "visitor", `\`### EXEC0\` accepts ${slot} at most once`);
+                throw new PlurnkParseError(pos.line, pos.column, "visitor", `${executor} accepts ${slot} at most once`);
             }
             return found[0] ?? null;
         };
@@ -444,6 +524,11 @@ export default class AstBuilder {
     static #targetFromCtx(ctx, pos) {
         if (ctx === null)
             return null;
+        const nestedScope = ctx.lineMarker();
+        if (nestedScope !== null) {
+            const point = AstBuilder.#positionOf(nestedScope);
+            AstBuilder.#advisories.push(new PlurnkParseError(point.line, point.column, "parser", "The scope was inside the target slot; it was applied as the operation scope.", "warning"));
+        }
         const text = ctx.TARGET_TEXT().map((token) => token.getText()).join("");
         return AstBuilder.parsePath(text, pos);
     }
@@ -457,10 +542,12 @@ export default class AstBuilder {
         const target = AstBuilder.#targetFromCtx(AstBuilder.#findFirst(ctx, TargetContext), pos);
         if (target === null)
             throw new Error("resource selection grammar did not produce a target");
+        const lifted = AstBuilder.#liftMatcher("COPY/MOVE", AstBuilder.#metadataFromCtx(ctx), pos);
         return {
             target,
-            metadata: AstBuilder.#metadataFromCtx(ctx),
-            lineMarker: AstBuilder.#textLineMarkerFromCtx(AstBuilder.#findFirst(ctx, LineMarkerContext)),
+            metadata: lifted.metadata,
+            lineMarker: AstBuilder.#textLineMarkerFromCtx(AstBuilder.#singleMarker(ctx, pos)),
+            matcher: lifted.matcher,
         };
     }
     static #lineMarkerFromCtx(ctx) {
@@ -473,32 +560,66 @@ export default class AstBuilder {
         if (ctx === null)
             return null;
         const text = ctx.L_MARKER()?.getText() ?? "";
-        return AstBuilder.#parseTextLineMarker(text);
+        return AstBuilder.#parseTextLineMarker(text, AstBuilder.#positionOf(ctx));
     }
-    static #parseTextLineMarker(text) {
+    static #parseTextLineMarker(text, position) {
         if (!text.includes("@"))
             return AstBuilder.#parseLineMarker(text);
-        const marks = text.slice(1, -1).split(/, ?/).map((component) => component.startsWith("@") ? component : Number.parseFloat(component));
+        const marks = text.slice(1, -1).split(/, ?/).map((component) => {
+            // {§anchor-digits} — `@210` is the line number 210 with the anchor's sigil, not a hash.
+            if (/^@[0-9]{1,4}$/u.test(component)) {
+                if (position !== undefined) {
+                    AstBuilder.#advisories.push(new PlurnkParseError(position.line, position.column, "parser", `\`${component}\` was read as line ${component.slice(1)}; an anchor is five characters (\`@abcde\`).`, "warning"));
+                }
+                return Number.parseInt(component.slice(1), 10);
+            }
+            // {§combined-anchor-tolerance} — `@abcde 42` / `@abcde:42` is the displayed prefix copied whole;
+            // the anchor is the coordinate and the number is dropped.
+            const combined = /^(@[0-9A-Za-z]{5})[: ][1-9][0-9]*$/u.exec(component);
+            if (combined !== null) {
+                if (position !== undefined) {
+                    AstBuilder.#advisories.push(new PlurnkParseError(position.line, position.column, "parser", `\`${component}\` was read as the anchor \`${combined[1]}\`; a scope position takes the anchor without its displayed line number.`, "warning"));
+                }
+                return combined[1];
+            }
+            return component.startsWith("@") ? component : Number.parseFloat(component);
+        });
         return { marks: marks };
     }
     static #positionOf(ctx) {
         const start = ctx.start;
         return { line: start?.line ?? 0, column: start?.column ?? 0 };
     }
-    static #annotationOf(ctx) {
-        const token = AstBuilder.#findToken(ctx, plurnkLexer.ANNOTATION);
-        return token === null ? null : token.slice("<!--".length, -"-->".length).trim();
+    static #asideOf(ctx) {
+        const token = AstBuilder.#findToken(ctx, plurnkLexer.ASIDE);
+        if (token === null)
+            return null;
+        const inner = token.endsWith("-->") ? token.slice("<!--".length, -"-->".length) : token.slice("<!--".length);
+        return inner.trim();
     }
+    // {§closer-fallback} — without a real closer (the block ended at the next heading or at the end
+    // of the input) the body is cut back to its last bare fence line, which is the closer the model
+    // meant, and one terminating line ending goes with it. A synthetic SECTION_END carries no backtick.
     static #bodyTextOf(ctx) {
-        return AstBuilder.#findFirst(ctx, BodyContext)?.getText() ?? null;
+        const text = AstBuilder.#findFirst(ctx, BodyContext)?.getText() ?? null;
+        if (text === null)
+            return null;
+        const closer = AstBuilder.#findToken(ctx, plurnkLexer.SECTION_END);
+        if (closer !== null && closer.includes("`"))
+            return text;
+        const lines = text.split("\n");
+        for (let index = lines.length - 1; index >= 0; index -= 1) {
+            if (/^[ \t]*`{3,}[0-9]*[ \t]*\r?$/u.test(lines[index] ?? "")) {
+                const kept = lines.slice(0, index).join("\n");
+                return kept === "" ? null : kept;
+            }
+        }
+        const trimmed = text.replace(/\r?\n$/u, "");
+        return trimmed === "" ? null : trimmed;
     }
     static #requiredBodyTextOf(ctx) {
         return AstBuilder.#bodyTextOf(ctx) ?? "";
     }
-    static #splitDelimiter(headingText, op) {
-        const marker = op === "PLAN" ? "## " : "### ";
-        return headingText.slice(marker.length + op.length);
-    }
     static #isDigit(c) {
         return c !== undefined && c >= "0" && c <= "9";
     }
@@ -547,7 +668,12 @@ export default class AstBuilder {
             return null;
         const target = PathSyntax.unescapeTarget(raw);
         if (!AstBuilder.#SCHEME_PATTERN.test(target)) {
-            return { kind: "local", raw: target };
+            // {§local-path-fragment} — `#channel` after a bare path is the channel, exactly as on a
+            // URL; a spelling that opens with `#` names no path, so it stays whole.
+            const hash = target.indexOf("#");
+            if (hash < 1)
+                return { kind: "local", raw: target };
+            return { kind: "local", raw: target.slice(0, hash), fragment: target.slice(hash + 1) };
         }
         const protectedTarget = AstBuilder.#protectPathBraces(target);
         let url;
@@ -621,7 +747,7 @@ export default class AstBuilder {
         const raw = body.replace(/(?:\r\n|\r|\n)$/u, "");
         const lineCount = raw.split(/\r\n|\r|\n/u).length;
         if (lineCount !== 1) {
-            throw new PlurnkParseError(pos.line, pos.column, "visitor", `Matcher body has ${lineCount} lines; expected 1.`);
+            throw new PlurnkParseError(pos.line, pos.column, "visitor", `Matcher has ${lineCount} lines; expected 1.`);
         }
         if (raw.startsWith("//")) {
             try {
@@ -632,12 +758,24 @@ export default class AstBuilder {
             }
             return { dialect: "xpath", raw };
         }
+        // {§naked-pattern} — a matcher opening with `^` is a regex written without slashes or flags.
+        if (raw.startsWith("^")) {
+            const inline = AstBuilder.#liftInlineFlags(raw.slice(1), "", pos);
+            const pattern = `^${inline.pattern}`;
+            try {
+                new RegExp(pattern, inline.flags);
+            }
+            catch (e) {
+                throw new PlurnkParseError(pos.line, pos.column, "visitor", `pattern leads with \`^\` but is not a valid regex - ${AstBuilder.#detail(e)}`);
+            }
+            return { dialect: "regex", raw, pattern, flags: inline.flags };
+        }
         if (raw.startsWith("/")) {
-            const regex = AstBuilder.#tryParseSlashRegex(raw);
+            const regex = AstBuilder.#tryParseSlashRegex(raw, pos);
             if (regex.ok)
                 return { dialect: "regex", raw, pattern: regex.pattern, flags: regex.flags };
-            if (regex.reason === "invalid" && /^[\t ]/u.test(regex.flags)) {
-                throw new PlurnkParseError(pos.line, pos.column, "visitor", "Regex matcher has trailing text after its closing `/`; operation modifiers precede the line ending, and the matcher occupies the next line: `### FIND0 (path) <scope>` above, `/pattern/` below.");
+            if (regex.reason === "trailing") {
+                throw new PlurnkParseError(pos.line, pos.column, "visitor", "Regex matcher has trailing text after `/pattern/flags`.");
             }
             const slashRecovery = regex.reason === "invalid"
                 && regex.detail.includes("Invalid flags supplied")
@@ -662,7 +800,7 @@ export default class AstBuilder {
             return { dialect: "jsonpath", raw };
         }
         if (raw.startsWith("~"))
-            return { dialect: "semantic", raw };
+            return { dialect: "fts", raw };
         if (raw.startsWith("&")) {
             if (!AstBuilder.#GRAPH_MATCHER.test(raw)) {
                 throw new PlurnkParseError(pos.line, pos.column, "visitor", "Malformed graph matcher; expected `&symbol`, `&<symbol`, or `&>symbol`.");
@@ -677,7 +815,18 @@ export default class AstBuilder {
     // Splits an ECMAScript `/pattern/flags` literal. Backslash escapes and character
     // classes keep a slash inside the pattern; the first unescaped slash outside a
     // class closes it. The native constructor owns pattern and flag validity.
-    static #tryParseSlashRegex(raw) {
+    // {§inline-flag-tolerance} — a leading PCRE inline modifier such as `(?i)` is the pretrained
+    // spelling of a flag; ECMAScript refuses the group, so it is lifted into the flags with one
+    // advisory rather than refused.
+    static #liftInlineFlags(pattern, flags, pos) {
+        const inline = /^\(\?([ims]+)\)/u.exec(pattern);
+        if (inline === null)
+            return { pattern, flags };
+        const lifted = [...new Set([...flags, ...inline[1]])].join("");
+        AstBuilder.#advisories.push(new PlurnkParseError(pos.line, pos.column, "parser", `\`${inline[0]}\` was read as the \`${inline[1]}\` flag; an ECMAScript regex takes its flags after the closing \`/\`.`, "warning"));
+        return { pattern: pattern.slice(inline[0].length), flags: lifted };
+    }
+    static #tryParseSlashRegex(raw, pos) {
         let i = 1;
         let inClass = false;
         while (i < raw.length) {
@@ -701,14 +850,18 @@ export default class AstBuilder {
         }
         if (i >= raw.length)
             return { ok: false, reason: "unclosed" };
-        const pattern = raw.slice(1, i);
-        const flags = raw.slice(i + 1);
+        const authored = raw.slice(i + 1);
+        const trailing = /^([A-Za-z]*)[\t ]/u.exec(authored);
+        const inline = AstBuilder.#liftInlineFlags(raw.slice(1, i), trailing?.[1] ?? authored, pos);
+        const { pattern, flags } = inline;
         try {
             new RegExp(pattern, flags);
         }
         catch (e) {
             return { ok: false, reason: "invalid", detail: AstBuilder.#detail(e), flags };
         }
+        if (trailing !== null)
+            return { ok: false, reason: "trailing" };
         return { ok: true, pattern, flags };
     }
     static #parseSendBody(raw) {