@plurnk/plurnk-grammar 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@plurnk/plurnk-grammar",
+  "version": "0.1.0",
+  "description": "ANTLR4 grammar for the Plurnk LLM agent protocol",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=23.6"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "plurnk": "./bin/plurnk.ts"
+  },
+  "files": [
+    "bin/plurnk.ts",
+    "src/*.ts",
+    "src/generated/*.ts",
+    "SPEC.md",
+    "plurnk.md"
+  ],
+  "scripts": {
+    "build:grammar": "antlr-ng -D language=TypeScript -o src/generated --generate-visitor true --generate-listener false plurnkLexer.g4 plurnkParser.g4 && node scriptify/fix-generated-imports.ts",
+    "antlr:tokens": "testrig src/generated/plurnk document --tokens",
+    "antlr:trace": "testrig src/generated/plurnk document --trace",
+    "antlr:parse": "testrig src/generated/plurnk document --tree",
+    "test:lint": "tsc --noEmit",
+    "test:unit": "node --test test/unit/*.test.ts",
+    "test:intg": "node --test test/integration/*.test.ts",
+    "test:demo": "node --test test/demo/*.test.ts",
+    "test:all": "npm run test:lint && npm run test:unit && npm run test:intg && npm run test:demo",
+    "prepublishOnly": "npm run build:grammar && npm run test:all"
+  },
+  "dependencies": {
+    "antlr4ng": "^3.0.0",
+    "jsonpath-plus": "^10.4.0",
+    "xpath": "^0.0.34"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "antlr-ng": "^1.0.10",
+    "typescript": "^6.0.3"
+  }
+}

package/plurnk.md

@@ -0,0 +1,116 @@
+# Plurnk System Grammar
+
+YOU MUST ONLY use the HEREDOC-inspired Plurnk Operations (FIND|READ|EDIT|COPY|MOVE|SHOW|HIDE|SEND|EXEC).
+
+## Syntax
+
+```
+<<OPsuffix[signal]?(path)?<L>?:body?:OPsuffix
+```
+
+Slot order is fixed. Slots between `<<OPsuffix` and `:body:` are all optional. `:body:` fences are required (use `::` when body is empty). Close tag's `OPsuffix` must character-match the open.
+
+## Operations
+
+| OP   | `[signal]`    | `(path)` | `<L>`            | body                     |
+|------|---------------|----------|------------------|--------------------------|
+| FIND | filter tags   | required | results `N-M`    | matcher                  |
+| READ | filter tags   | required | lines `N-M`      | matcher                  |
+| EDIT | tags          | required | lines `N-M`      | content (empty = clear)  |
+| COPY | apply tags    | required | lines `N-M`      | destination URI          |
+| MOVE | apply tags    | required | lines `N-M`      | destination URI          |
+| SHOW | filter tags   | required | results `N-M`    | matcher                  |
+| HIDE | filter tags   | required | results `N-M`    | matcher                  |
+| SEND | HTTP status   | optional | —                | message (JSON for data)  |
+| EXEC | Runtime Tag   | required | —                | command or code          |
+
+SEND signal is a single integer. EXEC signal is a single Runtime Tag (`sh`, `node`, `python`, etc.). All other signals are CSV.
+
+## `<L>`
+
+`<N>` selects position N. `<N-M>` selects the inclusive range N-M. N and M are signed integers. Sentinels: `<0>` before position 1 (prepend), `<-1>` after the last position (append). Range example: `<-3--1>` is positions -3..-1.
+
+## Body matcher dispatch (FIND, READ, SHOW, HIDE)
+
+| leading prefix | dialect  | form                  |
+|----------------|----------|-----------------------|
+| `//`           | xpath    | `//selector`          |
+| `/`            | regex    | `/pattern/[igmsu]?`   |
+| `$`            | jsonpath | `$.field`             |
+| otherwise      | glob     | `pattern`             |
+
+Escape `/` inside a regex pattern as `\/`. XPath body begins with `//`.
+
+## Paths
+
+URI-shaped: `[scheme://]rest`.
+
+* Bare paths (no scheme) default to local relative project file paths.
+* Glob metacharacters (`*`, `**`, `?`, `[...]`) are allowed in path segments.
+
+Internal schemes:
+
+- `unknown://` — pending / open questions.
+- `known://` — knowledgebase entries.
+- `skill://` — available skill entries.
+- `log://<loop>/<turn>/<action>/...` — event log.
+- `stream://` — live data streams.
+
+## Context
+
+The agent maintains two contexts:
+
+- **Index** — entries listed in the active index.
+- **Archive** — entries archived; out of working memory (HIDE), but promotable (SHOW) by path or pattern lookup.
+
+`SHOW` promotes matching entries to the active index. `HIDE` demotes to archive. The model curates its own working memory by issuing these between substantive operations. New entries created via `EDIT` enter active index by default.
+
+## Suffix
+
+For nested Plurnk Operations inside a body (recording, quoting, demonstrating), the outer statement uses an optional non-empty suffix so its close tag is distinct from inner close tags. Empty suffix is default. The suffix character class is `[A-Za-z0-9_]`.
+
+```
+<<EDITouter(known://demo):
+quoted: <<EDIT(known://inner):hello:EDIT
+:EDITouter
+```
+
+## Examples
+
+```
+<<FIND(config/**/*.xml)://user[@role='admin']:FIND
+<<READ(lang/??.json):$.greeting:READ
+<<READ(https://en.wikipedia.org/wiki/Paris)<426-465>::READ
+<<EDIT[philosophy,existentialism](known://philosophy/existentialism/meaning):The meaning of life is 42:EDIT
+<<EDIT[france,geography](unknown://countries/france/capital):What is the capital of France?:EDIT
+<<EDIT[plan,france,task](known://plan):
+- [ ] Decompose prompt into unknowns
+- [ ] Discover capital of France
+- [ ] Deliver
+:EDIT
+<<EDIT(known://plan)<2>:- [x] Discover capital of France:EDIT
+<<EDIT(known://countries/france/capital)<-1>:[Wikipedia: Paris](https://en.wikipedia.org/wiki/Paris):EDIT
+<<EDIT(known://countries/france/capital)::EDIT
+<<COPY[archive,2026-05-14](known://draft):known://archive/2026-05-14/draft:COPY
+<<MOVE(known://draft):known://final/answer:MOVE
+<<SHOW[france](known://countries/**):Paris*:SHOW
+<<HIDE(log://**/get)<101-200>::HIDE
+<<FIND(log://**/error):/timeout|deadline exceeded/i:FIND
+<<EXEC[node](./):
+const sum = [1, 2, 3].reduce((a, b) => a + b, 0);
+console.log(sum);
+:EXEC
+<<SEND[102]:decomposed prompt; plan initialized:SEND
+<<SEND[200]:{"answer":"Paris","confidence":0.95}:SEND
+```
+
+## Invariants
+
+- `<<OPsuffix` and `:OPsuffix` MUST character-match.
+- `:body:` fences MUST be present (use `::` for empty body).
+- `:` and `OPsuffix` in the close tag MUST be character-adjacent.
+- Header slot order MUST be `[signal]` → `(path)` → `<L>` → `:`.
+- Inside `[…]`, `(…)`, `<…>`, between `OP` and `suffix` — no whitespace.
+- Between header elements — whitespace is non-significant.
+- Inside body — whitespace and newlines are preserved verbatim.
+- A body containing `:OPkeyword` MUST use a suffix on the enclosing statement.

package/src/ast.ts

@@ -0,0 +1,348 @@
+import type { StatementContext } from "./generated/plurnkParser.ts";
+import { PlurnkParseError } from "./errors.ts";
+import * as xpath from "xpath";
+import { JSONPath } from "jsonpath-plus";
+
+// The xpath package's .d.ts omits its `parse` function (it only types the
+// document-evaluation surface). Augment the type here — `parse` is exported
+// at runtime and throws on a syntactically invalid XPath 1.0 expression.
+declare module "xpath" {
+    export function parse(expression: string): unknown;
+}
+
+export type Position = { line: number; column: number };
+
+export type PlurnkOp =
+    | "FIND"
+    | "READ"
+    | "EDIT"
+    | "COPY"
+    | "MOVE"
+    | "SHOW"
+    | "HIDE"
+    | "SEND"
+    | "EXEC";
+
+export interface LineMarker {
+    /** First position. Can be negative (sentinels: 0 = prepend anchor, -1 = append anchor). */
+    first: number;
+    /** Second position when the marker is a range `<N-M>`; null when single `<N>`. */
+    last: number | null;
+}
+
+/**
+ * Parsed path slot. A path is either a local source path (no scheme — filesystem-style)
+ * or a URL with a recognized `scheme://` prefix. URLs are fully decomposed via WHATWG URL;
+ * locals are kept as raw strings (resolution is the runtime's job).
+ *
+ * Subdomain / registrable-domain splitting requires the public suffix list (PSL) and is
+ * deferred to the runtime — `hostname` is the full host string as parsed by URL.
+ */
+export type ParsedPath = LocalPath | UrlPath;
+
+export interface LocalPath {
+    kind: "local";
+    raw: string;
+}
+
+export interface UrlPath {
+    kind: "url";
+    raw: string;
+    /** Scheme without trailing `:` — `"https"`, `"known"`, etc. */
+    scheme: string;
+    username: string | null;
+    password: string | null;
+    /** Full hostname as parsed by URL. For custom schemes (`known://draft`), this is the first authority segment. */
+    hostname: string | null;
+    port: number | null;
+    /** Path component (everything after the authority, before `?` or `#`). May be empty. */
+    pathname: string;
+    /** Query parameters. Multi-value keys are arrays. Empty record if no query. */
+    search: Record<string, string | string[]>;
+    /** Fragment (after `#`), with the `#` stripped; null if no fragment. */
+    fragment: string | null;
+}
+
+interface StatementBase<S> {
+    suffix: string;
+    signal: S | null;
+    path: ParsedPath | null;
+    lineMarker: LineMarker | null;
+    position: Position;
+}
+
+/**
+ * Typed body for FIND/READ/SHOW/HIDE pattern matchers. The dialect is detected
+ * by the body's leading characters and validated by the Visitor — `xpath` via
+ * `xpath.parse()`, `regex` via `new RegExp()`, `jsonpath` via `jsonpath-plus`,
+ * `glob` is pass-through.
+ */
+export type MatcherBody =
+    | { dialect: "xpath"; raw: string }
+    | { dialect: "regex"; raw: string; pattern: string; flags: string; regexp: RegExp }
+    | { dialect: "jsonpath"; raw: string }
+    | { dialect: "glob"; raw: string };
+
+/**
+ * Typed body for SEND. The raw payload is always present; `json` holds the
+ * `JSON.parse(raw)` result if the body is valid JSON, null otherwise.
+ * Best-effort: plain-text bodies (`<<SEND[200]:Paris:SEND`) leave json=null.
+ */
+export interface SendBody {
+    raw: string;
+    json: unknown | null;
+}
+
+/** Matcher OPs: body is a typed pattern matcher (or null if no body). */
+export interface FindStatement extends StatementBase<string[]> { op: "FIND"; body: MatcherBody | null; }
+export interface ReadStatement extends StatementBase<string[]> { op: "READ"; body: MatcherBody | null; }
+export interface ShowStatement extends StatementBase<string[]> { op: "SHOW"; body: MatcherBody | null; }
+export interface HideStatement extends StatementBase<string[]> { op: "HIDE"; body: MatcherBody | null; }
+
+/** EDIT body is arbitrary content (markdown, code, JSON, prose) — kept raw. */
+export interface EditStatement extends StatementBase<string[]> { op: "EDIT"; body: string | null; }
+
+/** COPY/MOVE body is the destination URI, parsed identically to the path slot. */
+export interface CopyStatement extends StatementBase<string[]> { op: "COPY"; body: ParsedPath | null; }
+export interface MoveStatement extends StatementBase<string[]> { op: "MOVE"; body: ParsedPath | null; }
+
+/** SEND body: raw plus best-effort JSON parse. */
+export interface SendStatement extends StatementBase<number> { op: "SEND"; body: SendBody | null; }
+
+/** EXEC body is a command or code snippet — kept raw. */
+export interface ExecStatement extends StatementBase<string> { op: "EXEC"; body: string | null; }
+
+export type PlurnkStatement =
+    | FindStatement
+    | ReadStatement
+    | EditStatement
+    | CopyStatement
+    | MoveStatement
+    | ShowStatement
+    | HideStatement
+    | SendStatement
+    | ExecStatement;
+
+const OPS: readonly PlurnkOp[] = [
+    "FIND", "READ", "EDIT", "COPY", "MOVE", "SHOW", "HIDE", "SEND", "EXEC",
+];
+
+const splitOpAndSuffix = (openTagText: string): { op: PlurnkOp; suffix: string } => {
+    const stripped = openTagText.slice(2);
+    for (const op of OPS) {
+        if (stripped.startsWith(op)) {
+            return { op, suffix: stripped.slice(op.length) };
+        }
+    }
+    throw new Error(`unrecognized OP in open tag: ${openTagText}`);
+};
+
+const isDigit = (c: string | undefined): boolean => c !== undefined && c >= "0" && c <= "9";
+
+const parseLineMarker = (text: string): LineMarker => {
+    const inner = text.slice(1, -1);
+    let i = 0;
+    if (inner[i] === "-") i++;
+    while (isDigit(inner[i])) i++;
+    const first = Number.parseInt(inner.slice(0, i), 10);
+    if (i >= inner.length) return { first, last: null };
+    i++;
+    const last = Number.parseInt(inner.slice(i), 10);
+    return { first, last };
+};
+
+const coerceSendSignal = (raw: string[] | null, pos: Position): number | null => {
+    if (raw === null) return null;
+    if (raw.length === 0) {
+        throw new PlurnkParseError(pos.line, pos.column, "visitor", "SEND signal slot is present but empty");
+    }
+    if (raw.length > 1) {
+        throw new PlurnkParseError(pos.line, pos.column, "visitor", `SEND signal must be a single integer; got ${raw.length} values`);
+    }
+    const text = raw[0]!;
+    if (!/^-?\d+$/.test(text)) {
+        throw new PlurnkParseError(pos.line, pos.column, "visitor", `SEND signal must be an integer; got "${text}"`);
+    }
+    return Number.parseInt(text, 10);
+};
+
+const coerceExecSignal = (raw: string[] | null, pos: Position): string | null => {
+    if (raw === null) return null;
+    if (raw.length === 0) {
+        throw new PlurnkParseError(pos.line, pos.column, "visitor", "EXEC signal slot is present but empty");
+    }
+    if (raw.length > 1) {
+        throw new PlurnkParseError(pos.line, pos.column, "visitor", `EXEC signal must be a single runtime tag; got ${raw.length} values`);
+    }
+    return raw[0]!;
+};
+
+const SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+const parsePath = (raw: string, pos: Position): ParsedPath | null => {
+    if (raw.length === 0) return null;
+    if (!SCHEME_PATTERN.test(raw)) {
+        return { kind: "local", raw };
+    }
+    let url: URL;
+    try {
+        url = new URL(raw);
+    } catch (e: any) {
+        throw new PlurnkParseError(pos.line, pos.column, "visitor", `invalid URI in path: ${e?.message ?? raw}`);
+    }
+    const search: Record<string, string | string[]> = {};
+    for (const [key, value] of url.searchParams) {
+        const existing = search[key];
+        if (existing === undefined) {
+            search[key] = value;
+        } else if (Array.isArray(existing)) {
+            existing.push(value);
+        } else {
+            search[key] = [existing, value];
+        }
+    }
+    return {
+        kind: "url",
+        raw,
+        scheme: url.protocol.replace(/:$/, ""),
+        username: url.username || null,
+        password: url.password || null,
+        hostname: url.hostname || null,
+        port: url.port ? Number.parseInt(url.port, 10) : null,
+        pathname: url.pathname,
+        search,
+        fragment: url.hash ? url.hash.slice(1) : null,
+    };
+};
+
+type MatcherDialect = "xpath" | "regex" | "jsonpath" | "glob";
+
+const detectMatcherDialect = (body: string): MatcherDialect => {
+    if (body.startsWith("//")) return "xpath";
+    if (body.startsWith("/")) return "regex";
+    if (body.startsWith("$")) return "jsonpath";
+    return "glob";
+};
+
+const parseRegexLiteral = (body: string, pos: Position): { pattern: string; flags: string } => {
+    let i = 1;
+    while (i < body.length) {
+        if (body[i] === "\\") { i += 2; continue; }
+        if (body[i] === "/") break;
+        i++;
+    }
+    if (i >= body.length) {
+        throw new PlurnkParseError(pos.line, pos.column, "visitor", "regex body missing closing /");
+    }
+    return { pattern: body.slice(1, i), flags: body.slice(i + 1) };
+};
+
+const parseMatcherBody = (body: string, pos: Position): MatcherBody => {
+    const dialect = detectMatcherDialect(body);
+    if (dialect === "regex") {
+        const { pattern, flags } = parseRegexLiteral(body, pos);
+        let regexp: RegExp;
+        try {
+            regexp = new RegExp(pattern, flags);
+        } catch (e: any) {
+            throw new PlurnkParseError(pos.line, pos.column, "visitor", `invalid regex: ${e?.message ?? body}`);
+        }
+        return { dialect: "regex", raw: body, pattern, flags, regexp };
+    }
+    if (dialect === "xpath") {
+        try {
+            xpath.parse(body);
+        } catch (e: any) {
+            throw new PlurnkParseError(pos.line, pos.column, "visitor", `invalid xpath: ${e?.message ?? body}`);
+        }
+        return { dialect: "xpath", raw: body };
+    }
+    if (dialect === "jsonpath") {
+        try {
+            JSONPath({ path: body, json: {} });
+        } catch (e: any) {
+            throw new PlurnkParseError(pos.line, pos.column, "visitor", `invalid jsonpath: ${e?.message ?? body}`);
+        }
+        return { dialect: "jsonpath", raw: body };
+    }
+    return { dialect: "glob", raw: body };
+};
+
+const parseSendBody = (raw: string): SendBody => {
+    let json: unknown | null = null;
+    try { json = JSON.parse(raw); } catch { /* best-effort: not all SEND bodies are JSON */ }
+    return { raw, json };
+};
+
+export const buildStatement = (ctx: StatementContext): PlurnkStatement => {
+    const openTagCtx = ctx.openTag();
+    const openTagText = openTagCtx.getText();
+    const { op, suffix } = splitOpAndSuffix(openTagText);
+
+    const start = ctx.start ?? openTagCtx.start;
+    const position: Position = {
+        line: start?.line ?? 0,
+        column: start?.column ?? 0,
+    };
+
+    const signalCtx = ctx.signal();
+    let rawSignal: string[] | null = null;
+    if (signalCtx) {
+        const text = signalCtx.SIGNAL_TEXT()?.getText() ?? "";
+        rawSignal = text.length > 0 ? text.split(",") : [];
+    }
+
+    const pathCtx = ctx.path();
+    let rawPath: string | null = null;
+    if (pathCtx) {
+        rawPath = pathCtx.PATH_TEXT()?.getText() ?? "";
+    }
+    const path: ParsedPath | null = rawPath !== null ? parsePath(rawPath, position) : null;
+
+    const lineMarkerCtx = ctx.lineMarker();
+    let lineMarker: LineMarker | null = null;
+    if (lineMarkerCtx) {
+        const text = lineMarkerCtx.L_MARKER()?.getText() ?? "";
+        lineMarker = parseLineMarker(text);
+    }
+
+    const bodyCtx = ctx.body();
+    const rawBody: string | null = bodyCtx ? bodyCtx.getText() : null;
+
+    // Per-OP signal coercion.
+    let signal: string[] | number | string | null;
+    switch (op) {
+        case "SEND":
+            signal = coerceSendSignal(rawSignal, position);
+            break;
+        case "EXEC":
+            signal = coerceExecSignal(rawSignal, position);
+            break;
+        default:
+            signal = rawSignal;
+    }
+
+    // Per-OP body shaping.
+    let body: MatcherBody | ParsedPath | SendBody | string | null;
+    switch (op) {
+        case "FIND":
+        case "READ":
+        case "SHOW":
+        case "HIDE":
+            body = rawBody !== null ? parseMatcherBody(rawBody, position) : null;
+            break;
+        case "COPY":
+        case "MOVE":
+            body = rawBody !== null ? parsePath(rawBody, position) : null;
+            break;
+        case "SEND":
+            body = rawBody !== null ? parseSendBody(rawBody) : null;
+            break;
+        case "EDIT":
+        case "EXEC":
+            body = rawBody;
+            break;
+    }
+
+    return { op, suffix, signal, path, lineMarker, body, position } as PlurnkStatement;
+};

package/src/error-strategy.ts

@@ -0,0 +1,140 @@
+import {
+    DefaultErrorStrategy,
+    InputMismatchException,
+    NoViableAltException,
+    Token,
+    type Parser,
+    type RecognitionException,
+} from "antlr4ng";
+import { plurnkParser } from "./generated/plurnkParser.ts";
+import { plurnkLexer } from "./generated/plurnkLexer.ts";
+
+const LEXER_MODE_CONTEXT: Record<string, string> = {
+    DEFAULT_MODE: "between statements",
+    OPENED: "in statement header",
+    POST_SIGNAL: "in statement header",
+    POST_PATH: "in statement header",
+    POST_L: "in statement header",
+    SIGNAL: "in signal",
+    PATH: "in path",
+    BODY: "in body",
+};
+
+const OFFENDING_CHAR_RE = /at: '([^']*)'$/;
+
+const extractOffendingChar = (msg: string): string => {
+    const m = OFFENDING_CHAR_RE.exec(msg);
+    if (!m) return "input";
+    const text = m[1];
+    return text === "" ? "end of input" : `'${text}'`;
+};
+
+export const translateLexerMessage = (lexer: plurnkLexer, originalMsg: string): string => {
+    const modeName = lexer.modeNames[lexer.mode] ?? "DEFAULT_MODE";
+    const context = LEXER_MODE_CONTEXT[modeName] ?? "between statements";
+    const ch = extractOffendingChar(originalMsg);
+    return `unrecognized character ${ch} ${context}`;
+};
+
+const SLOT_BY_TOKEN: Record<number, string> = {
+    [plurnkParser.OPEN_FIND]: "open tag",
+    [plurnkParser.OPEN_READ]: "open tag",
+    [plurnkParser.OPEN_EDIT]: "open tag",
+    [plurnkParser.OPEN_COPY]: "open tag",
+    [plurnkParser.OPEN_MOVE]: "open tag",
+    [plurnkParser.OPEN_SHOW]: "open tag",
+    [plurnkParser.OPEN_HIDE]: "open tag",
+    [plurnkParser.OPEN_SEND]: "open tag",
+    [plurnkParser.OPEN_EXEC]: "open tag",
+    [plurnkParser.LBRACKET]: "'['",
+    [plurnkParser.RBRACKET]: "']'",
+    [plurnkParser.LPAREN]: "'('",
+    [plurnkParser.RPAREN]: "')'",
+    [plurnkParser.L_MARKER]: "line marker",
+    [plurnkParser.COLON]: "':'",
+    [plurnkParser.SIGNAL_TEXT]: "signal content",
+    [plurnkParser.PATH_TEXT]: "path content",
+    [plurnkParser.BODY_TEXT]: "body content",
+    [plurnkParser.CLOSE_TAG]: "close tag",
+    [plurnkParser.TEXT]: "text between statements",
+};
+
+const describeToken = (tok: Token | null): string => {
+    if (!tok || tok.type === Token.EOF) return "end of input";
+    const slot = SLOT_BY_TOKEN[tok.type];
+    if (slot) return slot;
+    const text = tok.text ?? "";
+    return text.length > 0 ? `'${text}'` : "input";
+};
+
+const describeExpected = (
+    _parser: Parser,
+    e: RecognitionException,
+): string | null => {
+    const expected = e.getExpectedTokens();
+    if (!expected) return null;
+    const types: number[] = expected.toArray();
+    if (types.length === 0) return null;
+    const names = types
+        .map((t) => SLOT_BY_TOKEN[t])
+        .filter((s): s is string => Boolean(s));
+    if (names.length === 0) return null;
+    if (names.length === 1) return names[0];
+    if (names.length === 2) return `${names[0]} or ${names[1]}`;
+    return `${names.slice(0, -1).join(", ")}, or ${names[names.length - 1]}`;
+};
+
+export class PlurnkErrorStrategy extends DefaultErrorStrategy {
+    public override reportError(recognizer: Parser, e: RecognitionException): void {
+        if (this.inErrorRecoveryMode(recognizer)) return;
+        this.beginErrorCondition(recognizer);
+
+        const got = describeToken(e.offendingToken);
+        const expected = describeExpected(recognizer, e);
+
+        let msg: string;
+        if (e instanceof InputMismatchException || e instanceof NoViableAltException) {
+            msg = expected ? `unexpected ${got}; expected ${expected}` : `unexpected ${got}`;
+        } else {
+            msg = `unexpected ${got}`;
+        }
+
+        recognizer.notifyErrorListeners(msg, e.offendingToken, e);
+    }
+
+    public override reportMissingToken(recognizer: Parser): void {
+        if (this.inErrorRecoveryMode(recognizer)) return;
+        this.beginErrorCondition(recognizer);
+        const tok = recognizer.getCurrentToken();
+        const expectedTokens = this.getExpectedTokens(recognizer);
+        const expectedNames = expectedTokens
+            .toArray()
+            .map((t) => SLOT_BY_TOKEN[t])
+            .filter((s): s is string => Boolean(s));
+        const expected = expectedNames.length > 0
+            ? (expectedNames.length === 1 ? expectedNames[0] : expectedNames.join(" or "))
+            : "more input";
+        const got = describeToken(tok);
+        const msg = `expected ${expected}; got ${got}`;
+        recognizer.notifyErrorListeners(msg, tok, null);
+    }
+
+    public override reportUnwantedToken(recognizer: Parser): void {
+        if (this.inErrorRecoveryMode(recognizer)) return;
+        this.beginErrorCondition(recognizer);
+        const tok = recognizer.getCurrentToken();
+        const got = describeToken(tok);
+        const expectedTokens = this.getExpectedTokens(recognizer);
+        const expectedNames = expectedTokens
+            .toArray()
+            .map((t) => SLOT_BY_TOKEN[t])
+            .filter((s): s is string => Boolean(s));
+        const expected = expectedNames.length > 0
+            ? (expectedNames.length === 1 ? expectedNames[0] : expectedNames.join(" or "))
+            : null;
+        const msg = expected
+            ? `unexpected ${got}; expected ${expected}`
+            : `unexpected ${got}`;
+        recognizer.notifyErrorListeners(msg, tok, null);
+    }
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+export type ErrorSource = "lexer" | "parser" | "visitor";
+
+export class PlurnkParseError extends Error {
+    readonly line: number;
+    readonly column: number;
+    readonly source: ErrorSource;
+
+    constructor(line: number, column: number, source: ErrorSource, message: string) {
+        super(`Plurnk ${source} error at ${line}:${column} — ${message}`);
+        this.name = "PlurnkParseError";
+        this.line = line;
+        this.column = column;
+        this.source = source;
+    }
+
+    /** JSON serialization — `JSON.stringify` picks this up automatically. */
+    toJSON(): { line: number; column: number; source: ErrorSource; message: string } {
+        return {
+            line: this.line,
+            column: this.column,
+            source: this.source,
+            message: this.message,
+        };
+    }
+}