@sharpee/story-loader 3.1.0 → 3.3.0

package/loader.js

@@ -27,15 +27,20 @@ exports.createStory = createStory;
 const chord_1 = require("@sharpee/chord");
 const stdlib_1 = require("@sharpee/stdlib");
 const if_domain_1 = require("@sharpee/if-domain");
-const helpers_1 = require("@sharpee/helpers");
+const plugin_npc_1 = require("@sharpee/plugin-npc");
 const plugin_scheduler_1 = require("@sharpee/plugin-scheduler");
+const plugin_state_machine_1 = require("@sharpee/plugin-state-machine");
+const stdlib_2 = require("@sharpee/stdlib");
 const world_model_1 = require("@sharpee/world-model");
-const errors_1 = require("./errors");
-const evaluator_1 = require("./evaluator");
-const hatch_context_1 = require("./hatch-context");
-const runtime_1 = require("./runtime");
-const state_keys_1 = require("./state-keys");
-const text_1 = require("./text");
+const chain_map_js_1 = require("./chain-map.js");
+const errors_js_1 = require("./errors.js");
+const event_id_map_js_1 = require("./event-id-map.js");
+const extension_registry_js_1 = require("./extension-registry.js");
+const evaluator_js_1 = require("./evaluator.js");
+const hatch_context_js_1 = require("./hatch-context.js");
+const runtime_js_1 = require("./runtime.js");
+const state_keys_js_1 = require("./state-keys.js");
+const text_js_1 = require("./text.js");
 /**
  * Marker trait for entities carrying loader-compiled `detail` providers
  * (Z3b): the one state-clause contributor registered per load looks up the
@@ -76,8 +81,8 @@ class ChordStory {
     producers = new Map();
     /** Bound `define action X from` hatches: four-phase Action objects by name. */
     boundActions = new Map();
-    /** Bound `define behavior X from` hatches: CapabilityBehaviors by name. */
-    boundBehaviors = new Map();
+    /** Bound `define chain X from` hatches (ADR-094): EventChainHandlers by chain alias. */
+    boundChains = new Map();
     /** The turn-by-turn runtime (rules, on-clauses, derived properties). */
     runtime;
     /** The condition evaluator — shared with the runtime; Z2 gate thunks close over it. */
@@ -98,7 +103,7 @@ class ChordStory {
         const lower = name.toLowerCase();
         const target = this.ir.entities.find((e) => e.name.toLowerCase() === lower || e.aka.includes(lower));
         if (!target) {
-            throw new errors_1.LoadError(`\`${name}\` (config \`${configKey}\`) names no entity.`, span);
+            throw new errors_js_1.LoadError(`\`${name}\` (config \`${configKey}\`) names no entity.`, span);
         }
         return { irRefId: target.id, ownerName: owner.name, span, apply };
     }
@@ -120,7 +125,7 @@ class ChordStory {
     constructor(ir, options) {
         this.ir = ir;
         if (ir.format !== chord_1.IR_FORMAT) {
-            throw new errors_1.LoadError(`Unsupported IR format \`${String(ir.format)}\` — this loader reads \`${chord_1.IR_FORMAT}\`.`);
+            throw new errors_js_1.LoadError(`Unsupported IR format \`${String(ir.format)}\` — this loader reads \`${chord_1.IR_FORMAT}\`.`);
         }
         this.config = {
             id: ir.meta.fields.id ?? ir.meta.title.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
@@ -130,8 +135,8 @@ class ChordStory {
             description: ir.meta.fields.blurb,
         };
         this.bindHatches(options);
-        this.evaluator = new evaluator_1.Evaluator(ir, this, options.seed);
-        this.runtime = new runtime_1.ChordRuntime(ir, this, this.evaluator);
+        this.evaluator = new evaluator_js_1.Evaluator(ir, this, options.seed);
+        this.runtime = new runtime_js_1.ChordRuntime(ir, this, this.evaluator);
     }
     /** The world entity ID for an IR entity ID (after initializeWorld). */
     entityId(irId) {
@@ -151,29 +156,31 @@ class ChordStory {
         // any module — no author-supplied code is read, called, or bound.
         if ((options.profile ?? 'devkit') === 'pure-ir' && this.ir.hatches.length > 0) {
             const names = this.ir.hatches.map((h) => `\`${h.name}\` (${h.modulePath})`).join(', ');
-            throw new errors_1.LoadError(`This profile runs pure-IR stories only — the story declares ${this.ir.hatches.length} TS hatch(es): ${names}. Load it with the devkit profile, or remove the hatches.`);
+            throw new errors_js_1.LoadError(`This profile runs pure-IR stories only — the story declares ${this.ir.hatches.length} TS hatch(es): ${names}. Load it with the devkit profile, or remove the hatches.`);
         }
         for (const hatch of this.ir.hatches) {
             const module = options.hatchModules?.[hatch.modulePath];
             if (!module) {
-                throw new errors_1.LoadError(`Hatch module \`${hatch.modulePath}\` was not provided to the loader.`, hatch.span);
+                throw new errors_js_1.LoadError(`Hatch module \`${hatch.modulePath}\` was not provided to the loader.`, hatch.span);
             }
-            const bound = module[hatch.name];
+            // A chain hatch's alias (`opened-revealed`) is not a JS identifier, so its
+            // module default-exports the handler (falling back to a matching named export).
+            const bound = hatch.hatchKind === 'chain' ? (module[hatch.name] ?? module.default) : module[hatch.name];
             // Bind-time `'chord.'` lint (design.md §5.6, best-effort backstop —
             // the staging facade is the wall): the loader-private state namespace
             // is off-limits to hatches; a quoted literal fails the bind atomically,
             // like a missing export. The devkit source lint is the authoritative
             // layer (this one can miss minified code and can trip on a quoted
             // literal inside a compiled-in comment — reword the comment).
-            const chordLiteral = (0, hatch_context_1.findChordLiteral)(bound);
+            const chordLiteral = (0, hatch_context_js_1.findChordLiteral)(bound);
             if (chordLiteral !== null) {
-                throw new errors_1.LoadError(`Hatch \`${hatch.name}\` in \`${hatch.modulePath}\` references the loader-private \`chord.*\` state namespace (\`${chordLiteral}\`) — hatches read the world through their context only (design.md §5.6). If the match is inside a comment, reword it.`, hatch.span);
+                throw new errors_js_1.LoadError(`Hatch \`${hatch.name}\` in \`${hatch.modulePath}\` references the loader-private \`chord.*\` state namespace (\`${chordLiteral}\`) — hatches read the world through their context only (design.md §5.6). If the match is inside a comment, reword it.`, hatch.span);
             }
             const kind = hatch.hatchKind ?? 'text';
             switch (kind) {
                 case 'text': {
                     if (typeof bound !== 'function') {
-                        throw new errors_1.LoadError(`Hatch \`${hatch.name}\` in \`${hatch.modulePath}\` is ${bound === undefined ? 'missing' : 'not a function'} — expected a dynamic-text producer export.`, hatch.span);
+                        throw new errors_js_1.LoadError(`Hatch \`${hatch.name}\` in \`${hatch.modulePath}\` is ${bound === undefined ? 'missing' : 'not a function'} — expected a dynamic-text producer export.`, hatch.span);
                     }
                     this.producers.set(hatch.name, bound);
                     break;
@@ -182,48 +189,130 @@ class ChordStory {
                     // Interface Contract 3: the export IS a four-phase Action.
                     const action = bound;
                     if (!action || typeof action !== 'object' || typeof action.validate !== 'function' || typeof action.execute !== 'function') {
-                        throw new errors_1.LoadError(`Hatch \`${hatch.name}\` in \`${hatch.modulePath}\` is ${bound === undefined ? 'missing' : 'not an Action'} — expected a four-phase Action export (validate/execute/report/blocked).`, hatch.span);
+                        throw new errors_js_1.LoadError(`Hatch \`${hatch.name}\` in \`${hatch.modulePath}\` is ${bound === undefined ? 'missing' : 'not an Action'} — expected a four-phase Action export (validate/execute/report/blocked).`, hatch.span);
                     }
                     this.boundActions.set(hatch.name, bound);
                     break;
                 }
-                case 'behavior': {
-                    const behavior = bound;
-                    if (!behavior || typeof behavior !== 'object' || typeof behavior.validate !== 'function' || typeof behavior.execute !== 'function' || typeof behavior.report !== 'function') {
-                        throw new errors_1.LoadError(`Hatch \`${hatch.name}\` in \`${hatch.modulePath}\` is ${bound === undefined ? 'missing' : 'not a CapabilityBehavior'} — expected a validate/execute/report export.`, hatch.span);
+                case 'chain': {
+                    // ADR-094: the export IS an EventChainHandler; registered in
+                    // initializeWorld to REPLACE the stdlib chain (same key).
+                    if (typeof bound !== 'function') {
+                        throw new errors_js_1.LoadError(`Chain hatch \`${hatch.name}\` in \`${hatch.modulePath}\` is ${bound === undefined ? 'missing' : 'not a function'} — expected an EventChainHandler (the module's default export).`, hatch.span);
                     }
-                    this.boundBehaviors.set(hatch.name, bound);
+                    this.boundChains.set(hatch.name, bound);
                     break;
                 }
+                // The `behavior` hatch kind was removed (ADR-235 D2, 2026-07-18) —
+                // it carried no binding key and could never fire; the compiler now
+                // refuses the declaration outright.
             }
         }
     }
     // ------------------------------------------------------------ lifecycle
     initializeWorld(world) {
         this.world = world;
+        // ADR-094 chain hatches: register each replacement handler under its stdlib
+        // chain key. `registerStandardChains` ran at engine init (before setStory →
+        // initializeWorld), so a same-key `chainEvent` REPLACES the stdlib default
+        // in place. Idempotent across restart (keyed replacement).
+        for (const [alias, handler] of this.boundChains) {
+            const reg = (0, chain_map_js_1.resolveChain)(alias);
+            if (!reg) {
+                // The chord analyzer's `analysis.unknown-chain` gate catches this first;
+                // this backstops rogue IR reaching the loader.
+                throw new errors_js_1.LoadError(`Chain hatch \`${alias}\` names no known stdlib chain.`);
+            }
+            world.chainEvent(reg.trigger, handler, { key: reg.key, priority: reg.priority });
+        }
+        // ADR-215: `use`-declared trusted extensions register FIRST — their
+        // world-side registrations (interceptors, resolvers) must exist before
+        // any entity composes their vocabulary. Unknown names are LoadErrors
+        // (the compiler's manifest gate catches them first; this backstops
+        // rogue IR).
+        for (const name of this.ir.uses ?? []) {
+            const registration = extension_registry_js_1.EXTENSION_REGISTRY.get(name);
+            if (!registration) {
+                throw new errors_js_1.LoadError(`\`use ${name}\` names no trusted extension — known: ${[...extension_registry_js_1.EXTENSION_REGISTRY.keys()].join(', ')}.`);
+            }
+            registration.registerWorld?.(world);
+        }
         const built = [];
-        // Pass 1 — create every non-player entity.
+        // Pass 0 — regions, parents before children (ADR-236 D3): a nested
+        // region's `parentRegionId` is validated by `createRegion` at creation,
+        // so the parent's world entity must already exist.
+        for (const irEntity of this.regionsInParentFirstOrder()) {
+            built.push({ ir: irEntity, entity: this.buildEntity(world, irEntity) });
+        }
+        // Pass 1 — create every remaining non-player entity.
         for (const irEntity of this.ir.entities) {
-            if (irEntity.isPlayer)
+            if (irEntity.isPlayer || this.worldIds.has(irEntity.id))
                 continue;
             built.push({ ir: irEntity, entity: this.buildEntity(world, irEntity) });
         }
         // Pass 2 — placement, exits, blocked exits, initial states.
+        // Placement is WORLD CONSTRUCTION, not a runtime action: it goes through
+        // AuthorModel.moveEntity, which bypasses the runtime containment rules
+        // (a closed trunk can hold its contents at load — the plain
+        // world.moveEntity refusal was a silent drop; David-approved fix,
+        // 2026-07-18, matching the TS story path's established pattern).
+        const author = new world_model_1.AuthorModel(world.getDataStore(), world);
         for (const { ir: irEntity, entity } of built) {
             if (irEntity.placement && irEntity.placement.relation !== 'starts-in') {
-                world.moveEntity(entity.id, this.requireWorldId(irEntity.placement.place, irEntity));
+                author.moveEntity(entity.id, this.requireWorldId(irEntity.placement.place, irEntity));
             }
-            for (const exit of irEntity.exits) {
-                world.connectRooms(entity.id, this.requireWorldId(exit.to, irEntity), toDirection(exit.direction, irEntity));
+            // ADR-236 D2: region membership through the platform seam —
+            // `assignRoom` sets RoomTrait.regionId (never touched directly here);
+            // member regions were parented at creation (pass 0), so only room
+            // members remain to wire.
+            for (const member of irEntity.containing ?? []) {
+                const memberIr = this.ir.entities.find((e) => e.id === member.id);
+                if (memberIr && memberIr.kinds.some((k) => k.name === 'room')) {
+                    world.assignRoom(this.requireWorldId(member.id, irEntity), entity.id);
+                }
             }
-            for (const blocked of irEntity.blockedExits) {
-                // Unconditional blocks are static; `is blocked while <cond>` blocks
-                // are derived — the runtime recomputes them with dark-while (grammar
-                // log 2026-07-10; initial evaluation at player finalization).
-                if (blocked.condition === null) {
-                    world_model_1.RoomBehavior.blockExit(entity, toDirection(blocked.direction, irEntity), this.phraseText(blocked.phraseKey));
+            for (const exit of irEntity.exits) {
+                const toId = this.requireWorldId(exit.to, irEntity);
+                const direction = toDirection(exit.direction, irEntity);
+                if (exit.via === null) {
+                    // Defensive (Phase 8 #6, belt-and-suspenders with the analyzer's
+                    // door-plain-mirror gate): connectRooms stamps BOTH directions, so
+                    // a plain exit whose reverse side is already door-wired would
+                    // silently unwire that door. The compiler refuses this; reaching
+                    // here means rogue IR.
+                    const targetRoomTrait = world.getEntity(toId)?.get(world_model_1.TraitType.ROOM);
+                    const reverseExit = targetRoomTrait?.exits?.[(0, world_model_1.getOppositeDirection)(direction)];
+                    if (reverseExit?.via && reverseExit.destination === entity.id) {
+                        throw new errors_js_1.LoadError(`\`${irEntity.name}\`: plain \`${exit.direction}\` exit mirrors a door-wired exit on \`${exit.to}\` — rogue IR (the compiler's door-plain-mirror gate refuses this).`, exit.span);
+                    }
+                    world.connectRooms(entity.id, toId, direction);
+                    continue;
+                }
+                // ADR-234 D1/D2 via ADR-237 D4: the door exit wires through the
+                // one platform primitive — DoorTrait attached here (room1 = the
+                // declaring room, per the createDoor placement convention), then
+                // connectRooms stamps `via` both directions and places the door.
+                // A door wires exactly once: the analyzer's checkDoors gates
+                // guarantee any second reference is the exact mirror, whose exits
+                // the first wiring already stamped — verified, then skipped.
+                const doorId = this.requireWorldId(exit.via, irEntity);
+                const door = world.getEntity(doorId);
+                const doorTrait = door?.get(world_model_1.TraitType.DOOR);
+                if (doorTrait) {
+                    const isMirror = doorTrait.room1 === toId && doorTrait.room2 === entity.id;
+                    if (!isMirror) {
+                        throw new errors_js_1.LoadError(`\`${irEntity.name}\`: door \`${exit.via}\` is already wired to a different room pair — rogue IR (the compiler's door gates refuse this).`, exit.span);
+                    }
+                    continue;
                 }
+                door?.add(new world_model_1.DoorTrait({ room1: entity.id, room2: toId }));
+                world.connectRooms(entity.id, toId, direction, doorId);
             }
+            // Blocked exits — ADR-240 D2 (Option A): ALL of them, conditional and
+            // unconditional alike, are registered as live evaluators by the
+            // runtime's bind(); nothing is stamped onto RoomTrait.blockedExits
+            // here anymore (the trait map remains the hand-written TS stories'
+            // surface, consulted by going as the fall-through).
             // ADR-227: `deadly: <phrase>` — the no-escape room marker lowers to
             // DeadlyRoomTrait (safeVerbs default look/examine); the ENGINE
             // auto-registers the deadly-room transformer, so no runtime code here.
@@ -238,7 +327,7 @@ class ChordStory {
             // to one command transformer in onEngineReady.
             for (const deadly of irEntity.deadlyExits) {
                 if (deadly.condition !== null) {
-                    throw new errors_1.LoadError('`is deadly while <condition>` is not wired yet — the conditional deadly exit is post-scope (mirror: role-bound trait clauses). Use an unconditional `is deadly:` or an `on going` clause with `kill the player when <condition>`.', deadly.span);
+                    throw new errors_js_1.LoadError('`is deadly while <condition>` is not wired yet — the conditional deadly exit is post-scope (mirror: role-bound trait clauses). Use an unconditional `is deadly:` or an `on going` clause with `kill the player when <condition>`.', deadly.span);
                 }
                 const direction = toDirection(deadly.direction, irEntity);
                 const byRoom = this.deadlyExits.get(entity.id) ?? new Map();
@@ -246,7 +335,7 @@ class ChordStory {
                 this.deadlyExits.set(entity.id, byRoom);
             }
             if (irEntity.states.length > 0) {
-                world.setStateValue(state_keys_1.CHORD_STATE_PREFIX + irEntity.id, irEntity.states[0]);
+                world.setStateValue(state_keys_js_1.CHORD_STATE_PREFIX + irEntity.id, irEntity.states[0]);
             }
             // Z2 (ADR-211): compile `{key}` description markers onto ADR-209
             // snippet storage — atomically per room, before the engine's
@@ -255,9 +344,17 @@ class ChordStory {
                 this.compileRoomSnippets(world, irEntity, entity);
             }
         }
+        // ADR-234 D3 backstop (rogue IR — the compiler's `door-unconnected`
+        // gate refuses this): a door no `through` exit wired has no room pair
+        // and could never resolve in play.
+        for (const { ir: irEntity, entity } of built) {
+            if (irEntity.kinds.some((k) => k.name === 'door') && !entity.has(world_model_1.TraitType.DOOR)) {
+                throw new errors_js_1.LoadError(`Door \`${irEntity.name}\` was never wired by a \`through\` exit line — rogue IR (the compiler's door gates refuse this).`, irEntity.span);
+            }
+        }
         // The story object starts in its first declared phase (ratchet D2).
         if (this.ir.story.states.length > 0) {
-            world.setStateValue(state_keys_1.CHORD_STORY_STATE_KEY, this.ir.story.states[0]);
+            world.setStateValue(state_keys_js_1.CHORD_STORY_STATE_KEY, this.ir.story.states[0]);
         }
         // Declared scores set the ceiling (dedup-by-identity makes the sum
         // exact — ADR-129).
@@ -329,6 +426,17 @@ class ChordStory {
         if (startIr) {
             world.moveEntity(player.id, this.requireWorldId(startIr, irPlayer ?? undefined));
         }
+        // Player-block composition (Gap-2 ruling, David 2026-07-18): the
+        // player composes trait adjectives + `starts` states through the SAME
+        // loader path as any entity (`a person` is analyzer-gated to a no-op;
+        // NPC behaviors are refused at compile). Runs here — the second
+        // lifecycle hook — so entity-valued configs resolve against the
+        // fully-built world regardless of createPlayer/initializeWorld order.
+        if (irPlayer) {
+            this.applyTraitAdjectives(player, irPlayer, null);
+            this.applyStartsStates(player, irPlayer);
+            this.resolvePendingEntityRefs();
+        }
         // Carried items: into inventory (ADR-230 Phase 6 — `carries the X`).
         for (const carriedIrId of irPlayer?.carries ?? []) {
             world.moveEntity(this.requireWorldId(carriedIrId, irPlayer ?? undefined), player.id);
@@ -340,14 +448,13 @@ class ChordStory {
             const worn = world.getEntity(wornId);
             const wearable = worn?.get(world_model_1.TraitType.WEARABLE);
             if (!wearable) {
-                throw new errors_1.LoadError(`\`${wornIrId}\` is worn by the player but is not wearable.`, irPlayer?.span);
+                throw new errors_js_1.LoadError(`\`${wornIrId}\` is worn by the player but is not wearable.`, irPlayer?.span);
             }
             wearable.worn = true;
             wearable.wornBy = player.id;
         }
-        // Initial evaluation of derived properties (`dark while`) — the player
-        // and their possessions now exist, so conditions are decidable.
-        this.runtime.recomputeDerived(world);
+        // ADR-240: no initial derived-property evaluation — derived state is
+        // registered evaluators, consulted live at every read.
     }
     extendLanguage(language) {
         // `addMessage` is the concrete providers' registration surface
@@ -355,12 +462,23 @@ class ChordStory {
         // structurally so the loader stays locale-neutral.
         const registry = language;
         if (typeof registry.addMessage !== 'function') {
-            throw new errors_1.LoadError('The language provider does not support message registration (addMessage).');
+            throw new errors_js_1.LoadError('The language provider does not support message registration (addMessage).');
         }
         const table = this.ir.phrases.locales[this.ir.phrases.defaultLocale] ?? {};
         for (const [key, phrase] of Object.entries(table)) {
             registry.addMessage(key, templateFor(phrase));
         }
+        // ADR-242 D7: declared pronoun sets ride the same seam — the same
+        // structural probe, throwing a legible error only when a story
+        // actually declares sets the provider cannot take.
+        if (this.ir.pronounSets.length > 0) {
+            if (typeof registry.registerPronounSet !== 'function') {
+                throw new errors_js_1.LoadError('The language provider does not support pronoun-set registration (registerPronounSet).');
+            }
+            for (const set of this.ir.pronounSets) {
+                registry.registerPronounSet(set.name, set.forms);
+            }
+        }
     }
     getCustomVocabulary() {
         return { verbs: this.ir.verbs.map((v) => toVocabularyVerb(v)) };
@@ -379,6 +497,37 @@ class ChordStory {
      * state is world state — no runner-state plumbing (design.md §6).
      */
     onEngineReady(engine) {
+        // ADR-216 `client has`: wire the LIVE capability source (the engine
+        // negotiates capabilities at start(); reads happen per evaluation).
+        // Engines without the accessor leave the text-only default in place.
+        if (engine.getClientCapabilities) {
+            this.evaluator.setCapabilitiesProvider(() => engine.getClientCapabilities());
+        }
+        // ADR-215 Q4: NPCs are CORE — the plugin auto-wires unconditionally
+        // (unlike the scheduler's daemon-gated registration below), and each
+        // factory-configured behavior registers under its per-entity id.
+        const npcPlugin = new plugin_npc_1.NpcPlugin();
+        engine.getPluginRegistry().register(npcPlugin);
+        const npcService = npcPlugin.getNpcService();
+        for (const pending of this.npcBehaviors) {
+            npcService.registerBehavior(this.buildNpcBehavior(pending));
+        }
+        // ADR-215 `use state-machines`: the plugin registers engine-side and
+        // every `define machine` lowers into its registry (Chord conditions
+        // ride as custom guards, Chord bodies as custom effects). Machines in
+        // rogue IR without the `use` are a LoadError, never silently dead.
+        if ((this.ir.machines ?? []).length > 0 && !(this.ir.uses ?? []).includes('state-machines')) {
+            throw new errors_js_1.LoadError('`define machine` needs `use state-machines` in the story header.', this.ir.machines[0].span);
+        }
+        if ((this.ir.uses ?? []).includes('state-machines')) {
+            const smPlugin = new plugin_state_machine_1.StateMachinePlugin();
+            engine.getPluginRegistry().register(smPlugin);
+            const smRegistry = smPlugin.getRegistry();
+            for (const machine of this.ir.machines ?? []) {
+                const { definition, bindings } = this.buildMachineDefinition(machine);
+                smRegistry.register(definition, bindings);
+            }
+        }
         const daemons = this.runtime.buildSchedulerDaemons();
         if (daemons.length > 0) {
             const plugin = new plugin_scheduler_1.SchedulerPlugin();
@@ -399,6 +548,58 @@ class ChordStory {
         // built-in contributor evaluates them.
         this.registerPresentEntries(engine);
     }
+    /**
+     * ADR-216 custom channels + ADR-215's third contribution part: every
+     * `define channel` lowers to a real IOChannel (JSON data projection —
+     * the turn's last event of the declared type, `take` fields projected
+     * from its data), and every `use`d extension gets its reserved
+     * `registerChannels` slot invoked (no bundled extension registers one
+     * today — the leg is live but unexercised; a novel renderer would ship
+     * there, keeping stories pure IR). The engine invokes this hook once at
+     * start (`Story.registerChannels`, engine/src/game-engine.ts).
+     *
+     * ADR-241 D4: family channels (`define ambient`/`define layer`, plus
+     * the implied `main` bed) register through stdlib's family builders —
+     * `ambient:<word>` / `image:<word>` ids, capability gates inherited
+     * from the builders (`sound` / `images`). Data channels are untouched.
+     */
+    registerChannels(registry) {
+        for (const channel of this.ir.channels ?? []) {
+            if (channel.family !== 'data') {
+                registry.add(channel.family === 'ambient'
+                    ? (0, stdlib_1.createAmbientChannel)(channel.name)
+                    : (0, stdlib_1.createImageChannel)(channel.name));
+                continue;
+            }
+            const { returns } = channel;
+            // ADR-256: the IR `fromEvent` is a dotless Chord id; match against the
+            // platform runtime type (media.* → dotted; author events pass through),
+            // the same translation the emit seam applies, so the two always agree.
+            const fromEvent = (0, event_id_map_js_1.translateEventId)(channel.fromEvent);
+            const definition = {
+                id: channel.name,
+                contentType: 'json',
+                mode: channel.mode,
+                emit: 'sparse',
+                ...(channel.gatedBy ? { gatedBy: channel.gatedBy } : {}),
+                produce: (ctx) => {
+                    for (let i = ctx.events.length - 1; i >= 0; i--) {
+                        const event = ctx.events[i];
+                        if (event.type !== fromEvent)
+                            continue;
+                        const data = (event.data ?? {});
+                        const value = this.evaluateChannelReturn(returns, data);
+                        return channel.mode === 'append' ? [value] : value;
+                    }
+                    return undefined;
+                },
+            };
+            registry.add(definition);
+        }
+        for (const name of this.ir.uses ?? []) {
+            extension_registry_js_1.EXTENSION_REGISTRY.get(name)?.registerChannels?.(registry);
+        }
+    }
     /**
      * The deadly-exit command transformer (ADR-227). Redirects `going
      * <deadly-direction>` from a room with declared deadly exits to
@@ -468,13 +669,13 @@ class ChordStory {
             const ownerWorldId = this.worldIds.get(irEntity.id);
             if (!ownerWorldId)
                 continue;
-            const texts = phrase.variants.map((v) => (v.text === 'nothing' ? '' : (0, text_1.withLineBreaks)(v.text)));
+            const texts = phrase.variants.map((v) => (v.text === 'nothing' ? '' : (0, text_js_1.withLineBreaks)(v.text)));
             const content = texts.length === 1 && !phrase.strategy
                 ? { kind: 'literal', text: texts[0] }
                 : {
                     kind: 'choice',
                     alternatives: texts.map((text) => ({ kind: 'literal', text })),
-                    selector: runtime_1.STRATEGY_SELECTOR[phrase.strategy ?? 'cycling'],
+                    selector: runtime_js_1.STRATEGY_SELECTOR[phrase.strategy ?? 'cycling'],
                     // ADR-212 §4 caller contract: entityId = owner, messageKey =
                     // counterKey — the platform warns on a mismatch.
                     entityId: ownerWorldId,
@@ -512,6 +713,14 @@ class ChordStory {
     extendParser(parser) {
         const grammar = parser.getStoryGrammar();
         for (const action of this.ir.actions) {
+            // Bare-verb forms (platform-issue-sweep Phase 8 #13, David's ruling:
+            // ALL dispatch actions): dispatch validate fully handles the no-target
+            // case (authored `refuse without` arm, else the platform default), but
+            // compiler-emitted grammar always carried the slot, so a bare `lower`
+            // (or friendly-zoo's `pet`/`feed`) never parsed far enough to reach it.
+            // Register each pattern's literal prefix as its own rule, below the
+            // slotted forms so they win whenever a target is named.
+            const bareForms = new Set();
             for (const pattern of action.patterns) {
                 if (pattern.cardinality)
                     continue; // `→ each …` expansion is engine-owned (Phase C)
@@ -519,6 +728,18 @@ class ChordStory {
                     .map((part) => (part.kind === 'slot' ? `:${part.word}` : part.word))
                     .join(' ');
                 grammar.define(text).mapsTo(`chord.action.${action.name}`).withPriority(150).build();
+                const slotIndex = pattern.parts.findIndex((part) => part.kind === 'slot');
+                if (slotIndex > 0) {
+                    const bare = pattern.parts
+                        .slice(0, slotIndex)
+                        .map((part) => part.word)
+                        .join(' ');
+                    if (bare)
+                        bareForms.add(bare);
+                }
+            }
+            for (const bare of bareForms) {
+                grammar.define(bare).mapsTo(`chord.action.${action.name}`).withPriority(140).build();
             }
         }
     }
@@ -541,87 +762,181 @@ class ChordStory {
         };
     }
     // ------------------------------------------------------- entity build
+    /** Region IR id → parent region IR id (the parent's `containing` lists the child — ADR-236 D3). */
+    regionParents = new Map();
+    /**
+     * Region entities in parent-first order, filling `regionParents` on the
+     * way (ADR-236 D3). The compiler's cycle gate guarantees the walk ends; a
+     * cycle here means rogue IR and is a LoadError, never a hang.
+     */
+    regionsInParentFirstOrder() {
+        const regions = this.ir.entities.filter((e) => !e.isPlayer && e.kinds.some((k) => k.name === 'region'));
+        const byId = new Map(regions.map((r) => [r.id, r]));
+        this.regionParents.clear();
+        for (const region of regions) {
+            for (const member of region.containing ?? []) {
+                if (byId.has(member.id))
+                    this.regionParents.set(member.id, region.id);
+            }
+        }
+        const ordered = [];
+        const state = new Map();
+        const visit = (region) => {
+            const s = state.get(region.id);
+            if (s === 'done')
+                return;
+            if (s === 'visiting') {
+                throw new errors_js_1.LoadError(`Region containment cycle at \`${region.name}\` — the compiler gate should have refused this story.`, region.span);
+            }
+            state.set(region.id, 'visiting');
+            const parentId = this.regionParents.get(region.id);
+            const parent = parentId ? byId.get(parentId) : undefined;
+            if (parent)
+                visit(parent);
+            state.set(region.id, 'done');
+            ordered.push(region);
+        };
+        for (const region of regions)
+            visit(region);
+        return ordered;
+    }
     buildEntity(world, irEntity) {
         if (irEntity.kinds.length > 1) {
-            throw new errors_1.LoadError(`\`${irEntity.name}\` declares more than one kind noun.`, irEntity.span);
+            throw new errors_js_1.LoadError(`\`${irEntity.name}\` declares more than one kind noun.`, irEntity.span);
         }
         const kind = irEntity.kinds[0]?.name ?? null;
         const description = irEntity.descriptionKey ? this.phraseText(irEntity.descriptionKey) : undefined;
-        const h = (0, helpers_1.createHelpers)(world);
+        // ADR-237 D3: direct trait composition — the loader builds on the
+        // world-model surface itself; `@sharpee/helpers` is author-facing only.
+        const aliases = irEntity.aka.length ? irEntity.aka : undefined;
         let entity;
         switch (kind) {
             case 'room': {
-                const builder = h.room(irEntity.name);
-                if (description)
-                    builder.description(description);
                 // Z1: `first time` prose → RoomTrait.initialDescription (first look
                 // shows it, later looks show the standard description — stdlib's
                 // looking-data reads the field; no stdlib change).
                 const initialDescription = irEntity.initialDescriptionKey
                     ? this.phraseText(irEntity.initialDescriptionKey)
                     : undefined;
-                if (initialDescription)
-                    builder.initialDescription(initialDescription);
-                if (irEntity.aka.length)
-                    builder.aliases(...irEntity.aka);
-                if (irEntity.traits.some((t) => t.name === 'dark' && t.condition === null))
-                    builder.dark();
-                entity = builder.build();
+                entity = world.createEntity(irEntity.name, 'room');
+                entity.add(new world_model_1.RoomTrait({
+                    requiresLight: irEntity.traits.some((t) => t.name === 'dark' && t.condition === null),
+                    initialDescription,
+                }));
+                entity.add(new world_model_1.IdentityTrait({ name: irEntity.name, description, aliases }));
                 break;
             }
             case 'container': {
-                const builder = h.container(irEntity.name);
-                if (description)
-                    builder.description(description);
-                if (irEntity.aka.length)
-                    builder.aliases(...irEntity.aka);
-                if (irEntity.traits.some((t) => t.name === 'openable'))
-                    builder.openable();
-                // NOTE: no `builder.lockable()` pre-add — applyTraitAdjectives owns
-                // the lockable composition so `with key X` config is never dropped
-                // (ADR-230 Phase 9a: the keyless pre-add made the keyed re-add skip).
-                entity = builder.build();
+                // NOTE: no OpenableTrait/LockableTrait pre-adds — applyTraitAdjectives
+                // owns both compositions uniformly. For lockable, a keyless pre-add
+                // made the keyed re-add skip, dropping `with key X` config (ADR-230
+                // Phase 9a). For openable, the pre-add carried an open-by-default,
+                // splitting container-kind entities from adjective-only ones; ADR-231
+                // D5b removed it so OpenableTrait's default (closed) is authoritative
+                // everywhere — `starts open` is the author's escape hatch.
+                entity = world.createEntity(irEntity.name, 'object');
+                entity.add(new world_model_1.IdentityTrait({ name: irEntity.name, description, aliases }));
+                entity.add(new world_model_1.ContainerTrait());
                 this.applyContainerConfig(entity, irEntity.kinds[0]);
                 break;
             }
             case 'person': {
-                const builder = h.actor(irEntity.name);
-                if (description)
-                    builder.description(description);
-                if (irEntity.aka.length)
-                    builder.aliases(...irEntity.aka);
-                entity = builder.build();
+                entity = world.createEntity(irEntity.name, 'actor');
+                entity.add(new world_model_1.ActorTrait());
+                // ADR-242 D2/D3: `proper` → the player's own proper-name shape
+                // (properName + empty article); otherwise the plain IdentityTrait
+                // defaults stand ('a', contextual articles). The old helpers-era
+                // `article: undefined` pin is gone — no loader path constructs an
+                // undefined article. `pronouns` maps to pronounSet only when
+                // declared (ruled Q-2: no injected default — by-number fallback).
+                const proper = irEntity.traits.some((t) => t.name === 'proper' && t.condition === null);
+                entity.add(new world_model_1.IdentityTrait({
+                    name: irEntity.name,
+                    description,
+                    aliases,
+                    ...(proper ? { properName: true, article: '' } : {}),
+                    ...(irEntity.pronouns !== undefined ? { pronounSet: irEntity.pronouns } : {}),
+                }));
                 break;
             }
             case 'supporter': {
-                const builder = h.object(irEntity.name);
-                if (description)
-                    builder.description(description);
-                if (irEntity.aka.length)
-                    builder.aliases(...irEntity.aka);
-                entity = builder.build();
+                entity = world.createEntity(irEntity.name, 'object');
+                entity.add(new world_model_1.IdentityTrait({ name: irEntity.name, description, aliases }));
                 entity.add(new world_model_1.SupporterTrait({ capacity: supporterCapacity(irEntity.kinds[0]) }));
                 break;
             }
-            case 'door':
-                throw new errors_1.LoadError(`\`${irEntity.name}\`: doors need \`between\` placement, which the Phase A loader does not support yet.`, irEntity.span);
+            case 'region': {
+                // ADR-236 D1: built on the shipped platform seam — createRegion +
+                // assignRoom ARE the shared mechanics (RoomTrait.regionId is never
+                // set directly). Pass 0 built parents first, so a nested child's
+                // parentRegionId resolves here.
+                const parentIr = this.regionParents.get(irEntity.id);
+                const parentRegionId = parentIr ? this.worldIds.get(parentIr) : undefined;
+                entity = world.createRegion(`rg-${irEntity.id}`, {
+                    name: irEntity.name,
+                    ...(parentRegionId ? { parentRegionId } : {}),
+                });
+                // A region block composes like any entity block (aka, description):
+                // both live on IdentityTrait; whether any action surfaces them is
+                // the platform's business (ADR-236 D1).
+                entity.add(new world_model_1.IdentityTrait({
+                    name: irEntity.name,
+                    ...(description ? { description } : {}),
+                    aliases: irEntity.aka,
+                    article: irEntity.article ?? 'the',
+                }));
+                break;
+            }
+            case 'door': {
+                // ADR-234 D4: SceneryTrait + OpenableTrait starting closed compose
+                // automatically (createDoor parity; `starts open` is the author's
+                // override via applyStartsStates). DoorTrait is attached at exit
+                // wiring — its room pair comes from the `through` exit line, and
+                // the trait's constructor requires both rooms.
+                entity = world.createEntity(irEntity.name, 'door');
+                entity.add(new world_model_1.IdentityTrait({ name: irEntity.name, description, aliases }));
+                entity.add(new world_model_1.SceneryTrait());
+                entity.add(new world_model_1.OpenableTrait({ isOpen: false }));
+                break;
+            }
             case null: {
-                const builder = h.object(irEntity.name);
-                if (description)
-                    builder.description(description);
-                if (irEntity.aka.length)
-                    builder.aliases(...irEntity.aka);
-                entity = builder.build();
+                entity = world.createEntity(irEntity.name, 'object');
+                entity.add(new world_model_1.IdentityTrait({ name: irEntity.name, description, aliases }));
                 break;
             }
             default:
-                throw new errors_1.LoadError(`\`${irEntity.name}\`: unknown kind noun \`${kind}\`.`, irEntity.span);
+                throw new errors_js_1.LoadError(`\`${irEntity.name}\`: unknown kind noun \`${kind}\`.`, irEntity.span);
         }
         this.applyTraitAdjectives(entity, irEntity, kind);
+        this.applyStartsStates(entity, irEntity);
         this.worldIds.set(irEntity.id, entity.id);
         this.irIds.set(entity.id, irEntity.id);
         return entity;
     }
+    /**
+     * ADR-231 D5a: map each accepted `starts <state>` initializer to the
+     * paired trait's initial-value field (locked→isLocked:true, closed→
+     * isOpen:false, on→isOn:true, …). Runs AFTER trait composition (the
+     * adjective-composed traits, ADR-231 D5b: there are no builder pre-adds
+     * left) — so a declared initializer always wins over any
+     * trait default. Only the trait boolean is set; the state adjective
+     * itself is never stored story state (the shadow-state ratchet).
+     * The analyzer's pairing gate guarantees the trait is present; a missing
+     * trait here is a defect, reported as a LoadError, never a silent skip.
+     */
+    applyStartsStates(entity, irEntity) {
+        for (const state of irEntity.startsStates ?? []) {
+            const mapping = STARTS_STATE_TRAIT_FIELDS.get(state);
+            if (!mapping) {
+                throw new errors_js_1.LoadError(`\`${irEntity.name}\`: \`starts ${state}\` has no trait-field mapping — the compiler and loader tables are out of step.`, irEntity.span);
+            }
+            const trait = entity.get(mapping.traitType);
+            if (!trait) {
+                throw new errors_js_1.LoadError(`\`${irEntity.name}\`: \`starts ${state}\` needs the \`${mapping.traitName}\` trait composed — the analyzer pairing gate should have refused this story.`, irEntity.span);
+            }
+            trait[mapping.field] = mapping.value;
+        }
+    }
     /**
      * Resolve trait-config entity references (`with tool X`, `with key X`)
      * to world entity ids (ADR-230 D3c / Phase 9a) — runs once, after every
@@ -631,7 +946,7 @@ class ChordStory {
         for (const pending of this.pendingEntityRefs) {
             const worldId = this.worldIds.get(pending.irRefId);
             if (!worldId) {
-                throw new errors_1.LoadError(`\`${pending.ownerName}\`: a trait-config entity reference was never built.`, pending.span);
+                throw new errors_js_1.LoadError(`\`${pending.ownerName}\`: a trait-config entity reference was never built.`, pending.span);
             }
             pending.apply(worldId);
         }
@@ -678,10 +993,10 @@ class ChordStory {
                     surfaces++;
                 }
                 if (surfaces === 0) {
-                    throw new errors_1.LoadError(`\`${irEntity.name}\` is ${adjective} but registers no ${gerund} implementation — add \`on ${gerund} it:\` (or compose a trait that has one).`, irEntity.span);
+                    throw new errors_js_1.LoadError(`\`${irEntity.name}\` is ${adjective} but registers no ${gerund} implementation — add \`on ${gerund} it:\` (or compose a trait that has one).`, irEntity.span);
                 }
                 if (surfaces > 1) {
-                    throw new errors_1.LoadError(`\`${irEntity.name}\` has ${surfaces} ${gerund} implementations — a ${adjective} entity registers exactly one (one \`on ${gerund} it\` clause or one capability behavior).`, irEntity.span);
+                    throw new errors_js_1.LoadError(`\`${irEntity.name}\` has ${surfaces} ${gerund} implementations — a ${adjective} entity registers exactly one (one \`on ${gerund} it\` clause or one capability behavior).`, irEntity.span);
                 }
             }
         }
@@ -698,12 +1013,18 @@ class ChordStory {
                     continue;
                 const def = this.ir.traits.find((t) => t.name === trait.name);
                 if (def && def.onClauses.length > 0 && def.onClauses.every((c) => c.binding === 'every-turn')) {
-                    entity.add(new ChordDataTrait(state_keys_1.CHORD_TRAIT_PREFIX + def.name, this.traitFieldValues(def, trait)));
+                    entity.add(new ChordDataTrait(state_keys_js_1.CHORD_TRAIT_PREFIX + def.name, this.traitFieldValues(def, trait)));
                     continue;
                 }
-                throw new errors_1.LoadError(`Conditional composition isn't supported for \`${trait.name}\` — move the condition inside the trait (\`on <action> it\` clauses can test it) or split the behavior.`, trait.span);
+                throw new errors_js_1.LoadError(`Conditional composition isn't supported for \`${trait.name}\` — move the condition inside the trait (\`on <action> it\` clauses can test it) or split the behavior.`, trait.span);
             }
             switch (trait.name) {
+                case 'proper':
+                    // ADR-242 D1: identity configuration, consumed by the person
+                    // branch's IdentityTrait construction (like the room branch's
+                    // `dark`) — without this case it would fall through to the
+                    // authored-trait default and mint a spurious ChordDataTrait.
+                    break;
                 case 'scenery':
                     if (!entity.has(world_model_1.TraitType.SCENERY))
                         entity.add(new world_model_1.SceneryTrait());
@@ -714,18 +1035,38 @@ class ChordStory {
                 case 'readable':
                     entity.add(new world_model_1.ReadableTrait({ text: configValue(trait, 'text') ?? '' }));
                     break;
-                case 'openable':
-                    if (!entity.has(world_model_1.TraitType.OPENABLE))
-                        entity.add(new world_model_1.OpenableTrait());
+                case 'openable': {
+                    // Defect D3 fix (2026-07-17, ratchet G4): `openable with the
+                    // crowbar` (keyless per R3) gates opening on holding the tool
+                    // (OpenableTrait.toolId, ADR-230 D3b). Name → world id via the
+                    // shared pending mechanism — never the raw display-name string
+                    // (the lockable-bug class).
+                    if (entity.has(world_model_1.TraitType.OPENABLE))
+                        break;
+                    const openable = new world_model_1.OpenableTrait();
+                    const openToolName = entityConfigValue(trait);
+                    if (openToolName !== undefined) {
+                        this.pendingEntityRefs.push(this.entityRefFor(openToolName, 'tool', irEntity, trait.span, (worldId) => {
+                            openable.toolId = worldId;
+                        }));
+                    }
+                    entity.add(openable);
                     break;
+                }
                 case 'lockable': {
-                    // ADR-230 Phase 9a: `with key X` resolves name → world id through
-                    // the shared pending mechanism (forward refs legal) — the raw
-                    // display-name string never reaches LockableTrait.keyId.
+                    // ADR-230 Phase 9a: the key entity (`lockable with the iron key`,
+                    // keyless per R3) resolves name → world id through the shared
+                    // pending mechanism (forward refs legal) — the raw display-name
+                    // string never reaches LockableTrait.keyId.
                     if (entity.has(world_model_1.TraitType.LOCKABLE))
                         break;
-                    const lockable = new world_model_1.LockableTrait({});
-                    const keyName = configValue(trait, 'key');
+                    // ADR-234 D4 kind-scoped default: a lockable DOOR starts locked
+                    // (the IF convention; createDoor's `isLocked ?? true` parity) —
+                    // everywhere else the trait-wide default (unlocked) stands.
+                    // `starts unlocked` is the author's override: applyStartsStates
+                    // runs after composition, so a declared initializer always wins.
+                    const lockable = new world_model_1.LockableTrait(kind === 'door' ? { isLocked: true } : {});
+                    const keyName = entityConfigValue(trait);
                     if (keyName !== undefined) {
                         this.pendingEntityRefs.push(this.entityRefFor(keyName, 'key', irEntity, trait.span, (worldId) => {
                             lockable.keyId = worldId;
@@ -743,7 +1084,7 @@ class ChordStory {
                     if (entity.has(traitType))
                         break;
                     const toolGated = trait.name === 'cuttable' ? new world_model_1.CuttableTrait() : new world_model_1.DiggableTrait();
-                    const toolName = configValue(trait, 'tool');
+                    const toolName = entityConfigValue(trait);
                     if (toolName !== undefined) {
                         this.pendingEntityRefs.push(this.entityRefFor(toolName, 'tool', irEntity, trait.span, (worldId) => {
                             toolGated.toolId = worldId;
@@ -756,8 +1097,56 @@ class ChordStory {
                     entity.add(new world_model_1.SwitchableTrait());
                     break;
                 case 'edible':
-                    entity.add(new world_model_1.EdibleTrait());
+                    // Guarded so `edible, drinkable` composes order-independently —
+                    // a bare re-add here would drop drinkable's liquid flag.
+                    if (!entity.has(world_model_1.TraitType.EDIBLE))
+                        entity.add(new world_model_1.EdibleTrait());
+                    break;
+                case 'drinkable': {
+                    // Ratchet G1 (2026-07-17): the liquid marker — EDIBLE.liquid is
+                    // what routes the entity to drinking instead of eating.
+                    const edible = entity.get(world_model_1.TraitType.EDIBLE);
+                    if (edible)
+                        edible.liquid = true;
+                    else
+                        entity.add(new world_model_1.EdibleTrait({ liquid: true }));
+                    break;
+                }
+                case 'pushable':
+                    // Defect D1 fix (2026-07-17): the catalog accepted these two but
+                    // the loader had no case — `--check` passed stories that load
+                    // rejected. Default config (button-style, repeatable).
+                    if (!entity.has(world_model_1.TraitType.PUSHABLE))
+                        entity.add(new world_model_1.PushableTrait({}));
+                    break;
+                case 'pullable':
+                    if (!entity.has(world_model_1.TraitType.PULLABLE))
+                        entity.add(new world_model_1.PullableTrait({}));
+                    break;
+                case 'concealed': {
+                    // Ratchet G2 (2026-07-17): marker adjective — hidden from normal
+                    // view until searching reveals it (IdentityTrait.concealed).
+                    const identity = entity.get(world_model_1.TraitType.IDENTITY);
+                    if (identity)
+                        identity.concealed = true;
+                    break;
+                }
+                case 'hiding-spot': {
+                    // Ratchet G3 (2026-07-17): bare = the actor may hide at any
+                    // position; `with position <word>` narrows to exactly one.
+                    const HIDING_POSITIONS = ['behind', 'under', 'on', 'inside'];
+                    const position = configValue(trait, 'position');
+                    if (position !== undefined && !HIDING_POSITIONS.includes(position)) {
+                        throw new errors_js_1.LoadError(`\`${position}\` is not a hiding position — use behind, under, on, or inside.`, trait.span);
+                    }
+                    entity.add(new world_model_1.ConcealmentTrait({
+                        positions: position
+                            ? [position]
+                            : [...HIDING_POSITIONS],
+                        quality: 'good',
+                    }));
                     break;
+                }
                 case 'enterable': // ADR-218 §1a (ratchet F1) — default config, preposition `in`
                     if (!entity.has(world_model_1.TraitType.ENTERABLE))
                         entity.add(new world_model_1.EnterableTrait());
@@ -769,6 +1158,26 @@ class ChordStory {
                 case 'light-source':
                     entity.add(new world_model_1.LightSourceTrait());
                     break;
+                case 'guard':
+                case 'passive':
+                case 'wanderer':
+                case 'follower':
+                case 'patrol': {
+                    // ADR-215 Q4: CORE NPC behavior vocabulary — no `use` gate.
+                    this.applyNpcAdjective(entity, irEntity, trait);
+                    break;
+                }
+                case 'combatant':
+                case 'weapon': {
+                    // ADR-215 combat vocabulary — `use combat` extension adjectives.
+                    // The analyzer gated use-declaration and field names/types; this
+                    // check is the rogue-IR backstop.
+                    if (!(this.ir.uses ?? []).includes('combat')) {
+                        throw new errors_js_1.LoadError(`\`${trait.name}\` is \`combat\` extension vocabulary — add \`use combat\` to the story header.`, trait.span);
+                    }
+                    this.applyCombatAdjective(entity, irEntity, trait);
+                    break;
+                }
                 case 'plural': {
                     const identity = entity.get(world_model_1.TraitType.IDENTITY);
                     if (identity)
@@ -777,7 +1186,7 @@ class ChordStory {
                 }
                 case 'dark': {
                     if (kind !== 'room') {
-                        throw new errors_1.LoadError(`\`dark\` applies to rooms only.`, trait.span);
+                        throw new errors_js_1.LoadError(`\`dark\` applies to rooms only.`, trait.span);
                     }
                     break; // unconditional dark handled by the room builder
                 }
@@ -787,13 +1196,247 @@ class ChordStory {
                     // via `set`, serialized with the world — AC-6-safe).
                     const def = this.ir.traits.find((t) => t.name === trait.name);
                     if (def) {
-                        entity.add(new ChordDataTrait(state_keys_1.CHORD_TRAIT_PREFIX + def.name, this.traitFieldValues(def, trait)));
+                        entity.add(new ChordDataTrait(state_keys_js_1.CHORD_TRAIT_PREFIX + def.name, this.traitFieldValues(def, trait)));
                         break;
                     }
-                    throw new errors_1.LoadError(`Trait \`${trait.name}\` is not declared (\`define trait ${trait.name}\`) and is not a v1 adjective.`, trait.span);
+                    throw new errors_js_1.LoadError(`Trait \`${trait.name}\` is not declared (\`define trait ${trait.name}\`) and is not a v1 adjective.`, trait.span);
+                }
+            }
+        }
+    }
+    /**
+     * Per-entity NPC behavior configs stashed at composition time and
+     * registered with the NPC service at engine-ready (world ids exist by
+     * then, so patrol routes resolve). guard/passive use the plugin's
+     * pre-registered behaviors; the factory-built three get per-entity ids.
+     */
+    npcBehaviors = [];
+    /**
+     * ADR-215 Q4 core NPC routing: compose NpcTrait from a behavior
+     * adjective — behaviorId (`guard`/`passive` built-in; factory behaviors
+     * get `chord.npc.<id>`), movement defaults (movement behaviors default
+     * `canMove: true`), boolean fields via NPC_FIELD_ROUTES, and room-list
+     * fields (`allowed-rooms`/`forbidden-rooms`) filled through the shared
+     * pending-entity-ref mechanism once every entity exists.
+     */
+    applyNpcAdjective(entity, irEntity, trait) {
+        const isFactory = trait.name === 'wanderer' || trait.name === 'follower' || trait.name === 'patrol';
+        const data = {
+            behaviorId: isFactory ? `chord.npc.${irEntity.id}` : trait.name,
+            // Movement behaviors move by definition; `can-move false` overrides.
+            canMove: isFactory,
+        };
+        for (const setting of trait.config) {
+            const route = extension_registry_js_1.NPC_FIELD_ROUTES.get(setting.key);
+            if (!route)
+                continue; // behavior-factory params — consumed at engine-ready
+            if (route.convert === 'boolean') {
+                if (setting.value !== 'true' && setting.value !== 'false') {
+                    throw new errors_js_1.LoadError(`\`${irEntity.name}\`: \`${setting.key}\` takes \`true\` or \`false\`, got \`${setting.value}\`.`, trait.span);
                 }
+                data[route.field] = setting.value === 'true';
             }
         }
+        const npcTrait = new world_model_1.NpcTrait(data);
+        entity.add(npcTrait);
+        // Room lists resolve after every entity exists (pass-1 ordering).
+        for (const setting of trait.config) {
+            const route = extension_registry_js_1.NPC_FIELD_ROUTES.get(setting.key);
+            if (route?.convert !== 'rooms')
+                continue;
+            const target = [];
+            npcTrait[route.field] = target;
+            for (const memberIrId of setting.values ?? []) {
+                this.pendingEntityRefs.push({
+                    irRefId: memberIrId,
+                    ownerName: irEntity.name,
+                    span: trait.span,
+                    apply: (worldId) => target.push(worldId),
+                });
+            }
+        }
+        if (isFactory) {
+            this.npcBehaviors.push({ irId: irEntity.id, adjective: trait.name, config: trait.config, span: trait.span });
+        }
+    }
+    /**
+     * Build one per-entity NPC behavior instance from its stashed config
+     * (engine-ready time — world ids exist). Chord percentages convert to
+     * the platform's fractions here (`move-chance 50` → 0.5).
+     */
+    buildNpcBehavior(pending) {
+        const numberOf = (key) => {
+            const setting = pending.config.find((s) => s.key === key);
+            return setting ? Number(setting.value) : undefined;
+        };
+        const boolOf = (key) => {
+            const setting = pending.config.find((s) => s.key === key);
+            return setting ? setting.value === 'true' : undefined;
+        };
+        let behavior;
+        switch (pending.adjective) {
+            case 'wanderer': {
+                const percent = numberOf('move-chance');
+                behavior = (0, stdlib_2.createWandererBehavior)(percent === undefined ? {} : { moveChance: percent / 100 });
+                break;
+            }
+            case 'follower':
+                behavior = (0, stdlib_2.createFollowerBehavior)(boolOf('immediate') === undefined ? {} : { immediate: boolOf('immediate') });
+                break;
+            case 'patrol': {
+                const routeSetting = pending.config.find((s) => s.key === 'route');
+                if (!routeSetting || (routeSetting.values ?? []).length === 0) {
+                    throw new errors_js_1.LoadError(`A \`patrol\` NPC needs \`with route [ … ]\` naming its rooms.`, pending.span);
+                }
+                const route = (routeSetting.values ?? []).map((irId) => {
+                    const worldId = this.worldIds.get(irId);
+                    if (!worldId)
+                        throw new errors_js_1.LoadError(`A patrol route entry was never built.`, pending.span);
+                    return worldId;
+                });
+                behavior = (0, stdlib_2.createPatrolBehavior)({
+                    route,
+                    ...(boolOf('loop') === undefined ? {} : { loop: boolOf('loop') }),
+                    ...(numberOf('wait-turns') === undefined ? {} : { waitTurns: numberOf('wait-turns') }),
+                });
+                break;
+            }
+            default:
+                throw new errors_js_1.LoadError(`Unknown NPC behavior adjective \`${pending.adjective}\`.`, pending.span);
+        }
+        behavior.id = `chord.npc.${pending.irId}`;
+        return behavior;
+    }
+    /**
+     * Lower one `define machine` onto the ADR-119 shapes: platform id
+     * `chord.machine.<slug>`, role bindings as `$<role>` entries (world
+     * ids), action triggers on `if.action.<gerund>`, Chord conditions as
+     * custom guards over the shared evaluator, Chord bodies as one custom
+     * effect each through the runtime's statement executor.
+     */
+    buildMachineDefinition(machine) {
+        const bindings = {};
+        for (const role of machine.roles) {
+            const worldId = this.worldIds.get(role.entity);
+            if (!worldId) {
+                throw new errors_js_1.LoadError(`Machine \`${machine.name}\`: role \`${role.name}\`'s entity was never built.`, machine.span);
+            }
+            bindings[`$${role.name}`] = worldId;
+        }
+        const chordGuard = (condition) => ({
+            type: 'custom',
+            evaluate: (world) => this.evaluator.evalCondition(condition, { world: world }),
+        });
+        const chordEffect = (statements) => ({
+            type: 'custom',
+            execute: (world) => ({
+                events: this.runtime
+                    .execMachineBody(statements, world)
+                    .map((e) => ({ type: e.type, data: e.data, entities: e.entities })),
+            }),
+        });
+        const states = {};
+        for (const state of machine.states) {
+            const transitions = state.transitions.map((t) => {
+                let trigger;
+                switch (t.trigger.kind) {
+                    case 'action': {
+                        let targetEntity;
+                        if (t.trigger.target) {
+                            targetEntity = t.trigger.target.startsWith('$')
+                                ? t.trigger.target
+                                : this.worldIds.get(t.trigger.target);
+                            if (targetEntity === undefined) {
+                                throw new errors_js_1.LoadError(`Machine \`${machine.name}\`: a trigger target was never built.`, t.span);
+                            }
+                        }
+                        trigger = {
+                            type: 'action',
+                            actionId: `if.action.${t.trigger.action}`,
+                            ...(targetEntity !== undefined ? { targetEntity } : {}),
+                        };
+                        break;
+                    }
+                    case 'event':
+                        // ADR-256: translate the dotless Chord id to the platform runtime
+                        // type the machine fires on (media.* → dotted; author events pass
+                        // through), matching the emit seam.
+                        trigger = { type: 'event', eventId: (0, event_id_map_js_1.translateEventId)(t.trigger.event) };
+                        break;
+                    case 'condition':
+                        trigger = { type: 'condition', condition: chordGuard(t.trigger.condition) };
+                        break;
+                }
+                return {
+                    target: t.target,
+                    trigger,
+                    ...(t.condition ? { guard: chordGuard(t.condition) } : {}),
+                };
+            });
+            states[state.name] = {
+                ...(state.terminal ? { terminal: true } : {}),
+                ...(state.onEnter.length > 0 ? { onEnter: [chordEffect(state.onEnter)] } : {}),
+                ...(state.onExit.length > 0 ? { onExit: [chordEffect(state.onExit)] } : {}),
+                ...(transitions.length > 0 ? { transitions } : {}),
+            };
+        }
+        return {
+            definition: {
+                id: `chord.machine.${machine.name.replace(/\s+/g, '-')}`,
+                initialState: machine.initialState,
+                states,
+            },
+            bindings,
+        };
+    }
+    /**
+     * ADR-215 combat routing: compose `combatant` (CombatantTrait + the
+     * REQUIRED HealthTrait per ADR-226 — health/max-health route THERE) or
+     * `weapon` (WeaponTrait) from a composition's `with`-fields, via the
+     * exported COMBAT_FIELD_ROUTES table the manifest-conformance test pins.
+     */
+    applyCombatAdjective(entity, irEntity, trait) {
+        const values = {
+            combatant: {},
+            health: {},
+            weapon: {},
+        };
+        for (const setting of trait.config) {
+            const route = extension_registry_js_1.COMBAT_FIELD_ROUTES.get(setting.key);
+            if (!route) {
+                throw new errors_js_1.LoadError(`\`${irEntity.name}\`: \`${setting.key}\` has no combat field route — the compiler manifest and loader routes are out of step.`, trait.span);
+            }
+            if (route.convert === 'number') {
+                const parsed = Number(setting.value);
+                if (Number.isNaN(parsed)) {
+                    throw new errors_js_1.LoadError(`\`${irEntity.name}\`: \`${setting.key}\` needs a number, got \`${setting.value}\`.`, trait.span);
+                }
+                values[route.trait][route.field] = parsed;
+            }
+            else {
+                if (setting.value !== 'true' && setting.value !== 'false') {
+                    throw new errors_js_1.LoadError(`\`${irEntity.name}\`: \`${setting.key}\` takes \`true\` or \`false\`, got \`${setting.value}\`.`, trait.span);
+                }
+                values[route.trait][route.field] = setting.value === 'true';
+            }
+        }
+        if (trait.name === 'weapon') {
+            entity.add(new world_model_1.WeaponTrait(values.weapon));
+            return;
+        }
+        // CombatantTrait REQUIRES a HealthTrait (ADR-226 §2) — auto-attach,
+        // seeded from the health/max-health fields (defaults when omitted).
+        if (!entity.has(world_model_1.TraitType.HEALTH)) {
+            entity.add(new world_model_1.HealthTrait(values.health));
+        }
+        else if (Object.keys(values.health).length > 0) {
+            const health = entity.get(world_model_1.TraitType.HEALTH);
+            Object.assign(health, values.health);
+            if (values.health.health !== undefined && values.health.maxHealth === undefined) {
+                health.maxHealth = Math.max(health.maxHealth, health.health);
+            }
+        }
+        entity.add(new world_model_1.CombatantTrait(values.combatant));
     }
     /**
      * Initial values for a `define trait` instance: declared `starts`
@@ -811,7 +1454,7 @@ class ChordStory {
                 const lower = setting.value.toLowerCase();
                 const target = this.ir.entities.find((e) => e.name.toLowerCase() === lower || e.aka.includes(lower));
                 if (!target) {
-                    throw new errors_1.LoadError(`\`${setting.value}\` (config \`${setting.key}\`) names no entity.`, comp.span);
+                    throw new errors_js_1.LoadError(`\`${setting.value}\` (config \`${setting.key}\`) names no entity.`, comp.span);
                 }
                 values[setting.key] = target.id;
             }
@@ -838,7 +1481,7 @@ class ChordStory {
     requireWorldId(irId, at) {
         const id = this.worldIds.get(irId);
         if (!id) {
-            throw new errors_1.LoadError(`Entity \`${irId}\` is referenced before it exists in the world.`, at?.span);
+            throw new errors_js_1.LoadError(`Entity \`${irId}\` is referenced before it exists in the world.`, at?.span);
         }
         return id;
     }
@@ -890,9 +1533,9 @@ class ChordStory {
                 if (phrase.verbatim) {
                     // The analyzer already errors here (analysis.verbatim-marker);
                     // this is the loader's defensive half of the same contract.
-                    throw new errors_1.LoadError(`\`{${marker}}\` in \`${irEntity.name}\` names a verbatim phrase — verbatim text cannot splice at a description marker.`, phrase.span);
+                    throw new errors_js_1.LoadError(`\`{${marker}}\` in \`${irEntity.name}\` names a verbatim phrase — verbatim text cannot splice at a description marker.`, phrase.span);
                 }
-                const variantTexts = phrase.variants.map((v) => (v.text === 'nothing' ? '' : (0, text_1.withLineBreaks)(v.text)));
+                const variantTexts = phrase.variants.map((v) => (v.text === 'nothing' ? '' : (0, text_js_1.withLineBreaks)(v.text)));
                 let mentions;
                 if (phrase.condition) {
                     const subject = presenceSubject(phrase.condition, irEntity.id);
@@ -904,7 +1547,7 @@ class ChordStory {
                         gates.push(() => (0, stdlib_1.registerSnippetGate)(entity.id, marker, () => this.evaluator.evalCondition(condition, { world })));
                     }
                 }
-                const selector = phrase.strategy ? runtime_1.STRATEGY_SELECTOR[phrase.strategy] : undefined;
+                const selector = phrase.strategy ? runtime_js_1.STRATEGY_SELECTOR[phrase.strategy] : undefined;
                 let entry;
                 if (!selector && variantTexts.length === 1) {
                     // Single-variant plain phrase → plain string entry, never a Choice.
@@ -999,7 +1642,7 @@ class ChordStory {
                     break;
                 if (!phrase.condition)
                     continue; // analyzer already errored (detail-unconditional)
-                const text = (0, text_1.withLineBreaks)(phrase.variants[0]?.text ?? '');
+                const text = (0, text_js_1.withLineBreaks)(phrase.variants[0]?.text ?? '');
                 const shape = detailTraitShape(phrase.condition, irEntity.id);
                 if (shape === 'on' && entity.has(world_model_1.TraitType.SWITCHABLE)) {
                     entity.get(world_model_1.TraitType.SWITCHABLE).detailWhenOn = text;
@@ -1033,9 +1676,31 @@ class ChordStory {
     phraseText(key) {
         const phrase = this.ir.phrases.locales[this.ir.phrases.defaultLocale]?.[key];
         if (!phrase) {
-            throw new errors_1.LoadError(`Phrase \`${key}\` is missing from the IR — the compiler gate should have caught this.`);
+            throw new errors_js_1.LoadError(`Phrase \`${key}\` is missing from the IR — the compiler gate should have caught this.`);
+        }
+        return (0, text_js_1.withLineBreaks)(phrase.variants[0]?.text ?? '');
+    }
+    /**
+     * Evaluate a channel's `return` construct (ADR-253 D1) against an event's
+     * payload to produce the channel's value:
+     *  - `field`  → the raw field value (may be a non-string);
+     *  - `text`   → the template with each `(slot)` replaced by its event field;
+     *  - `phrase` → the named phrase's first-variant text, its `(slot)`s likewise
+     *    filled from the event payload (locale-aware via `phraseText`).
+     */
+    evaluateChannelReturn(returns, data) {
+        const fill = (template) => template.replace(/\(\s*([^)]+?)\s*\)/g, (_m, name) => {
+            const v = data[name];
+            return v === undefined || v === null ? '' : String(v);
+        });
+        switch (returns.kind) {
+            case 'field':
+                return data[returns.field];
+            case 'text':
+                return fill(returns.text);
+            case 'phrase':
+                return fill(this.phraseText(returns.phrase));
         }
-        return (0, text_1.withLineBreaks)(phrase.variants[0]?.text ?? '');
     }
 }
 exports.ChordStory = ChordStory;
@@ -1080,11 +1745,26 @@ function presenceSubject(cond, roomIrId) {
     }
     return null;
 }
+/**
+ * ADR-231 D5a platform mapping: `starts <state>` word → the paired trait's
+ * initial-value field and the boolean it sets. The language-side pairing
+ * table (which trait must be composed) is @sharpee/chord's
+ * STARTS_STATE_PAIRINGS; this is the loader's platform half — future
+ * stateful traits extend both tables, not the code.
+ */
+const STARTS_STATE_TRAIT_FIELDS = new Map([
+    ['locked', { traitType: world_model_1.TraitType.LOCKABLE, traitName: 'lockable', field: 'isLocked', value: true }],
+    ['unlocked', { traitType: world_model_1.TraitType.LOCKABLE, traitName: 'lockable', field: 'isLocked', value: false }],
+    ['closed', { traitType: world_model_1.TraitType.OPENABLE, traitName: 'openable', field: 'isOpen', value: false }],
+    ['open', { traitType: world_model_1.TraitType.OPENABLE, traitName: 'openable', field: 'isOpen', value: true }],
+    ['off', { traitType: world_model_1.TraitType.SWITCHABLE, traitName: 'switchable', field: 'isOn', value: false }],
+    ['on', { traitType: world_model_1.TraitType.SWITCHABLE, traitName: 'switchable', field: 'isOn', value: true }],
+]);
 /** Chord direction word → world-model DirectionType. */
 function toDirection(word, at) {
     const dir = world_model_1.Direction[word.toUpperCase()];
     if (!dir)
-        throw new errors_1.LoadError(`Unknown direction \`${word}\`.`, at?.span);
+        throw new errors_js_1.LoadError(`Unknown direction \`${word}\`.`, at?.span);
     return dir;
 }
 /** `with capacity N` on a supporter kind. */
@@ -1095,6 +1775,14 @@ function supporterCapacity(kind) {
 function configValue(comp, key) {
     return comp.config.find((c) => c.key === key)?.value;
 }
+/**
+ * Ratchet R3 (ADR-234 D6): the adjective's single-entity `with` value —
+ * keyless (`lockable with the iron key`). The parser stores it under the
+ * empty key with valueKind 'name'.
+ */
+function entityConfigValue(comp) {
+    return comp.config.find((c) => c.key === '' && c.valueKind === 'name')?.value;
+}
 /**
  * The Language Provider template for an IR phrase. Single-variant phrases
  * register their text (with `{br}` mapped to hard line breaks); verbatim
@@ -1105,7 +1793,7 @@ function templateFor(phrase) {
     if (phrase.verbatim)
         return '{verbatim:text}';
     if (phrase.strategy === null && phrase.variants.length === 1)
-        return (0, text_1.withLineBreaks)(phrase.variants[0].text);
+        return (0, text_js_1.withLineBreaks)(phrase.variants[0].text);
     return '{variants}';
 }
 /**
@@ -1122,7 +1810,7 @@ function toVocabularyVerb(verb) {
     const KNOWN = { 'put on': 'PUT_ON' };
     const actionId = KNOWN[`${base} ${preposition ?? ''}`.trim()];
     if (!actionId || slots !== 2) {
-        throw new errors_1.LoadError(`\`define verb ${verb.verbs.join(' or ')}\` maps to \`${words.join(' ')}\`, which the Phase A loader cannot register.`);
+        throw new errors_js_1.LoadError(`\`define verb ${verb.verbs.join(' or ')}\` maps to \`${words.join(' ')}\`, which the Phase A loader cannot register.`);
     }
     return {
         actionId,