@sharpee/chord 3.0.0

package/parser.js

@@ -0,0 +1,2303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStory = parseStory;
+const lexer_1 = require("./lexer");
+const span_1 = require("./span");
+const ARTICLES = new Set(['the', 'a', 'an']);
+const DIRECTIONS = new Set([
+    'north', 'south', 'east', 'west',
+    'northeast', 'northwest', 'southeast', 'southwest',
+    'up', 'down',
+]);
+/** Z5 strategy adverbs (ADR-211 Decision 4). `ordered`/`once` are retired — load errors naming their replacement. */
+const STRATEGIES = new Set(['randomly', 'cycling', 'stopping', 'sticky', 'first-time']);
+/** Retired strategy adverb → its replacement, for the AC-13 fix-it diagnostic. */
+const RETIRED_STRATEGIES = { ordered: 'stopping', once: 'first-time' };
+const ORDINALS = {
+    first: 1, second: 2, third: 3, fourth: 4, fifth: 5,
+    sixth: 6, seventh: 7, eighth: 8, ninth: 9, tenth: 10,
+};
+/** Words that terminate a noun phrase in condition/statement positions. */
+const PHRASE_STOPS = new Set(['is', 'has', 'holds', 'wears', 'can', 'and', 'or', 'then', 'to', 'while', 'with']);
+const TOP_KEYWORDS = new Set(['story', 'create', 'define', 'when', 'once', 'every']);
+/**
+ * Parse `.story` source into an AST.
+ * @param source full `.story` text
+ * @param diagnostics receives lex + parse diagnostics; parse always returns
+ *   a (possibly partial) StoryFile — callers gate on diagnostics.hasErrors()
+ */
+function parseStory(source, diagnostics) {
+    return new Parser((0, lexer_1.lex)(source, diagnostics), diagnostics).parseFile();
+}
+/** Cursor over one line's tokens. */
+class Cursor {
+    tokens;
+    line;
+    i = 0;
+    constructor(tokens, line) {
+        this.tokens = tokens;
+        this.line = line;
+    }
+    peek(offset = 0) {
+        return this.tokens[this.i + offset] ?? null;
+    }
+    next() {
+        return this.tokens[this.i++] ?? null;
+    }
+    atEnd() {
+        return this.i >= this.tokens.length;
+    }
+    /** Consume the next token iff it is the given word (case-sensitive). */
+    matchWord(word) {
+        const t = this.peek();
+        if (t && t.kind === 'word' && t.text === word)
+            return this.next();
+        return null;
+    }
+    isWord(word, offset = 0) {
+        const t = this.peek(offset);
+        return !!t && t.kind === 'word' && t.text === word;
+    }
+    /** Span from the current position to end of line (or whole line when spent). */
+    restSpan() {
+        const t = this.peek();
+        if (t)
+            return (0, span_1.mergeSpans)(t.span, this.tokens[this.tokens.length - 1].span);
+        return lineSpan(this.line);
+    }
+}
+function lineSpan(line) {
+    if (line.tokens.length === 0)
+        return (0, span_1.spanOf)(line.lineNo, line.indent + 1, Math.max(1, line.raw.trim().length));
+    return (0, span_1.mergeSpans)(line.tokens[0].span, line.tokens[line.tokens.length - 1].span);
+}
+function firstWord(line) {
+    const t = line.tokens[0];
+    return t && t.kind === 'word' ? t.text : null;
+}
+/** True for `end <keyword>` lines. */
+function isEndLine(line) {
+    return firstWord(line) === 'end';
+}
+/** Words that open a statement or block boundary inside behavior bodies. */
+const STATEMENT_OPENERS = new Set([
+    'refuse', 'phrase', 'emit', 'set', 'change', 'move', 'remove', 'award', 'win', 'lose',
+    'if', 'select', 'each', 'end', 'else', 'or', 'when', 'at',
+]);
+/**
+ * True when a line reads as a statement/boundary rather than bare prose —
+ * used to decide whether a deeper-indented line after `phrase <key>` is the
+ * declare-and-emit inline text. Case-sensitive on purpose: prose sentences
+ * start capitalized, statement keywords are lowercase.
+ */
+function isStatementLine(line) {
+    const word = firstWord(line);
+    if (word && STATEMENT_OPENERS.has(word))
+        return true;
+    if (word && ORDINALS[word] !== undefined)
+        return true;
+    if (lineHasMust(line))
+        return true;
+    // `<n> turns later` sequence-step headers open with a number.
+    return line.tokens[0]?.kind === 'number' && line.tokens[1]?.text === 'turns';
+}
+/**
+ * True for `must`-requirement lines (ratchet D6): a lowercase subject
+ * opener plus a `must` token. Case-sensitive so capitalized prose
+ * ("The goats must be fed.") stays prose.
+ */
+function lineHasMust(line) {
+    const word = firstWord(line);
+    return (word === 'the' || word === 'it' || word === 'its')
+        && line.tokens.some((t) => t.kind === 'word' && t.text === 'must');
+}
+class Parser {
+    lines;
+    diagnostics;
+    pos = 0;
+    constructor(lines, diagnostics) {
+        this.lines = lines;
+        this.diagnostics = diagnostics;
+    }
+    // ------------------------------------------------------------------ file
+    parseFile() {
+        let header = null;
+        const declarations = [];
+        const start = this.lines[0] ? lineSpan(this.lines[0]) : (0, span_1.spanOf)(1, 1);
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent !== 0) {
+                this.diagnostics.error('parse.unexpected-indent', 'Unexpected indentation — expected a top-level declaration.', lineSpan(line));
+                this.recoverToTopLevel();
+                continue;
+            }
+            const word = firstWord(line);
+            switch (word) {
+                case 'story':
+                    if (header) {
+                        this.diagnostics.error('parse.duplicate-story-header', 'Duplicate story header — only one `story` line is allowed.', lineSpan(line));
+                        this.recoverToTopLevel(true);
+                    }
+                    else {
+                        header = this.parseStoryHeader();
+                    }
+                    break;
+                case 'create':
+                    declarations.push(this.parseCreate());
+                    break;
+                case 'define': {
+                    const d = this.parseDefine();
+                    if (d)
+                        declarations.push(d);
+                    break;
+                }
+                // Ownership-package removals (ratchet 2026-07-11): floating rules
+                // are gone — each gets a fix-it naming its owner-attached form.
+                case 'when':
+                    this.diagnostics.error('parse.removed-when', 'Top-level `when` rules were removed (ownership package, 2026-07-11) — attach the rule to its owner: `after <verb> it` on the entity or room it is about.', lineSpan(line));
+                    this.recoverToTopLevel(true);
+                    break;
+                case 'once':
+                    this.diagnostics.error('parse.removed-once', 'Top-level `once <condition>` rules were removed (ownership package, 2026-07-11) — use a `, once` clause modifier on the owner: `on every turn while <condition>, once`.', lineSpan(line));
+                    this.recoverToTopLevel(true);
+                    break;
+                case 'every':
+                    this.diagnostics.error('parse.removed-every', 'Top-level `every N turns` rules were removed (ownership package, 2026-07-11) — use a story-owned `define sequence`, or an every-turn clause on the owner.', lineSpan(line));
+                    this.recoverToTopLevel(true);
+                    break;
+                case 'each':
+                    // Never top-level (given 9: all behavior is owned) — ratchet E3.
+                    this.diagnostics.error('parse.each-top-level', '`each` blocks run inside an owner\'s behavior — place the block in an `on`/`after` clause body, an action body, a trait clause body, or a sequence step (never top-level).', lineSpan(line));
+                    this.recoverToTopLevel(true);
+                    break;
+                default:
+                    this.diagnostics.error('parse.unknown-declaration', `Unknown declaration \`${word ?? line.raw.trim()}\` — expected story, create, or define.`, lineSpan(line));
+                    this.recoverToTopLevel(true);
+            }
+        }
+        const last = this.lines[this.lines.length - 1];
+        return {
+            kind: 'story-file',
+            header,
+            declarations,
+            span: last ? (0, span_1.mergeSpans)(start, lineSpan(last)) : start,
+        };
+    }
+    /** Skip lines until the next top-level keyword at indent 0. */
+    recoverToTopLevel(consumeCurrent = false) {
+        if (consumeCurrent)
+            this.pos++;
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent === 0 && TOP_KEYWORDS.has(firstWord(line) ?? ''))
+                return;
+            this.pos++;
+        }
+    }
+    // ---------------------------------------------------------------- header
+    parseStoryHeader() {
+        const line = this.lines[this.pos++];
+        const c = new Cursor(line.tokens, line);
+        c.matchWord('story');
+        const titleTok = c.peek();
+        let title = '';
+        if (titleTok && titleTok.kind === 'string') {
+            title = titleTok.text;
+            c.next();
+        }
+        else {
+            this.diagnostics.error('parse.story-title', 'Expected a quoted story title after `story`.', c.restSpan());
+        }
+        let author = '';
+        if (c.matchWord('by')) {
+            const authorTok = c.peek();
+            if (authorTok && authorTok.kind === 'string') {
+                author = authorTok.text;
+                c.next();
+            }
+            else {
+                this.diagnostics.error('parse.story-author', 'Expected a quoted author after `by`.', c.restSpan());
+            }
+        }
+        const fields = {};
+        const states = [];
+        let statesReversible = false;
+        const scores = [];
+        let span = lineSpan(line);
+        while (this.pos < this.lines.length && this.lines[this.pos].indent > 0) {
+            const fieldLine = this.lines[this.pos++];
+            span = (0, span_1.mergeSpans)(span, lineSpan(fieldLine));
+            const key = firstWord(fieldLine);
+            // `states[, reversible]: a, b` — story phases (ratchet D2/D4).
+            if (key === 'states') {
+                const sc = new Cursor(fieldLine.tokens, fieldLine);
+                sc.next();
+                const parsed = this.parseStatesTail(sc, fieldLine);
+                if (parsed) {
+                    states.push(...parsed.states);
+                    statesReversible = parsed.reversible;
+                }
+                continue;
+            }
+            // `score <name> worth N` — story-owned score identity (ratchet D12).
+            if (key === 'score') {
+                const s = this.parseScoreLine(fieldLine);
+                if (s)
+                    scores.push(s);
+                continue;
+            }
+            const colon = fieldLine.tokens[1];
+            if (!key || !colon || colon.kind !== 'colon') {
+                this.diagnostics.error('parse.header-field', 'Expected `key: value` in the story header.', lineSpan(fieldLine));
+                continue;
+            }
+            const colonAt = fieldLine.raw.indexOf(':');
+            fields[key] = fieldLine.raw.slice(colonAt + 1).trim();
+        }
+        return { kind: 'story-header', title, author, fields, states, statesReversible, scores, span };
+    }
+    /**
+     * Parse the tail of a `states` line after the `states` word:
+     * `[, reversible] : <name>, <name>…` (ratchet D2/D4/D8). Shared by the
+     * story header, create blocks, and trait blocks.
+     */
+    parseStatesTail(c, line) {
+        let reversible = false;
+        if (c.peek()?.kind === 'comma') {
+            c.next();
+            if (c.matchWord('reversible')) {
+                reversible = true;
+            }
+            else {
+                this.diagnostics.error('parse.states-modifier', 'Expected `reversible` after the comma in the `states` declaration.', c.restSpan());
+                return null;
+            }
+        }
+        const colon = c.next();
+        if (!colon || colon.kind !== 'colon') {
+            this.diagnostics.error('parse.states', 'Expected `:` after `states`.', c.restSpan());
+            return null;
+        }
+        return { states: this.parseStateList(c), reversible };
+    }
+    /** `score <name> worth <n>` — owner-attached score line (ratchet D12). */
+    parseScoreLine(line) {
+        const c = new Cursor(line.tokens, line);
+        c.matchWord('score');
+        const name = c.next();
+        if (!name || name.kind !== 'word') {
+            this.diagnostics.error('parse.score-name', 'Expected a score name after `score`.', c.restSpan());
+            return null;
+        }
+        if (!c.matchWord('worth')) {
+            this.diagnostics.error('parse.score-worth', 'Expected `worth <number>` in the score line.', c.restSpan());
+            return null;
+        }
+        const worth = c.next();
+        if (!worth || worth.kind !== 'number') {
+            this.diagnostics.error('parse.score-worth', 'Expected a number after `worth`.', c.restSpan());
+            return null;
+        }
+        return { kind: 'score', name: name.text, worth: Number(worth.text), span: lineSpan(line) };
+    }
+    // ---------------------------------------------------------------- create
+    parseCreate() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.matchWord('create');
+        const name = this.parseNameRef(c, () => false);
+        if (name.words.length === 0) {
+            this.diagnostics.error('parse.create-name', 'Expected an entity name after `create`.', lineSpan(headLine));
+        }
+        const decl = {
+            kind: 'create',
+            name,
+            aka: [],
+            compositions: [],
+            placement: null,
+            wears: [],
+            exits: [],
+            blockedExits: [],
+            states: [],
+            statesReversible: false,
+            scores: [],
+            description: null,
+            initialDescription: null,
+            phraseOverrides: [],
+            onClauses: [],
+            span: lineSpan(headLine),
+        };
+        let sawBlank = false;
+        while (this.pos < this.lines.length && this.lines[this.pos].indent > 0) {
+            const line = this.lines[this.pos];
+            sawBlank = sawBlank || line.afterBlank;
+            decl.span = (0, span_1.mergeSpans)(decl.span, lineSpan(line));
+            const word = firstWord(line);
+            const cur = new Cursor(line.tokens, line);
+            if (word === 'aka') {
+                this.pos++;
+                cur.matchWord('aka');
+                decl.aka.push(...this.parseCommaWords(cur));
+            }
+            else if (word === 'states' && (line.tokens[1]?.kind === 'colon' || line.tokens[1]?.kind === 'comma')) {
+                this.pos++;
+                cur.next();
+                const parsed = this.parseStatesTail(cur, line);
+                if (parsed) {
+                    decl.states.push(...parsed.states);
+                    decl.statesReversible = parsed.reversible;
+                }
+            }
+            else if (word === 'score') {
+                this.pos++;
+                const s = this.parseScoreLine(line);
+                if (s)
+                    decl.scores.push(s);
+            }
+            else if (word === 'wears') {
+                this.pos++;
+                cur.matchWord('wears');
+                decl.wears.push(this.parseNameRef(cur, () => false));
+            }
+            else if (word === 'starts' && cur.isWord('in', 1)) {
+                this.pos++;
+                cur.next();
+                cur.next();
+                decl.placement = this.finishPlacement('starts-in', cur, line);
+            }
+            else if ((word === 'in' || word === 'on') && line.tokens[1] && line.tokens[1].kind === 'word' && ARTICLES.has(line.tokens[1].text)) {
+                this.pos++;
+                cur.next();
+                decl.placement = this.finishPlacement(word, cur, line);
+            }
+            else if (word === 'on') {
+                decl.onClauses.push(this.parseOnClause(line.indent, 'on'));
+            }
+            else if (word === 'after') {
+                decl.onClauses.push(this.parseOnClause(line.indent, 'after'));
+            }
+            else if (word === 'phrase' &&
+                line.tokens[1]?.kind === 'word' &&
+                line.tokens.some((t) => t.kind === 'colon')) {
+                // Colon anywhere on the line: the header may carry `, <strategy>`
+                // and/or `while <condition>` before it (CP3/Z3b).
+                this.pos++;
+                decl.phraseOverrides.push(this.parsePhraseOverride(line));
+            }
+            else if (word && ORDINALS[word] !== undefined && cur.isWord('time', 1)) {
+                // Z1: a `first time` block whose body is bare prose is the
+                // first-VISIT description (RoomTrait.initialDescription). Other
+                // ordinals have no platform field at create scope — load errors,
+                // never a guess.
+                this.pos++;
+                if (word !== 'first') {
+                    this.diagnostics.error('parse.create-ordinal-time', `\`${word} time\` is not allowed in a \`create\` block — only \`first time\` exists (RoomTrait.initialDescription has no later-visit siblings).`, lineSpan(line));
+                    while (this.pos < this.lines.length && this.lines[this.pos].indent > line.indent && !isEndLine(this.lines[this.pos])) {
+                        this.pos++;
+                    }
+                }
+                else if (decl.initialDescription) {
+                    this.diagnostics.error('parse.first-time-duplicate', 'This `create` block already has a `first time` description.', lineSpan(line));
+                    while (this.pos < this.lines.length && this.lines[this.pos].indent > line.indent && !isEndLine(this.lines[this.pos])) {
+                        this.pos++;
+                    }
+                }
+                else {
+                    const next = this.lines[this.pos];
+                    if (!next || next.indent <= line.indent || isEndLine(next)) {
+                        this.diagnostics.error('parse.first-time-empty', '`first time` needs an indented prose block beneath it.', lineSpan(line));
+                    }
+                    else {
+                        decl.initialDescription = this.parseProseParagraph(next.indent, line.indent);
+                    }
+                }
+            }
+            else if (word && DIRECTIONS.has(word) && cur.isWord('to', 1)) {
+                this.pos++;
+                cur.next();
+                cur.next();
+                const to = this.parseNameRef(cur, () => false);
+                decl.exits.push({ kind: 'exit', direction: word, to, span: lineSpan(line) });
+            }
+            else if (word && DIRECTIONS.has(word) && cur.isWord('is', 1) && cur.isWord('blocked', 2)) {
+                this.pos++;
+                const blocked = this.parseBlockedExit(word, line);
+                if (blocked)
+                    decl.blockedExits.push(blocked);
+            }
+            else if (!sawBlank || !line.afterBlank) {
+                if (sawBlank) {
+                    this.diagnostics.error('parse.create-property', `Unrecognized line in \`create\` block: \`${line.raw.trim()}\`.`, lineSpan(line));
+                    this.pos++;
+                }
+                else {
+                    this.pos++;
+                    decl.compositions.push(...this.parseCompositionLine(cur, line));
+                }
+            }
+            else {
+                const prose = this.parseProseParagraph(line.indent);
+                if (decl.description) {
+                    // All consecutive bare paragraphs form the description — a later
+                    // bare paragraph appends as a new paragraph (grammar log 2026-07-10).
+                    decl.description = {
+                        ...decl.description,
+                        text: `${decl.description.text}\n\n${prose.text}`,
+                        markers: [...decl.description.markers, ...prose.markers],
+                        span: (0, span_1.mergeSpans)(decl.description.span, prose.span),
+                    };
+                }
+                else {
+                    decl.description = prose;
+                }
+            }
+        }
+        return decl;
+    }
+    finishPlacement(relation, c, line) {
+        const place = this.parseNameRef(c, () => false);
+        if (place.words.length === 0) {
+            this.diagnostics.error('parse.placement', 'Expected a place name.', lineSpan(line));
+        }
+        return { kind: 'placement', relation, place, span: lineSpan(line) };
+    }
+    parseBlockedExit(direction, line) {
+        // <direction> is blocked [while <condition>]: <phrase-key>
+        // (conditional form: grammar log 2026-07-10, Phase B)
+        const c = new Cursor(line.tokens, line);
+        c.next(); // direction
+        c.next(); // is
+        c.next(); // blocked
+        let condition = null;
+        if (c.matchWord('while')) {
+            const condTokens = [];
+            while (!c.atEnd() && c.peek().kind !== 'colon')
+                condTokens.push(c.next());
+            condition = this.parseCondition(new Cursor(condTokens, line), line);
+        }
+        const colon = c.next();
+        if (!colon || colon.kind !== 'colon') {
+            this.diagnostics.error('parse.blocked-exit', 'Expected `: <phrase-key>` after `is blocked`.', lineSpan(line));
+            return null;
+        }
+        const key = c.next();
+        if (!key || key.kind !== 'word') {
+            this.diagnostics.error('parse.blocked-exit', 'Expected a phrase key after `is blocked:`.', lineSpan(line));
+            return null;
+        }
+        return { kind: 'blocked-exit', direction, phraseKey: key.text, condition, span: lineSpan(line) };
+    }
+    parseCompositionLine(c, line) {
+        const items = [];
+        while (!c.atEnd()) {
+            const startTok = c.peek();
+            let article = null;
+            const first = c.peek();
+            if (first && first.kind === 'word' && ARTICLES.has(first.text)) {
+                article = first.text;
+                c.next();
+            }
+            const words = [];
+            while (!c.atEnd() && c.peek().kind === 'word' && !c.isWord('with') && !c.isWord('while')) {
+                if (c.peek().kind !== 'word')
+                    break;
+                words.push(c.next().text);
+                if (c.peek()?.kind === 'comma')
+                    break;
+            }
+            const config = [];
+            let condition = null;
+            if (c.matchWord('with')) {
+                config.push(...this.parseConfigSettings(c, line));
+            }
+            if (c.matchWord('while')) {
+                condition = this.parseCondition(c, line);
+            }
+            const endTok = c.tokens[c.i - 1] ?? startTok;
+            if (words.length === 0) {
+                this.diagnostics.error('parse.composition', 'Expected a kind or trait name.', lineSpan(line));
+                break;
+            }
+            items.push({
+                kind: 'composition',
+                article,
+                words,
+                config,
+                condition,
+                span: (0, span_1.mergeSpans)(startTok.span, endTok.span),
+            });
+            if (c.peek()?.kind === 'comma')
+                c.next();
+            else
+                break;
+        }
+        if (!c.atEnd()) {
+            this.diagnostics.error('parse.composition-trailing', `Unexpected trailing text in composition line: \`${c.peek().text}\`.`, c.restSpan());
+        }
+        return items;
+    }
+    parseConfigSettings(c, line) {
+        const settings = [];
+        for (;;) {
+            const startTok = c.peek();
+            const key = [];
+            while (!c.atEnd() && c.peek().kind === 'word' && !c.isWord('and') && !c.isWord('while')) {
+                const t = c.peek();
+                // An article starts an entity-name value (`with food the handful of
+                // feed`, Phase B) — everything after it is the value.
+                if (ARTICLES.has(t.text) && key.length > 0)
+                    break;
+                // Otherwise the last token of a setting is its value; words before
+                // it are the key.
+                const after = c.peek(1);
+                const isValuePosition = !after || after.kind === 'comma' || (after.kind === 'word' && (after.text === 'and' || after.text === 'while'));
+                if (isValuePosition && key.length > 0)
+                    break;
+                key.push(t.text);
+                c.next();
+            }
+            const articleTok = c.peek();
+            if (articleTok && articleTok.kind === 'word' && ARTICLES.has(articleTok.text) && key.length > 0) {
+                c.next(); // article
+                const nameWords = [];
+                let lastTok = articleTok;
+                while (!c.atEnd() && c.peek().kind === 'word' && !c.isWord('and') && !c.isWord('while')) {
+                    lastTok = c.next();
+                    nameWords.push(lastTok.text);
+                }
+                if (nameWords.length === 0) {
+                    this.diagnostics.error('parse.config-value', 'Expected an entity name after the article.', c.restSpan());
+                    break;
+                }
+                settings.push({
+                    key,
+                    value: nameWords.join(' '),
+                    valueKind: 'name',
+                    span: startTok ? (0, span_1.mergeSpans)(startTok.span, lastTok.span) : lastTok.span,
+                });
+                if (!c.matchWord('and'))
+                    break;
+                continue;
+            }
+            const valueTok = c.peek();
+            if (!valueTok || (valueTok.kind !== 'number' && valueTok.kind !== 'string' && valueTok.kind !== 'word')) {
+                this.diagnostics.error('parse.config-value', 'Expected a value to end this `with` setting.', c.restSpan());
+                break;
+            }
+            c.next();
+            settings.push({
+                key,
+                value: valueTok.text,
+                valueKind: valueTok.kind,
+                span: startTok ? (0, span_1.mergeSpans)(startTok.span, valueTok.span) : valueTok.span,
+            });
+            if (!c.matchWord('and'))
+                break;
+        }
+        return settings;
+    }
+    parsePhraseOverride(line) {
+        const c = new Cursor(line.tokens, line);
+        c.matchWord('phrase');
+        const key = c.next(); // validated by caller
+        // CP3: optional `, <strategy>` (the Z5 adverb set, retired fix-its
+        // included) — `phrase present, cycling:`.
+        let strategy = null;
+        if (c.peek()?.kind === 'comma') {
+            c.next();
+            const s = c.next();
+            if (s && s.kind === 'word' && STRATEGIES.has(s.text)) {
+                strategy = s.text;
+            }
+            else if (s && s.kind === 'word' && RETIRED_STRATEGIES[s.text]) {
+                this.diagnostics.error('parse.phrase-strategy-retired', `\`${s.text}\` is no longer a strategy adverb — use \`${RETIRED_STRATEGIES[s.text]}\` (ADR-211 Decision 4).`, s.span);
+            }
+            else {
+                this.diagnostics.error('parse.phrase-strategy', 'Expected a strategy (randomly, cycling, stopping, sticky, first-time) after the comma.', s?.span ?? c.restSpan());
+            }
+        }
+        // Z3b: optional `while <condition>` up to the colon — `phrase detail
+        // while it is on:` (`it` = the owner; the analyzer resolves).
+        let condition = null;
+        if (c.isWord('while')) {
+            c.next();
+            const condTokens = [];
+            while (!c.atEnd() && c.peek().kind !== 'colon')
+                condTokens.push(c.next());
+            condition = this.parseCondition(new Cursor(condTokens, line), line);
+        }
+        if (c.peek()?.kind === 'colon') {
+            c.next();
+        }
+        else {
+            this.diagnostics.error('parse.phrase-override-colon', 'Expected `:` to end the `phrase` header.', c.restSpan());
+        }
+        const variants = [];
+        const str = c.peek();
+        if (str && str.kind === 'string') {
+            c.next();
+            this.reportSameLineText(str.span);
+            variants.push(this.textFromString(str)); // recovery: keep the text so analysis continues
+        }
+        else {
+            // First variant, then `or`-separated further variants (CP3): `or`
+            // stands alone at the SAME indent as the `phrase` header line.
+            variants.push(this.parseProseParagraph(line.indent + 1, line.indent));
+            for (;;) {
+                const next = this.lines[this.pos];
+                if (!next || next.indent !== line.indent || firstWord(next) !== 'or' || next.tokens.length !== 1)
+                    break;
+                this.pos++;
+                variants.push(this.parseProseParagraph(line.indent + 1, line.indent));
+            }
+        }
+        const last = variants[variants.length - 1];
+        return {
+            kind: 'phrase-override',
+            key: key.text,
+            strategy,
+            condition,
+            variants,
+            span: (0, span_1.mergeSpans)(lineSpan(line), last?.span ?? lineSpan(line)),
+        };
+    }
+    /** Same-line phrase text (quoted or bare) was removed — grammar log 2026-07-10. */
+    reportSameLineText(span) {
+        this.diagnostics.error('parse.phrase-text-form', 'Phrase text goes in an indented prose block — the same-line form was removed (grammar log 2026-07-10).', span);
+    }
+    parseCommaWords(c) {
+        const out = [];
+        let current = [];
+        while (!c.atEnd()) {
+            const t = c.next();
+            if (t.kind === 'comma') {
+                if (current.length)
+                    out.push(current.join(' '));
+                current = [];
+            }
+            else {
+                current.push(t.text);
+            }
+        }
+        if (current.length)
+            out.push(current.join(' '));
+        return out;
+    }
+    parseStateList(c) {
+        const out = [];
+        while (!c.atEnd()) {
+            const t = c.next();
+            if (t.kind === 'word')
+                out.push({ name: t.text, span: t.span });
+            else if (t.kind !== 'comma') {
+                this.diagnostics.error('parse.states', 'Expected a comma-separated list of state names.', t.span);
+            }
+        }
+        return out;
+    }
+    // ------------------------------------------------------------------ prose
+    /**
+     * Collect a prose block: consecutive lines at indent >= minIndent. When
+     * `strictlyAbove` is given, lines must be indented strictly deeper than it
+     * (phrase-entry values, variants, overrides) — and in that mode a blank
+     * line starts a new PARAGRAPH (`\n\n` in the text) instead of ending the
+     * block (grammar log 2026-07-10), since the block is already delimited by
+     * shallower-indented lines. In minIndent mode (create-block descriptions)
+     * a blank line still ends the block — the create loop merges consecutive
+     * bare paragraphs itself, keeping keyword lines out of prose.
+     */
+    parseProseParagraph(minIndent, strictlyAbove) {
+        const paragraphs = [];
+        let current = [];
+        const markers = [];
+        let span = null;
+        let first = true;
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            const deepEnough = strictlyAbove !== undefined ? line.indent > strictlyAbove : line.indent >= minIndent;
+            if (!deepEnough || isEndLine(line))
+                break;
+            if (!first && line.afterBlank) {
+                if (strictlyAbove === undefined)
+                    break;
+                paragraphs.push(current);
+                current = [];
+            }
+            this.pos++;
+            const text = line.raw.trim();
+            this.extractMarkers(line, markers);
+            current.push(text);
+            span = span ? (0, span_1.mergeSpans)(span, lineSpan(line)) : lineSpan(line);
+            first = false;
+        }
+        if (current.length)
+            paragraphs.push(current);
+        return {
+            kind: 'text',
+            form: 'prose',
+            text: paragraphs.map((p) => p.join(' ')).join('\n\n'),
+            markers,
+            span: span ?? (0, span_1.spanOf)(this.lines[this.pos - 1]?.lineNo ?? 1, 1),
+        };
+    }
+    /**
+     * Collect a verbatim block (`define phrase X, verbatim`): every line
+     * deeper than the head line, with line structure, interior blank lines,
+     * and relative indentation preserved exactly. The common leading indent
+     * is stripped; lines join with `\n`.
+     */
+    parseVerbatimBlock() {
+        const collected = [];
+        const markers = [];
+        let span = null;
+        let first = true;
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            // Only a column-1 line (`end phrase`, next top-level keyword) ends the
+            // block — verbatim content may contain any words, including `end`.
+            if (line.indent === 0)
+                break;
+            collected.push({ raw: line.raw, blankBefore: !first && line.afterBlank });
+            this.extractMarkers(line, markers);
+            span = span ? (0, span_1.mergeSpans)(span, lineSpan(line)) : lineSpan(line);
+            this.pos++;
+            first = false;
+        }
+        const common = Math.min(...collected.map((l) => l.raw.length - l.raw.trimStart().length));
+        const lines = [];
+        for (const l of collected) {
+            if (l.blankBefore)
+                lines.push('');
+            lines.push(l.raw.slice(common).trimEnd());
+        }
+        return {
+            kind: 'text',
+            form: 'verbatim',
+            text: lines.join('\n'),
+            markers,
+            span: span ?? (0, span_1.spanOf)(this.lines[this.pos - 1]?.lineNo ?? 1, 1),
+        };
+    }
+    extractMarkers(line, into) {
+        const re = /\{([^}]*)\}/g;
+        let m;
+        while ((m = re.exec(line.raw)) !== null) {
+            into.push({ content: m[1], span: (0, span_1.spanOf)(line.lineNo, m.index + 1, m[0].length) });
+        }
+    }
+    /** Error-recovery only: a removed same-line quoted value, kept as prose text. */
+    textFromString(tok) {
+        const markers = [];
+        const re = /\{([^}]*)\}/g;
+        let m;
+        while ((m = re.exec(tok.text)) !== null) {
+            markers.push({ content: m[1], span: (0, span_1.spanOf)(tok.span.line, tok.span.column + 1 + m.index, m[0].length) });
+        }
+        return { kind: 'text', form: 'prose', text: tok.text, markers, span: tok.span };
+    }
+    // ---------------------------------------------------------------- define
+    parseDefine() {
+        const line = this.lines[this.pos];
+        const sub = line.tokens[1];
+        const subWord = sub && sub.kind === 'word' ? sub.text : null;
+        switch (subWord) {
+            case 'condition':
+                return this.parseDefineCondition();
+            case 'phrase':
+                return this.parseDefinePhrase();
+            case 'phrases':
+                return this.parseDefinePhrases();
+            case 'verb':
+                return this.parseDefineVerb();
+            case 'text':
+                return this.parseDefineText();
+            case 'flag':
+                // Removed — given 8 (ratchet 2026-07-11).
+                this.diagnostics.error('parse.removed-flag', '`define flag` was removed (given 8: no global booleans) — model the fact as `states:` on its owner, or derive it with a condition over world state.', lineSpan(line));
+                this.recoverToTopLevel(true);
+                return null;
+            case 'trait':
+                return this.parseDefineTrait();
+            case 'action':
+                return this.parseDefineAction();
+            case 'behavior':
+                return this.parseDefineBehaviorHatch();
+            case 'score':
+                // Removed — ratchet D12/CP5 (2026-07-11).
+                this.diagnostics.error('parse.removed-score', '`define score` was removed (ownership package) — attach the score to its earning owner: `score <name> worth N` in the owner\'s create/trait/action block or the story header.', lineSpan(line));
+                this.recoverToTopLevel(true);
+                return null;
+            case 'sequence':
+                return this.parseDefineSequence();
+            default:
+                this.diagnostics.error('parse.unknown-define', `Unknown declaration \`define ${subWord ?? ''}\`.`, lineSpan(line));
+                this.recoverToTopLevel(true);
+                return null;
+        }
+    }
+    parseDefineCondition() {
+        const line = this.lines[this.pos++];
+        const c = new Cursor(line.tokens, line);
+        c.next();
+        c.next(); // define condition
+        const name = c.next();
+        if (!name || name.kind !== 'word') {
+            this.diagnostics.error('parse.condition-name', 'Expected a condition name after `define condition`.', c.restSpan());
+            return null;
+        }
+        const colon = c.next();
+        if (!colon || colon.kind !== 'colon') {
+            this.diagnostics.error('parse.condition-colon', 'Expected `:` after the condition name.', c.restSpan());
+            return null;
+        }
+        const condition = this.parseCondition(c, line);
+        return { kind: 'define-condition', name: name.text, condition, span: lineSpan(line) };
+    }
+    parseDefinePhrase() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next();
+        c.next(); // define phrase
+        const keyTok = c.next();
+        const key = keyTok && keyTok.kind === 'word' ? keyTok.text : '';
+        if (!key) {
+            this.diagnostics.error('parse.phrase-key', 'Expected a phrase key after `define phrase`.', lineSpan(headLine));
+        }
+        let strategy = null;
+        let verbatim = false;
+        if (c.peek()?.kind === 'comma') {
+            c.next();
+            const s = c.next();
+            if (s && s.kind === 'word' && STRATEGIES.has(s.text)) {
+                strategy = s.text;
+            }
+            else if (s && s.kind === 'word' && RETIRED_STRATEGIES[s.text]) {
+                // Z5 / AC-13: retired adverbs are load errors that name their replacement.
+                this.diagnostics.error('parse.phrase-strategy-retired', `\`${s.text}\` is no longer a strategy adverb — use \`${RETIRED_STRATEGIES[s.text]}\` (ADR-211 Decision 4).`, s.span);
+            }
+            else if (s && s.kind === 'word' && s.text === 'verbatim') {
+                verbatim = true; // grammar log 2026-07-10: whitespace-preserving text
+            }
+            else {
+                this.diagnostics.error('parse.phrase-strategy', 'Expected a strategy (randomly, cycling, stopping, sticky, first-time) or `verbatim` after the comma.', s?.span ?? c.restSpan());
+            }
+        }
+        // Z2/CP1': optional trailing `while <condition>` gates the fragment —
+        // presence conditions compile to `mentions`, anything else registers on
+        // the ADR-211 gate seam (resolution is the analyzer's/loader's job).
+        let condition = null;
+        if (c.isWord('while')) {
+            c.next();
+            condition = this.parseCondition(c, headLine);
+        }
+        const variants = [];
+        let span = lineSpan(headLine);
+        for (;;) {
+            const line = this.lines[this.pos];
+            if (!line) {
+                this.diagnostics.error('parse.unterminated-block', 'Missing `end phrase`.', span);
+                break;
+            }
+            if (isEndLine(line)) {
+                span = (0, span_1.mergeSpans)(span, lineSpan(line));
+                this.consumeEnd('phrase', headLine);
+                break;
+            }
+            if (firstWord(line) === 'or' && line.tokens.length === 1) {
+                if (verbatim) {
+                    this.diagnostics.error('parse.verbatim-variants', 'A verbatim phrase has a single text — `or` variants need a strategy instead.', lineSpan(line));
+                }
+                this.pos++;
+                continue;
+            }
+            if (line.indent === 0 && TOP_KEYWORDS.has(firstWord(line) ?? '')) {
+                this.diagnostics.error('parse.unterminated-block', 'Missing `end phrase`.', span);
+                break;
+            }
+            const variant = verbatim ? this.parseVerbatimBlock() : this.parseProseParagraph(1, 0);
+            variants.push(variant);
+            span = (0, span_1.mergeSpans)(span, variant.span);
+        }
+        return { kind: 'define-phrase', key, strategy, verbatim, condition, variants, span };
+    }
+    parseDefinePhrases() {
+        const headLine = this.lines[this.pos++];
+        return this.parsePhrasesBlock(headLine, 2);
+    }
+    /**
+     * Parse a phrases block from its header line (`define phrases <locale>` at
+     * top level, or `phrases <locale>` inside a trait/action, Phase B). The
+     * locale token index distinguishes the two; entries are lines indented
+     * deeper than the header.
+     */
+    parsePhrasesBlock(headLine, localeTokenIndex) {
+        const locTok = headLine.tokens[localeTokenIndex];
+        let locale = '';
+        if (locTok && locTok.kind === 'word') {
+            locale = locTok.text;
+        }
+        else {
+            this.diagnostics.error('parse.phrases-locale', 'Expected a locale after `phrases` (e.g. en-US).', lineSpan(headLine));
+        }
+        const entries = [];
+        let span = lineSpan(headLine);
+        while (this.pos < this.lines.length && this.lines[this.pos].indent > headLine.indent) {
+            const line = this.lines[this.pos];
+            const key = line.tokens[0];
+            const colon = line.tokens[1];
+            if (!key || key.kind !== 'word' || !colon || colon.kind !== 'colon') {
+                this.diagnostics.error('parse.phrase-entry', 'Expected `key: <text>` in the phrases block.', lineSpan(line));
+                this.pos++;
+                continue;
+            }
+            this.pos++;
+            let value;
+            const inline = line.tokens[2];
+            if (inline && inline.kind === 'string') {
+                this.reportSameLineText(inline.span);
+                value = this.textFromString(inline); // recovery: keep the text so analysis continues
+            }
+            else if (inline) {
+                // Same-line bare text after the colon — removed with the quoted form.
+                this.reportSameLineText(inline.span);
+                const colonAt = line.raw.indexOf(':');
+                const text = line.raw.slice(colonAt + 1).trim();
+                const markers = [];
+                this.extractMarkers(line, markers);
+                value = { kind: 'text', form: 'prose', text, markers, span: lineSpan(line) };
+            }
+            else {
+                value = this.parseProseParagraph(line.indent + 1, line.indent);
+                if (value.text === '') {
+                    this.diagnostics.error('parse.phrase-entry-empty', `Phrase \`${key.text}\` has no text.`, lineSpan(line));
+                }
+            }
+            entries.push({ key: key.text, value, span: (0, span_1.mergeSpans)(lineSpan(line), value.span) });
+            span = (0, span_1.mergeSpans)(span, entries[entries.length - 1].span);
+        }
+        return { kind: 'define-phrases', locale, entries, span };
+    }
+    parseDefineVerb() {
+        const line = this.lines[this.pos++];
+        const c = new Cursor(line.tokens, line);
+        c.next();
+        c.next(); // define verb
+        const verbs = [];
+        for (;;) {
+            const v = c.next();
+            if (!v || v.kind !== 'word') {
+                this.diagnostics.error('parse.verb-name', 'Expected a verb word.', v?.span ?? c.restSpan());
+                return null;
+            }
+            verbs.push(v.text);
+            if (!c.matchWord('or'))
+                break;
+        }
+        if (!c.matchWord('means')) {
+            this.diagnostics.error('parse.verb-means', 'Expected `means <pattern>` in the verb definition.', c.restSpan());
+            return null;
+        }
+        const pattern = [];
+        while (!c.atEnd()) {
+            const t = c.next();
+            if (t.kind === 'lparen') {
+                const slot = c.next();
+                const close = c.next();
+                if (!slot || slot.kind !== 'word' || !close || close.kind !== 'rparen') {
+                    this.diagnostics.error('parse.verb-slot', 'Expected `(something)` slot in the verb pattern.', t.span);
+                    return null;
+                }
+                pattern.push({ kind: 'slot', word: slot.text, span: (0, span_1.mergeSpans)(t.span, close.span) });
+            }
+            else if (t.kind === 'word') {
+                pattern.push({ kind: 'word', word: t.text, span: t.span });
+            }
+            else {
+                this.diagnostics.error('parse.verb-pattern', `Unexpected \`${t.text}\` in the verb pattern.`, t.span);
+            }
+        }
+        return { kind: 'define-verb', verbs, pattern, span: lineSpan(line) };
+    }
+    parseDefineText() {
+        const line = this.lines[this.pos++];
+        const c = new Cursor(line.tokens, line);
+        c.next();
+        c.next(); // define text
+        const name = c.next();
+        if (!name || name.kind !== 'word') {
+            this.diagnostics.error('parse.text-name', 'Expected a producer name after `define text`.', c.restSpan());
+            return null;
+        }
+        if (!c.matchWord('from')) {
+            this.diagnostics.error('parse.text-from', 'Expected `from "<module>"` in the hatch declaration.', c.restSpan());
+            return null;
+        }
+        const mod = c.next();
+        if (!mod || mod.kind !== 'string') {
+            this.diagnostics.error('parse.text-module', 'Expected a quoted module path after `from`.', c.restSpan());
+            return null;
+        }
+        return { kind: 'define-text', name: name.text, modulePath: mod.text, span: lineSpan(line) };
+    }
+    // -------------------------------------------- Phase B declarations (§2.2/§2.3/§2.5)
+    /** `define trait <name>` … `end trait` — data, phrases, on-clauses. */
+    parseDefineTrait() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next();
+        c.next(); // define trait
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.trait-name', 'Expected a trait name after `define trait`.', c.restSpan());
+            return null;
+        }
+        const data = [];
+        const states = [];
+        let statesReversible = false;
+        const scores = [];
+        let phrases = null;
+        const onClauses = [];
+        const build = (span) => ({
+            kind: 'define-trait', name: nameTok.text, data, states, statesReversible, scores, phrases, onClauses, span,
+        });
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent === 0) {
+                if (isEndLine(line))
+                    break;
+                this.diagnostics.error('parse.unterminated-block', 'Missing `end trait`.', lineSpan(headLine));
+                return build(lineSpan(headLine));
+            }
+            const word = firstWord(line);
+            if (word === 'data' && line.tokens.length === 1) {
+                this.pos++;
+                data.push(...this.parseTraitFields(line));
+            }
+            else if (word === 'states') {
+                // Trait-declared states (ratchet D8) — every composer gets the set.
+                this.pos++;
+                const sc = new Cursor(line.tokens, line);
+                sc.next();
+                const parsed = this.parseStatesTail(sc, line);
+                if (parsed) {
+                    states.push(...parsed.states);
+                    statesReversible = parsed.reversible;
+                }
+            }
+            else if (word === 'score') {
+                this.pos++;
+                const s = this.parseScoreLine(line);
+                if (s)
+                    scores.push(s);
+            }
+            else if (word === 'phrases') {
+                this.pos++;
+                phrases = this.parsePhrasesBlock(line, 1);
+            }
+            else if (word === 'on') {
+                onClauses.push(this.parseOnClause(line.indent, 'on'));
+            }
+            else if (word === 'after') {
+                onClauses.push(this.parseOnClause(line.indent, 'after'));
+            }
+            else {
+                this.diagnostics.error('parse.trait-section', `Unrecognized line in \`define trait\`: \`${line.raw.trim()}\` — expected data, states, score, phrases, or an \`on\`/\`after\` clause.`, lineSpan(line));
+                this.pos++;
+            }
+        }
+        const endSpan = this.consumeEnd('trait', headLine);
+        return build((0, span_1.mergeSpans)(lineSpan(headLine), endSpan));
+    }
+    /** `data` block fields: `locked: flag`, `body part: optional name`, `kind: one of a, b`. */
+    parseTraitFields(dataLine) {
+        const fields = [];
+        while (this.pos < this.lines.length && this.lines[this.pos].indent > dataLine.indent) {
+            const line = this.lines[this.pos++];
+            const c = new Cursor(line.tokens, line);
+            const name = [];
+            while (!c.atEnd() && c.peek().kind === 'word')
+                name.push(c.next().text);
+            const colon = c.next();
+            if (name.length === 0 || !colon || colon.kind !== 'colon') {
+                this.diagnostics.error('parse.trait-field', 'Expected `<field>: <type>` in the data block.', lineSpan(line));
+                continue;
+            }
+            const optional = !!c.matchWord('optional');
+            let type = null;
+            let oneOf = null;
+            if (c.isWord('one') && c.isWord('of', 1)) {
+                c.next();
+                c.next();
+                type = 'one-of';
+                oneOf = [];
+                while (!c.atEnd()) {
+                    const t = c.next();
+                    if (t.kind === 'word')
+                        oneOf.push(t.text);
+                    else if (t.kind !== 'comma')
+                        break;
+                }
+                if (oneOf.length === 0) {
+                    this.diagnostics.error('parse.trait-field-oneof', 'Expected members after `one of`.', c.restSpan());
+                }
+            }
+            else {
+                const typeTok = c.next();
+                if (typeTok && typeTok.kind === 'word' && ['entity', 'number', 'name'].includes(typeTok.text)) {
+                    type = typeTok.text;
+                }
+                else if (typeTok && typeTok.kind === 'word' && typeTok.text === 'flag') {
+                    // Removed — given 8 / ratchet D8 (2026-07-11).
+                    this.diagnostics.error('parse.removed-flag-field', 'The `flag` field type was removed (given 8: no booleans at any scope) — declare `states[, reversible]: …` on the trait and name what the thing IS in each state.', typeTok.span);
+                    continue;
+                }
+                else {
+                    this.diagnostics.error('parse.trait-field-type', 'Expected a field type: entity, number, name, or `one of …`.', typeTok?.span ?? c.restSpan());
+                    continue;
+                }
+            }
+            let initial = null;
+            if (c.peek()?.kind === 'comma') {
+                c.next();
+                if (c.matchWord('starts')) {
+                    const v = c.next();
+                    if (v)
+                        initial = v.text;
+                    else
+                        this.diagnostics.error('parse.trait-field-starts', 'Expected a value after `starts`.', c.restSpan());
+                }
+                else {
+                    this.diagnostics.error('parse.trait-field-starts', 'Expected `starts <value>` after the comma.', c.restSpan());
+                }
+            }
+            // Trailing tokens were previously dropped silently — `shine: number
+            // starts 1` (missing comma) parsed as a plain field with NO initial
+            // (found 2026-07-12 building the zoo chain). Never a guess.
+            if (!c.atEnd()) {
+                this.diagnostics.error('parse.trait-field-trailing', 'Unexpected words after the field type — an initial value is written `, starts <value>` (the comma is required).', c.restSpan());
+            }
+            fields.push({ name, type: type, optional, initial, oneOf, span: lineSpan(line) });
+        }
+        return fields;
+    }
+    /** `define action <name>` — dispatch declaration (dedent-terminated) or `from "<mod>"` hatch. */
+    parseDefineAction() {
+        const headLine = this.lines[this.pos];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next();
+        c.next(); // define action
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.action-name', 'Expected an action name after `define action`.', c.restSpan());
+            this.pos++;
+            return null;
+        }
+        if (c.isWord('from')) {
+            return this.parseHatchTail(headLine, c, 'action', nameTok.text);
+        }
+        this.pos++;
+        const patterns = [];
+        const constraints = [];
+        const musts = [];
+        const refusals = [];
+        let otherwise = null;
+        const scores = [];
+        let phrases = null;
+        const body = [];
+        let span = lineSpan(headLine);
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent === 0)
+                break; // dedent-terminated (no `end action`, design.md §2.3/§3.4)
+            const word = firstWord(line);
+            if (word === 'grammar' && line.tokens.length === 1) {
+                this.pos++;
+                patterns.push(...this.parseActionPatterns(line));
+            }
+            else if (lineHasMust(line)) {
+                // With a `: <key>` tail it is a must-requirement (ratchet D6);
+                // without one it is the scope-constraint kit (`must be reachable`).
+                this.pos++;
+                if (line.tokens.some((t) => t.kind === 'colon')) {
+                    const m = this.parseMustLine(line);
+                    if (m)
+                        musts.push(m);
+                }
+                else {
+                    const sc = this.parseScopeConstraint(line);
+                    if (sc)
+                        constraints.push(sc);
+                }
+            }
+            else if (word === 'score') {
+                this.pos++;
+                const s = this.parseScoreLine(line);
+                if (s)
+                    scores.push(s);
+            }
+            else if (word === 'refuse' && (line.tokens[1]?.text === 'without' || line.tokens[1]?.text === 'when')) {
+                this.pos++;
+                const r = this.parseActionRefusal(line);
+                if (r)
+                    refusals.push(r);
+            }
+            else if (word === 'otherwise') {
+                this.pos++;
+                const oc = new Cursor(line.tokens, line);
+                oc.next();
+                if (!oc.matchWord('refuse')) {
+                    this.diagnostics.error('parse.action-otherwise', 'Expected `otherwise refuse <phrase-key>`.', lineSpan(line));
+                }
+                else {
+                    const key = oc.next();
+                    if (key && key.kind === 'word')
+                        otherwise = { phraseKey: key.text, span: lineSpan(line) };
+                    else
+                        this.diagnostics.error('parse.action-otherwise', 'Expected a phrase key after `otherwise refuse`.', oc.restSpan());
+                }
+            }
+            else if (word === 'phrases') {
+                this.pos++;
+                phrases = this.parsePhrasesBlock(line, 1);
+            }
+            else {
+                const stmt = this.parseStatement(line, 'action');
+                if (stmt)
+                    body.push(stmt);
+            }
+            span = (0, span_1.mergeSpans)(span, lineSpan(line));
+        }
+        return { kind: 'define-action', name: nameTok.text, patterns, constraints, musts, refusals, otherwise, scores, phrases, body, span };
+    }
+    /**
+     * `<subject> must <predicate>: <phrase-key>` — the D6 requirement form
+     * (define-action line AND body statement). The predicate is infinitive
+     * (`be hungry`, `have its food`, `hold the camera`) and normalized here.
+     */
+    parseMustLine(line) {
+        const colonIndex = line.tokens.map((t) => t.kind === 'colon').lastIndexOf(true);
+        if (colonIndex === -1 || colonIndex !== line.tokens.length - 2) {
+            this.diagnostics.error('parse.must', 'Expected `<subject> must <predicate>: <phrase-key>`.', lineSpan(line));
+            return null;
+        }
+        const keyTok = line.tokens[colonIndex + 1];
+        if (keyTok.kind !== 'word') {
+            this.diagnostics.error('parse.must', 'Expected a phrase key after the colon in the `must` requirement.', keyTok.span);
+            return null;
+        }
+        const c = new Cursor(line.tokens.slice(0, colonIndex), line);
+        const subject = this.parseValueExpr(c, line, new Set(['must']));
+        if (!c.matchWord('must')) {
+            this.diagnostics.error('parse.must', 'Expected `must` after the subject in the requirement.', c.restSpan());
+            return null;
+        }
+        if (c.isWord('not')) {
+            // Requirements are positive by design (decision 6) — same stance as
+            // the analysis.negated-requirement gate on `refuse when not`.
+            this.diagnostics.error('parse.must-negative', 'State requirements positively — `must not …` is not a form. Use `refuse when <condition>: <key>` for prohibitions.', c.restSpan());
+            return null;
+        }
+        const predicate = this.parseInfinitivePredicate(c, line);
+        if (!predicate)
+            return null;
+        return { kind: 'must', subject, predicate, phraseKey: keyTok.text, span: lineSpan(line) };
+    }
+    /** Infinitive predicate after `must`: be / have / hold / wear / see / reach. */
+    parseInfinitivePredicate(c, line) {
+        const t = c.next();
+        if (!t || t.kind !== 'word') {
+            this.diagnostics.error('parse.must-predicate', 'Expected a predicate after `must`: be, have, hold, wear, see, or reach.', t?.span ?? c.restSpan());
+            return null;
+        }
+        switch (t.text) {
+            case 'be': {
+                if (c.isWord('a') || c.isWord('an')) {
+                    c.next();
+                    const cls = this.collectWords(c, new Set());
+                    return { kind: 'is-a', negated: false, classifier: cls.words, span: cls.span ?? t.span };
+                }
+                if (c.isWord('in')) {
+                    c.next();
+                    const place = this.parseNameRef(c, () => false);
+                    return { kind: 'is-in', negated: false, place, span: place.span };
+                }
+                // `be any <name>` — membership over a named open condition (David,
+                // 2026-07-12, each package P3). Same standalone-name rule as the
+                // condition-position quantifiers: a value that merely starts with
+                // `any` keeps its ordinary parse.
+                if (c.isWord('any')) {
+                    const nameTok = c.peek(1);
+                    if (nameTok && nameTok.kind === 'word' && this.isBareConditionRef(c, 1)) {
+                        const anyTok = c.next();
+                        c.next();
+                        return { kind: 'is-any', condition: nameTok.text, span: (0, span_1.mergeSpans)(anyTok.span, nameTok.span) };
+                    }
+                }
+                // `be no <name>` — a negated requirement in disguise (decision 6):
+                // same stance as `must not`.
+                if (c.isWord('no')) {
+                    const nameTok = c.peek(1);
+                    if (nameTok && nameTok.kind === 'word' && this.isBareConditionRef(c, 1)) {
+                        this.diagnostics.error('parse.must-negative', 'State requirements positively — `must be no <name>` is not a form. Use `refuse when <condition>: <key>` for prohibitions.', c.restSpan());
+                        return null;
+                    }
+                }
+                const value = this.parseValueExpr(c, line, new Set());
+                return { kind: 'is', negated: false, value, span: value.span };
+            }
+            case 'have': {
+                const thing = this.parseNameRef(c, (tok) => tok.kind === 'word' && PHRASE_STOPS.has(tok.text));
+                return { kind: 'has', thing, span: thing.span };
+            }
+            case 'hold': {
+                const thing = this.parseNameRef(c, (tok) => tok.kind === 'word' && PHRASE_STOPS.has(tok.text));
+                return { kind: 'holds', thing, span: thing.span };
+            }
+            case 'wear': {
+                const thing = this.parseNameRef(c, (tok) => tok.kind === 'word' && PHRASE_STOPS.has(tok.text));
+                return { kind: 'wears', thing, span: thing.span };
+            }
+            case 'see':
+            case 'reach': {
+                const thing = this.parseNameRef(c, (tok) => tok.kind === 'word' && PHRASE_STOPS.has(tok.text));
+                return { kind: 'can', ability: t.text, thing, span: (0, span_1.mergeSpans)(t.span, thing.span) };
+            }
+            default:
+                this.diagnostics.error('parse.must-predicate', `Unknown predicate \`${t.text}\` after \`must\` — expected be, have, hold, wear, see, or reach.`, t.span);
+                return null;
+        }
+    }
+    /** grammar-block pattern lines: words + `:slot`s, optional `→ each …` cardinality. */
+    parseActionPatterns(grammarLine) {
+        const patterns = [];
+        while (this.pos < this.lines.length && this.lines[this.pos].indent > grammarLine.indent) {
+            const line = this.lines[this.pos++];
+            const parts = [];
+            let cardinality = null;
+            const c = new Cursor(line.tokens, line);
+            while (!c.atEnd()) {
+                const t = c.next();
+                if (t.kind === 'punct' && t.text === '→') {
+                    cardinality = [];
+                    while (!c.atEnd())
+                        cardinality.push(c.next().text);
+                    break;
+                }
+                if (t.kind === 'colon') {
+                    const slot = c.next();
+                    if (slot && slot.kind === 'word') {
+                        parts.push({ kind: 'slot', word: slot.text, span: (0, span_1.mergeSpans)(t.span, slot.span) });
+                    }
+                    else {
+                        this.diagnostics.error('parse.action-slot', 'Expected a slot name after `:`.', t.span);
+                    }
+                }
+                else if (t.kind === 'word') {
+                    parts.push({ kind: 'word', word: t.text, span: t.span });
+                }
+                else {
+                    this.diagnostics.error('parse.action-pattern', `Unexpected \`${t.text}\` in a grammar pattern.`, t.span);
+                }
+            }
+            if (parts.length === 0) {
+                this.diagnostics.error('parse.action-pattern', 'Empty grammar pattern.', lineSpan(line));
+                continue;
+            }
+            patterns.push({ parts, cardinality, span: lineSpan(line) });
+        }
+        return patterns;
+    }
+    /** `the <slot> must be <requirement>` */
+    parseScopeConstraint(line) {
+        const c = new Cursor(line.tokens, line);
+        c.next(); // the
+        const slot = c.next();
+        if (!slot || slot.kind !== 'word') {
+            this.diagnostics.error('parse.action-constraint', 'Expected a slot name after `the`.', c.restSpan());
+            return null;
+        }
+        if (!c.matchWord('must') || !c.matchWord('be')) {
+            this.diagnostics.error('parse.action-constraint', 'Expected `must be <requirement>`.', c.restSpan());
+            return null;
+        }
+        const req = c.next();
+        if (!req || req.kind !== 'word') {
+            this.diagnostics.error('parse.action-constraint', 'Expected a requirement word (reachable, visible, …).', c.restSpan());
+            return null;
+        }
+        return { slot: slot.text, requirement: req.text, span: lineSpan(line) };
+    }
+    /** `refuse without <slot>: <key>` / `refuse when <condition>: <key>` */
+    parseActionRefusal(line) {
+        const c = new Cursor(line.tokens, line);
+        c.next(); // refuse
+        const form = c.next().text;
+        if (form === 'without') {
+            const slot = c.next();
+            const colon = c.next();
+            const key = c.next();
+            if (!slot || slot.kind !== 'word' || !colon || colon.kind !== 'colon' || !key || key.kind !== 'word') {
+                this.diagnostics.error('parse.action-refusal', 'Expected `refuse without <slot>: <phrase-key>`.', lineSpan(line));
+                return null;
+            }
+            return { kind: 'without', slot: slot.text, condition: null, phraseKey: key.text, span: lineSpan(line) };
+        }
+        // when: condition runs to the LAST colon; the key follows it.
+        const colonIndex = line.tokens.map((t) => t.kind === 'colon').lastIndexOf(true);
+        if (colonIndex === -1 || colonIndex !== line.tokens.length - 2) {
+            this.diagnostics.error('parse.action-refusal', 'Expected `refuse when <condition>: <phrase-key>`.', lineSpan(line));
+            return null;
+        }
+        const condCursor = new Cursor(line.tokens.slice(2, colonIndex), line);
+        const condition = this.parseCondition(condCursor, line);
+        const key = line.tokens[colonIndex + 1];
+        if (!key || key.kind !== 'word') {
+            this.diagnostics.error('parse.action-refusal', 'Expected a phrase key after the colon.', lineSpan(line));
+            return null;
+        }
+        return { kind: 'when', slot: null, condition, phraseKey: key.text, span: lineSpan(line) };
+    }
+    /** `define behavior <name> from "<module>"` — CapabilityBehavior hatch. */
+    parseDefineBehaviorHatch() {
+        const line = this.lines[this.pos];
+        const c = new Cursor(line.tokens, line);
+        c.next();
+        c.next(); // define behavior
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.behavior-name', 'Expected a behavior name after `define behavior`.', c.restSpan());
+            this.pos++;
+            return null;
+        }
+        return this.parseHatchTail(line, c, 'behavior', nameTok.text);
+    }
+    /** Shared `from "<module>"` tail for action/behavior hatches. */
+    parseHatchTail(line, c, hatchKind, name) {
+        this.pos++;
+        if (!c.matchWord('from')) {
+            this.diagnostics.error('parse.hatch-from', 'Expected `from "<module>"` in the hatch declaration.', c.restSpan());
+            return null;
+        }
+        const mod = c.next();
+        if (!mod || mod.kind !== 'string') {
+            this.diagnostics.error('parse.hatch-module', 'Expected a quoted module path after `from`.', c.restSpan());
+            return null;
+        }
+        return { kind: 'define-hatch', hatchKind, name, modulePath: mod.text, span: lineSpan(line) };
+    }
+    /** `define sequence <name>` … steps … `end sequence` — timeline (§2.5/§3.3). */
+    parseDefineSequence() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next();
+        c.next(); // define sequence
+        const name = [];
+        while (!c.atEnd() && c.peek().kind === 'word')
+            name.push(c.next().text);
+        if (name.length === 0) {
+            this.diagnostics.error('parse.sequence-name', 'Expected a sequence name after `define sequence`.', c.restSpan());
+        }
+        const steps = [];
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent === 0)
+                break;
+            const sc = new Cursor(line.tokens, line);
+            let timing = null;
+            let turns = 0;
+            let owner = null;
+            let state = null;
+            if (sc.isWord('at') && sc.isWord('turn', 1)) {
+                sc.next();
+                sc.next();
+                const n = sc.next();
+                if (n && n.kind === 'number') {
+                    timing = 'at-turn';
+                    turns = Number(n.text);
+                }
+            }
+            else if (line.tokens[0]?.kind === 'number' && line.tokens[1]?.text === 'turns' && line.tokens[2]?.text === 'later') {
+                timing = 'later';
+                turns = Number(line.tokens[0].text);
+            }
+            else if (sc.isWord('when')) {
+                // `when <owner> becomes <state>` — state anchor (ratchet D10).
+                sc.next();
+                owner = this.parseNameRef(sc, (t) => t.kind === 'word' && t.text === 'becomes');
+                if (sc.matchWord('becomes')) {
+                    const st = sc.next();
+                    if (st && st.kind === 'word') {
+                        timing = 'becomes';
+                        state = st.text;
+                    }
+                    else {
+                        this.diagnostics.error('parse.sequence-anchor', 'Expected a state name after `becomes`.', sc.restSpan());
+                    }
+                }
+                else {
+                    this.diagnostics.error('parse.sequence-anchor', 'Expected `when <owner> becomes <state>` in the step anchor.', sc.restSpan());
+                }
+            }
+            if (!timing) {
+                this.diagnostics.error('parse.sequence-step', 'Expected `at turn <n>`, `<n> turns later`, or `when <owner> becomes <state>` to open a sequence step.', lineSpan(line));
+                this.pos++;
+                continue;
+            }
+            this.pos++;
+            const body = this.parseStatements(line.indent, 'sequence');
+            steps.push({ kind: 'sequence-step', timing, turns, owner, state, body, span: lineSpan(line) });
+        }
+        const endSpan = this.consumeEnd('sequence', headLine);
+        return { kind: 'define-sequence', name, steps, span: (0, span_1.mergeSpans)(lineSpan(headLine), endSpan) };
+    }
+    // ------------------------------------------------------------- on clause
+    /**
+     * `on <verb> it` (intercept) / `after <verb> it` (react, ratchet D3) /
+     * `on every turn` — with `while <cond>` on any binding and the `, once`
+     * clause modifier (D5). Terminated by `end on` / `end after`.
+     */
+    parseOnClause(indent, clauseKind) {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.matchWord(clauseKind);
+        const action = c.next();
+        let actionWord = '';
+        if (action && action.kind === 'word') {
+            actionWord = action.text;
+        }
+        else {
+            this.diagnostics.error('parse.on-action', `Expected an action word after \`${clauseKind}\`.`, lineSpan(headLine));
+        }
+        let binding = 'it';
+        let role = null;
+        let condition = null;
+        let once = false;
+        let ordering = null;
+        if (actionWord === 'every' && c.isWord('turn')) {
+            // `on every turn [while <condition>] [, once]` (§3.3 + D5).
+            c.next();
+            binding = 'every-turn';
+            actionWord = 'every-turn';
+            if (clauseKind === 'after') {
+                this.diagnostics.error('parse.after-every-turn', '`after every turn` is not a form — every-turn clauses are `on every turn` (they are not reactions to an action).', lineSpan(headLine));
+            }
+        }
+        else if (c.matchWord('anything')) {
+            // `on <action> anything as the <role>` (design.md §2.2 role binding).
+            binding = 'role';
+            if (!c.matchWord('as') || !c.matchWord('the')) {
+                this.diagnostics.error('parse.on-role', 'Expected `as the <role>` after `anything`.', c.restSpan());
+            }
+            const roleTok = c.next();
+            if (roleTok && roleTok.kind === 'word') {
+                role = roleTok.text;
+            }
+            else {
+                this.diagnostics.error('parse.on-role', 'Expected a role name after `as the`.', c.restSpan());
+            }
+        }
+        else {
+            if (!c.matchWord('it')) {
+                this.diagnostics.error('parse.on-target', `Expected \`it\`, \`anything as the <role>\`, or \`every turn\` in the \`${clauseKind}\` header.`, c.restSpan());
+            }
+        }
+        // `while <condition>` — legal on every binding (ownership package).
+        if (c.matchWord('while')) {
+            condition = this.parseCondition(c, headLine);
+        }
+        // Comma modifiers: `, once` (D5) and `, before/after <trait>` ordering (§2.2).
+        while (c.peek()?.kind === 'comma') {
+            c.next();
+            const mod = c.next();
+            if (mod && mod.kind === 'word' && mod.text === 'once') {
+                once = true;
+            }
+            else if (mod && (mod.text === 'before' || mod.text === 'after')) {
+                const traitTok = c.next();
+                if (traitTok && traitTok.kind === 'word') {
+                    ordering = { relation: mod.text, trait: traitTok.text };
+                }
+                else {
+                    this.diagnostics.error('parse.on-ordering', `Expected a trait name after \`${mod.text}\`.`, c.restSpan());
+                }
+            }
+            else {
+                this.diagnostics.error('parse.on-modifier', 'Expected `once`, `before <trait>`, or `after <trait>` after the comma.', mod?.span ?? c.restSpan());
+            }
+        }
+        const body = this.parseStatements(headLine.indent, clauseKind);
+        const endSpan = this.consumeEnd(clauseKind, headLine);
+        return {
+            kind: 'on-clause',
+            clauseKind,
+            action: actionWord,
+            binding,
+            role,
+            condition,
+            once,
+            ordering,
+            body,
+            span: (0, span_1.mergeSpans)(lineSpan(headLine), endSpan),
+        };
+    }
+    // ------------------------------------------------------------ statements
+    /**
+     * Parse statement lines until an `end`/`else`/`or`/`when`-arm boundary at
+     * or below `openIndent` is reached. The terminator line is NOT consumed.
+     */
+    parseStatements(openIndent, blockKeyword) {
+        const body = [];
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent <= openIndent)
+                break;
+            if (isEndLine(line) || ((firstWord(line) === 'else' || firstWord(line) === 'or') && line.tokens.length === 1))
+                break;
+            const stmt = this.parseStatement(line, blockKeyword);
+            if (stmt)
+                body.push(stmt);
+        }
+        return body;
+    }
+    parseStatement(line, blockKeyword) {
+        const word = firstWord(line);
+        const c = new Cursor(line.tokens, line);
+        if (word && ORDINALS[word] !== undefined && c.isWord('time', 1)) {
+            return this.parseOrdinalBlock(line);
+        }
+        // `<subject> must <predicate>: <key>` body statement (ratchet D6).
+        if (lineHasMust(line)) {
+            this.pos++;
+            if (blockKeyword === 'after') {
+                this.reportRefusalInAfter(line);
+                return null;
+            }
+            return this.parseMustLine(line);
+        }
+        switch (word) {
+            case 'refuse':
+            case 'phrase': {
+                this.pos++;
+                c.next();
+                // `refuse when <condition>: <key>` — the prohibition form (D6) in
+                // body position; same shape as the define-action line.
+                if (word === 'refuse' && c.isWord('when')) {
+                    if (blockKeyword === 'after') {
+                        this.reportRefusalInAfter(line);
+                        return null;
+                    }
+                    return this.parseRefuseWhenStatement(line);
+                }
+                const key = this.readDottedKey(c);
+                if (!key) {
+                    this.diagnostics.error('parse.phrase-ref', `Expected a phrase key after \`${word}\`.`, c.restSpan());
+                    return null;
+                }
+                const params = this.parseParams(c, line);
+                if (word === 'refuse') {
+                    if (blockKeyword === 'after') {
+                        this.reportRefusalInAfter(line);
+                        return null;
+                    }
+                    return { kind: 'refuse', phraseKey: key, params, span: lineSpan(line) };
+                }
+                const stmtWhen = this.parseStatementWhen(c, line);
+                // Declare-and-emit sugar (§2.6/§3.3): a deeper-indented bare prose
+                // block after `phrase <key>` registers the text under the key.
+                let inlineText = null;
+                const next = this.lines[this.pos];
+                if (next && next.indent > line.indent && !isStatementLine(next)) {
+                    inlineText = this.parseProseParagraph(line.indent + 1, line.indent);
+                }
+                const span = inlineText ? (0, span_1.mergeSpans)(lineSpan(line), inlineText.span) : lineSpan(line);
+                return { kind: 'phrase', phraseKey: key, params, inlineText, stmtWhen, span };
+            }
+            case 'emit': {
+                this.pos++;
+                c.next();
+                const event = [];
+                while (!c.atEnd() && !c.isWord('when'))
+                    event.push(c.next().text);
+                if (event.length === 0) {
+                    this.diagnostics.error('parse.emit', 'Expected an event name after `emit`.', lineSpan(line));
+                    return null;
+                }
+                const stmtWhen = this.parseStatementWhen(c, line);
+                return { kind: 'emit', event, stmtWhen, span: lineSpan(line) };
+            }
+            case 'set': {
+                this.pos++;
+                c.next();
+                const target = this.parseValueExpr(c, line, new Set(['to']));
+                if (!c.matchWord('to')) {
+                    this.diagnostics.error('parse.set-to', 'Expected `to <value>` in the `set` statement.', c.restSpan());
+                    return null;
+                }
+                const value = this.parseValueExpr(c, line, new Set());
+                return { kind: 'set', target, value, span: lineSpan(line) };
+            }
+            case 'change': {
+                this.pos++;
+                c.next();
+                const entity = this.parseNameRef(c, (t) => t.kind === 'word' && t.text === 'to');
+                if (!c.matchWord('to')) {
+                    this.diagnostics.error('parse.change-to', 'Expected `to <state>` in the `change` statement.', c.restSpan());
+                    return null;
+                }
+                const state = c.next();
+                if (!state || state.kind !== 'word') {
+                    this.diagnostics.error('parse.change-state', 'Expected a state name after `to`.', c.restSpan());
+                    return null;
+                }
+                const stmtWhen = this.parseStatementWhen(c, line);
+                return { kind: 'change', entity, state: state.text, stmtWhen, span: lineSpan(line) };
+            }
+            case 'move': {
+                this.pos++;
+                c.next();
+                const entity = this.parseNameRef(c, (t) => t.kind === 'word' && t.text === 'to');
+                if (!c.matchWord('to')) {
+                    this.diagnostics.error('parse.move-to', 'Expected `to <place>` in the `move` statement.', c.restSpan());
+                    return null;
+                }
+                const place = this.parseNameRef(c, (t) => t.kind === 'word' && t.text === 'when');
+                const stmtWhen = this.parseStatementWhen(c, line);
+                return { kind: 'move', entity, place, stmtWhen, span: lineSpan(line) };
+            }
+            case 'remove': {
+                // Z6 (ADR-213 Q3): `remove <entity> [when <cond>]` — out of play
+                // entirely, permanently. No `to` clause (orphaning is not a form).
+                this.pos++;
+                c.next();
+                const entity = this.parseNameRef(c, (t) => t.kind === 'word' && t.text === 'when');
+                if (entity.words.length === 0) {
+                    this.diagnostics.error('parse.remove-entity', 'Expected an entity after `remove`.', c.restSpan());
+                    return null;
+                }
+                const stmtWhen = this.parseStatementWhen(c, line);
+                return { kind: 'remove', entity, stmtWhen, span: lineSpan(line) };
+            }
+            case 'award': {
+                this.pos++;
+                c.next();
+                const expression = [];
+                let once = false;
+                while (!c.atEnd() && !c.isWord('when')) {
+                    const t = c.next();
+                    if (t.kind === 'comma' && c.isWord('once')) {
+                        c.next();
+                        once = true;
+                        break;
+                    }
+                    expression.push(t.text);
+                }
+                const stmtWhen = this.parseStatementWhen(c, line);
+                return { kind: 'award', expression, once, stmtWhen, span: lineSpan(line) };
+            }
+            case 'win':
+            case 'lose': {
+                this.pos++;
+                c.next();
+                const key = c.peek();
+                let phraseKey = null;
+                if (key && key.kind === 'word' && key.text !== 'when') {
+                    phraseKey = key.text;
+                    c.next();
+                }
+                const stmtWhen = this.parseStatementWhen(c, line);
+                return { kind: word, phraseKey, stmtWhen, span: lineSpan(line) };
+            }
+            case 'if':
+                // Removed — given 4 amended (ratchet 2026-07-11).
+                this.diagnostics.error('parse.removed-if', '`if` was removed (given 4 amended) — use a `must` requirement for guards (`it must be hungry: already-fed`), a statement `when` suffix for conditionals (`award X when <condition>`), or `select` for branching.', lineSpan(line));
+                this.pos++;
+                this.recoverPastEndNested('if', line.indent);
+                return null;
+            case 'select':
+                return this.parseSelect(line);
+            case 'each':
+                return this.parseEachBlock(line, blockKeyword);
+            default:
+                this.diagnostics.error('parse.unknown-statement', `Unknown statement \`${word ?? line.raw.trim()}\` in \`${blockKeyword}\` block.`, lineSpan(line));
+                this.pos++;
+                return null;
+        }
+    }
+    /** The statement `when <condition>` suffix (ratchet D7); null when absent. */
+    parseStatementWhen(c, line) {
+        if (!c.matchWord('when'))
+            return null;
+        return this.parseCondition(c, line);
+    }
+    /** `refuse when <condition>: <key>` as a body statement (prohibition, D6). */
+    parseRefuseWhenStatement(line) {
+        const colonIndex = line.tokens.map((t) => t.kind === 'colon').lastIndexOf(true);
+        if (colonIndex === -1 || colonIndex !== line.tokens.length - 2) {
+            this.diagnostics.error('parse.refuse-when', 'Expected `refuse when <condition>: <phrase-key>`.', lineSpan(line));
+            return null;
+        }
+        const keyTok = line.tokens[colonIndex + 1];
+        if (keyTok.kind !== 'word') {
+            this.diagnostics.error('parse.refuse-when', 'Expected a phrase key after the colon.', keyTok.span);
+            return null;
+        }
+        const condCursor = new Cursor(line.tokens.slice(2, colonIndex), line);
+        const condition = this.parseCondition(condCursor, line);
+        return { kind: 'refuse-when', condition, phraseKey: keyTok.text, span: lineSpan(line) };
+    }
+    /** `refuse`/`must` inside an `after` clause — reactions cannot refuse (D3). */
+    reportRefusalInAfter(line) {
+        this.diagnostics.error('parse.react-refusal', 'Refusals (`refuse`, `must`) cannot appear in an `after` clause — reactions run after the action succeeded. Use an `on` clause to intercept.', lineSpan(line));
+    }
+    /**
+     * Read a phrase key: a word, optionally continued by `.`-joined words
+     * (`zoo.pa.closing-3`, design.md §3.3). Returns null when no word follows.
+     */
+    readDottedKey(c) {
+        const first = c.peek();
+        if (!first || first.kind !== 'word')
+            return null;
+        c.next();
+        let key = first.text;
+        while (c.peek()?.kind === 'punct' && c.peek().text === '.' && c.peek(1)?.kind === 'word') {
+            c.next();
+            key += '.' + c.next().text;
+        }
+        return key;
+    }
+    parseParams(c, line) {
+        const params = [];
+        while (c.matchWord('with')) {
+            const start = c.peek();
+            const param = [];
+            while (!c.atEnd() && !(c.peek().kind === 'punct' && c.peek().text === '=')) {
+                param.push(c.next().text);
+            }
+            const eq = c.next();
+            if (!eq) {
+                this.diagnostics.error('parse.param-eq', 'Expected `= <value>` in the `with` binding.', c.restSpan());
+                break;
+            }
+            const value = this.parseValueExpr(c, line, new Set(['with']));
+            params.push({ param, value, span: start ? (0, span_1.mergeSpans)(start.span, value.span) : value.span });
+        }
+        return params;
+    }
+    parseOrdinalBlock(headLine) {
+        this.pos++;
+        const word = firstWord(headLine);
+        const body = [];
+        let span = lineSpan(headLine);
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent <= headLine.indent)
+                break;
+            if (isEndLine(line))
+                break;
+            const stmt = this.parseStatement(line, 'ordinal');
+            if (stmt) {
+                body.push(stmt);
+                span = (0, span_1.mergeSpans)(span, stmt.span);
+            }
+        }
+        return { kind: 'ordinal', ordinal: ORDINALS[word], ordinalWord: word, body, span };
+    }
+    /**
+     * `each <condition-name> … end each` — body-position iteration block
+     * (ratchet E3, 2026-07-12). The body takes the host's statement kit —
+     * `blockKeyword` propagates so refusal legality follows the host clause
+     * (legal in `on`, error in `after`, exactly as outside the block).
+     * The open-condition requirement is the analyzer's gate, not the parser's.
+     */
+    parseEachBlock(headLine, blockKeyword) {
+        this.pos++;
+        const c = new Cursor(headLine.tokens, headLine);
+        c.matchWord('each');
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.each-condition', 'Expected a condition name after `each`.', c.restSpan());
+            this.recoverPastEndNested('each', headLine.indent);
+            return null;
+        }
+        if (!c.atEnd()) {
+            this.diagnostics.error('parse.each-trailing', `Unexpected \`${c.peek().text}\` after the condition name — an \`each\` header is \`each <condition-name>\`.`, c.restSpan());
+        }
+        const body = this.parseStatements(headLine.indent, blockKeyword);
+        const endSpan = this.consumeEnd('each', headLine);
+        return { kind: 'each', condition: nameTok.text, body, span: (0, span_1.mergeSpans)(lineSpan(headLine), endSpan) };
+    }
+    parseSelect(headLine) {
+        this.pos++;
+        const c = new Cursor(headLine.tokens, headLine);
+        c.matchWord('select');
+        if (c.matchWord('on')) {
+            const subject = this.parseValueExpr(c, headLine, new Set());
+            const arms = [];
+            while (this.pos < this.lines.length) {
+                const line = this.lines[this.pos];
+                if (line.indent <= headLine.indent)
+                    break;
+                if (firstWord(line) === 'when') {
+                    this.pos++;
+                    const armCursor = new Cursor(line.tokens, line);
+                    armCursor.next();
+                    const valueTok = armCursor.next();
+                    if (!valueTok || valueTok.kind !== 'word') {
+                        this.diagnostics.error('parse.select-arm', 'Expected a value after `when` in the select arm.', lineSpan(line));
+                        continue;
+                    }
+                    const body = this.parseStatements(line.indent, 'select');
+                    arms.push({ value: valueTok.text, body, span: lineSpan(line) });
+                }
+                else {
+                    this.diagnostics.error('parse.select-body', `Expected \`when <value>\` arm in \`select on\`, got \`${line.raw.trim()}\`.`, lineSpan(line));
+                    this.pos++;
+                }
+            }
+            const endSpan = this.consumeEnd('select', headLine);
+            return { kind: 'select-on', subject, arms, span: (0, span_1.mergeSpans)(lineSpan(headLine), endSpan) };
+        }
+        const strategyTok = c.next();
+        if (!strategyTok || strategyTok.kind !== 'word' || !STRATEGIES.has(strategyTok.text)) {
+            // Z5 applies everywhere strategies are legal (ratchet 2026-07-12) —
+            // a retired adverb here gets the same fix-it as at `define phrase`.
+            if (strategyTok && strategyTok.kind === 'word' && RETIRED_STRATEGIES[strategyTok.text]) {
+                this.diagnostics.error('parse.select-strategy-retired', `\`${strategyTok.text}\` is no longer a strategy adverb — use \`${RETIRED_STRATEGIES[strategyTok.text]}\` (ADR-211 Decision 4).`, strategyTok.span);
+            }
+            else {
+                this.diagnostics.error('parse.select-strategy', 'Expected `on <value>` or a strategy (randomly, cycling, stopping, sticky, first-time) after `select`.', strategyTok?.span ?? lineSpan(headLine));
+            }
+            this.recoverPastEndNested('select', headLine.indent);
+            return null;
+        }
+        const alternatives = [];
+        for (;;) {
+            alternatives.push(this.parseStatements(headLine.indent, 'select'));
+            const line = this.lines[this.pos];
+            if (line && firstWord(line) === 'or' && line.tokens.length === 1 && line.indent === headLine.indent) {
+                this.pos++;
+                continue;
+            }
+            break;
+        }
+        const endSpan = this.consumeEnd('select', headLine);
+        return { kind: 'select-strategy', strategy: strategyTok.text, alternatives, span: (0, span_1.mergeSpans)(lineSpan(headLine), endSpan) };
+    }
+    /** Consume the expected `end <keyword>` line; diagnose a mismatch or absence. */
+    consumeEnd(keyword, openLine) {
+        const line = this.lines[this.pos];
+        if (line && isEndLine(line)) {
+            this.pos++;
+            const kw = line.tokens[1];
+            if (!kw || kw.kind !== 'word' || kw.text !== keyword) {
+                this.diagnostics.error('parse.end-mismatch', `Expected \`end ${keyword}\` to close the block opened at line ${openLine.lineNo}, got \`${line.raw.trim()}\`.`, lineSpan(line));
+            }
+            return lineSpan(line);
+        }
+        this.diagnostics.error('parse.unterminated-block', `Missing \`end ${keyword}\` for the block opened at line ${openLine.lineNo}.`, line ? lineSpan(line) : lineSpan(openLine));
+        return line ? lineSpan(line) : lineSpan(openLine);
+    }
+    /** Error recovery inside statement blocks: skip past a nested `end` at the open indent. */
+    recoverPastEndNested(keyword, openIndent) {
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent <= openIndent && isEndLine(line)) {
+                this.pos++;
+                return;
+            }
+            if (line.indent === 0 && TOP_KEYWORDS.has(firstWord(line) ?? ''))
+                return;
+            this.pos++;
+        }
+    }
+    // ----------------------------------------------------------- expressions
+    /** Parse a name reference: optional article + words until a stop. */
+    parseNameRef(c, stop) {
+        let article = null;
+        const first = c.peek();
+        let span = first ? first.span : null;
+        if (first && first.kind === 'word' && ARTICLES.has(first.text)) {
+            article = first.text;
+            c.next();
+        }
+        const words = [];
+        while (!c.atEnd()) {
+            const t = c.peek();
+            if (t.kind !== 'word' && t.kind !== 'number')
+                break;
+            if (stop(t))
+                break;
+            words.push(t.text);
+            span = span ? (0, span_1.mergeSpans)(span, t.span) : t.span;
+            c.next();
+        }
+        return { kind: 'name', article, words, span: span ?? (0, span_1.spanOf)(c.line.lineNo, 1) };
+    }
+    /**
+     * Parse a value expression: literal, name reference, or possessive chain
+     * (`the player's location`, `its state`). Stops at PHRASE_STOPS or any
+     * word in `extraStops`.
+     */
+    parseValueExpr(c, line, extraStops) {
+        const first = c.peek();
+        if (!first) {
+            this.diagnostics.error('parse.value', 'Expected a value.', lineSpan(line));
+            return { kind: 'bare', words: [], span: lineSpan(line) };
+        }
+        if (first.kind === 'number' || first.kind === 'string') {
+            c.next();
+            return { kind: 'literal', value: first.text, literalKind: first.kind, span: first.span };
+        }
+        // `the match` — the `each`-block binder (ratchet E3, 2026-07-12).
+        // Only the exact form: a following name word keeps the ordinary
+        // reference parse (`the match box` stays an entity name). Position
+        // validity (inside an `each` body) is the analyzer's gate.
+        if (first.kind === 'word' && first.text === 'the') {
+            const m = c.peek(1);
+            const after = c.peek(2);
+            const matchStandsAlone = !after || after.kind !== 'word' || PHRASE_STOPS.has(after.text) || extraStops.has(after.text);
+            if (m && m.kind === 'word' && m.text === 'match' && matchStandsAlone) {
+                c.next();
+                c.next();
+                return { kind: 'match', span: (0, span_1.mergeSpans)(first.span, m.span) };
+            }
+        }
+        // `its <field>` — possessive on `it`.
+        if (first.kind === 'word' && first.text === 'its') {
+            c.next();
+            const field = this.collectWords(c, extraStops);
+            const base = { kind: 'ref', ref: { kind: 'name', article: null, words: ['it'], span: first.span }, span: first.span };
+            return { kind: 'possessive', base, field: field.words, span: (0, span_1.mergeSpans)(first.span, field.span ?? first.span) };
+        }
+        let article = null;
+        let span = first.span;
+        if (first.kind === 'word' && ARTICLES.has(first.text)) {
+            article = first.text;
+            c.next();
+        }
+        const words = [];
+        let possessiveBase = null;
+        while (!c.atEnd()) {
+            const t = c.peek();
+            if (t.kind !== 'word')
+                break;
+            if (PHRASE_STOPS.has(t.text) || extraStops.has(t.text))
+                break;
+            c.next();
+            span = (0, span_1.mergeSpans)(span, t.span);
+            const poss = /^(.*)'s$/.exec(t.text);
+            if (poss) {
+                words.push(poss[1]);
+                possessiveBase = poss[1];
+                break;
+            }
+            words.push(t.text);
+        }
+        if (words.length === 0) {
+            this.diagnostics.error('parse.value', 'Expected a value.', first.span);
+            return { kind: 'bare', words: [], span: first.span };
+        }
+        const refExpr = {
+            kind: 'ref',
+            ref: { kind: 'name', article, words, span },
+            span,
+        };
+        if (possessiveBase !== null) {
+            const field = this.collectWords(c, extraStops);
+            return { kind: 'possessive', base: refExpr, field: field.words, span: (0, span_1.mergeSpans)(span, field.span ?? span) };
+        }
+        return refExpr;
+    }
+    collectWords(c, extraStops) {
+        const words = [];
+        let span = null;
+        while (!c.atEnd()) {
+            const t = c.peek();
+            if (t.kind !== 'word' || PHRASE_STOPS.has(t.text) || extraStops.has(t.text))
+                break;
+            words.push(t.text);
+            span = span ? (0, span_1.mergeSpans)(span, t.span) : t.span;
+            c.next();
+        }
+        return { words, span };
+    }
+    // ------------------------------------------------------------ conditions
+    /** `or`-composed condition (lowest precedence). */
+    parseCondition(c, line) {
+        const left = this.parseConditionAnd(c, line);
+        if (!c.isWord('or'))
+            return left;
+        const operands = [left];
+        let span = left.span;
+        while (c.matchWord('or')) {
+            const right = this.parseConditionAnd(c, line);
+            operands.push(right);
+            span = (0, span_1.mergeSpans)(span, right.span);
+        }
+        return { kind: 'or', operands, span };
+    }
+    parseConditionAnd(c, line) {
+        const left = this.parseConditionUnary(c, line);
+        if (!c.isWord('and'))
+            return left;
+        const operands = [left];
+        let span = left.span;
+        while (c.matchWord('and')) {
+            const right = this.parseConditionUnary(c, line);
+            operands.push(right);
+            span = (0, span_1.mergeSpans)(span, right.span);
+        }
+        return { kind: 'and', operands, span };
+    }
+    parseConditionUnary(c, line) {
+        const t = c.peek();
+        if (!t) {
+            this.diagnostics.error('parse.condition', 'Expected a condition.', lineSpan(line));
+            return { kind: 'condition-ref', name: '', span: lineSpan(line) };
+        }
+        if (t.kind === 'word' && t.text === 'not') {
+            c.next();
+            const operand = this.parseConditionUnary(c, line);
+            return { kind: 'not', operand, span: (0, span_1.mergeSpans)(t.span, operand.span) };
+        }
+        if (t.kind === 'lparen') {
+            c.next();
+            const inner = this.parseCondition(c, line);
+            const close = c.next();
+            if (!close || close.kind !== 'rparen') {
+                this.diagnostics.error('parse.condition-paren', 'Missing closing `)` in the condition.', c.restSpan());
+            }
+            return inner;
+        }
+        // one chance in <n>
+        if (t.kind === 'word' && t.text === 'one' && c.isWord('chance', 1) && c.isWord('in', 2)) {
+            c.next();
+            c.next();
+            c.next();
+            const n = c.next();
+            if (!n || n.kind !== 'number') {
+                this.diagnostics.error('parse.chance', 'Expected a number after `one chance in`.', n?.span ?? c.restSpan());
+                return { kind: 'chance', n: 0, span: t.span };
+            }
+            return { kind: 'chance', n: Number(n.text), span: (0, span_1.mergeSpans)(t.span, n.span) };
+        }
+        // `any <name>` / `no <name>` — existential / negated existential over a
+        // named open condition (ratchet E1/E2, 2026-07-12). Triggers only on the
+        // quantifier plus a single STANDALONE condition name, so a subject that
+        // merely starts with one of these words (`no smoking sign is …`) keeps
+        // its ordinary predicate parse.
+        if (t.kind === 'word' && (t.text === 'any' || t.text === 'no')) {
+            const nameTok = c.peek(1);
+            if (nameTok && nameTok.kind === 'word' && this.isBareConditionRef(c, 1)) {
+                c.next();
+                c.next();
+                return {
+                    kind: t.text === 'any' ? 'any-of' : 'none-of',
+                    condition: nameTok.text,
+                    span: (0, span_1.mergeSpans)(t.span, nameTok.span),
+                };
+            }
+        }
+        // Bare single word (before a connective or end of condition): a named
+        // condition reference, e.g. `while in-darkness`.
+        if (t.kind === 'word' && !ARTICLES.has(t.text) && this.isBareConditionRef(c)) {
+            c.next();
+            return { kind: 'condition-ref', name: t.text, span: t.span };
+        }
+        // <subject> <predicate>
+        const subject = this.parseValueExpr(c, line, new Set());
+        return this.parsePredicate(c, line, subject);
+    }
+    /**
+     * True when the word at `offset` stands alone (connective, comma, or
+     * nothing follows) — a bare condition-name position.
+     */
+    isBareConditionRef(c, offset = 0) {
+        const after = c.peek(offset + 1);
+        if (!after)
+            return true;
+        if (after.kind === 'rparen' || after.kind === 'comma')
+            return true;
+        return after.kind === 'word' && (after.text === 'and' || after.text === 'or' || after.text === 'then');
+    }
+    parsePredicate(c, line, subject) {
+        const t = c.peek();
+        if (!t || t.kind !== 'word') {
+            this.diagnostics.error('parse.predicate', 'Expected a predicate (is, has, holds, wears) after the subject.', t?.span ?? c.restSpan());
+            return { kind: 'predicate', subject, predicate: { kind: 'is', negated: false, value: { kind: 'bare', words: [], span: subject.span }, span: subject.span }, span: subject.span };
+        }
+        if (t.text === 'is') {
+            c.next();
+            const negated = !!c.matchWord('not');
+            if (c.isWord('a') || c.isWord('an')) {
+                c.next();
+                const cls = this.collectWords(c, new Set());
+                return {
+                    kind: 'predicate',
+                    subject,
+                    predicate: { kind: 'is-a', negated, classifier: cls.words, span: cls.span ?? t.span },
+                    span: (0, span_1.mergeSpans)(subject.span, cls.span ?? t.span),
+                };
+            }
+            if (c.isWord('in')) {
+                c.next();
+                const place = this.parseNameRef(c, () => false);
+                return {
+                    kind: 'predicate',
+                    subject,
+                    predicate: { kind: 'is-in', negated, place, span: place.span },
+                    span: (0, span_1.mergeSpans)(subject.span, place.span),
+                };
+            }
+            if (c.isWord('here')) {
+                // Z4 deictic: `<subject> is here` — subject shares the player's
+                // location. Must precede the generic value branch (`here` would
+                // otherwise parse as a bare value word).
+                const hereTok = c.next();
+                return {
+                    kind: 'predicate',
+                    subject,
+                    predicate: { kind: 'is-here', negated, span: hereTok.span },
+                    span: (0, span_1.mergeSpans)(subject.span, hereTok.span),
+                };
+            }
+            const value = this.parseValueExpr(c, line, new Set());
+            return {
+                kind: 'predicate',
+                subject,
+                predicate: { kind: 'is', negated, value, span: value.span },
+                span: (0, span_1.mergeSpans)(subject.span, value.span),
+            };
+        }
+        if (t.text === 'has' || t.text === 'holds' || t.text === 'wears') {
+            c.next();
+            const thing = this.parseNameRef(c, (tok) => tok.kind === 'word' && PHRASE_STOPS.has(tok.text));
+            return {
+                kind: 'predicate',
+                subject,
+                predicate: { kind: t.text, thing, span: thing.span },
+                span: (0, span_1.mergeSpans)(subject.span, thing.span),
+            };
+        }
+        if (t.text === 'can') {
+            // `can see <thing>` / `can reach <thing>` (design.md §2.7, Phase B).
+            c.next();
+            const ability = c.next();
+            if (!ability || ability.kind !== 'word' || (ability.text !== 'see' && ability.text !== 'reach')) {
+                this.diagnostics.error('parse.predicate-can', 'Expected `see` or `reach` after `can`.', ability?.span ?? c.restSpan());
+                return { kind: 'condition-ref', name: 'can', span: t.span };
+            }
+            const thing = this.parseNameRef(c, (tok) => tok.kind === 'word' && PHRASE_STOPS.has(tok.text));
+            return {
+                kind: 'predicate',
+                subject,
+                predicate: { kind: 'can', ability: ability.text, thing, span: (0, span_1.mergeSpans)(ability.span, thing.span) },
+                span: (0, span_1.mergeSpans)(subject.span, thing.span),
+            };
+        }
+        this.diagnostics.error('parse.predicate', `Unknown predicate \`${t.text}\` — expected is, is a, is in, has, holds, wears, or can see/reach.`, t.span);
+        c.next();
+        return { kind: 'condition-ref', name: t.text, span: t.span };
+    }
+}
+//# sourceMappingURL=parser.js.map