@sharpee/chord 3.1.0 → 3.5.0

package/parser.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseStory = parseStory;
-const lexer_1 = require("./lexer");
-const span_1 = require("./span");
+const catalog_js_1 = require("./catalog.js");
+const lexer_js_1 = require("./lexer.js");
+const span_js_1 = require("./span.js");
 const ARTICLES = new Set(['the', 'a', 'an']);
 const DIRECTIONS = new Set([
     'north', 'south', 'east', 'west',
@@ -19,7 +20,9 @@ const ORDINALS = {
 };
 /** 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']);
+/** Stop words ending an emit-payload value expression (ADR-216). */
+const EMIT_VALUE_STOPS = new Set(['and', 'when']);
+const TOP_KEYWORDS = new Set(['story', 'create', 'define', 'when', 'once', 'every', 'import', 'override']);
 /**
  * Parse `.story` source into an AST.
  * @param source full `.story` text
@@ -27,7 +30,7 @@ const TOP_KEYWORDS = new Set(['story', 'create', 'define', 'when', 'once', 'ever
  *   a (possibly partial) StoryFile — callers gate on diagnostics.hasErrors()
  */
 function parseStory(source, diagnostics) {
-    return new Parser((0, lexer_1.lex)(source, diagnostics), diagnostics).parseFile();
+    return new Parser((0, lexer_js_1.lex)(source, diagnostics), diagnostics).parseFile();
 }
 /** Cursor over one line's tokens. */
 class Cursor {
@@ -62,14 +65,14 @@ class Cursor {
     restSpan() {
         const t = this.peek();
         if (t)
-            return (0, span_1.mergeSpans)(t.span, this.tokens[this.tokens.length - 1].span);
+            return (0, span_js_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);
+        return (0, span_js_1.spanOf)(line.lineNo, line.indent + 1, Math.max(1, line.raw.trim().length));
+    return (0, span_js_1.mergeSpans)(line.tokens[0].span, line.tokens[line.tokens.length - 1].span);
 }
 function firstWord(line) {
     const t = line.tokens[0];
@@ -79,6 +82,15 @@ function firstWord(line) {
 function isEndLine(line) {
     return firstWord(line) === 'end';
 }
+/**
+ * True for any `##`-prefixed line at any indent (ADR-249). In code
+ * positions this is always an error — comments are only legal flagged
+ * (indent 0) and between top-level constructs. Prose positions never
+ * call this: an indented `##` in prose renders verbatim (§5.2 opacity).
+ */
+function looksLikeComment(line) {
+    return line.raw.trimStart().startsWith('##');
+}
 /** 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', 'kill',
@@ -123,9 +135,24 @@ class Parser {
     parseFile() {
         let header = null;
         const declarations = [];
-        const start = this.lines[0] ? lineSpan(this.lines[0]) : (0, span_1.spanOf)(1, 1);
+        const start = this.lines[0] ? lineSpan(this.lines[0]) : (0, span_js_1.spanOf)(1, 1);
         while (this.pos < this.lines.length) {
             const line = this.lines[this.pos];
+            if (line.comment) {
+                // ADR-249: comments are legal exactly between top-level
+                // constructs. A following indented line means this comment sits
+                // between a construct's header and its body — inside the block.
+                const next = this.lines[this.pos + 1];
+                if (next && next.indent > 0) {
+                    this.reportCommentInsideBlock(line);
+                    this.pos++;
+                    this.recoverToTopLevel();
+                }
+                else {
+                    this.pos++;
+                }
+                continue;
+            }
             if (line.indent !== 0) {
                 this.diagnostics.error('parse.unexpected-indent', 'Unexpected indentation — expected a top-level declaration.', lineSpan(line));
                 this.recoverToTopLevel();
@@ -151,6 +178,21 @@ class Parser {
                         declarations.push(d);
                     break;
                 }
+                case 'import': {
+                    // ADR-251: `import "<file>"` — the single generalized form.
+                    // Position IS the spliced content's arbitration position (D4).
+                    const d = this.parseImport();
+                    if (d)
+                        declarations.push(d);
+                    break;
+                }
+                case 'override': {
+                    // ADR-255: `override message <alias>` / `override messages <locale>`.
+                    const d = this.parseOverride();
+                    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':
@@ -165,6 +207,18 @@ class Parser {
                     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 'use':
+                    // ADR-215: `use` lives in the story header's indented body, not
+                    // at the top level — a pointed fix-it, never a generic error.
+                    this.diagnostics.error('parse.use-top-level', '`use <extension>` goes inside the story header\'s indented body (with `states:`, scores, …), not at the top level.', lineSpan(line));
+                    this.recoverToTopLevel(true);
+                    break;
+                case 'rank':
+                    // ADR-261 D2: a rung lives in the `use scoring` body, so that the
+                    // ladder cannot drift away from the line that enables it.
+                    this.diagnostics.error('parse.rank-outside-scoring', '`rank "<name>" at <n>` goes in the indented body of the story header\'s `use scoring` line, not at the top level.', 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));
@@ -180,9 +234,18 @@ class Parser {
             kind: 'story-file',
             header,
             declarations,
-            span: last ? (0, span_1.mergeSpans)(start, lineSpan(last)) : start,
+            span: last ? (0, span_js_1.mergeSpans)(start, lineSpan(last)) : start,
         };
     }
+    /** ADR-249: the one inside-block comment diagnostic, with its fix-it. */
+    reportCommentInsideBlock(line) {
+        this.diagnostics.error('parse.comment-inside-block', 'Comments are only legal outside blocks, at the top level of the story file.', lineSpan(line));
+    }
+    /** Report an inside-block comment and consume the line (block parsing continues). */
+    skipCommentInsideBlock(line) {
+        this.reportCommentInsideBlock(line);
+        this.pos++;
+    }
     /** Skip lines until the next top-level keyword at indent 0. */
     recoverToTopLevel(consumeCurrent = false) {
         if (consumeCurrent)
@@ -223,10 +286,121 @@ class Parser {
         const states = [];
         let statesReversible = false;
         const scores = [];
+        const onClauses = [];
+        const uses = [];
+        const usePhrasebooks = [];
+        const ranks = [];
+        let hunger;
         let span = lineSpan(line);
         while (this.pos < this.lines.length && this.lines[this.pos].indent > 0) {
+            const peeked = this.lines[this.pos];
+            const peekedWord = firstWord(peeked);
+            // `use <extension>` — a trusted platform extension (ADR-215): static,
+            // one name per line; the analyzer gates the name against the manifest
+            // registry.
+            if (peekedWord === 'use') {
+                const useLine = this.lines[this.pos++];
+                span = (0, span_js_1.mergeSpans)(span, lineSpan(useLine));
+                const uc = new Cursor(useLine.tokens, useLine);
+                uc.matchWord('use');
+                // ADR-250 D2: exactly the word `phrasebook` selects the two-word
+                // form — `use phrasebook <name> [while <condition>]`, stackable.
+                // Plain `use <extension>` keeps its strict one-word grammar.
+                if (uc.isWord('phrasebook')) {
+                    uc.next();
+                    const bookTok = uc.next();
+                    if (!bookTok || bookTok.kind !== 'word') {
+                        this.diagnostics.error('parse.use-phrasebook', 'Expected `use phrasebook <name> [while <condition>]` — a single kebab-case book name.', uc.restSpan());
+                        continue;
+                    }
+                    let bookCondition = null;
+                    if (uc.isWord('while')) {
+                        uc.next();
+                        const condTokens = [];
+                        while (!uc.atEnd())
+                            condTokens.push(uc.next());
+                        bookCondition = this.parseCondition(new Cursor(condTokens, useLine), useLine);
+                    }
+                    else if (!uc.atEnd()) {
+                        this.diagnostics.error('parse.use-phrasebook', 'Unexpected text after the book name — only `while <condition>` may follow.', uc.restSpan());
+                        continue;
+                    }
+                    usePhrasebooks.push({ name: bookTok.text, condition: bookCondition, span: lineSpan(useLine) });
+                    continue;
+                }
+                const nameTok = uc.next();
+                if (!nameTok || nameTok.kind !== 'word') {
+                    this.diagnostics.error('parse.use', 'Expected `use <extension>` — one extension name per line.', lineSpan(useLine));
+                    continue;
+                }
+                // Optional `, announce <mode>` (ADR-262 D3): how a metering extension's
+                // band crossings narrate. The analyzer validates the mode word.
+                let announce;
+                if (uc.peek()?.kind === 'comma') {
+                    uc.next(); // consume the comma
+                    if (!uc.isWord('announce')) {
+                        this.diagnostics.error('parse.use-announce', 'Expected `announce <mode>` after the comma in a `use` line.', uc.restSpan());
+                        continue;
+                    }
+                    uc.next(); // consume `announce`
+                    const modeTok = uc.next();
+                    if (!modeTok || modeTok.kind !== 'word') {
+                        this.diagnostics.error('parse.use-announce', 'Expected an announce mode (all, collapsed, combined, silent) after `announce`.', uc.restSpan());
+                        continue;
+                    }
+                    announce = modeTok.text;
+                }
+                if (!uc.atEnd()) {
+                    this.diagnostics.error('parse.use', 'Expected `use <extension>[, announce <mode>]` — one extension name per line.', lineSpan(useLine));
+                    continue;
+                }
+                uses.push(announce !== undefined
+                    ? { name: nameTok.text, announce, span: lineSpan(useLine) }
+                    : { name: nameTok.text, span: lineSpan(useLine) });
+                // ADR-261 D2 / ADR-263 D1: `use scoring` (rank ladder) and `use hunger`
+                // (satiety meter) are the `use` lines that take an indented body.
+                // `use combat` and `use state-machines` take none.
+                const body = [];
+                while (this.pos < this.lines.length && this.lines[this.pos].indent > useLine.indent) {
+                    body.push(this.lines[this.pos++]);
+                }
+                if (body.length === 0)
+                    continue;
+                if (nameTok.text === 'scoring') {
+                    for (const bodyLine of body) {
+                        span = (0, span_js_1.mergeSpans)(span, lineSpan(bodyLine));
+                        const rung = this.parseRankLine(bodyLine);
+                        if (rung)
+                            ranks.push(rung);
+                    }
+                }
+                else if (nameTok.text === 'hunger') {
+                    span = (0, span_js_1.mergeSpans)(span, lineSpan(body[body.length - 1]));
+                    hunger = this.parseHungerBody(body);
+                }
+                else {
+                    this.diagnostics.error('parse.use-body', `\`use ${nameTok.text}\` takes no indented body — only \`use scoring\` and \`use hunger\` declare one.`, lineSpan(body[0]));
+                }
+                continue;
+            }
+            // `on every turn [while <cond>][, once]` — the story-owned daemon
+            // (ADR-236 D7, ratchet R4). The only clause form the header hosts;
+            // anything else keeps its owner-attached home.
+            if (peekedWord === 'on' || peekedWord === 'after') {
+                const clause = this.parseOnClause(peeked.indent, peekedWord);
+                span = (0, span_js_1.mergeSpans)(span, clause.span);
+                if (clause.clauseKind === 'on' && clause.binding === 'every-turn') {
+                    onClauses.push(clause);
+                }
+                else if (!(clause.clauseKind === 'after' && clause.binding === 'every-turn')) {
+                    // (`after every turn` already got its own parse error inside
+                    // parseOnClause — don't stack a second diagnostic on it.)
+                    this.diagnostics.error('parse.story-clause', 'The story header hosts only `on every turn` clauses (ADR-236 D7) — action and event clauses belong to the entity they are about.', clause.span);
+                }
+                continue;
+            }
             const fieldLine = this.lines[this.pos++];
-            span = (0, span_1.mergeSpans)(span, lineSpan(fieldLine));
+            span = (0, span_js_1.mergeSpans)(span, lineSpan(fieldLine));
             const key = firstWord(fieldLine);
             // `states[, reversible]: a, b` — story phases (ratchet D2/D4).
             if (key === 'states') {
@@ -246,6 +420,13 @@ class Parser {
                     scores.push(s);
                 continue;
             }
+            // A rung outside a `use scoring` body (ADR-261 D2). Placing the ladder
+            // under the line that enables it is what stops a ladder silently doing
+            // nothing, so a stray rung is an error rather than a floating field.
+            if (key === 'rank') {
+                this.diagnostics.error('parse.rank-outside-scoring', '`rank "<name>" at <n>` belongs in the indented body of a `use scoring` line.', lineSpan(fieldLine));
+                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));
@@ -254,7 +435,126 @@ class Parser {
             const colonAt = fieldLine.raw.indexOf(':');
             fields[key] = fieldLine.raw.slice(colonAt + 1).trim();
         }
-        return { kind: 'story-header', title, author, fields, states, statesReversible, scores, span };
+        return { kind: 'story-header', title, author, fields, states, statesReversible, scores, onClauses, uses, usePhrasebooks, ranks, ...(hunger !== undefined ? { hunger } : {}), span };
+    }
+    /**
+     * The indented `use hunger` body (ADR-263 D1): `grows N each turn`,
+     * `<band> at <n> [says <key>]` rungs, and `fatal at N`.
+     */
+    parseHungerBody(body) {
+        let grows;
+        let fatal;
+        const rungs = [];
+        for (const line of body) {
+            const first = firstWord(line);
+            if (first === 'grows') {
+                const c = new Cursor(line.tokens, line);
+                c.matchWord('grows');
+                const nTok = c.next();
+                if (!nTok || nTok.kind !== 'number' || !c.matchWord('each') || !c.matchWord('turn') || !c.atEnd()) {
+                    this.diagnostics.error('parse.hunger-grows', 'Expected `grows <number> each turn`.', lineSpan(line));
+                    continue;
+                }
+                grows = Number(nTok.text);
+            }
+            else if (first === 'fatal') {
+                const c = new Cursor(line.tokens, line);
+                c.matchWord('fatal');
+                if (!c.matchWord('at')) {
+                    this.diagnostics.error('parse.hunger-fatal', 'Expected `fatal at <number>`.', lineSpan(line));
+                    continue;
+                }
+                const nTok = c.next();
+                if (!nTok || nTok.kind !== 'number' || !c.atEnd()) {
+                    this.diagnostics.error('parse.hunger-fatal', 'Expected `fatal at <number>`.', lineSpan(line));
+                    continue;
+                }
+                fatal = Number(nTok.text);
+            }
+            else {
+                const rung = this.parseMeterRungLine(line);
+                if (rung)
+                    rungs.push(rung);
+            }
+        }
+        return { grows, fatal, rungs, span: lineSpan(body[0]) };
+    }
+    /**
+     * `<band> at <n> [says <key>]` — one rung of a metering body (ADR-263 D1).
+     * The band is a bareword and doubles as the band id.
+     */
+    parseMeterRungLine(line) {
+        const c = new Cursor(line.tokens, line);
+        const bandTok = c.next();
+        if (!bandTok || bandTok.kind !== 'word') {
+            this.diagnostics.error('parse.hunger-body', 'The `use hunger` body holds `grows N each turn`, `<band> at <n> [says <key>]` rungs, and `fatal at N`.', lineSpan(line));
+            return null;
+        }
+        if (!c.matchWord('at')) {
+            this.diagnostics.error('parse.meter-threshold', 'Expected `at <number>` after the band name.', c.restSpan());
+            return null;
+        }
+        const thresholdTok = c.next();
+        if (!thresholdTok || thresholdTok.kind !== 'number') {
+            this.diagnostics.error('parse.meter-threshold', 'Expected a number after `at`.', c.restSpan());
+            return null;
+        }
+        let phraseKey;
+        if (c.isWord('says')) {
+            c.next();
+            const keyTok = c.next();
+            if (!keyTok || keyTok.kind !== 'word') {
+                this.diagnostics.error('parse.meter-says', 'Expected a phrase key after `says`.', c.restSpan());
+                return null;
+            }
+            phraseKey = keyTok.text;
+        }
+        if (!c.atEnd()) {
+            this.diagnostics.error('parse.meter-extra', 'Unexpected text after the rung — the line is `<band> at <n> [says <key>]`.', c.restSpan());
+            return null;
+        }
+        return { kind: 'meter-rung', band: bandTok.text, threshold: Number(thresholdTok.text), phraseKey, span: lineSpan(line) };
+    }
+    /**
+     * `rank "<name>" at <n> [says <key>]` — one rung of the ladder, from the
+     * indented `use scoring` body (ADR-261 D2/D7).
+     */
+    parseRankLine(line) {
+        const c = new Cursor(line.tokens, line);
+        if (!c.matchWord('rank')) {
+            this.diagnostics.error('parse.use-scoring-body', 'The `use scoring` body holds only `rank "<name>" at <n> [says <key>]` lines.', lineSpan(line));
+            return null;
+        }
+        const nameTok = c.peek();
+        if (!nameTok || nameTok.kind !== 'string') {
+            this.diagnostics.error('parse.rank-name', 'Expected a quoted rank name after `rank` — rank prose is author content, written the way entity names are.', c.restSpan());
+            return null;
+        }
+        c.next();
+        if (!c.matchWord('at')) {
+            this.diagnostics.error('parse.rank-threshold', 'Expected `at <number>` after the rank name — a threshold is absolute points, never a percentage of max.', c.restSpan());
+            return null;
+        }
+        const thresholdTok = c.next();
+        if (!thresholdTok || thresholdTok.kind !== 'number') {
+            this.diagnostics.error('parse.rank-threshold', 'Expected a number after `at`.', c.restSpan());
+            return null;
+        }
+        let phraseKey;
+        if (c.isWord('says')) {
+            c.next();
+            const keyTok = c.next();
+            if (!keyTok || keyTok.kind !== 'word') {
+                this.diagnostics.error('parse.rank-says', 'Expected a phrase key after `says` — a kebab-case key in the story\'s own phrase namespace.', c.restSpan());
+                return null;
+            }
+            phraseKey = keyTok.text;
+        }
+        if (!c.atEnd()) {
+            this.diagnostics.error('parse.rank-extra', 'Unexpected text after the rung — the line is `rank "<name>" at <n> [says <key>]`.', c.restSpan());
+            return null;
+        }
+        return { kind: 'rank', name: nameTok.text, threshold: Number(thresholdTok.text), phraseKey, span: lineSpan(line) };
     }
     /**
      * Parse the tail of a `states` line after the `states` word:
@@ -313,10 +613,13 @@ class Parser {
             kind: 'create',
             name,
             aka: [],
+            pronouns: [],
             compositions: [],
+            startsStates: [],
             placement: null,
             wears: [],
             carries: [],
+            containing: [],
             exits: [],
             blockedExits: [],
             deadlyExits: [],
@@ -334,7 +637,7 @@ class Parser {
         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));
+            decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
             const word = firstWord(line);
             const cur = new Cursor(line.tokens, line);
             if (word === 'aka') {
@@ -342,6 +645,20 @@ class Parser {
                 cur.matchWord('aka');
                 decl.aka.push(...this.parseCommaWords(cur));
             }
+            else if (word === 'pronouns') {
+                // ADR-242 D5: `pronouns <word>` — one word (a standard set or a
+                // `define pronouns` name). Person-only legality, word resolution,
+                // and duplicate-line rejection are the analyzer's gates.
+                this.pos++;
+                cur.matchWord('pronouns');
+                const wordTok = cur.next();
+                if (!wordTok || wordTok.kind !== 'word' || !cur.atEnd()) {
+                    this.diagnostics.error('parse.pronouns-word', 'Expected one pronoun-set word after `pronouns` (e.g. `pronouns she`).', lineSpan(line));
+                }
+                else {
+                    decl.pronouns.push({ word: wordTok.text.toLowerCase(), span: lineSpan(line) });
+                }
+            }
             else if (word === 'states' && (line.tokens[1]?.kind === 'colon' || line.tokens[1]?.kind === 'comma')) {
                 this.pos++;
                 cur.next();
@@ -369,7 +686,20 @@ class Parser {
                 cur.matchWord('carries');
                 decl.carries.push(this.parseNameRef(cur, () => false));
             }
+            else if (word === 'containing') {
+                // ADR-236 D2 (ratchet R2): region membership — `containing the
+                // Clearing, the Forest Path, and the Canyon View`. Additive across
+                // lines; region-block-only legality is the analyzer's gate.
+                this.pos++;
+                cur.matchWord('containing');
+                decl.containing.push(...this.parseNameRefList(cur, line));
+            }
             else if (word === 'starts' && cur.isWord('in', 1)) {
+                // The `starts` dispatch is one-token lookahead (ADR-231 D5a):
+                // `starts in <place>` is placement (here); `starts <known-state>` is
+                // an initializer clause, handled by the composition-line fallthrough
+                // below (parseCompositionLine's `starts` branch — same branch that
+                // rejects unknown words after `starts`).
                 this.pos++;
                 cur.next();
                 cur.next();
@@ -426,8 +756,26 @@ class Parser {
                 this.pos++;
                 cur.next();
                 cur.next();
-                const to = this.parseNameRef(cur, () => false);
-                decl.exits.push({ kind: 'exit', direction: word, to, span: lineSpan(line) });
+                // `through` is reserved on exit lines as the door tail (ADR-234 D1,
+                // ratchet R2) — it stops the destination name.
+                const to = this.parseNameRef(cur, (t) => t.kind === 'word' && t.text === 'through');
+                let via = null;
+                if (cur.matchWord('through')) {
+                    const doorRef = this.parseNameRef(cur, () => false);
+                    if (doorRef.words.length === 0) {
+                        this.diagnostics.error('parse.exit-through', 'Expected a door name after `through` (e.g. `north to the Hall through the oak door`).', lineSpan(line));
+                    }
+                    else {
+                        via = doorRef;
+                    }
+                }
+                // ADR-234 D4: `, one-way` is reserved (traversable in the written
+                // direction only) but NOT wired — a legible reservation error, not
+                // a generic parse failure, until its own ratchet entry lands.
+                if (cur.peek()?.kind === 'comma' && cur.isWord('one-way', 1)) {
+                    this.diagnostics.error('parse.exit-one-way-reserved', '`, one-way` is reserved but not yet wired — exits and doors are bidirectional for now.', lineSpan(line));
+                }
+                decl.exits.push({ kind: 'exit', direction: word, to, via, span: lineSpan(line) });
             }
             else if (word && DIRECTIONS.has(word) && cur.isWord('is', 1) && cur.isWord('blocked', 2)) {
                 this.pos++;
@@ -465,7 +813,7 @@ class Parser {
                 }
                 else {
                     this.pos++;
-                    decl.compositions.push(...this.parseCompositionLine(cur, line));
+                    decl.compositions.push(...this.parseCompositionLine(cur, line, decl.startsStates));
                 }
             }
             else {
@@ -477,7 +825,7 @@ class Parser {
                         ...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),
+                        span: (0, span_js_1.mergeSpans)(decl.description.span, prose.span),
                     };
                 }
                 else {
@@ -513,12 +861,12 @@ class Parser {
             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') {
+        const key = this.readLabelKey(c); // label-key = single WORD (ADR-254; readLabelKey rejects dots)
+        if (!key) {
             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) };
+        return { kind: 'blocked-exit', direction, phraseKey: key, condition, span: lineSpan(line) };
     }
     parseDeadlyExit(direction, line) {
         // <direction> is deadly [while <condition>]: <phrase-key> (ADR-227) —
@@ -539,17 +887,52 @@ class Parser {
             this.diagnostics.error('parse.deadly-exit', 'Expected `: <phrase-key>` after `is deadly`.', lineSpan(line));
             return null;
         }
-        const key = c.next();
-        if (!key || key.kind !== 'word') {
+        const key = this.readLabelKey(c); // label-key = single WORD (ADR-254; readLabelKey rejects dots)
+        if (!key) {
             this.diagnostics.error('parse.deadly-exit', 'Expected a phrase key after `is deadly:`.', lineSpan(line));
             return null;
         }
-        return { kind: 'deadly-exit', direction, phraseKey: key.text, condition, span: lineSpan(line) };
+        return { kind: 'deadly-exit', direction, phraseKey: key, condition, span: lineSpan(line) };
     }
-    parseCompositionLine(c, line) {
+    parseCompositionLine(c, line, startsStates) {
         const items = [];
         while (!c.atEnd()) {
             const startTok = c.peek();
+            // `starts <state>` initializer clause (ADR-231 D5a) — one-token
+            // lookahead on the `starts` word Chord already owns: a known state
+            // word (`locked`, `open`, …) initializes the paired trait's initial
+            // value; `in` is the placement line's spelling and can't ride a
+            // composition list; anything else is its own parse error, never a
+            // silent pass into trait-name resolution.
+            if (c.isWord('starts')) {
+                const startsTok = c.next();
+                const stateTok = c.peek();
+                if (stateTok && stateTok.kind === 'word' && catalog_js_1.STARTS_STATE_PAIRINGS.has(stateTok.text)) {
+                    c.next();
+                    startsStates.push({
+                        kind: 'starts-state',
+                        state: stateTok.text,
+                        span: (0, span_js_1.mergeSpans)(startsTok.span, stateTok.span),
+                    });
+                    if (c.peek()?.kind === 'comma') {
+                        c.next();
+                        continue;
+                    }
+                    break;
+                }
+                if (stateTok && stateTok.kind === 'word' && stateTok.text === 'in') {
+                    this.diagnostics.error('parse.starts-state', '`starts in <place>` is a placement line of its own — it cannot ride a composition list.', (0, span_js_1.mergeSpans)(startsTok.span, stateTok.span));
+                }
+                else {
+                    const known = [...catalog_js_1.STARTS_STATE_PAIRINGS.keys()].join(', ');
+                    this.diagnostics.error('parse.starts-state', stateTok
+                        ? `\`${stateTok.text}\` is not a state \`starts\` can initialize — known states: ${known} (placement is \`starts in <place>\`).`
+                        : `Expected a state after \`starts\` — known states: ${known} (placement is \`starts in <place>\`).`, stateTok ? stateTok.span : startsTok.span);
+                }
+                while (!c.atEnd())
+                    c.next(); // resynchronize: one mistake, one diagnostic
+                break;
+            }
             let article = null;
             const first = c.peek();
             if (first && first.kind === 'word' && ARTICLES.has(first.text)) {
@@ -583,7 +966,7 @@ class Parser {
                 words,
                 config,
                 condition,
-                span: (0, span_1.mergeSpans)(startTok.span, endTok.span),
+                span: (0, span_js_1.mergeSpans)(startTok.span, endTok.span),
             });
             if (c.peek()?.kind === 'comma')
                 c.next();
@@ -599,6 +982,33 @@ class Parser {
         const settings = [];
         for (;;) {
             const startTok = c.peek();
+            // Ratchet R3 (ADR-234 D6): an article directly after `with`/`and`
+            // starts the adjective's single-entity config value — no keyword
+            // (`lockable with the iron key`). Keyed named fields (`with food the
+            // handful of feed` on authored traits) still parse below: their key
+            // words come first, so the article is not in first position.
+            if (startTok && startTok.kind === 'word' && ARTICLES.has(startTok.text)) {
+                c.next(); // article
+                const nameWords = [];
+                let lastTok = startTok;
+                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: (0, span_js_1.mergeSpans)(startTok.span, lastTok.span),
+                });
+                if (!c.matchWord('and'))
+                    break;
+                continue;
+            }
             const key = [];
             while (!c.atEnd() && c.peek().kind === 'word' && !c.isWord('and') && !c.isWord('while')) {
                 const t = c.peek();
@@ -628,11 +1038,65 @@ class Parser {
                     this.diagnostics.error('parse.config-value', 'Expected an entity name after the article.', c.restSpan());
                     break;
                 }
+                // Ratchet R3 (ADR-234 D6): the `key`/`tool` config keywords are
+                // removed — the entity is written directly after `with`. One form
+                // per concept (Given 7); the fix-it names the replacement.
+                if (key.length === 1 && (key[0] === 'key' || key[0] === 'tool')) {
+                    this.diagnostics.error('parse.removed-config-keyword', `\`with ${key[0]} the …\` was removed (ratchet R3) — write the entity directly: \`with the ${nameWords.join(' ')}\`.`, startTok ? (0, span_js_1.mergeSpans)(startTok.span, lastTok.span) : lastTok.span);
+                    if (!c.matchWord('and'))
+                        break;
+                    continue;
+                }
                 settings.push({
                     key,
                     value: nameWords.join(' '),
                     valueKind: 'name',
-                    span: startTok ? (0, span_1.mergeSpans)(startTok.span, lastTok.span) : lastTok.span,
+                    span: startTok ? (0, span_js_1.mergeSpans)(startTok.span, lastTok.span) : lastTok.span,
+                });
+                if (!c.matchWord('and'))
+                    break;
+                continue;
+            }
+            // `[ … ]` list value (ADR-215): a bracketed, comma-separated list of
+            // name references (`patrol route [Hall, Study, Hall]`). Narrower than
+            // ADR-216's statement-payload arrays — config lists hold names only.
+            const bracketTok = c.peek();
+            if (bracketTok && bracketTok.kind === 'lbracket' && key.length > 0) {
+                c.next(); // [
+                const listValues = [];
+                for (;;) {
+                    if (c.peek()?.kind === 'rbracket')
+                        break;
+                    const ref = this.parseNameRef(c, () => false);
+                    if (ref.words.length === 0) {
+                        this.diagnostics.error('parse.config-list', 'Expected an entity name inside the `[ … ]` list.', c.restSpan());
+                        while (!c.atEnd() && c.peek().kind !== 'rbracket')
+                            c.next();
+                        break;
+                    }
+                    listValues.push(ref);
+                    if (c.peek()?.kind === 'comma')
+                        c.next();
+                    else
+                        break;
+                }
+                const close = c.next();
+                let lastSpan = bracketTok.span;
+                if (!close || close.kind !== 'rbracket') {
+                    this.diagnostics.error('parse.config-list', 'Expected `]` to close the list.', c.restSpan());
+                }
+                else {
+                    lastSpan = close.span;
+                }
+                if (listValues.length === 0) {
+                    this.diagnostics.error('parse.config-list', 'A `[ … ]` list needs at least one entry.', lastSpan);
+                }
+                settings.push({
+                    key,
+                    value: '',
+                    valueKind: 'list',
+                    listValues,
+                    span: startTok ? (0, span_js_1.mergeSpans)(startTok.span, lastSpan) : lastSpan,
                 });
                 if (!c.matchWord('and'))
                     break;
@@ -648,7 +1112,7 @@ class Parser {
                 key,
                 value: valueTok.text,
                 valueKind: valueTok.kind,
-                span: startTok ? (0, span_1.mergeSpans)(startTok.span, valueTok.span) : valueTok.span,
+                span: startTok ? (0, span_js_1.mergeSpans)(startTok.span, valueTok.span) : valueTok.span,
             });
             if (!c.matchWord('and'))
                 break;
@@ -658,7 +1122,8 @@ class Parser {
     parsePhraseOverride(line) {
         const c = new Cursor(line.tokens, line);
         c.matchWord('phrase');
-        const key = c.next(); // validated by caller
+        // Key word validated by the caller; phrase-key = WORD { "." WORD } (ADR-231 D1b).
+        const key = this.readLabelKey(c);
         // CP3: optional `, <strategy>` (the Z5 adverb set, retired fix-its
         // included) — `phrase present, cycling:`.
         let strategy = null;
@@ -713,11 +1178,11 @@ class Parser {
         const last = variants[variants.length - 1];
         return {
             kind: 'phrase-override',
-            key: key.text,
+            key,
             strategy,
             condition,
             variants,
-            span: (0, span_1.mergeSpans)(lineSpan(line), last?.span ?? lineSpan(line)),
+            span: (0, span_js_1.mergeSpans)(lineSpan(line), last?.span ?? lineSpan(line)),
         };
     }
     /** Same-line phrase text (quoted or bare) was removed — grammar log 2026-07-10. */
@@ -742,6 +1207,33 @@ class Parser {
             out.push(current.join(' '));
         return out;
     }
+    /**
+     * A comma-separated list of entity name references, Oxford-`and` welcome
+     * (`the Clearing, the Forest Path, and the Canyon View`). Each reference
+     * keeps its own article and span; an empty list is a parse error.
+     */
+    parseNameRefList(c, line) {
+        const refs = [];
+        for (;;) {
+            const ref = this.parseNameRef(c, (t) => t.kind === 'word' && t.text === 'and');
+            if (ref.words.length === 0) {
+                this.diagnostics.error('parse.name-list', 'Expected an entity name.', c.atEnd() ? lineSpan(line) : c.restSpan());
+                break;
+            }
+            refs.push(ref);
+            if (c.peek()?.kind === 'comma') {
+                c.next();
+                c.matchWord('and'); // Oxford `and` after the comma
+            }
+            else if (!c.matchWord('and')) {
+                break;
+            }
+        }
+        if (!c.atEnd()) {
+            this.diagnostics.error('parse.name-list', `Unexpected trailing text in name list: \`${c.peek().text}\`.`, c.restSpan());
+        }
+        return refs;
+    }
     parseStateList(c) {
         const out = [];
         while (!c.atEnd()) {
@@ -786,7 +1278,7 @@ class Parser {
             const text = line.raw.trim();
             this.extractMarkers(line, markers);
             current.push(text);
-            span = span ? (0, span_1.mergeSpans)(span, lineSpan(line)) : lineSpan(line);
+            span = span ? (0, span_js_1.mergeSpans)(span, lineSpan(line)) : lineSpan(line);
             first = false;
         }
         if (current.length)
@@ -796,7 +1288,7 @@ class Parser {
             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),
+            span: span ?? (0, span_js_1.spanOf)(this.lines[this.pos - 1]?.lineNo ?? 1, 1),
         };
     }
     /**
@@ -818,7 +1310,7 @@ class Parser {
                 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);
+            span = span ? (0, span_js_1.mergeSpans)(span, lineSpan(line)) : lineSpan(line);
             this.pos++;
             first = false;
         }
@@ -834,14 +1326,14 @@ class Parser {
             form: 'verbatim',
             text: lines.join('\n'),
             markers,
-            span: span ?? (0, span_1.spanOf)(this.lines[this.pos - 1]?.lineNo ?? 1, 1),
+            span: span ?? (0, span_js_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) });
+            into.push({ content: m[1], span: (0, span_js_1.spanOf)(line.lineNo, m.index + 1, m[0].length) });
         }
     }
     /** Error-recovery only: a removed same-line quoted value, kept as prose text. */
@@ -850,7 +1342,7 @@ class Parser {
         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) });
+            markers.push({ content: m[1], span: (0, span_js_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 };
     }
@@ -864,6 +1356,10 @@ class Parser {
                 return this.parseDefineCondition();
             case 'phrase':
                 return this.parseDefinePhrase();
+            case 'phrasebook':
+                // ADR-245/250 D1 (David 2026-07-21) — named, predicated phrase
+                // collections; entries reuse the phrase-override grammar.
+                return this.parseDefinePhrasebook();
             case 'phrases':
                 return this.parseDefinePhrases();
             case 'verb':
@@ -879,8 +1375,15 @@ class Parser {
                 return this.parseDefineTrait();
             case 'action':
                 return this.parseDefineAction();
+            case 'chain':
+                return this.parseDefineChainHatch();
             case 'behavior':
-                return this.parseDefineBehaviorHatch();
+                // ADR-235 D2 (removal, 2026-07-18): the behavior hatch carried no
+                // trait/action binding key, so it structurally could never fire —
+                // removed rather than repaired.
+                this.diagnostics.error('parse.removed-behavior-hatch', '`define behavior … from` was removed (ADR-235 D2) — it had no binding key and could never fire. Author the behavior in-language (`define trait <name>` with `on <verb> it` clauses, composed on the entity), or ship a full action with `define action <name> from "<module>"`.', lineSpan(this.lines[this.pos]));
+                this.pos++;
+                return null;
             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));
@@ -888,6 +1391,29 @@ class Parser {
                 return null;
             case 'sequence':
                 return this.parseDefineSequence();
+            case 'machine':
+                // ADR-215 `use state-machines` depth (spelling A, 2026-07-18) —
+                // the `use` requirement is the analyzer's gate.
+                return this.parseDefineMachine();
+            case 'sound':
+            case 'image':
+            case 'music':
+                // ADR-216 declared assets — DATA references, never hatches.
+                return this.parseDefineAsset(subWord);
+            case 'ambient':
+            case 'layer':
+                // ADR-241 D2 — named family channels (an ambient bed / an image
+                // layer), one-liners beside the asset declarations.
+                return this.parseDefineFamilyChannel(subWord);
+            case 'channel':
+                // ADR-216 custom channels (spelling A, 2026-07-18) — data projections.
+                return this.parseDefineChannel();
+            case 'topics':
+                // ADR-239 D3 (as amended) — the ask/tell topic table block.
+                return this.parseDefineTopics();
+            case 'pronouns':
+                // ADR-242 D7 (ruled Q-1) — named pronoun set, five named rows.
+                return this.parseDefinePronouns();
             default:
                 this.diagnostics.error('parse.unknown-define', `Unknown declaration \`define ${subWord ?? ''}\`.`, lineSpan(line));
                 this.recoverToTopLevel(true);
@@ -917,19 +1443,27 @@ class Parser {
         const c = new Cursor(headLine.tokens, headLine);
         c.next();
         c.next(); // define phrase
-        const keyTok = c.next();
-        let key = keyTok && keyTok.kind === 'word' ? keyTok.text : '';
+        // EBNF: phrase-key = WORD { "." WORD } (ADR-230 D5). Previously the
+        // parser silently registered only the first segment (`if.action.taking`
+        // became `if`), which made story-wide overrides of platform message ids
+        // impossible.
+        const key = this.readLabelKey(c) ?? '';
         if (!key) {
             this.diagnostics.error('parse.phrase-key', 'Expected a phrase key after `define phrase`.', lineSpan(headLine));
+            c.next(); // skip the offending token so header options still parse
         }
-        // EBNF: phrase-key = WORD { "." WORD } (ADR-230 D5). The lexer splits at
-        // dots, so consume `.WORD` segments — previously the parser silently
-        // registered only the first segment (`if.action.taking` became `if`),
-        // which made story-wide overrides of platform message ids impossible.
-        while (key && c.peek()?.kind === 'punct' && c.peek()?.text === '.' && c.peek(1)?.kind === 'word') {
-            c.next(); // consume '.'
-            key += '.' + c.next().text;
-        }
+        const body = this.readPhraseBody(c, headLine, 'phrase');
+        return { kind: 'define-phrase', key, ...body };
+    }
+    /**
+     * Read a phrase body from a header cursor positioned after the key/alias:
+     * the optional `, <strategy>|verbatim` header modifier, an optional trailing
+     * `while <condition>` gate, then the indented variant lines up to
+     * `end <endWord>`. Shared by `define phrase` and ADR-255's `override message`
+     * so the two constructs never drift (ADR-255 D1). Returns the body fields
+     * (the caller supplies the `kind` and key/alias).
+     */
+    readPhraseBody(c, headLine, endWord) {
         let strategy = null;
         let verbatim = false;
         if (c.peek()?.kind === 'comma') {
@@ -959,15 +1493,22 @@ class Parser {
         }
         const variants = [];
         let span = lineSpan(headLine);
+        let flaggedFlushLeft = false;
         for (;;) {
             const line = this.lines[this.pos];
             if (!line) {
-                this.diagnostics.error('parse.unterminated-block', 'Missing `end phrase`.', span);
+                this.diagnostics.error('parse.unterminated-block', `Missing \`end ${endWord}\`.`, span);
                 break;
             }
+            if (line.comment) {
+                // ADR-249 — indented `##` stays prose here; only a flagged
+                // (indent-0) comment line is an inside-block error.
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
             if (isEndLine(line)) {
-                span = (0, span_1.mergeSpans)(span, lineSpan(line));
-                this.consumeEnd('phrase', headLine);
+                span = (0, span_js_1.mergeSpans)(span, lineSpan(line));
+                this.consumeEnd(endWord, headLine);
                 break;
             }
             if (firstWord(line) === 'or' && line.tokens.length === 1) {
@@ -978,19 +1519,153 @@ class Parser {
                 continue;
             }
             if (line.indent === 0 && TOP_KEYWORDS.has(firstWord(line) ?? '')) {
-                this.diagnostics.error('parse.unterminated-block', 'Missing `end phrase`.', span);
+                this.diagnostics.error('parse.unterminated-block', `Missing \`end ${endWord}\`.`, span);
                 break;
             }
+            if (line.indent === 0) {
+                // A flush-left non-keyword line makes zero progress in either
+                // variant parser below (both require depth > 0) — without this
+                // guard the loop appended empty variants until OOM. One diagnostic
+                // for the first offending line; the rest of the flush-left run is
+                // consumed so `end <endWord>` still terminates the block.
+                if (!flaggedFlushLeft) {
+                    flaggedFlushLeft = true;
+                    this.diagnostics.error('parse.phrase-text-indent', `Text must be indented under \`${endWord === 'override' ? 'override message' : 'define phrase'}\`.`, lineSpan(line));
+                }
+                this.pos++;
+                continue;
+            }
             const variant = verbatim ? this.parseVerbatimBlock() : this.parseProseParagraph(1, 0);
             variants.push(variant);
-            span = (0, span_1.mergeSpans)(span, variant.span);
+            span = (0, span_js_1.mergeSpans)(span, variant.span);
+        }
+        return { strategy, verbatim, condition, variants, span };
+    }
+    /**
+     * `define phrasebook <name> [while <condition>] … end phrasebook`
+     * (ADR-250 D1). Entries are phrase-override-shaped lines
+     * (`<key>[, strategy]:` + `or` variants) at one indent level; the
+     * body carries the ADR-249 comment guard like every end-terminated
+     * block. Entry-level `while` parses here (override grammar) and is
+     * gated in the analyzer (`analysis.phrasebook-entry-gate`).
+     */
+    parseDefinePhrasebook() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.matchWord('define');
+        c.matchWord('phrasebook');
+        let name = '';
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.phrasebook-header', 'Expected `define phrasebook <name> [while <condition>]` — a single kebab-case book name.', c.restSpan());
+        }
+        else {
+            name = nameTok.text;
+        }
+        let condition = null;
+        if (c.isWord('while')) {
+            c.next();
+            const condTokens = [];
+            while (!c.atEnd())
+                condTokens.push(c.next());
+            condition = this.parseCondition(new Cursor(condTokens, headLine), headLine);
+        }
+        else if (!c.atEnd()) {
+            this.diagnostics.error('parse.phrasebook-header', 'Unexpected text after the book name — only `while <condition>` may follow.', c.restSpan());
+        }
+        const entries = [];
+        let span = lineSpan(headLine);
+        for (;;) {
+            const line = this.lines[this.pos];
+            if (!line) {
+                this.diagnostics.error('parse.phrasebook-end', 'Missing `end phrasebook`.', span);
+                break;
+            }
+            if (line.comment) {
+                // ADR-249: `##` inside a block is never a comment.
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
+            if (isEndLine(line)) {
+                span = (0, span_js_1.mergeSpans)(span, this.consumeEnd('phrasebook', headLine));
+                break;
+            }
+            if (line.indent === 0) {
+                this.diagnostics.error('parse.phrasebook-end', 'Missing `end phrasebook`.', span);
+                break;
+            }
+            if (line.tokens[0]?.kind !== 'word' || !line.tokens.some((t) => t.kind === 'colon')) {
+                this.diagnostics.error('parse.phrasebook-entry', 'Expected `<key>[, strategy]:` to open a phrasebook entry.', lineSpan(line));
+                this.pos++;
+                continue;
+            }
+            this.pos++;
+            const entry = this.parsePhraseOverride(line);
+            entries.push(entry);
+            span = (0, span_js_1.mergeSpans)(span, entry.span);
+        }
+        return { kind: 'define-phrasebook', name, condition, entries, span };
+    }
+    /**
+     * `import "<file>"` (ADR-251 D1) — the single generalized import form.
+     * The path is extension-free (the compiler appends `.chord` at resolve
+     * time — D2); any string is accepted at parse time. A bare word after
+     * `import` (the removed `phrasebook` sub-word, or anything else) or a
+     * missing string is `parse.import-form`.
+     */
+    parseImport() {
+        const line = this.lines[this.pos++];
+        const c = new Cursor(line.tokens, line);
+        c.matchWord('import');
+        const pathTok = c.next();
+        if (!pathTok || pathTok.kind !== 'string' || !c.atEnd()) {
+            this.diagnostics.error('parse.import-form', 'Expected a quoted file name: `import "<file>"` (no extension — `.chord` is assumed).', c.restSpan());
+            return null;
         }
-        return { kind: 'define-phrase', key, strategy, verbatim, condition, variants, span };
+        return { kind: 'import', path: pathTok.text, span: lineSpan(line) };
     }
     parseDefinePhrases() {
         const headLine = this.lines[this.pos++];
         return this.parsePhrasesBlock(headLine, 2);
     }
+    /**
+     * ADR-255: dispatch the two override forms off the word after `override`.
+     * `override message <alias> … end override` (full phrase body) vs.
+     * `override messages <locale>` (locale block of `alias: text` entries).
+     */
+    parseOverride() {
+        const headLine = this.lines[this.pos];
+        const kindTok = headLine.tokens[1];
+        if (kindTok?.kind === 'word' && kindTok.text === 'messages') {
+            return this.parseOverrideMessages();
+        }
+        if (kindTok?.kind === 'word' && kindTok.text === 'message') {
+            return this.parseOverrideMessage();
+        }
+        this.diagnostics.error('parse.override', 'Expected `override message <alias>` or `override messages <locale>`.', lineSpan(headLine));
+        this.pos++;
+        return null;
+    }
+    /** `override message <alias> [, strategy] [while <cond>] … end override` (ADR-255 D1). */
+    parseOverrideMessage() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next(); // override
+        c.next(); // message
+        const alias = this.readLabelKey(c) ?? '';
+        if (!alias) {
+            this.diagnostics.error('parse.override-alias', 'Expected an override alias after `override message`.', lineSpan(headLine));
+            c.next(); // skip the offending token so header options still parse
+        }
+        const body = this.readPhraseBody(c, headLine, 'override');
+        return { kind: 'override-message', alias, ...body };
+    }
+    /** `override messages <locale>` — a locale block of `alias: text` entries (ADR-255 D1). */
+    parseOverrideMessages() {
+        const headLine = this.lines[this.pos++];
+        const phrases = this.parsePhrasesBlock(headLine, 2);
+        return { kind: 'override-messages', locale: phrases.locale, entries: phrases.entries, span: phrases.span };
+    }
     /**
      * Parse a phrases block from its header line (`define phrases <locale>` at
      * top level, or `phrases <locale>` inside a trait/action, Phase B). The
@@ -1010,16 +1685,18 @@ class Parser {
         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') {
+            const ec = new Cursor(line.tokens, line);
+            const key = this.readLabelKey(ec); // label-key = single WORD (ADR-254; readLabelKey rejects dots)
+            const colon = ec.peek();
+            if (!key || !colon || colon.kind !== 'colon') {
                 this.diagnostics.error('parse.phrase-entry', 'Expected `key: <text>` in the phrases block.', lineSpan(line));
                 this.pos++;
                 continue;
             }
+            ec.next(); // colon
             this.pos++;
             let value;
-            const inline = line.tokens[2];
+            const inline = ec.peek();
             if (inline && inline.kind === 'string') {
                 this.reportSameLineText(inline.span);
                 value = this.textFromString(inline); // recovery: keep the text so analysis continues
@@ -1036,11 +1713,11 @@ class Parser {
             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));
+                    this.diagnostics.error('parse.phrase-entry-empty', `Phrase \`${key}\` 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);
+            entries.push({ key, value, span: (0, span_js_1.mergeSpans)(lineSpan(line), value.span) });
+            span = (0, span_js_1.mergeSpans)(span, entries[entries.length - 1].span);
         }
         return { kind: 'define-phrases', locale, entries, span };
     }
@@ -1074,7 +1751,7 @@ class Parser {
                     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) });
+                pattern.push({ kind: 'slot', word: slot.text, span: (0, span_js_1.mergeSpans)(t.span, close.span) });
             }
             else if (t.kind === 'word') {
                 pattern.push({ kind: 'word', word: t.text, span: t.span });
@@ -1129,6 +1806,10 @@ class Parser {
         });
         while (this.pos < this.lines.length) {
             const line = this.lines[this.pos];
+            if (looksLikeComment(line)) {
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
             if (line.indent === 0) {
                 if (isEndLine(line))
                     break;
@@ -1173,13 +1854,17 @@ class Parser {
             }
         }
         const endSpan = this.consumeEnd('trait', headLine);
-        return build((0, span_1.mergeSpans)(lineSpan(headLine), endSpan));
+        return build((0, span_js_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++];
+            if (looksLikeComment(line)) {
+                this.reportCommentInsideBlock(line);
+                continue;
+            }
             const c = new Cursor(line.tokens, line);
             const name = [];
             while (!c.atEnd() && c.peek().kind === 'word')
@@ -1276,6 +1961,10 @@ class Parser {
             const line = this.lines[this.pos];
             if (line.indent === 0)
                 break; // dedent-terminated (no `end action`, design.md §2.3/§3.4)
+            if (looksLikeComment(line)) {
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
             const word = firstWord(line);
             if (word === 'grammar' && line.tokens.length === 1) {
                 this.pos++;
@@ -1316,9 +2005,9 @@ class Parser {
                     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) };
+                    const key = this.readLabelKey(oc); // label-key = single WORD (ADR-254; readLabelKey rejects dots)
+                    if (key)
+                        otherwise = { phraseKey: key, span: lineSpan(line) };
                     else
                         this.diagnostics.error('parse.action-otherwise', 'Expected a phrase key after `otherwise refuse`.', oc.restSpan());
                 }
@@ -1332,7 +2021,7 @@ class Parser {
                 if (stmt)
                     body.push(stmt);
             }
-            span = (0, span_1.mergeSpans)(span, lineSpan(line));
+            span = (0, span_js_1.mergeSpans)(span, lineSpan(line));
         }
         return { kind: 'define-action', name: nameTok.text, patterns, constraints, musts, refusals, otherwise, scores, phrases, body, span };
     }
@@ -1343,13 +2032,14 @@ class Parser {
      */
     parseMustLine(line) {
         const colonIndex = line.tokens.map((t) => t.kind === 'colon').lastIndexOf(true);
-        if (colonIndex === -1 || colonIndex !== line.tokens.length - 2) {
+        if (colonIndex === -1 || colonIndex >= line.tokens.length - 1) {
             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);
+        const keyCursor = new Cursor(line.tokens.slice(colonIndex + 1), line);
+        const phraseKey = this.readLabelKey(keyCursor); // label-key = single WORD (ADR-254; readLabelKey rejects dots)
+        if (!phraseKey || !keyCursor.atEnd()) {
+            this.diagnostics.error('parse.must', 'Expected a phrase key after the colon in the `must` requirement.', line.tokens[colonIndex + 1].span);
             return null;
         }
         const c = new Cursor(line.tokens.slice(0, colonIndex), line);
@@ -1367,7 +2057,7 @@ class Parser {
         const predicate = this.parseInfinitivePredicate(c, line);
         if (!predicate)
             return null;
-        return { kind: 'must', subject, predicate, phraseKey: keyTok.text, span: lineSpan(line) };
+        return { kind: 'must', subject, predicate, phraseKey, span: lineSpan(line) };
     }
     /** Infinitive predicate after `must`: be / have / hold / wear / see / reach. */
     parseInfinitivePredicate(c, line) {
@@ -1397,7 +2087,7 @@ class Parser {
                     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) };
+                        return { kind: 'is-any', condition: nameTok.text, span: (0, span_js_1.mergeSpans)(anyTok.span, nameTok.span) };
                     }
                 }
                 // `be no <name>` — a negated requirement in disguise (decision 6):
@@ -1427,7 +2117,7 @@ class Parser {
             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) };
+                return { kind: 'can', ability: t.text, thing, span: (0, span_js_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);
@@ -1453,7 +2143,7 @@ class Parser {
                 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) });
+                        parts.push({ kind: 'slot', word: slot.text, span: (0, span_js_1.mergeSpans)(t.span, slot.span) });
                     }
                     else {
                         this.diagnostics.error('parse.action-slot', 'Expected a slot name after `:`.', t.span);
@@ -1502,43 +2192,49 @@ class Parser {
         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') {
+            if (!slot || slot.kind !== 'word' || !colon || colon.kind !== 'colon') {
+                this.diagnostics.error('parse.action-refusal', 'Expected `refuse without <slot>: <phrase-key>`.', lineSpan(line));
+                return null;
+            }
+            const key = this.readLabelKey(c); // label-key = single WORD (ADR-254; readLabelKey rejects dots)
+            if (!key) {
                 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) };
+            return { kind: 'without', slot: slot.text, condition: null, phraseKey: key, 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) {
+        if (colonIndex === -1 || colonIndex >= line.tokens.length - 1) {
             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') {
+        const keyCursor = new Cursor(line.tokens.slice(colonIndex + 1), line);
+        const key = this.readLabelKey(keyCursor); // label-key = single WORD (ADR-254; readLabelKey rejects dots)
+        if (!key || !keyCursor.atEnd()) {
             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) };
+        return { kind: 'when', slot: null, condition, phraseKey: key, span: lineSpan(line) };
     }
-    /** `define behavior <name> from "<module>"` — CapabilityBehavior hatch. */
-    parseDefineBehaviorHatch() {
+    /** `define chain <name> from "<module>"` — a TS chain hatch (ADR-094): the
+     *  named stdlib event chain is replaced by the module's handler. */
+    parseDefineChainHatch() {
         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());
+        c.next(); // define chain
+        const name = this.readLabelKey(c); // curated chain alias, single kebab word (ADR-254)
+        if (!name) {
+            this.diagnostics.error('parse.chain-hatch-name', 'Expected a chain name after `define chain` (e.g. `define chain opened-revealed from "…"`).', c.restSpan());
             this.pos++;
             return null;
         }
-        return this.parseHatchTail(line, c, 'behavior', nameTok.text);
+        return this.parseHatchTail(line, c, 'chain', name);
     }
-    /** Shared `from "<module>"` tail for action/behavior hatches. */
+    /** Shared `from "<module>"` tail for action / chain hatches. */
     parseHatchTail(line, c, hatchKind, name) {
         this.pos++;
         if (!c.matchWord('from')) {
@@ -1569,6 +2265,10 @@ class Parser {
             const line = this.lines[this.pos];
             if (line.indent === 0)
                 break;
+            if (looksLikeComment(line)) {
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
             const sc = new Cursor(line.tokens, line);
             let timing = null;
             let turns = 0;
@@ -1615,7 +2315,138 @@ class Parser {
             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) };
+        return { kind: 'define-sequence', name, steps, span: (0, span_js_1.mergeSpans)(lineSpan(headLine), endSpan) };
+    }
+    /**
+     * `define topics for <entity> … end topics` (ADR-239 D3 as amended) —
+     * the ask/tell topic table: `about` rows in two tiers (entity /
+     * quoted free-text with comma-separated aliases), each answering with
+     * a one-line statement or an indented statement body.
+     */
+    parseDefineTopics() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next();
+        c.next(); // define topics
+        let owner;
+        if (!c.matchWord('for')) {
+            this.diagnostics.error('parse.topics-for', 'Expected `for <entity>` after `define topics`.', c.restSpan());
+            owner = { kind: 'name', article: null, words: [], span: lineSpan(headLine) };
+        }
+        else {
+            owner = this.parseNameRef(c, () => false);
+            if (owner.words.length === 0 || !c.atEnd()) {
+                this.diagnostics.error('parse.topics-for', 'Expected `define topics for <entity>` — the owner name runs to the end of the line.', c.restSpan());
+            }
+        }
+        const decl = { kind: 'define-topics', owner, rows: [], span: lineSpan(headLine) };
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            const word = firstWord(line);
+            const lc = new Cursor(line.tokens, line);
+            if (word === 'end' && lc.isWord('topics', 1)) {
+                this.pos++;
+                decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
+                if (decl.rows.length === 0) {
+                    this.diagnostics.error('parse.topics-empty', 'This `define topics` block declares no rows — add `about …: <response>` rows, or remove the block.', decl.span);
+                }
+                return decl;
+            }
+            if (looksLikeComment(line)) {
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
+            if (line.indent === 0)
+                break; // dedent without `end topics` — reported below
+            decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
+            if (word === 'about') {
+                const row = this.parseTopicRow(line);
+                if (row) {
+                    decl.rows.push(row);
+                    decl.span = (0, span_js_1.mergeSpans)(decl.span, row.span);
+                }
+                continue;
+            }
+            this.diagnostics.error('parse.topics-row', `Unrecognized line in \`define topics\`: \`${line.raw.trim()}\` — expected an \`about …: <response>\` row or \`end topics\`.`, lineSpan(line));
+            this.pos++;
+        }
+        this.diagnostics.error('parse.topics-end', 'Expected `end topics` to close the block.', decl.span);
+        if (decl.rows.length === 0) {
+            this.diagnostics.error('parse.topics-empty', 'This `define topics` block declares no rows — add `about …: <response>` rows, or remove the block.', decl.span);
+        }
+        return decl;
+    }
+    /**
+     * One `about …: <response>` row. Entity tier: `about the <entity>:`.
+     * Free-text tier: `about "<text>"[, "<text>" …]:` — comma-separated
+     * quoted aliases (spelling ruled 2026-07-18). The response is either the
+     * rest of the line (one statement) or an indented statement body.
+     */
+    parseTopicRow(headLine) {
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next(); // about
+        let filter;
+        const first = c.peek();
+        if (first && first.kind === 'string') {
+            c.next();
+            if (first.text.trim() === '') {
+                this.diagnostics.error('parse.topics-row', 'A quoted topic cannot be empty.', first.span);
+                this.pos++;
+                return null;
+            }
+            const aliases = [];
+            let span = first.span;
+            while (c.peek()?.kind === 'comma') {
+                c.next();
+                const alias = c.next();
+                if (!alias || alias.kind !== 'string' || alias.text.trim() === '') {
+                    this.diagnostics.error('parse.topics-alias', 'Expected a quoted alias after the comma — aliases are declared quoted spellings: `about "treasure", "the hoard": …`.', alias?.span ?? c.restSpan());
+                    this.pos++;
+                    return null;
+                }
+                aliases.push(alias.text);
+                span = (0, span_js_1.mergeSpans)(span, alias.span);
+            }
+            filter = { kind: 'text', primary: first.text, aliases, span };
+        }
+        else {
+            const ref = this.parseNameRef(c, () => false);
+            if (ref.words.length === 0) {
+                this.diagnostics.error('parse.topics-row', 'Expected an entity name or a quoted topic after `about`.', c.restSpan());
+                this.pos++;
+                return null;
+            }
+            filter = { kind: 'entity', ref };
+        }
+        const colon = c.next();
+        if (!colon || colon.kind !== 'colon') {
+            this.diagnostics.error('parse.topics-colon', 'Expected `:` after the topic key.', colon?.span ?? c.restSpan());
+            this.pos++;
+            return null;
+        }
+        let body;
+        let span = lineSpan(headLine);
+        if (!c.atEnd()) {
+            // One-line response: the rest of the line is a single statement.
+            // parseStatement consumes this.lines[this.pos] (the row line itself).
+            const rest = { ...headLine, tokens: headLine.tokens.slice(c.i) };
+            const stmt = this.parseStatement(rest, 'topics');
+            if (!stmt)
+                return null; // the statement error is already reported
+            body = [stmt];
+        }
+        else {
+            // Indented statement body on the following lines.
+            this.pos++;
+            body = this.parseStatements(headLine.indent, 'topics');
+            if (body.length > 0)
+                span = (0, span_js_1.mergeSpans)(span, body[body.length - 1].span);
+        }
+        if (body.length === 0) {
+            this.diagnostics.error('parse.topics-response', 'Expected a response — a one-line statement after the `:`, or an indented statement body.', lineSpan(headLine));
+            return null;
+        }
+        return { kind: 'topic-row', filter, body, span };
     }
     // ------------------------------------------------------------- on clause
     /**
@@ -1704,8 +2535,629 @@ class Parser {
             once,
             ordering,
             body,
-            span: (0, span_1.mergeSpans)(lineSpan(headLine), endSpan),
+            span: (0, span_js_1.mergeSpans)(lineSpan(headLine), endSpan),
+        };
+    }
+    /**
+     * ADR-216 media sugar statements: `play sound|music|ambient <asset>
+     * [looping]`, `stop music|ambient`, `show image <asset> [in <layer>]`,
+     * `hide image`, `transition <kind>`, `clear` — each with the standard
+     * `when` suffix. Asset resolution/kind-checking is the analyzer's.
+     */
+    parseMediaStatement(first, c, line) {
+        c.next(); // the keyword
+        const fail = (message) => {
+            this.diagnostics.error('parse.media', message, lineSpan(line));
+            return null;
         };
+        let form;
+        let asset = null;
+        let layer = null;
+        let channel = null;
+        let looping = false;
+        let transitionKind = null;
+        /** ADR-241 D3: optional `in <channel-word>` tail on the ambient forms. */
+        const parseChannelTail = () => {
+            if (!c.matchWord('in'))
+                return true;
+            const channelTok = c.next();
+            if (!channelTok || channelTok.kind !== 'word') {
+                fail('Expected a channel word after `in`.');
+                return false;
+            }
+            channel = channelTok.text;
+            return true;
+        };
+        if (first === 'play') {
+            const what = c.next();
+            if (!what || what.kind !== 'word' || !['sound', 'music', 'ambient'].includes(what.text)) {
+                return fail('Expected `play sound|music|ambient <asset>`.');
+            }
+            const assetTok = c.next();
+            if (!assetTok || assetTok.kind !== 'word')
+                return fail(`Expected a declared asset name after \`play ${what.text}\`.`);
+            asset = assetTok.text;
+            if (what.text === 'music' && c.isWord('looping')) {
+                c.next();
+                looping = true;
+            }
+            if (what.text === 'ambient' && !parseChannelTail())
+                return null;
+            form = `play-${what.text}`;
+        }
+        else if (first === 'stop') {
+            const what = c.next();
+            if (!what || what.kind !== 'word' || !['music', 'ambient'].includes(what.text)) {
+                return fail('Expected `stop music` or `stop ambient`.');
+            }
+            if (what.text === 'ambient' && !parseChannelTail())
+                return null;
+            form = `stop-${what.text}`;
+        }
+        else if (first === 'show') {
+            if (!c.matchWord('image'))
+                return fail('Expected `show image <asset> [in <layer>]`.');
+            const assetTok = c.next();
+            if (!assetTok || assetTok.kind !== 'word')
+                return fail('Expected a declared asset name after `show image`.');
+            asset = assetTok.text;
+            if (c.matchWord('in')) {
+                const layerTok = c.next();
+                if (!layerTok || layerTok.kind !== 'word')
+                    return fail('Expected a layer word after `in`.');
+                layer = layerTok.text;
+            }
+            form = 'show-image';
+        }
+        else if (first === 'hide') {
+            if (!c.matchWord('image'))
+                return fail('Expected `hide image`.');
+            form = 'hide-image';
+        }
+        else if (first === 'transition') {
+            const kindTok = c.next();
+            if (!kindTok || kindTok.kind !== 'word')
+                return fail('Expected a transition kind after `transition` (e.g. `transition fade`).');
+            transitionKind = kindTok.text;
+            form = 'transition';
+        }
+        else {
+            form = 'clear';
+        }
+        const stmtWhen = this.parseStatementWhen(c, line);
+        if (!c.atEnd())
+            return fail(`Unexpected trailing text: \`${c.peek().text}\`.`);
+        return { kind: 'media', form, asset, layer, channel, looping, transitionKind, stmtWhen, span: lineSpan(line) };
+    }
+    /**
+     * `define channel <name> … end channel` (ADR-216; spelling A): keyword
+     * body lines `mode <word>`, `gated by <capability>`, `from event
+     * <dotted.key>`, `take <field>, …`. Value validation (mode set,
+     * capability flags, required lines) is the analyzer's.
+     */
+    parseDefineChannel() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next();
+        c.next(); // define channel
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.channel-name', 'Expected a channel name after `define channel`.', lineSpan(headLine));
+            return null;
+        }
+        const decl = {
+            kind: 'define-channel',
+            name: nameTok.text,
+            mode: null,
+            gatedBy: null,
+            fromEvent: null,
+            returns: null,
+            span: lineSpan(headLine),
+        };
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            const word = firstWord(line);
+            const lc = new Cursor(line.tokens, line);
+            if (word === 'end' && lc.isWord('channel', 1)) {
+                this.pos++;
+                decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
+                return decl;
+            }
+            if (looksLikeComment(line)) {
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
+            if (line.indent === 0)
+                break;
+            decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
+            this.pos++;
+            if (word === 'mode') {
+                lc.next();
+                const modeTok = lc.next();
+                if (!modeTok || modeTok.kind !== 'word' || !lc.atEnd()) {
+                    this.diagnostics.error('parse.channel-mode', 'Expected `mode replace|append|event`.', lineSpan(line));
+                }
+                else {
+                    decl.mode = modeTok.text;
+                }
+                continue;
+            }
+            if (word === 'gated' && lc.isWord('by', 1)) {
+                lc.next();
+                lc.next();
+                const capTok = lc.next();
+                if (!capTok || capTok.kind !== 'word' || !lc.atEnd()) {
+                    this.diagnostics.error('parse.channel-gate', 'Expected `gated by <capability>`.', lineSpan(line));
+                }
+                else {
+                    decl.gatedBy = capTok.text;
+                }
+                continue;
+            }
+            if (word === 'return') {
+                // ADR-253 D1: `return <field | "text" | phrase <key>> from <event>` —
+                // the event rides this clause (the standalone `from event`/`take` lines
+                // are removed below).
+                lc.next(); // return
+                const returns = this.parseChannelReturn(lc, line);
+                if (!returns)
+                    continue; // error already reported
+                if (!lc.matchWord('from')) {
+                    this.diagnostics.error('parse.channel-return', 'Expected `from <event>` after the returned construct — `return <construct> from <event>`.', lineSpan(line));
+                    continue;
+                }
+                const key = this.readLabelKey(lc); // ADR-256: dotless Chord event id; the loader translates to the platform id
+                if (!key || !lc.atEnd()) {
+                    this.diagnostics.error('parse.channel-return', 'Expected a single event id after `from`.', lineSpan(line));
+                    continue;
+                }
+                decl.returns = returns;
+                decl.fromEvent = key;
+                continue;
+            }
+            if (word === 'from' && lc.isWord('event', 1)) {
+                this.diagnostics.error('parse.channel-from-removed', '`from event` was removed (ADR-253) — the event rides the `return … from <event>` clause: `return <construct> from <event>`.', lineSpan(line));
+                continue;
+            }
+            if (word === 'take') {
+                this.diagnostics.error('parse.channel-take-removed', '`take` was removed (ADR-253) — a channel `return`s a construct: `return <field> from <event>`, `return "text (slot)" from <event>`, or `return phrase <key> from <event>`.', lineSpan(line));
+                continue;
+            }
+            this.diagnostics.error('parse.channel-body', `Unrecognized line in \`define channel\`: \`${line.raw.trim()}\` — expected \`mode\`, \`gated by\`, \`return … from <event>\`, or \`end channel\`.`, lineSpan(line));
+        }
+        this.diagnostics.error('parse.channel-end', 'Expected `end channel` to close the block.', decl.span);
+        return decl;
+    }
+    /**
+     * Parse the construct after `return` (ADR-253 D1), stopping before `from`:
+     * a `"quoted"` text template, a `phrase <key>`, or a bare field word. On a
+     * malformed construct reports `parse.channel-return` and returns null.
+     */
+    parseChannelReturn(lc, line) {
+        const tok = lc.peek();
+        if (!tok) {
+            this.diagnostics.error('parse.channel-return', 'Expected a field, a "text" template, or `phrase <key>` after `return`.', lineSpan(line));
+            return null;
+        }
+        if (tok.kind === 'string') {
+            lc.next();
+            return { kind: 'text', text: tok.text };
+        }
+        if (tok.kind === 'word' && tok.text === 'phrase') {
+            lc.next(); // phrase
+            const key = this.readLabelKey(lc);
+            if (!key) {
+                this.diagnostics.error('parse.channel-return', 'Expected a phrase key after `return phrase`.', lineSpan(line));
+                return null;
+            }
+            return { kind: 'phrase', phrase: key };
+        }
+        if (tok.kind === 'word') {
+            const field = this.readLabelKey(lc);
+            if (!field) {
+                this.diagnostics.error('parse.channel-return', 'Expected a field name after `return`.', lineSpan(line));
+                return null;
+            }
+            return { kind: 'field', field };
+        }
+        this.diagnostics.error('parse.channel-return', 'Expected a field, a "text" template, or `phrase <key>` after `return`.', lineSpan(line));
+        return null;
+    }
+    /**
+     * `define pronouns <name> … end pronouns` (ADR-242 D7, ruled Q-1):
+     * five named rows, each `<case> <form>` — `subject`, `object`,
+     * `possessive`, `possessive-pronoun`, `reflexive`. Row completeness,
+     * duplicates, and standard-word shadowing are the analyzer's gates
+     * (the parseDefineChannel split: parser collects, analyzer validates).
+     */
+    parseDefinePronouns() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next();
+        c.next(); // define pronouns
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word' || !c.atEnd()) {
+            this.diagnostics.error('parse.pronouns-name', 'Expected a set name after `define pronouns` (e.g. `define pronouns ze`).', lineSpan(headLine));
+            return null;
+        }
+        const decl = {
+            kind: 'define-pronouns',
+            name: nameTok.text.toLowerCase(),
+            rows: [],
+            span: lineSpan(headLine),
+        };
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            const word = firstWord(line);
+            const lc = new Cursor(line.tokens, line);
+            if (word === 'end' && lc.isWord('pronouns', 1)) {
+                this.pos++;
+                decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
+                return decl;
+            }
+            if (looksLikeComment(line)) {
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
+            if (line.indent === 0)
+                break;
+            decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
+            this.pos++;
+            if (word && catalog_js_1.PRONOUN_CASES.includes(word)) {
+                lc.next();
+                const formTok = lc.next();
+                if (!formTok || formTok.kind !== 'word' || !lc.atEnd()) {
+                    this.diagnostics.error('parse.pronouns-row', `Expected one form word after \`${word}\` (e.g. \`${word} zir\`).`, lineSpan(line));
+                }
+                else {
+                    decl.rows.push({ case: word, form: formTok.text, span: lineSpan(line) });
+                }
+                continue;
+            }
+            this.diagnostics.error('parse.pronouns-body', `Unrecognized line in \`define pronouns\`: \`${line.raw.trim()}\` — expected \`${catalog_js_1.PRONOUN_CASES.join('`, `')}\`, or \`end pronouns\`.`, lineSpan(line));
+        }
+        this.diagnostics.error('parse.pronouns-end', 'Expected `end pronouns` to close the block.', decl.span);
+        return decl;
+    }
+    /** `define sound|image|music <name> from "<file>"` (ADR-216) — data asset. */
+    parseDefineAsset(assetKind) {
+        const line = this.lines[this.pos++];
+        const c = new Cursor(line.tokens, line);
+        c.next();
+        c.next(); // define <kind>
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.asset-name', `Expected an asset name after \`define ${assetKind}\`.`, c.restSpan());
+            return null;
+        }
+        if (!c.matchWord('from')) {
+            this.diagnostics.error('parse.asset-from', `Expected \`from "<file>"\` in the ${assetKind} declaration.`, c.restSpan());
+            return null;
+        }
+        const pathTok = c.next();
+        if (!pathTok || pathTok.kind !== 'string') {
+            this.diagnostics.error('parse.asset-path', 'Expected a quoted file path after `from`.', c.restSpan());
+            return null;
+        }
+        return { kind: 'define-asset', assetKind, name: nameTok.text, path: pathTok.text, span: lineSpan(line) };
+    }
+    /**
+     * `define ambient <word>` / `define layer <word>` (ADR-241 D2): a
+     * one-line named family channel declaration. Exactly one word — the
+     * bed/layer name; the registered id is the loader's business.
+     */
+    parseDefineFamilyChannel(family) {
+        const line = this.lines[this.pos++];
+        const c = new Cursor(line.tokens, line);
+        c.next();
+        c.next(); // define ambient|layer
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.channel-name', `Expected a ${family === 'ambient' ? 'bed' : 'layer'} name after \`define ${family}\`.`, c.restSpan());
+            return null;
+        }
+        if (!c.atEnd()) {
+            this.diagnostics.error('parse.channel-name', `Unexpected trailing text after \`define ${family} ${nameTok.text}\` — the declaration is one word.`, c.restSpan());
+            return null;
+        }
+        return { kind: 'define-family-channel', family, name: nameTok.text, span: lineSpan(line) };
+    }
+    // ---------------------------------------------------------- emit payload
+    /**
+     * ADR-216 payload fields: `<field> <value>` separated by `and` at the
+     * flat (statement) level, by commas inside `{ … }` objects. Values:
+     * literals, `[ … ]` arrays, `{ … }` objects, or value expressions
+     * (world-state reads).
+     */
+    parseEmitFields(c, line, mode) {
+        const fields = [];
+        for (;;) {
+            if (mode === 'braced' && c.peek()?.kind === 'rbrace')
+                break;
+            if (mode === 'flat' && (c.atEnd() || c.isWord('when')))
+                break;
+            const startTok = c.peek();
+            const key = [];
+            while (!c.atEnd() && c.peek().kind === 'word' && !c.isWord('and') && !c.isWord('when')) {
+                const t = c.peek();
+                if (ARTICLES.has(t.text) && key.length > 0)
+                    break;
+                const after = c.peek(1);
+                const atValuePosition = !after ||
+                    after.kind === 'comma' ||
+                    after.kind === 'rbrace' ||
+                    (after.kind === 'word' && (after.text === 'and' || after.text === 'when'));
+                if (atValuePosition && key.length > 0)
+                    break;
+                key.push(t.text);
+                c.next();
+            }
+            if (key.length === 0) {
+                this.diagnostics.error('parse.emit-payload', 'Expected a payload field name.', c.restSpan());
+                break;
+            }
+            const value = this.parseEmitValue(c, line);
+            if (!value)
+                break;
+            fields.push({ key, value, span: startTok ? (0, span_js_1.mergeSpans)(startTok.span, value.span) : value.span });
+            if (mode === 'flat') {
+                if (!c.matchWord('and'))
+                    break;
+            }
+            else if (c.peek()?.kind === 'comma') {
+                c.next();
+            }
+            else {
+                break;
+            }
+        }
+        return fields;
+    }
+    /** One ADR-216 payload value (recursive: literals, arrays, objects, value exprs). */
+    parseEmitValue(c, line) {
+        const t = c.peek();
+        if (!t) {
+            this.diagnostics.error('parse.emit-payload', 'Expected a payload value.', c.restSpan());
+            return null;
+        }
+        if (t.kind === 'number' || t.kind === 'string') {
+            c.next();
+            return { kind: 'literal', value: t.text, literalKind: t.kind, span: t.span };
+        }
+        if (t.kind === 'lbracket') {
+            c.next();
+            const items = [];
+            while (c.peek() && c.peek().kind !== 'rbracket') {
+                const item = this.parseEmitValue(c, line);
+                if (!item)
+                    break;
+                items.push(item);
+                if (c.peek()?.kind === 'comma')
+                    c.next();
+                else
+                    break;
+            }
+            const close = c.next();
+            let endSpan = t.span;
+            if (!close || close.kind !== 'rbracket') {
+                this.diagnostics.error('parse.emit-payload', 'Expected `]` to close the array.', c.restSpan());
+            }
+            else {
+                endSpan = close.span;
+            }
+            return { kind: 'array', items, span: (0, span_js_1.mergeSpans)(t.span, endSpan) };
+        }
+        if (t.kind === 'lbrace') {
+            c.next();
+            const fields = this.parseEmitFields(c, line, 'braced');
+            const close = c.next();
+            let endSpan = t.span;
+            if (!close || close.kind !== 'rbrace') {
+                this.diagnostics.error('parse.emit-payload', 'Expected `}` to close the object.', c.restSpan());
+            }
+            else {
+                endSpan = close.span;
+            }
+            return { kind: 'object', fields, span: (0, span_js_1.mergeSpans)(t.span, endSpan) };
+        }
+        const expr = this.parseValueExpr(c, line, EMIT_VALUE_STOPS);
+        return { kind: 'expr', expr, span: expr.span };
+    }
+    // -------------------------------------------------------------- machines
+    /**
+     * `define machine <name> … end machine` (ADR-215 `use state-machines`
+     * depth; spelling A ratified 2026-07-18): `role <name> is <entity>`
+     * bindings, `starts <state>`, and `state <name>[, terminal]` blocks. The
+     * `use` requirement is the analyzer's gate.
+     */
+    parseDefineMachine() {
+        const headLine = this.lines[this.pos++];
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next();
+        c.next(); // define machine
+        const name = [];
+        while (!c.atEnd() && c.peek().kind === 'word')
+            name.push(c.next().text);
+        if (name.length === 0) {
+            this.diagnostics.error('parse.machine-name', 'Expected a machine name after `define machine`.', lineSpan(headLine));
+        }
+        const decl = { kind: 'define-machine', name, roles: [], initialState: null, states: [], span: lineSpan(headLine) };
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            const word = firstWord(line);
+            const lc = new Cursor(line.tokens, line);
+            if (word === 'end' && lc.isWord('machine', 1)) {
+                this.pos++;
+                decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
+                return decl;
+            }
+            if (looksLikeComment(line)) {
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
+            if (line.indent === 0)
+                break; // dedent without `end machine` — reported below
+            decl.span = (0, span_js_1.mergeSpans)(decl.span, lineSpan(line));
+            if (word === 'role') {
+                this.pos++;
+                lc.next();
+                const roleTok = lc.next();
+                if (!roleTok || roleTok.kind !== 'word' || !lc.matchWord('is')) {
+                    this.diagnostics.error('parse.machine-role', 'Expected `role <name> is <entity>`.', lineSpan(line));
+                    continue;
+                }
+                const entity = this.parseNameRef(lc, () => false);
+                if (entity.words.length === 0 || !lc.atEnd()) {
+                    this.diagnostics.error('parse.machine-role', 'Expected `role <name> is <entity>`.', lineSpan(line));
+                    continue;
+                }
+                decl.roles.push({ name: roleTok.text, entity, span: lineSpan(line) });
+                continue;
+            }
+            if (word === 'starts') {
+                this.pos++;
+                lc.next();
+                const stateTok = lc.next();
+                if (!stateTok || stateTok.kind !== 'word' || !lc.atEnd()) {
+                    this.diagnostics.error('parse.machine-starts', 'Expected `starts <state>`.', lineSpan(line));
+                    continue;
+                }
+                if (decl.initialState !== null) {
+                    this.diagnostics.error('parse.machine-starts', 'This machine already declared its `starts` state.', lineSpan(line));
+                    continue;
+                }
+                decl.initialState = stateTok.text;
+                continue;
+            }
+            if (word === 'state') {
+                const state = this.parseMachineState(line);
+                if (state) {
+                    decl.states.push(state);
+                    decl.span = (0, span_js_1.mergeSpans)(decl.span, state.span);
+                }
+                continue;
+            }
+            this.diagnostics.error('parse.machine-body', `Unrecognized line in \`define machine\`: \`${line.raw.trim()}\` — expected \`role\`, \`starts\`, \`state\`, or \`end machine\`.`, lineSpan(line));
+            this.pos++;
+        }
+        this.diagnostics.error('parse.machine-end', 'Expected `end machine` to close the block.', decl.span);
+        return decl;
+    }
+    /** One `state <name>[, terminal]` block: transition lines + `on enter`/`on exit` bodies. */
+    parseMachineState(headLine) {
+        this.pos++;
+        const c = new Cursor(headLine.tokens, headLine);
+        c.next(); // state
+        const nameTok = c.next();
+        if (!nameTok || nameTok.kind !== 'word') {
+            this.diagnostics.error('parse.machine-state', 'Expected a state name after `state`.', lineSpan(headLine));
+            return null;
+        }
+        let terminal = false;
+        if (c.peek()?.kind === 'comma') {
+            c.next();
+            if (c.matchWord('terminal'))
+                terminal = true;
+            else
+                this.diagnostics.error('parse.machine-state', 'Only `, terminal` may follow the state name.', c.restSpan());
+        }
+        const state = { name: nameTok.text, terminal, transitions: [], onEnter: [], onExit: [], span: lineSpan(headLine) };
+        while (this.pos < this.lines.length) {
+            const line = this.lines[this.pos];
+            if (line.indent <= headLine.indent)
+                break; // next state / end machine
+            state.span = (0, span_js_1.mergeSpans)(state.span, lineSpan(line));
+            const word = firstWord(line);
+            if (word === 'when') {
+                const transition = this.parseMachineTransition(line);
+                if (transition)
+                    state.transitions.push(transition);
+                continue;
+            }
+            if (word === 'on') {
+                const lc = new Cursor(line.tokens, line);
+                lc.next();
+                const which = lc.next();
+                if (which && which.kind === 'word' && (which.text === 'enter' || which.text === 'exit') && lc.atEnd()) {
+                    this.pos++;
+                    const body = this.parseStatements(line.indent, 'on');
+                    const endSpan = this.consumeEnd('on', line);
+                    state.span = (0, span_js_1.mergeSpans)(state.span, endSpan);
+                    if (which.text === 'enter')
+                        state.onEnter.push(...body);
+                    else
+                        state.onExit.push(...body);
+                    continue;
+                }
+                this.diagnostics.error('parse.machine-on', 'Only `on enter` and `on exit` blocks live in a machine `state`.', lineSpan(line));
+                this.pos++;
+                continue;
+            }
+            this.diagnostics.error('parse.machine-state-body', `Unrecognized line in a machine \`state\` block: \`${line.raw.trim()}\` — expected \`when …: <state>\`, \`on enter\`, or \`on exit\`.`, lineSpan(line));
+            this.pos++;
+        }
+        return state;
+    }
+    /**
+     * `when <trigger>[ while <condition>]: <target-state>`. Triggers:
+     * `event <dotted.key>`, `<gerund> <entity name>` (action on a target),
+     * a single bare word (analyzer resolves condition-vs-gerund), or a
+     * condition.
+     */
+    parseMachineTransition(line) {
+        this.pos++;
+        const tokens = line.tokens;
+        const colonIndex = tokens.map((t) => t.kind === 'colon').lastIndexOf(true);
+        if (colonIndex === -1 || colonIndex !== tokens.length - 2 || tokens[tokens.length - 1].kind !== 'word') {
+            this.diagnostics.error('parse.machine-when', 'Expected `when <trigger>[ while <condition>]: <target-state>`.', lineSpan(line));
+            return null;
+        }
+        const target = tokens[tokens.length - 1].text;
+        let head = tokens.slice(1, colonIndex);
+        let condition = null;
+        const whileIndex = head.findIndex((t) => t.kind === 'word' && t.text === 'while');
+        if (whileIndex !== -1) {
+            condition = this.parseCondition(new Cursor(head.slice(whileIndex + 1), line), line);
+            head = head.slice(0, whileIndex);
+        }
+        const hc = new Cursor(head, line);
+        const first = hc.peek();
+        if (!first) {
+            this.diagnostics.error('parse.machine-when', 'Expected a trigger after `when`.', lineSpan(line));
+            return null;
+        }
+        let trigger;
+        if (first.kind === 'word' && first.text === 'event') {
+            hc.next();
+            const key = this.readLabelKey(hc); // ADR-256: dotless Chord event id; story-loader translates to the platform id
+            if (!key || !hc.atEnd()) {
+                this.diagnostics.error('parse.machine-when', 'Expected `event <event.key>`.', lineSpan(line));
+                return null;
+            }
+            trigger = { kind: 'event', event: key };
+        }
+        else if (first.kind === 'word' && !ARTICLES.has(first.text) && head.length === 1) {
+            trigger = { kind: 'word', word: first.text, span: first.span };
+        }
+        else if (first.kind === 'word' && !ARTICLES.has(first.text) && head[1]?.kind === 'word' && (ARTICLES.has(head[1].text) || head[1].text === 'it')) {
+            const action = hc.next().text;
+            if (hc.isWord('it')) {
+                // Machines are story-owned — there is no `it` (mirror of the
+                // story-clause rule); name the entity or role.
+                this.diagnostics.error('parse.machine-when', '`it` is not bound in a machine — name the entity or a declared role.', lineSpan(line));
+                return null;
+            }
+            const targetRef = this.parseNameRef(hc, () => false);
+            if (targetRef.words.length === 0 || !hc.atEnd()) {
+                this.diagnostics.error('parse.machine-when', `Expected an entity or role name after \`${action}\`.`, lineSpan(line));
+                return null;
+            }
+            trigger = { kind: 'action', action, target: targetRef };
+        }
+        else {
+            trigger = { kind: 'condition', condition: this.parseCondition(hc, line) };
+        }
+        return { trigger, condition, target, span: lineSpan(line) };
     }
     // ------------------------------------------------------------ statements
     /**
@@ -1720,6 +3172,10 @@ class Parser {
                 break;
             if (isEndLine(line) || ((firstWord(line) === 'else' || firstWord(line) === 'or') && line.tokens.length === 1))
                 break;
+            if (looksLikeComment(line)) {
+                this.skipCommentInsideBlock(line);
+                continue;
+            }
             const stmt = this.parseStatement(line, blockKeyword);
             if (stmt)
                 body.push(stmt);
@@ -1755,7 +3211,7 @@ class Parser {
                     }
                     return this.parseRefuseWhenStatement(line);
                 }
-                const key = this.readDottedKey(c);
+                const key = this.readLabelKey(c);
                 if (!key) {
                     this.diagnostics.error('parse.phrase-ref', `Expected a phrase key after \`${word}\`.`, c.restSpan());
                     return null;
@@ -1766,6 +3222,14 @@ class Parser {
                         this.reportRefusalInAfter(line);
                         return null;
                     }
+                    // Misordered prohibition (platform-issue-sweep Phase 8 #15c):
+                    // `refuse <key> when <condition>` used to leave the `when …`
+                    // tokens unconsumed and silently compile as an UNCONDITIONAL
+                    // refuse. Error with a fix-it instead.
+                    if (c.isWord('when')) {
+                        this.diagnostics.error('parse.refuse-order', `The condition comes first — write \`refuse when <condition>: ${key}\`.`, c.restSpan());
+                        return null;
+                    }
                     return { kind: 'refuse', phraseKey: key, params, span: lineSpan(line) };
                 }
                 const stmtWhen = this.parseStatementWhen(c, line);
@@ -1776,21 +3240,43 @@ class Parser {
                 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);
+                const span = inlineText ? (0, span_js_1.mergeSpans)(lineSpan(line), inlineText.span) : lineSpan(line);
                 return { kind: 'phrase', phraseKey: key, params, inlineText, stmtWhen, span };
             }
             case 'emit': {
                 this.pos++;
                 c.next();
+                // ADR-256: an event id is a single dotless Chord token (`media-sound-play`);
+                // story-loader translates it to the platform's dotted id at the emit seam.
+                // A `.` now raises `parse.dotted-key` (ADR-254 uniform).
                 const event = [];
-                while (!c.atEnd() && !c.isWord('when'))
-                    event.push(c.next().text);
+                while (!c.atEnd() && !c.isWord('when') && !c.isWord('with')) {
+                    const segment = this.readLabelKey(c);
+                    if (!segment)
+                        break;
+                    event.push(segment);
+                }
                 if (event.length === 0) {
                     this.diagnostics.error('parse.emit', 'Expected an event name after `emit`.', lineSpan(line));
                     return null;
                 }
+                // ADR-216 payload: `with <field> <value> [and …]` — the create-data
+                // grammar; bracketed/braced structures inside separate with commas.
+                const payload = [];
+                if (c.matchWord('with')) {
+                    payload.push(...this.parseEmitFields(c, line, 'flat'));
+                }
                 const stmtWhen = this.parseStatementWhen(c, line);
-                return { kind: 'emit', event, stmtWhen, span: lineSpan(line) };
+                return { kind: 'emit', event, payload, stmtWhen, span: lineSpan(line) };
+            }
+            case 'play':
+            case 'stop':
+            case 'show':
+            case 'hide':
+            case 'transition':
+            case 'clear': {
+                this.pos++;
+                return this.parseMediaStatement(word, c, line);
             }
             case 'set': {
                 this.pos++;
@@ -1917,38 +3403,53 @@ class Parser {
     /** `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) {
+        if (colonIndex === -1 || colonIndex >= line.tokens.length - 1) {
             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);
+        const keyCursor = new Cursor(line.tokens.slice(colonIndex + 1), line);
+        const key = this.readLabelKey(keyCursor); // label-key = single WORD (ADR-254; readLabelKey rejects dots)
+        if (!key || !keyCursor.atEnd()) {
+            this.diagnostics.error('parse.refuse-when', 'Expected a phrase key after the colon.', line.tokens[colonIndex + 1].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) };
+        return { kind: 'refuse-when', condition, phraseKey: key, 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.
+     * Read a label/key: a single kebab-case `WORD` (ADR-254). A `.` in any label
+     * position — author labels (phrase, exit, refusal keys) AND the event-type
+     * sites (`emit`, channel `from event`, machine `when event`) — is a parse
+     * error (`parse.dotted-key`). The ban is uniform: ADR-256 made the event-type
+     * sites dotless too (the dotless Chord event id is translated to the platform's
+     * dotted id in `@sharpee/story-loader`, so no dotted form ever appears in a
+     * `.story`). Returns `null` when no word is present.
      */
-    readDottedKey(c) {
+    readLabelKey(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') {
+        const key = first.text;
+        const dotFollows = () => c.peek()?.kind === 'punct' && c.peek().text === '.' && c.peek(1)?.kind === 'word';
+        if (!dotFollows())
+            return key;
+        // ADR-254/256: a `.` in a label is a parse error. Consume the dotted
+        // segments (one clean error, no cascade), flag the first dot, and hand back
+        // the kebab-cased form so downstream parsing does not spuriously break.
+        const dot = c.peek();
+        const segments = [key];
+        while (dotFollows()) {
             c.next();
-            key += '.' + c.next().text;
+            segments.push(c.next().text);
         }
-        return key;
+        this.diagnostics.error('parse.dotted-key', `Labels are single words; "." is not allowed in "${segments.join('.')}" — use kebab-case, e.g. "${segments.join('-')}".`, dot.span);
+        return segments.join('-');
     }
     parseParams(c, line) {
         const params = [];
@@ -1964,7 +3465,7 @@ class Parser {
                 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 });
+            params.push({ param, value, span: start ? (0, span_js_1.mergeSpans)(start.span, value.span) : value.span });
         }
         return params;
     }
@@ -1982,7 +3483,7 @@ class Parser {
             const stmt = this.parseStatement(line, 'ordinal');
             if (stmt) {
                 body.push(stmt);
-                span = (0, span_1.mergeSpans)(span, stmt.span);
+                span = (0, span_js_1.mergeSpans)(span, stmt.span);
             }
         }
         return { kind: 'ordinal', ordinal: ORDINALS[word], ordinalWord: word, body, span };
@@ -2009,7 +3510,7 @@ class Parser {
         }
         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) };
+        return { kind: 'each', condition: nameTok.text, body, span: (0, span_js_1.mergeSpans)(lineSpan(headLine), endSpan) };
     }
     parseSelect(headLine) {
         this.pos++;
@@ -2040,7 +3541,7 @@ class Parser {
                 }
             }
             const endSpan = this.consumeEnd('select', headLine);
-            return { kind: 'select-on', subject, arms, span: (0, span_1.mergeSpans)(lineSpan(headLine), endSpan) };
+            return { kind: 'select-on', subject, arms, span: (0, span_js_1.mergeSpans)(lineSpan(headLine), endSpan) };
         }
         const strategyTok = c.next();
         if (!strategyTok || strategyTok.kind !== 'word' || !STRATEGIES.has(strategyTok.text)) {
@@ -2066,7 +3567,7 @@ class Parser {
             break;
         }
         const endSpan = this.consumeEnd('select', headLine);
-        return { kind: 'select-strategy', strategy: strategyTok.text, alternatives, span: (0, span_1.mergeSpans)(lineSpan(headLine), endSpan) };
+        return { kind: 'select-strategy', strategy: strategyTok.text, alternatives, span: (0, span_js_1.mergeSpans)(lineSpan(headLine), endSpan) };
     }
     /** Consume the expected `end <keyword>` line; diagnose a mismatch or absence. */
     consumeEnd(keyword, openLine) {
@@ -2113,10 +3614,10 @@ class Parser {
             if (stop(t))
                 break;
             words.push(t.text);
-            span = span ? (0, span_1.mergeSpans)(span, t.span) : t.span;
+            span = span ? (0, span_js_1.mergeSpans)(span, t.span) : t.span;
             c.next();
         }
-        return { kind: 'name', article, words, span: span ?? (0, span_1.spanOf)(c.line.lineNo, 1) };
+        return { kind: 'name', article, words, span: span ?? (0, span_js_1.spanOf)(c.line.lineNo, 1) };
     }
     /**
      * Parse a value expression: literal, name reference, or possessive chain
@@ -2144,7 +3645,7 @@ class Parser {
             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) };
+                return { kind: 'match', span: (0, span_js_1.mergeSpans)(first.span, m.span) };
             }
         }
         // `its <field>` — possessive on `it`.
@@ -2152,7 +3653,7 @@ class Parser {
             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) };
+            return { kind: 'possessive', base, field: field.words, span: (0, span_js_1.mergeSpans)(first.span, field.span ?? first.span) };
         }
         let article = null;
         let span = first.span;
@@ -2169,7 +3670,7 @@ class Parser {
             if (PHRASE_STOPS.has(t.text) || extraStops.has(t.text))
                 break;
             c.next();
-            span = (0, span_1.mergeSpans)(span, t.span);
+            span = (0, span_js_1.mergeSpans)(span, t.span);
             const poss = /^(.*)'s$/.exec(t.text);
             if (poss) {
                 words.push(poss[1]);
@@ -2189,7 +3690,7 @@ class Parser {
         };
         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 { kind: 'possessive', base: refExpr, field: field.words, span: (0, span_js_1.mergeSpans)(span, field.span ?? span) };
         }
         return refExpr;
     }
@@ -2201,7 +3702,7 @@ class Parser {
             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;
+            span = span ? (0, span_js_1.mergeSpans)(span, t.span) : t.span;
             c.next();
         }
         return { words, span };
@@ -2217,7 +3718,7 @@ class Parser {
         while (c.matchWord('or')) {
             const right = this.parseConditionAnd(c, line);
             operands.push(right);
-            span = (0, span_1.mergeSpans)(span, right.span);
+            span = (0, span_js_1.mergeSpans)(span, right.span);
         }
         return { kind: 'or', operands, span };
     }
@@ -2230,7 +3731,7 @@ class Parser {
         while (c.matchWord('and')) {
             const right = this.parseConditionUnary(c, line);
             operands.push(right);
-            span = (0, span_1.mergeSpans)(span, right.span);
+            span = (0, span_js_1.mergeSpans)(span, right.span);
         }
         return { kind: 'and', operands, span };
     }
@@ -2243,7 +3744,19 @@ class Parser {
         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) };
+            return { kind: 'not', operand, span: (0, span_js_1.mergeSpans)(t.span, operand.span) };
+        }
+        // `client has <capability>` (ADR-216) — `client` is reserved in
+        // condition-subject position; the capability word is the analyzer's gate.
+        if (t.kind === 'word' && t.text === 'client' && c.isWord('has', 1)) {
+            c.next();
+            c.next(); // client has
+            const capability = c.next();
+            if (!capability || capability.kind !== 'word') {
+                this.diagnostics.error('parse.client-has', 'Expected a capability word after `client has` (sound, images, …).', c.restSpan());
+                return { kind: 'condition-ref', name: '', span: lineSpan(line) };
+            }
+            return { kind: 'client-has', capability: capability.text, span: (0, span_js_1.mergeSpans)(t.span, capability.span) };
         }
         if (t.kind === 'lparen') {
             c.next();
@@ -2264,7 +3777,7 @@ class Parser {
                 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) };
+            return { kind: 'chance', n: Number(n.text), span: (0, span_js_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
@@ -2279,7 +3792,7 @@ class Parser {
                 return {
                     kind: t.text === 'any' ? 'any-of' : 'none-of',
                     condition: nameTok.text,
-                    span: (0, span_1.mergeSpans)(t.span, nameTok.span),
+                    span: (0, span_js_1.mergeSpans)(t.span, nameTok.span),
                 };
             }
         }
@@ -2321,7 +3834,7 @@ class Parser {
                     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),
+                    span: (0, span_js_1.mergeSpans)(subject.span, cls.span ?? t.span),
                 };
             }
             if (c.isWord('in')) {
@@ -2331,7 +3844,7 @@ class Parser {
                     kind: 'predicate',
                     subject,
                     predicate: { kind: 'is-in', negated, place, span: place.span },
-                    span: (0, span_1.mergeSpans)(subject.span, place.span),
+                    span: (0, span_js_1.mergeSpans)(subject.span, place.span),
                 };
             }
             if (c.isWord('here')) {
@@ -2343,7 +3856,7 @@ class Parser {
                     kind: 'predicate',
                     subject,
                     predicate: { kind: 'is-here', negated, span: hereTok.span },
-                    span: (0, span_1.mergeSpans)(subject.span, hereTok.span),
+                    span: (0, span_js_1.mergeSpans)(subject.span, hereTok.span),
                 };
             }
             const value = this.parseValueExpr(c, line, new Set());
@@ -2351,7 +3864,7 @@ class Parser {
                 kind: 'predicate',
                 subject,
                 predicate: { kind: 'is', negated, value, span: value.span },
-                span: (0, span_1.mergeSpans)(subject.span, value.span),
+                span: (0, span_js_1.mergeSpans)(subject.span, value.span),
             };
         }
         if (t.text === 'has' || t.text === 'holds' || t.text === 'wears') {
@@ -2361,7 +3874,7 @@ class Parser {
                 kind: 'predicate',
                 subject,
                 predicate: { kind: t.text, thing, span: thing.span },
-                span: (0, span_1.mergeSpans)(subject.span, thing.span),
+                span: (0, span_js_1.mergeSpans)(subject.span, thing.span),
             };
         }
         if (t.text === 'can') {
@@ -2376,8 +3889,8 @@ class Parser {
             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),
+                predicate: { kind: 'can', ability: ability.text, thing, span: (0, span_js_1.mergeSpans)(ability.span, thing.span) },
+                span: (0, span_js_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);