@sharpee/story-loader 3.0.0

package/hatch-context.d.ts

@@ -0,0 +1,57 @@
+/**
+ * hatch-context.ts — the narrow staging context handed to text-hatch
+ * producers, plus the bind-time `'chord.'` source lint (design.md §5.6,
+ * hatch-context proposal 2026-07-12).
+ *
+ * Enforcement is by construction: chord producers are invoked at phrase
+ * staging (runtime.ts `phraseEvent`), and the context they receive is built
+ * HERE — a fresh object whose `world` exposes only `RenderWorld`'s read
+ * methods. A hatch cannot misuse what it is never given; casting the facade
+ * finds nothing (the gateStatus precedent: a producer once cast its way to
+ * `getStateValue` and read a loader-private `chord.*` key that a later
+ * ratchet deleted, silently).
+ *
+ * Public interface: HATCH_CONTEXT_VERSION, stagingRenderContext,
+ * findChordLiteral.
+ * Owner context: @sharpee/story-loader.
+ */
+import type { RenderContext } from '@sharpee/if-domain';
+import type { WorldModel } from '@sharpee/world-model';
+/**
+ * Version of the surface hatches can see. Bumped only when the narrowed
+ * staging surface changes (a `RenderContext`/`RenderWorld` member becomes
+ * available to hatches). Re-exported by @sharpee/ide-protocol so the IDE
+ * can state exactly what a hatch may touch (the §5.6 IDE contract).
+ */
+export declare const HATCH_CONTEXT_VERSION = 1;
+/**
+ * Build the narrow, honest `RenderContext` a producer is invoked with at
+ * staging time. `world` is a three-method facade over the live world
+ * (`nounPhraseFor` is omitted — optional, stdlib-bound, and staging-time
+ * producers do not realize noun phrases). The remaining seams are inert by
+ * construction because they genuinely do not exist at staging: persistent
+ * text state is an assembler-time seam — a producer that needs it returns
+ * a `Choice` atom (ADR-196) realized later against the engine's real
+ * context. No member exposes mutation or state-key reads.
+ *
+ * @param world the live world model (read-only access only)
+ * @returns a genuine `RenderContext` (no cast) safe to hand author code
+ */
+export declare function stagingRenderContext(world: WorldModel): RenderContext;
+/**
+ * Bind-time lint (best-effort backstop; the facade is the wall): scan a
+ * bound hatch export's source text for a quoted `chord.` literal. For a
+ * function export the function's own source is scanned; for an object
+ * export (action/behavior hatches) each function-valued own property is.
+ *
+ * Documented imprecisions (proposal §3.2): minified bundles may evade the
+ * scan (the devkit source lint is the authoritative layer), and a QUOTED
+ * `chord.` inside a comment in the compiled output trips it — the remedy
+ * is rewording the comment.
+ *
+ * @param bound the module export about to be bound
+ * @returns the offending source snippet (trimmed to the match line), or
+ *   null when clean or unscannable
+ */
+export declare function findChordLiteral(bound: unknown): string | null;
+//# sourceMappingURL=hatch-context.d.ts.map

package/hatch-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hatch-context.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/story-loader/src/hatch-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CA2BrE;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkB9D"}

package/hatch-context.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HATCH_CONTEXT_VERSION = void 0;
+exports.stagingRenderContext = stagingRenderContext;
+exports.findChordLiteral = findChordLiteral;
+/**
+ * Version of the surface hatches can see. Bumped only when the narrowed
+ * staging surface changes (a `RenderContext`/`RenderWorld` member becomes
+ * available to hatches). Re-exported by @sharpee/ide-protocol so the IDE
+ * can state exactly what a hatch may touch (the §5.6 IDE contract).
+ */
+exports.HATCH_CONTEXT_VERSION = 1;
+/**
+ * Build the narrow, honest `RenderContext` a producer is invoked with at
+ * staging time. `world` is a three-method facade over the live world
+ * (`nounPhraseFor` is omitted — optional, stdlib-bound, and staging-time
+ * producers do not realize noun phrases). The remaining seams are inert by
+ * construction because they genuinely do not exist at staging: persistent
+ * text state is an assembler-time seam — a producer that needs it returns
+ * a `Choice` atom (ADR-196) realized later against the engine's real
+ * context. No member exposes mutation or state-key reads.
+ *
+ * @param world the live world model (read-only access only)
+ * @returns a genuine `RenderContext` (no cast) safe to hand author code
+ */
+function stagingRenderContext(world) {
+    const facade = {
+        getEntity: (entityId) => world.getEntity(entityId),
+        getEntityContents: (entityId) => world.getContents(entityId),
+        getContainingRoom: (entityId) => world.getContainingRoom(entityId),
+    };
+    return {
+        world: facade,
+        params: {},
+        settings: {},
+        narrative: { person: 'second' },
+        reference: {
+            lastMentioned: () => undefined,
+            note: () => {
+                // Staging has no realization order — nothing to note.
+            },
+        },
+        textState: {
+            get: () => undefined,
+            set: () => {
+                // Inert at staging: persistent choice state belongs to the assembler pass.
+            },
+        },
+        contribute: () => {
+            // Slot contributions are a per-turn render seam; staging has no slot store.
+        },
+    };
+}
+/** Matches a quoted string literal opening with `chord.` — the loader-private namespace. */
+const CHORD_LITERAL = /['"`]chord\./;
+/**
+ * Bind-time lint (best-effort backstop; the facade is the wall): scan a
+ * bound hatch export's source text for a quoted `chord.` literal. For a
+ * function export the function's own source is scanned; for an object
+ * export (action/behavior hatches) each function-valued own property is.
+ *
+ * Documented imprecisions (proposal §3.2): minified bundles may evade the
+ * scan (the devkit source lint is the authoritative layer), and a QUOTED
+ * `chord.` inside a comment in the compiled output trips it — the remedy
+ * is rewording the comment.
+ *
+ * @param bound the module export about to be bound
+ * @returns the offending source snippet (trimmed to the match line), or
+ *   null when clean or unscannable
+ */
+function findChordLiteral(bound) {
+    const sources = [];
+    if (typeof bound === 'function') {
+        sources.push(Function.prototype.toString.call(bound));
+    }
+    else if (bound !== null && typeof bound === 'object') {
+        for (const value of Object.values(bound)) {
+            if (typeof value === 'function')
+                sources.push(Function.prototype.toString.call(value));
+        }
+    }
+    for (const source of sources) {
+        const match = CHORD_LITERAL.exec(source);
+        if (match) {
+            const start = source.lastIndexOf('\n', match.index) + 1;
+            const end = source.indexOf('\n', match.index);
+            return source.slice(start, end === -1 ? undefined : end).trim();
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=hatch-context.js.map

package/hatch-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hatch-context.js","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/story-loader/src/hatch-context.ts"],"names":[],"mappings":";;;AAyCA,oDA2BC;AAoBD,4CAkBC;AAtFD;;;;;GAKG;AACU,QAAA,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAAC,KAAiB;IACpD,MAAM,MAAM,GAAgB;QAC1B,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC;QAClD,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC;QAC5D,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,iBAAiB,CAAC,QAAQ,CAAC;KACnE,CAAC;IACF,OAAO;QACL,KAAK,EAAE,MAAM;QACb,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC/B,SAAS,EAAE;YACT,aAAa,EAAE,GAAG,EAAE,CAAC,SAAS;YAC9B,IAAI,EAAE,GAAG,EAAE;gBACT,sDAAsD;YACxD,CAAC;SACF;QACD,SAAS,EAAE;YACT,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;YACpB,GAAG,EAAE,GAAG,EAAE;gBACR,2EAA2E;YAC7E,CAAC;SACF;QACD,UAAU,EAAE,GAAG,EAAE;YACf,4EAA4E;QAC9E,CAAC;KACF,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,MAAM,aAAa,GAAG,cAAc,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,SAAgB,gBAAgB,CAAC,KAAc;IAC7C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,CAAC;SAAM,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;YAC9C,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QAClE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @sharpee/story-loader — the Story IR interpreter (ADR-210).
+ *
+ * Purpose: construct a generic `Story` implementation from compiled Story IR —
+ * world building, phrase registration, custom vocabulary, endings, and (Phase 5)
+ * event-rule binding, the expression evaluator, occurrence materialization,
+ * and seeded RNG.
+ *
+ * Public interface: createStory(), ChordStory, StoryLoaderOptions, LoadError,
+ * CHORD_STATE_PREFIX.
+ *
+ * Owner context: Chord runtime consumer. Language-neutral by design — it
+ * consumes IR and never sees Chord syntax. Depends on the platform
+ * (world-model, helpers, engine, if-domain, core); nothing platform depends
+ * on it (ADR-210 Direction rule).
+ */
+export { LoadError } from './errors';
+export { EVENT_TRIGGERS, EVENT_PAYLOAD_FIELDS } from './event-contract';
+export { HATCH_CONTEXT_VERSION, stagingRenderContext, findChordLiteral } from './hatch-context';
+export { ChordDataTrait, ChordDetailTrait, ChordStory, createStory, StoryLoaderOptions } from './loader';
+export { Evaluator, EvalContext, EntityIdResolver } from './evaluator';
+export { ChordRuntime, ChordBehaviorTrait } from './runtime';
+export { CHORD_OCCURRENCE_PREFIX, CHORD_RNG_KEY, CHORD_STATE_PREFIX, CHORD_TRAIT_PREFIX, } from './state-keys';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/story-loader/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAChG,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACzG,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,cAAc,CAAC"}

package/index.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * @sharpee/story-loader — the Story IR interpreter (ADR-210).
+ *
+ * Purpose: construct a generic `Story` implementation from compiled Story IR —
+ * world building, phrase registration, custom vocabulary, endings, and (Phase 5)
+ * event-rule binding, the expression evaluator, occurrence materialization,
+ * and seeded RNG.
+ *
+ * Public interface: createStory(), ChordStory, StoryLoaderOptions, LoadError,
+ * CHORD_STATE_PREFIX.
+ *
+ * Owner context: Chord runtime consumer. Language-neutral by design — it
+ * consumes IR and never sees Chord syntax. Depends on the platform
+ * (world-model, helpers, engine, if-domain, core); nothing platform depends
+ * on it (ADR-210 Direction rule).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHORD_TRAIT_PREFIX = exports.CHORD_STATE_PREFIX = exports.CHORD_RNG_KEY = exports.CHORD_OCCURRENCE_PREFIX = exports.ChordBehaviorTrait = exports.ChordRuntime = exports.Evaluator = exports.createStory = exports.ChordStory = exports.ChordDetailTrait = exports.ChordDataTrait = exports.findChordLiteral = exports.stagingRenderContext = exports.HATCH_CONTEXT_VERSION = exports.EVENT_PAYLOAD_FIELDS = exports.EVENT_TRIGGERS = exports.LoadError = void 0;
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "LoadError", { enumerable: true, get: function () { return errors_1.LoadError; } });
+var event_contract_1 = require("./event-contract");
+Object.defineProperty(exports, "EVENT_TRIGGERS", { enumerable: true, get: function () { return event_contract_1.EVENT_TRIGGERS; } });
+Object.defineProperty(exports, "EVENT_PAYLOAD_FIELDS", { enumerable: true, get: function () { return event_contract_1.EVENT_PAYLOAD_FIELDS; } });
+var hatch_context_1 = require("./hatch-context");
+Object.defineProperty(exports, "HATCH_CONTEXT_VERSION", { enumerable: true, get: function () { return hatch_context_1.HATCH_CONTEXT_VERSION; } });
+Object.defineProperty(exports, "stagingRenderContext", { enumerable: true, get: function () { return hatch_context_1.stagingRenderContext; } });
+Object.defineProperty(exports, "findChordLiteral", { enumerable: true, get: function () { return hatch_context_1.findChordLiteral; } });
+var loader_1 = require("./loader");
+Object.defineProperty(exports, "ChordDataTrait", { enumerable: true, get: function () { return loader_1.ChordDataTrait; } });
+Object.defineProperty(exports, "ChordDetailTrait", { enumerable: true, get: function () { return loader_1.ChordDetailTrait; } });
+Object.defineProperty(exports, "ChordStory", { enumerable: true, get: function () { return loader_1.ChordStory; } });
+Object.defineProperty(exports, "createStory", { enumerable: true, get: function () { return loader_1.createStory; } });
+var evaluator_1 = require("./evaluator");
+Object.defineProperty(exports, "Evaluator", { enumerable: true, get: function () { return evaluator_1.Evaluator; } });
+var runtime_1 = require("./runtime");
+Object.defineProperty(exports, "ChordRuntime", { enumerable: true, get: function () { return runtime_1.ChordRuntime; } });
+Object.defineProperty(exports, "ChordBehaviorTrait", { enumerable: true, get: function () { return runtime_1.ChordBehaviorTrait; } });
+var state_keys_1 = require("./state-keys");
+Object.defineProperty(exports, "CHORD_OCCURRENCE_PREFIX", { enumerable: true, get: function () { return state_keys_1.CHORD_OCCURRENCE_PREFIX; } });
+Object.defineProperty(exports, "CHORD_RNG_KEY", { enumerable: true, get: function () { return state_keys_1.CHORD_RNG_KEY; } });
+Object.defineProperty(exports, "CHORD_STATE_PREFIX", { enumerable: true, get: function () { return state_keys_1.CHORD_STATE_PREFIX; } });
+Object.defineProperty(exports, "CHORD_TRAIT_PREFIX", { enumerable: true, get: function () { return state_keys_1.CHORD_TRAIT_PREFIX; } });
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/story-loader/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,mCAAqC;AAA5B,mGAAA,SAAS,OAAA;AAClB,mDAAwE;AAA/D,gHAAA,cAAc,OAAA;AAAE,sHAAA,oBAAoB,OAAA;AAC7C,iDAAgG;AAAvF,sHAAA,qBAAqB,OAAA;AAAE,qHAAA,oBAAoB,OAAA;AAAE,iHAAA,gBAAgB,OAAA;AACtE,mCAAyG;AAAhG,wGAAA,cAAc,OAAA;AAAE,0GAAA,gBAAgB,OAAA;AAAE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAClE,yCAAuE;AAA9D,sGAAA,SAAS,OAAA;AAClB,qCAA6D;AAApD,uGAAA,YAAY,OAAA;AAAE,6GAAA,kBAAkB,OAAA;AACzC,2CAKsB;AAJpB,qHAAA,uBAAuB,OAAA;AACvB,2GAAA,aAAa,OAAA;AACb,gHAAA,kBAAkB,OAAA;AAClB,gHAAA,kBAAkB,OAAA"}

package/loader.d.ts

@@ -0,0 +1,241 @@
+/**
+ * loader.ts — the generic `Story` constructed from Chord Story IR (ADR-210).
+ *
+ * Purpose: interpret a compiled IR into the platform's standard story
+ * lifecycle: world building (`initializeWorld`), player creation
+ * (`createPlayer`), phrase registration (`extendLanguage`), custom verbs
+ * (`getCustomVocabulary`), and completion (`isComplete` via the if-domain
+ * ending flag). Phase A slice: static world only — when-rules, on-clause
+ * interceptors, derived properties, and the evaluator bind in Phase 5.
+ *
+ * Public interface: createStory(), ChordStory, StoryLoaderOptions.
+ * Owner context: @sharpee/story-loader (language-neutral IR consumer; the
+ * runtime platform never depends on this package — ADR-210 Direction rule).
+ *
+ * Invariants:
+ * - Atomic load: any defect throws LoadError; no partial registration.
+ * - No filesystem access: hatch modules arrive pre-loaded via options
+ *   (the CLI/devkit owns module resolution and compilation).
+ * - Every phrase key in the IR is registered with the Language Provider
+ *   (given 3); blocked-exit/description text is ALSO written where the
+ *   platform reads it today (dual-mode, ADR-107).
+ */
+import { StoryIR } from '@sharpee/chord';
+import type { Phrase } from '@sharpee/if-domain';
+import type { ISemanticEvent } from '@sharpee/core';
+import type { LanguageProvider, PhraseProducer, StoryEndingKind } from '@sharpee/if-domain';
+import type { CustomVocabulary, Story, StoryConfig } from '@sharpee/engine';
+import { CapabilityBehavior, IFEntity, ITrait, WorldModel } from '@sharpee/world-model';
+import { ChordRuntime } from './runtime';
+/**
+ * Marker trait for entities carrying loader-compiled `detail` providers
+ * (Z3b): the one state-clause contributor registered per load looks up the
+ * owner's gated detail specs through it. Data-free — the specs live on the
+ * loader (nothing serialized; re-registered every load).
+ */
+export declare class ChordDetailTrait implements ITrait {
+    static readonly type = "chord.detail";
+    readonly type = "chord.detail";
+}
+/**
+ * A `define trait` runtime instance: type `chord.trait.<name>`, data fields
+ * as own enumerable properties (world serialization covers them — AC-6).
+ */
+export declare class ChordDataTrait implements ITrait {
+    readonly type: string;
+    [field: string]: unknown;
+    constructor(type: string, values: Record<string, unknown>);
+}
+export interface StoryLoaderOptions {
+    /**
+     * Pre-loaded hatch modules keyed by the `.story` module path
+     * (`"./extras.ts"` → its named exports). The host that owns module
+     * resolution (CLI/devkit) supplies these; the loader never touches the
+     * filesystem, so it stays browser-safe and the pure-IR profile can
+     * simply pass none.
+     */
+    hatchModules?: Record<string, Record<string, unknown>>;
+    /**
+     * Seed for the story's random stream (`randomly`, `one chance in <n>`).
+     * A fixed seed makes repeated runs byte-identical (AC-5); omitted, the
+     * stream is time-seeded.
+     */
+    seed?: number;
+    /**
+     * Load profile (design.md §5.6, AC-4): 'devkit' (default) binds hatches;
+     * 'pure-ir' REFUSES any hatch-bearing story at construction — before any
+     * binding, so no author-supplied code is touched. Hatch-free stories load
+     * identically under both.
+     */
+    profile?: 'devkit' | 'pure-ir';
+}
+/**
+ * Build a `Story` from compiled IR.
+ * @param ir a gate-clean Story IR (`compile().ok` was true)
+ * @param options hatch modules and host wiring
+ * @throws LoadError on format mismatch or unbindable hatch (atomic load)
+ */
+export declare function createStory(ir: StoryIR, options?: StoryLoaderOptions): ChordStory;
+/** The generic Story implementation interpreted from IR. */
+export declare class ChordStory implements Story {
+    readonly ir: StoryIR;
+    readonly config: StoryConfig;
+    /** Bound `define text` producers by hatch name. */
+    readonly producers: Map<string, PhraseProducer>;
+    /** Bound `define action X from` hatches: four-phase Action objects by name. */
+    readonly boundActions: Map<string, unknown>;
+    /** Bound `define behavior X from` hatches: CapabilityBehaviors by name. */
+    readonly boundBehaviors: Map<string, CapabilityBehavior>;
+    /** The turn-by-turn runtime (rules, on-clauses, derived properties). */
+    readonly runtime: ChordRuntime;
+    /** The condition evaluator — shared with the runtime; Z2 gate thunks close over it. */
+    private readonly evaluator;
+    /** IR entity ID → world entity ID (populated by initializeWorld/createPlayer). */
+    private readonly worldIds;
+    /** World entity ID → IR entity ID (state lookups in the evaluator). */
+    private readonly irIds;
+    private world;
+    /** True once initializeWorld has built the world content. */
+    private worldBuilt;
+    /** True once the player has been placed/equipped (exactly-once guard). */
+    private playerFinalized;
+    constructor(ir: StoryIR, options: StoryLoaderOptions);
+    /** The world entity ID for an IR entity ID (after initializeWorld). */
+    entityId(irId: string): string | undefined;
+    /** The IR entity ID for a world entity ID. */
+    irIdOf(worldId: string): string | undefined;
+    /** The player's world id, once createPlayer has run. */
+    playerWorldId(): string | undefined;
+    private playerId;
+    private bindHatches;
+    initializeWorld(world: WorldModel): void;
+    createPlayer(world: WorldModel): IFEntity;
+    /**
+     * Place and equip the player, then run the initial derived-property
+     * evaluation. Runs exactly once, from whichever lifecycle hook fires
+     * second — both the engine order (createPlayer → initializeWorld) and
+     * the direct order (initializeWorld → createPlayer) are supported.
+     */
+    private finalizePlayer;
+    extendLanguage(language: LanguageProvider): void;
+    getCustomVocabulary(): CustomVocabulary;
+    /**
+     * Custom actions for engine registration: `define action` dispatch
+     * actions (Phase B, §5.4) plus `define action X from` hatch Actions
+     * (grammar for hatch actions is the module's own concern).
+     */
+    getCustomActions(): unknown[];
+    /**
+     * Register scheduler constructs (`once`/`every`/`define sequence`/
+     * every-turn trait clauses) as plugin-scheduler daemons. All progression
+     * state is world state — no runner-state plumbing (design.md §6).
+     */
+    onEngineReady(engine: {
+        getPluginRegistry(): {
+            register(plugin: unknown): void;
+        };
+        registerSlotEntry?(entry: ChordSlotEntry): void;
+    }): void;
+    /**
+     * Z3 `present` channel → ADR-212 slot entries. One `registerSlotEntry`
+     * call per authoring entity: `slotKey: 'here'`, owner = the entity,
+     * content = variants as a `Choice` per the Z5 table (single plain variant
+     * → `Literal`), order = declaration order, `counterKey: 'present'` (the
+     * §4 owner + channel-key convention — the Choice's own keys match it).
+     * An ungated block relies on the platform's `owner-present` default; a
+     * `while`-gated block uses the predicate seam, ANDed with the same
+     * presence check so the gate narrows the channel rather than replacing
+     * its semantics.
+     *
+     * @param engine the engine surface (structural — absent method is a no-op)
+     */
+    private registerPresentEntries;
+    /**
+     * Register `define action` grammar patterns as story grammar (ADR-087).
+     * The param is the Story contract's stdlib Parser; typed structurally at
+     * the use site to keep story-loader's dependency surface unchanged.
+     */
+    extendParser(parser: Parameters<NonNullable<Story['extendParser']>>[0]): void;
+    isComplete(): boolean;
+    /**
+     * End the story: set the if-domain ending flag and build the blessed
+     * ending event (Prerequisite 3). The caller (rule evaluator) emits it.
+     */
+    triggerEnding(world: WorldModel, ending: StoryEndingKind, messageId?: string): ISemanticEvent;
+    private buildEntity;
+    private applyTraitAdjectives;
+    /**
+     * Initial values for a `define trait` instance: declared `starts`
+     * defaults overlaid by the composition's `with` config. Entity-name
+     * values (`with food the handful of feed`) resolve to IR entity ids.
+     */
+    private traitFieldValues;
+    private applyContainerConfig;
+    private requireWorldId;
+    /** Resolved default-locale text for a phrase key (single-variant read). */
+    /**
+     * Z2 (ADR-211): compile `{key}` strategy-phrase markers in this room's
+     * description prose onto ADR-209 storage. ATOMIC per room: every
+     * rewrite/entry/gate is computed first and applied only when the whole
+     * room compiled clean — a LoadError leaves the room untouched, never
+     * partial. Markers rewrite to `{snippet:key}`; variants populate
+     * `RoomTrait.snippets[key]` (`nothing` → `''`, strategy → selector via the
+     * Z5 table; a single-variant plain phrase compiles to a plain string
+     * entry); the phrase's `while` gate compiles — a presence condition on the
+     * marker's own room (`is here` / `is in <this room>`, non-negated) becomes
+     * `mentions`, anything else registers on the ADR-211 gate seam keyed
+     * `(roomId, marker)` (stdlib `registerSnippetGate` — in-memory, nothing
+     * serialized, re-registered every story load). Both description texts
+     * share one entry per marker (Z1/ADR-211 Q6: shared entries + counters).
+     *
+     * @param world the world being built (gate thunks close over it)
+     * @param irEntity the room's IR entity (presence-gate room identity)
+     * @param entity the built room entity
+     */
+    private compileRoomSnippets;
+    /**
+     * Z3 (ADR-213 §2): register the one `disappeared` observer, when any
+     * entity authors the channel. On a successful removal: skip the player
+     * (out of the channel's scope), require an authored block, require the
+     * removal to be witnessed (the player's containing room equals the
+     * entity's last containing room), then ENQUEUE the phrase through the
+     * existing phrase-event path — never rendered inline from the observer.
+     * Unwitnessed removals enqueue nothing and consume nothing (D11).
+     * Orphaning never reaches here (the seam fires only in `removeEntity`).
+     *
+     * @param world the world being built (the observer closes over it)
+     */
+    private registerRemovalObserver;
+    /**
+     * Z3b: compile each entity's gated `detail` blocks. The two shipped trait
+     * shapes bind their fields directly — `while it is on` →
+     * `SwitchableTrait.detailWhenOn`, `while it is lit` →
+     * `LightSourceTrait.detailWhenLit` (both read by world-model's
+     * state-clauses registry). Any other condition joins the loader-owned
+     * provider: one marker trait per owner, ONE contributor registered per
+     * load (last-wins on the registry — the ADR-211/212 lifecycle), which
+     * evaluates the gate live at examine time.
+     *
+     * @param world the world being built (the provider closes over it)
+     */
+    private compileDetailChannels;
+    private phraseText;
+}
+/**
+ * Structural slice of `GameEngine.registerSlotEntry`'s entry (ADR-212 §1) —
+ * typed at the use site to keep story-loader's dependency surface unchanged
+ * (the `extendParser` precedent).
+ */
+interface ChordSlotEntry {
+    slotKey: string;
+    owner: string;
+    content: Phrase;
+    order?: number;
+    gate?: {
+        kind: 'predicate';
+        holds: (world: WorldModel) => boolean;
+    };
+    counterKey?: string;
+}
+export {};
+//# sourceMappingURL=loader.d.ts.map

package/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/story-loader/src/loader.ts"],"names":[],"mappings":"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"}