@sdxc/spec 0.0.0-pre.1

package/dist/expectation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Assertion semantics: the two `expect` forms (value truthiness/equality and
+ * observable tools) and the `eventually` retry loop. The executor drives this
+ * module through the `ExpectationHost` seam, so expression evaluation and
+ * tool dispatch stay in the executor while the assertion rules live here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { ArgumentNode, EventuallyNode, ExpectNode, ExpressionNode } from "./ast.js";
+import type { Registry, ResolvedCallable } from "./registry.js";
+import type { Span } from "./source.js";
+import type { Value } from "./values.js";
+import { SpecError } from "./errors.js";
+/** Deadline of an `eventually` block with no `within` clause, in milliseconds. */
+export declare const DEFAULT_EVENTUALLY_MS = 5000;
+/** Pause between `eventually` attempts, in milliseconds. */
+export declare const POLL_INTERVAL_MS = 100;
+/**
+ * What `expect` and `eventually` need from their caller: the enclosing scope
+ * for binding lookups, the suite's resolution table, and the executor's
+ * dispatch seam, which owns argument evaluation and the central permission gate.
+ */
+export interface ExpectationHost {
+    /** The enclosing scope, for binding lookups and ambiguity detection. */
+    scope: Map<string, Value>;
+    /** The suite's name-resolution table. */
+    registry: Registry;
+    /** Namespaces imported by the calling file, in `use` order. */
+    uses: readonly string[];
+    /** Evaluate one expression in the enclosing scope. */
+    evaluate(expression: ExpressionNode): Result<Value, SpecError>;
+    /**
+     * Invoke a resolved tool with raw argument nodes. The implementation owns
+     * argument evaluation and the runtime's central permission gate.
+     */
+    callTool(tool: Extract<ResolvedCallable, {
+        kind: "tool";
+    }>, args: ArgumentNode[], span: Span): Promise<Result<Value, SpecError>>;
+}
+/**
+ * Execute one `expect` statement. The first argument decides the form: bound
+ * and callable is `ambiguous-name`, a bound name (or literal) selects the
+ * value form, and a callable observable tool selects the observable form.
+ *
+ * @param node - The `expect` statement to execute.
+ * @param host - The executor-provided scope, registry, and dispatch seam.
+ * @returns Success when the assertion held, otherwise the structured failure.
+ */
+export declare function executeExpect(node: ExpectNode, host: ExpectationHost): Promise<Result<undefined, SpecError>>;
+/**
+ * Execute one `eventually` block: only `expect` statements and observable
+ * calls may appear, since a retried mutation is not a retried assertion. Every
+ * name resolves once before the first attempt, because `let` is banned inside the block.
+ *
+ * @param node - The `eventually` statement to execute.
+ * @param host - The executor-provided scope, registry, and dispatch seam.
+ * @returns Success once an attempt fully passed, otherwise the last failure.
+ */
+export declare function executeEventually(node: EventuallyNode, host: ExpectationHost): Promise<Result<undefined, SpecError>>;

package/dist/expectation.js

@@ -0,0 +1,222 @@
+/**
+ * Assertion semantics: the two `expect` forms (value truthiness/equality and
+ * observable tools) and the `eventually` retry loop. The executor drives this
+ * module through the `ExpectationHost` seam, so expression evaluation and
+ * tool dispatch stay in the executor while the assertion rules live here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, isSuccess, success } from "@sdxc/result";
+import { ExpectationError, ResolutionError, SpecError, ToolError } from "./errors.js";
+import { formatValue, valueEquals } from "./values.js";
+/** Deadline of an `eventually` block with no `within` clause, in milliseconds. */
+export const DEFAULT_EVENTUALLY_MS = 5000;
+/** Pause between `eventually` attempts, in milliseconds. */
+export const POLL_INTERVAL_MS = 100;
+/**
+ * Execute one `expect` statement. The first argument decides the form: bound
+ * and callable is `ambiguous-name`, a bound name (or literal) selects the
+ * value form, and a callable observable tool selects the observable form.
+ *
+ * @param node - The `expect` statement to execute.
+ * @param host - The executor-provided scope, registry, and dispatch seam.
+ * @returns Success when the assertion held, otherwise the structured failure.
+ */
+export async function executeExpect(node, host) {
+    let head = node.args[0];
+    if (head === undefined) {
+        return failure(anchor(new SpecError("usage-error", "expect needs at least one argument"), node.span));
+    }
+    let resolved = resolveExpectMode(head, host);
+    if (isFailure(resolved))
+        return resolved;
+    if (resolved.data.mode === "observable") {
+        return executeObservableExpect(node, resolved.data.tool, host);
+    }
+    return executeValueExpect(node, head, host);
+}
+/**
+ * Execute one `eventually` block: only `expect` statements and observable
+ * calls may appear, since a retried mutation is not a retried assertion. Every
+ * name resolves once before the first attempt, because `let` is banned inside the block.
+ *
+ * @param node - The `eventually` statement to execute.
+ * @param host - The executor-provided scope, registry, and dispatch seam.
+ * @returns Success once an attempt fully passed, otherwise the last failure.
+ */
+export async function executeEventually(node, host) {
+    let attempts = [];
+    for (let statement of node.block.statements) {
+        if (statement.kind === "expect") {
+            let expectNode = statement;
+            let head = expectNode.args[0];
+            if (head === undefined) {
+                return failure(anchor(new SpecError("usage-error", "expect needs at least one argument"), expectNode.span));
+            }
+            let headArgument = head;
+            let resolved = resolveExpectMode(headArgument, host);
+            if (isFailure(resolved))
+                return resolved;
+            let mode = resolved.data;
+            if (mode.mode === "observable") {
+                let tool = mode.tool;
+                attempts.push(() => executeObservableExpect(expectNode, tool, host));
+            }
+            else {
+                attempts.push(async () => executeValueExpect(expectNode, headArgument, host));
+            }
+            continue;
+        }
+        if (statement.kind === "call") {
+            let callNode = statement;
+            let resolved = host.registry.resolveCallable(callNode.target, host.uses);
+            if (isFailure(resolved))
+                return failure(anchor(resolved.error, callNode.span));
+            if (resolved.data.kind !== "tool" || resolved.data.descriptor.kind !== "observable") {
+                return failure(anchor(new SpecError("usage-error", `Only expect statements and observable calls may appear inside eventually; "${callNode.target}" is not an observable`), callNode.span));
+            }
+            let tool = resolved.data;
+            attempts.push(async () => {
+                let result = await host.callTool(tool, callNode.args, callNode.span);
+                if (isFailure(result))
+                    return failure(anchor(result.error, callNode.span));
+                /**
+                 * A bare observable is still an assertion: `false` fails the
+                 * attempt exactly as it fails the expect form of the same call.
+                 */
+                if (result.data === false) {
+                    return failure(anchor(new ExpectationError(`Expected ${qualifiedName(tool)} to hold, observed false`, true, false), callNode.span));
+                }
+                return success(undefined);
+            });
+            continue;
+        }
+        return failure(anchor(new SpecError("usage-error", `Only expect statements and observable calls may appear inside eventually; found a ${statement.kind} statement`), statement.span));
+    }
+    let deadline = Date.now() + (node.withinMs ?? DEFAULT_EVENTUALLY_MS);
+    while (true) {
+        let error = await runAttempt(attempts);
+        if (error === undefined)
+            return success(undefined);
+        if (Date.now() >= deadline)
+            return failure(anchor(error, node.span));
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+/** Run one full attempt of an `eventually` block; the first failure ends it. */
+async function runAttempt(attempts) {
+    for (let attempt of attempts) {
+        let result = await attempt();
+        if (isFailure(result))
+            return result.error;
+    }
+    return undefined;
+}
+/**
+ * Decide which `expect` form the first argument selects. Words and
+ * one-segment references are treated alike: bound and callable is ambiguous,
+ * bound alone is the value form, callable alone must be an observable tool.
+ */
+function resolveExpectMode(head, host) {
+    let name;
+    let headBinding;
+    if (head.kind === "word") {
+        name = head.word;
+        headBinding = head.word;
+    }
+    else if (head.kind === "reference") {
+        let first = head.path[0];
+        if (first === undefined) {
+            return failure(anchor(new ResolutionError("unknown-name", "expect received an empty reference"), head.span));
+        }
+        name = head.path.join(".");
+        headBinding = first;
+    }
+    else {
+        return success({ mode: "value" });
+    }
+    let bound = host.scope.has(headBinding);
+    let resolved = host.registry.resolveCallable(name, host.uses);
+    if (bound && isSuccess(resolved)) {
+        return failure(anchor(new ResolutionError("ambiguous-name", `"${name}" is both a binding and a callable; the runtime never guesses — rename the binding or qualify the tool`, [qualifiedName(resolved.data)]), head.span));
+    }
+    if (bound)
+        return success({ mode: "value" });
+    if (isSuccess(resolved)) {
+        if (resolved.data.kind !== "tool" || resolved.data.descriptor.kind !== "observable") {
+            return failure(anchor(new ToolError(`"${qualifiedName(resolved.data)}" is not an observable; only observable tools can head an expect`), head.span));
+        }
+        return success({ mode: "observable", tool: resolved.data });
+    }
+    return failure(anchor(resolved.error, head.span));
+}
+/**
+ * The value form: `expect A` asserts truthiness, `expect A B` asserts deep
+ * structural equality, anything longer is a usage error.
+ */
+function executeValueExpect(node, head, host) {
+    if (node.args.length > 2) {
+        return failure(anchor(new SpecError("usage-error", "value-form expect takes at most two arguments: a value and an optional expected value"), node.span));
+    }
+    let observed = evaluateValueArgument(head, host);
+    if (isFailure(observed))
+        return observed;
+    let expectedArgument = node.args[1];
+    if (expectedArgument === undefined) {
+        if (observed.data)
+            return success(undefined);
+        return failure(anchor(new ExpectationError(`Expected a truthy value, observed ${formatValue(observed.data)}`, undefined, observed.data), node.span));
+    }
+    let expected = evaluateValueArgument(expectedArgument, host);
+    if (isFailure(expected))
+        return expected;
+    if (valueEquals(observed.data, expected.data))
+        return success(undefined);
+    return failure(anchor(new ExpectationError(`Expected ${formatValue(expected.data)}, observed ${formatValue(observed.data)}`, expected.data, observed.data), node.span));
+}
+/**
+ * The observable form: call the tool with the remaining arguments; its own
+ * failure propagates, and a plain `false` return becomes an expectation
+ * failure.
+ */
+async function executeObservableExpect(node, tool, host) {
+    let result = await host.callTool(tool, node.args.slice(1), node.span);
+    if (isFailure(result))
+        return failure(anchor(result.error, node.span));
+    if (result.data === false) {
+        return failure(anchor(new ExpectationError(`Expected ${qualifiedName(tool)} to hold, observed false`, true, false), node.span));
+    }
+    return success(undefined);
+}
+/**
+ * Evaluate one argument as a value: expressions evaluate in the scope, and a
+ * bare word reads the binding of the same spelling — words are only symbolic
+ * when a tool receives them.
+ */
+function evaluateValueArgument(argument, host) {
+    if (argument.kind !== "word")
+        return host.evaluate(argument);
+    if (!host.scope.has(argument.word)) {
+        return failure(anchor(new ResolutionError("unknown-name", `Unknown name "${argument.word}" — nothing is bound under it`), argument.span));
+    }
+    return success(host.scope.get(argument.word) ?? null);
+}
+/** The fully qualified spelling of a resolved callable, for diagnostics. */
+function qualifiedName(callable) {
+    if (callable.kind === "tool")
+        return `${callable.namespace}.${callable.descriptor.name}`;
+    return callable.command.name;
+}
+/** Stamp a span onto an error that does not carry one yet. */
+function anchor(error, span) {
+    if (error.span === undefined)
+        error.span = span;
+    return error;
+}
+/** Resolve after the given pause, for the `eventually` poll loop. */
+function sleep(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(() => resolve(undefined), milliseconds);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Public surface of `@sdxc/spec`, the executable specification runtime
+ * consumed by the `spec` CLI and available to programmatic embedders. This
+ * entry point assumes a Bun or Node process because it reaches the
+ * filesystem and spawns processes; a runtime without those imports
+ * `@sdxc/spec/workers` for the same language core with a smaller capability set.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type * from "./ast.js";
+export { BUILTIN_NAMESPACES, createBuiltinPlugins } from "./builtins.js";
+export type { BuiltinNamespace } from "./builtins.js";
+export type { Sink, SuiteResult, TestResult, TestStatus } from "./diagnostics.js";
+export { ExpectationError, LoadError, ParseError, PermissionDeniedError, ResolutionError, SpecError, ToolError, WorkspaceEscapeError, } from "./errors.js";
+export type { DiagnosticCode } from "./errors.js";
+export { executeTest } from "./executor.js";
+export type { ExecutionContext } from "./executor.js";
+export { lex } from "./lexer.js";
+export { loadSuite } from "./loader.js";
+export { parse } from "./parser.js";
+export { createPermissionSet, parseGrants } from "./permissions.js";
+export type { Grant, Grants, PermissionKind, PermissionSet } from "./permissions.js";
+export type { Plugin, ToolContext, ToolDescriptor, ToolParam } from "./plugin.js";
+export { createBrowserPlugin } from "./plugins/browser.js";
+export { createCliPlugin } from "./plugins/cli.js";
+export { createDbPlugin } from "./plugins/db.js";
+export { createEnvPlugin } from "./plugins/env.js";
+export { createFsPlugin } from "./plugins/fs.js";
+export { createHttpPlugin } from "./plugins/http.js";
+export { createJwtPlugin } from "./plugins/jwt.js";
+export { createUrlPlugin } from "./plugins/url.js";
+export { createRegistry } from "./registry.js";
+export type { Registry, ResolvedCallable } from "./registry.js";
+export { reportFatal, reportSuite } from "./reporter.js";
+export { runTests } from "./run.js";
+export type { RunTestsOptions, WorkspaceFactory } from "./run.js";
+export { runSuite } from "./runner.js";
+export type { RunOptions } from "./runner.js";
+export { positionAt } from "./source.js";
+export type { Position, SourceFile, Span } from "./source.js";
+export { loadSources } from "./sources.js";
+export type { LoadedSuite, SpecSource } from "./sources.js";
+export type { Token, TokenKind } from "./tokens.js";
+export { KEYWORDS } from "./tokens.js";
+export { connectStdioPlugin, servePlugin } from "./transport-stdio.js";
+export { formatValue, valueEquals } from "./values.js";
+export type { ToolArg, Value, ValueObject } from "./values.js";
+export { createWorkspace } from "./workspace.js";
+export type { Workspace } from "./workspace.js";
+export { createNoFilesystemWorkspace } from "./workspace-none.js";

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * Public surface of `@sdxc/spec`, the executable specification runtime
+ * consumed by the `spec` CLI and available to programmatic embedders. This
+ * entry point assumes a Bun or Node process because it reaches the
+ * filesystem and spawns processes; a runtime without those imports
+ * `@sdxc/spec/workers` for the same language core with a smaller capability set.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { BUILTIN_NAMESPACES, createBuiltinPlugins } from "./builtins.js";
+export { ExpectationError, LoadError, ParseError, PermissionDeniedError, ResolutionError, SpecError, ToolError, WorkspaceEscapeError, } from "./errors.js";
+export { executeTest } from "./executor.js";
+export { lex } from "./lexer.js";
+export { loadSuite } from "./loader.js";
+export { parse } from "./parser.js";
+export { createPermissionSet, parseGrants } from "./permissions.js";
+export { createBrowserPlugin } from "./plugins/browser.js";
+export { createCliPlugin } from "./plugins/cli.js";
+export { createDbPlugin } from "./plugins/db.js";
+export { createEnvPlugin } from "./plugins/env.js";
+export { createFsPlugin } from "./plugins/fs.js";
+export { createHttpPlugin } from "./plugins/http.js";
+export { createJwtPlugin } from "./plugins/jwt.js";
+export { createUrlPlugin } from "./plugins/url.js";
+export { createRegistry } from "./registry.js";
+export { reportFatal, reportSuite } from "./reporter.js";
+export { runTests } from "./run.js";
+export { runSuite } from "./runner.js";
+export { positionAt } from "./source.js";
+export { loadSources } from "./sources.js";
+export { KEYWORDS } from "./tokens.js";
+export { connectStdioPlugin, servePlugin } from "./transport-stdio.js";
+export { formatValue, valueEquals } from "./values.js";
+export { createWorkspace } from "./workspace.js";
+export { createNoFilesystemWorkspace } from "./workspace-none.js";

package/dist/lexer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The lexer for `.spec` source text: turns a file into the flat token stream
+ * GRAMMAR.md's token table defines — literals, dotted identifiers, keywords,
+ * punctuation, and significant newlines — with every failure returned as a
+ * `ParseError` value.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { SourceFile } from "./source.js";
+import type { Token } from "./tokens.js";
+import { ParseError } from "./errors.js";
+/**
+ * Tokenize a `.spec` file per GRAMMAR.md's lexical rules: comments are
+ * discarded, newlines collapse into single tokens, dotted identifiers merge,
+ * and durations are validated and converted to milliseconds at lex time.
+ *
+ * @param source - The file to tokenize.
+ * @returns The token stream, or a `ParseError` pointing at the offending text.
+ */
+export declare function lex(source: SourceFile): Result<Token[], ParseError>;

package/dist/lexer.js

@@ -0,0 +1,284 @@
+/**
+ * The lexer for `.spec` source text: turns a file into the flat token stream
+ * GRAMMAR.md's token table defines — literals, dotted identifiers, keywords,
+ * punctuation, and significant newlines — with every failure returned as a
+ * `ParseError` value.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { parse as parseDuration } from "@sdxc/duration";
+import { failure, isFailure, success } from "@sdxc/result";
+import { ParseError } from "./errors.js";
+import { KEYWORDS } from "./tokens.js";
+/** Single-character punctuation, mapped to the token kind each one lexes as. */
+const PUNCTUATION = {
+    "{": "lbrace",
+    "}": "rbrace",
+    "(": "lparen",
+    ")": "rparen",
+    ",": "comma",
+    ":": "colon",
+    "=": "equals",
+};
+/** The escape sequences a single-line string accepts, by escaped character. */
+const STRING_ESCAPES = {
+    '"': '"',
+    "\\": "\\",
+    n: "\n",
+    t: "\t",
+    r: "\r",
+};
+/** Matches a line that is empty or contains only horizontal whitespace. */
+const BLANK_LINE = /^[ \t\r]*$/;
+/** Matches the leading horizontal whitespace of a line. */
+const LEADING_WHITESPACE = /^[ \t]*/;
+/**
+ * Tokenize a `.spec` file per GRAMMAR.md's lexical rules: comments are
+ * discarded, newlines collapse into single tokens, dotted identifiers merge,
+ * and durations are validated and converted to milliseconds at lex time.
+ *
+ * @param source - The file to tokenize.
+ * @returns The token stream, or a `ParseError` pointing at the offending text.
+ */
+export function lex(source) {
+    let text = source.text;
+    let tokens = [];
+    let index = 0;
+    /** Abort lexing with a `ParseError` pointing at the offending range. */
+    function fail(message, start, end) {
+        throw new ParseError(message, source.path, { start, end: Math.max(end, start + 1) });
+    }
+    /** Emit a newline token unless the previous token already is one. */
+    function pushNewline() {
+        let last = tokens[tokens.length - 1];
+        if (last && last.kind !== "newline") {
+            tokens.push({ kind: "newline", text: "\n", span: { start: index, end: index + 1 } });
+        }
+        index += 1;
+    }
+    /** Lex a `"…"` string, decoding its escape sequences. */
+    function readString() {
+        let start = index;
+        index += 1;
+        let value = "";
+        while (true) {
+            if (index >= text.length || text[index] === "\n") {
+                fail('Unterminated string: expected a closing `"` before the end of the line.', start, index);
+            }
+            let char = text[index] ?? "";
+            if (char === '"') {
+                index += 1;
+                break;
+            }
+            if (char === "\\") {
+                let escape = text[index + 1] ?? "";
+                let decoded = STRING_ESCAPES[escape];
+                if (decoded === undefined) {
+                    fail(`Unknown escape sequence "\\${escape}" in string; expected \\" \\\\ \\n \\t or \\r.`, index, index + 2);
+                }
+                value += decoded;
+                index += 2;
+                continue;
+            }
+            value += char;
+            index += 1;
+        }
+        tokens.push({
+            kind: "string",
+            text: text.slice(start, index),
+            span: { start, end: index },
+            value,
+        });
+    }
+    /** Lex a `"""…"""` multiline string; content is raw, then dedented. */
+    function readMultilineString() {
+        let start = index;
+        index += 3;
+        let close = text.indexOf('"""', index);
+        if (close === -1) {
+            fail('Unterminated multiline string: expected a closing `"""`.', start, text.length);
+        }
+        let raw = text.slice(index, close);
+        index = close + 3;
+        tokens.push({
+            kind: "multiline-string",
+            text: text.slice(start, index),
+            span: { start, end: index },
+            value: dedentMultiline(raw),
+        });
+    }
+    /** Lex a number, or a duration when a unit is glued to the integer. */
+    function readNumberOrDuration() {
+        let start = index;
+        if (text[index] === "-")
+            index += 1;
+        while (isDigit(text[index] ?? ""))
+            index += 1;
+        let isInteger = true;
+        if (text[index] === "." && isDigit(text[index + 1] ?? "")) {
+            isInteger = false;
+            index += 1;
+            while (isDigit(text[index] ?? ""))
+                index += 1;
+        }
+        if (isIdentifierStart(text[index] ?? "")) {
+            while (isIdentifierPart(text[index] ?? ""))
+                index += 1;
+            let raw = text.slice(start, index);
+            if (!isInteger) {
+                fail(`Invalid duration "${raw}": the amount must be a whole number.`, start, index);
+            }
+            let parsed = parseDuration(raw);
+            if (isFailure(parsed)) {
+                fail(`Invalid duration "${raw}": expected an integer followed by a unit like ms, s, m, h, d, or w.`, start, index);
+            }
+            tokens.push({
+                kind: "duration",
+                text: raw,
+                span: { start, end: index },
+                value: parsed.data,
+            });
+            return;
+        }
+        let raw = text.slice(start, index);
+        tokens.push({ kind: "number", text: raw, span: { start, end: index }, value: Number(raw) });
+    }
+    /** Lex an identifier, a keyword, or a dotted path joined by adjacent dots. */
+    function readIdentifierOrKeyword() {
+        let start = index;
+        let segments = [];
+        while (true) {
+            let segmentStart = index;
+            while (isIdentifierPart(text[index] ?? ""))
+                index += 1;
+            segments.push(text.slice(segmentStart, index));
+            if (text[index] === "." && isIdentifierStart(text[index + 1] ?? "")) {
+                index += 1;
+                continue;
+            }
+            break;
+        }
+        let raw = text.slice(start, index);
+        if (segments.length === 1) {
+            let keyword = asKeyword(raw);
+            if (keyword) {
+                tokens.push({ kind: "keyword", text: raw, span: { start, end: index }, keyword });
+                return;
+            }
+            tokens.push({ kind: "identifier", text: raw, span: { start, end: index } });
+            return;
+        }
+        for (let segment of segments) {
+            if (asKeyword(segment)) {
+                fail(`The keyword "${segment}" is reserved and cannot appear in the dotted name "${raw}".`, start, index);
+            }
+        }
+        tokens.push({ kind: "identifier", text: raw, span: { start, end: index } });
+    }
+    try {
+        while (index < text.length) {
+            let char = text[index] ?? "";
+            if (char === " " || char === "\t" || char === "\r") {
+                index += 1;
+            }
+            else if (char === "\n") {
+                pushNewline();
+            }
+            else if (char === "#") {
+                while (index < text.length && text[index] !== "\n")
+                    index += 1;
+            }
+            else if (char === '"') {
+                if (text.startsWith('"""', index))
+                    readMultilineString();
+                else
+                    readString();
+            }
+            else if (isDigit(char) || (char === "-" && isDigit(text[index + 1] ?? ""))) {
+                readNumberOrDuration();
+            }
+            else if (isIdentifierStart(char)) {
+                readIdentifierOrKeyword();
+            }
+            else {
+                let kind = PUNCTUATION[char];
+                if (!kind)
+                    fail(`Unexpected character ${JSON.stringify(char)}.`, index, index + 1);
+                tokens.push({ kind, text: char, span: { start: index, end: index + 1 } });
+                index += 1;
+            }
+        }
+        tokens.push({ kind: "eof", text: "", span: { start: text.length, end: text.length } });
+        return success(tokens);
+    }
+    catch (error) {
+        if (error instanceof ParseError)
+            return failure(error);
+        let message = error instanceof Error ? error.message : String(error);
+        return failure(new ParseError(message, source.path));
+    }
+}
+/** Whether the character can start an identifier segment. */
+function isIdentifierStart(char) {
+    return (char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || char === "_";
+}
+/** Whether the character can continue an identifier segment. */
+function isIdentifierPart(char) {
+    return isIdentifierStart(char) || isDigit(char);
+}
+/** Whether the character is an ASCII digit. */
+function isDigit(char) {
+    return char >= "0" && char <= "9";
+}
+/** The reserved word the text spells, or `undefined` when it is not one. */
+function asKeyword(text) {
+    return KEYWORDS.find((keyword) => keyword === text);
+}
+/**
+ * Apply GRAMMAR.md's three multiline-string steps in order: drop a leading
+ * newline, drop whitespace indenting a closing delimiter on its own line,
+ * then strip the common indentation of the non-blank lines; content stays raw.
+ *
+ * @param raw - The text between the `"""` delimiters, untouched.
+ * @returns The processed string value.
+ */
+function dedentMultiline(raw) {
+    let content = raw;
+    if (content.startsWith("\r\n"))
+        content = content.slice(2);
+    else if (content.startsWith("\n"))
+        content = content.slice(1);
+    let lastBreak = content.lastIndexOf("\n");
+    if (lastBreak !== -1) {
+        let tail = content.slice(lastBreak + 1);
+        if (tail.length > 0 && BLANK_LINE.test(tail))
+            content = content.slice(0, lastBreak + 1);
+    }
+    let lines = content.split("\n");
+    let indent;
+    for (let line of lines) {
+        if (BLANK_LINE.test(line))
+            continue;
+        let leading = LEADING_WHITESPACE.exec(line)?.[0] ?? "";
+        indent = indent === undefined ? leading : commonPrefix(indent, leading);
+    }
+    if (indent === undefined || indent === "")
+        return content;
+    let prefix = indent;
+    return lines
+        .map((line) => {
+        let leading = LEADING_WHITESPACE.exec(line)?.[0] ?? "";
+        let strip = commonPrefix(prefix, leading);
+        return line.slice(strip.length);
+    })
+        .join("\n");
+}
+/** The longest prefix two strings share, character by character. */
+function commonPrefix(left, right) {
+    let length = 0;
+    while (length < left.length && length < right.length && left[length] === right[length]) {
+        length += 1;
+    }
+    return left.slice(0, length);
+}