@sharpee/engine 0.9.113 → 1.0.0

package/prose-pipeline/stages/sort.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Event sorting stage — orders events within a turn for correct prose
+ * sequence: lifecycle first, then per-transaction implicit-take →
+ * room-description → action.* → others, finally by chain depth.
+ *
+ * Public interface: `sortEventsForProse`, `getChainMetadata`. Used
+ * internally by the prose pipeline as the second per-turn stage,
+ * after filtering.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-094 Event Chaining (preserved; the sort responsibility
+ *   ports from `@sharpee/text-service`)
+ * @see ADR-174 §Engine-internal prose pipeline
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortEventsForProse = sortEventsForProse;
+exports.getChainMetadata = getChainMetadata;
+const LIFECYCLE_EVENTS = new Set([
+    'game.started',
+    'game.starting',
+    'game.loading',
+    'game.loaded',
+    'game.initialized',
+]);
+/**
+ * Sort events for correct prose order within transactions.
+ *
+ * Stable sort — preserves cross-transaction order while applying
+ * within-transaction rules.
+ */
+function sortEventsForProse(events) {
+    return [...events].sort((a, b) => {
+        const aData = a.data;
+        const bData = b.data;
+        const aTxnId = aData?._transactionId;
+        const bTxnId = bData?._transactionId;
+        // Game lifecycle events come first, before everything.
+        // Ensures the banner displays before the first room description.
+        // Note: matches specific lifecycle events only, NOT game.message.
+        const aIsGameLifecycle = LIFECYCLE_EVENTS.has(a.type);
+        const bIsGameLifecycle = LIFECYCLE_EVENTS.has(b.type);
+        if (aIsGameLifecycle && !bIsGameLifecycle)
+            return -1;
+        if (!aIsGameLifecycle && bIsGameLifecycle)
+            return 1;
+        // Different transactions or no transaction: maintain original order.
+        if (aTxnId !== bTxnId)
+            return 0;
+        // Implicit take events come first, before the main action result:
+        //   "first taking the X" before "X reads:..."
+        const aIsImplicitTake = a.type === 'if.event.implicit_take';
+        const bIsImplicitTake = b.type === 'if.event.implicit_take';
+        if (aIsImplicitTake && !bIsImplicitTake)
+            return -1;
+        if (!aIsImplicitTake && bIsImplicitTake)
+            return 1;
+        // Room description before action.success (for contents list):
+        //   "Room Name\nDescription" before "You see X here."
+        const aIsRoomDesc = a.type === 'if.event.room.description' ||
+            a.type === 'if.event.room_description';
+        const bIsRoomDesc = b.type === 'if.event.room.description' ||
+            b.type === 'if.event.room_description';
+        if (aIsRoomDesc && !bIsRoomDesc)
+            return -1;
+        if (!aIsRoomDesc && bIsRoomDesc)
+            return 1;
+        // Within transaction: action.* first (after room description).
+        const aIsAction = a.type.startsWith('action.');
+        const bIsAction = b.type.startsWith('action.');
+        if (aIsAction && !bIsAction)
+            return -1;
+        if (!aIsAction && bIsAction)
+            return 1;
+        // Then by chain depth (lower depth first).
+        const aDepth = aData?._chainDepth ?? 0;
+        const bDepth = bData?._chainDepth ?? 0;
+        return aDepth - bDepth;
+    });
+}
+/**
+ * Extract chain metadata from event data.
+ */
+function getChainMetadata(event) {
+    const data = event.data;
+    return {
+        _transactionId: data?._transactionId,
+        _chainDepth: data?._chainDepth,
+        _chainedFrom: data?._chainedFrom,
+        _chainSourceId: data?._chainSourceId,
+    };
+}
+//# sourceMappingURL=sort.js.map

package/prose-pipeline/stages/sort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/stages/sort.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AA4BH,gDAgDC;AAKD,4CAQC;AA3ED,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,cAAc;IACd,eAAe;IACf,cAAc;IACd,aAAa;IACb,kBAAkB;CACnB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,MAAwB;IACzD,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC/B,MAAM,KAAK,GAAG,CAAC,CAAC,IAAiC,CAAC;QAClD,MAAM,KAAK,GAAG,CAAC,CAAC,IAAiC,CAAC;QAElD,MAAM,MAAM,GAAG,KAAK,EAAE,cAAc,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,EAAE,cAAc,CAAC;QAErC,uDAAuD;QACvD,iEAAiE;QACjE,kEAAkE;QAClE,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtD,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,gBAAgB,IAAI,CAAC,gBAAgB;YAAE,OAAO,CAAC,CAAC,CAAC;QACrD,IAAI,CAAC,gBAAgB,IAAI,gBAAgB;YAAE,OAAO,CAAC,CAAC;QAEpD,qEAAqE;QACrE,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO,CAAC,CAAC;QAEhC,kEAAkE;QAClE,8CAA8C;QAC9C,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,KAAK,wBAAwB,CAAC;QAC5D,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,KAAK,wBAAwB,CAAC;QAC5D,IAAI,eAAe,IAAI,CAAC,eAAe;YAAE,OAAO,CAAC,CAAC,CAAC;QACnD,IAAI,CAAC,eAAe,IAAI,eAAe;YAAE,OAAO,CAAC,CAAC;QAElD,8DAA8D;QAC9D,sDAAsD;QACtD,MAAM,WAAW,GACf,CAAC,CAAC,IAAI,KAAK,2BAA2B;YACtC,CAAC,CAAC,IAAI,KAAK,2BAA2B,CAAC;QACzC,MAAM,WAAW,GACf,CAAC,CAAC,IAAI,KAAK,2BAA2B;YACtC,CAAC,CAAC,IAAI,KAAK,2BAA2B,CAAC;QACzC,IAAI,WAAW,IAAI,CAAC,WAAW;YAAE,OAAO,CAAC,CAAC,CAAC;QAC3C,IAAI,CAAC,WAAW,IAAI,WAAW;YAAE,OAAO,CAAC,CAAC;QAE1C,+DAA+D;QAC/D,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,SAAS,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,SAAS,IAAI,SAAS;YAAE,OAAO,CAAC,CAAC;QAEtC,2CAA2C;QAC3C,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QACvC,OAAO,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,KAAqB;IACpD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAiC,CAAC;IACrD,OAAO;QACL,cAAc,EAAE,IAAI,EAAE,cAAc;QACpC,WAAW,EAAE,IAAI,EAAE,WAAW;QAC9B,YAAY,EAAE,IAAI,EAAE,YAAY;QAChC,cAAc,EAAE,IAAI,EAAE,cAAc;KACrC,CAAC;AACJ,CAAC"}

package/prose-pipeline/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Prose pipeline service interface — engine-internal home for the
+ * `ITextService` contract.
+ *
+ * Per ADR-174, the responsibility for translating events into blocks
+ * moves into `@sharpee/engine`. The transitional `ITextService` name
+ * is preserved here so engine code already typed against it (the
+ * three `processTurn` call sites in `game-engine.ts` and the
+ * `getTextService` / `setTextService` accessors) can keep compiling
+ * during sub-phase 1.6's import swap. A follow-up cleanup may rename
+ * this to `IProsePipeline` once the legacy alias is no longer
+ * imported anywhere.
+ *
+ * Public interface: `ITextService`. Implemented by `ProsePipeline`
+ * (and by `MockProsePipeline` in tests).
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Internal interfaces
+ */
+import type { ISemanticEvent } from "../../core/index";
+import type { ITextBlock } from "../../text-blocks/index";
+/**
+ * Per-turn prose translator.
+ *
+ * Stateless transformer: takes the events emitted during a turn,
+ * returns the structured `ITextBlock[]` the channel layer hands off
+ * to renderers. Engine constructs an implementation once during
+ * `setStory()` and calls `processTurn` per turn (and per
+ * meta-command / restart).
+ */
+export interface ITextService {
+    /**
+     * Process turn events and produce TextBlocks.
+     *
+     * Called by Engine after each turn completes — and again on the
+     * meta-command path (restart, restore) where the same per-turn
+     * shape applies.
+     *
+     * @param events All events from this turn, including chained ones.
+     * @returns Blocks in render order.
+     */
+    processTurn(events: ISemanticEvent[]): ITextBlock[];
+}
+//# sourceMappingURL=types.d.ts.map

package/prose-pipeline/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,UAAU,EAAE,CAAC;CACrD"}

package/prose-pipeline/types.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Prose pipeline service interface — engine-internal home for the
+ * `ITextService` contract.
+ *
+ * Per ADR-174, the responsibility for translating events into blocks
+ * moves into `@sharpee/engine`. The transitional `ITextService` name
+ * is preserved here so engine code already typed against it (the
+ * three `processTurn` call sites in `game-engine.ts` and the
+ * `getTextService` / `setTextService` accessors) can keep compiling
+ * during sub-phase 1.6's import swap. A follow-up cleanup may rename
+ * this to `IProsePipeline` once the legacy alias is no longer
+ * imported anywhere.
+ *
+ * Public interface: `ITextService`. Implemented by `ProsePipeline`
+ * (and by `MockProsePipeline` in tests).
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Internal interfaces
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/prose-pipeline/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/sound/dispatcher.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Per-turn audibility dispatcher (ADR-172 Phase 6).
+ *
+ * Closes the loop between `emitSound` (authoring API; Step 6.1) and the
+ * `audibility` channel (Phase 5). For each `ISound` buffered during a
+ * turn, the dispatcher walks every entity carrying `ListenerTrait`,
+ * calls `propagate(sound, listenerId, world, timestamp)`, and emits one
+ * `sound.audibility.heard` `ISemanticEvent` per (sound × listener) pair
+ * that produced a non-null `IAudibilityEvent`.
+ *
+ * The dispatcher is pure: same buffer + same world state + same
+ * timestamp → same event array. Listeners are processed in entity-id
+ * sort order for deterministic event ordering across turns and runs.
+ *
+ * Owner context: `@sharpee/engine` — runtime / sound subsystem.
+ *
+ * Public interface:
+ *   - `class SoundDispatcher` — the dispatcher itself.
+ *   - `SoundDispatcher.dispatch(buffer, world, timestamp)` — produces
+ *     the `sound.audibility.heard` events for the turn.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ * @see ADR-163 — Channel-Service Platform (audibility channel)
+ */
+import { type ISemanticEvent } from "../../core/index";
+import type { IAudibilityEvent, ISound } from "../../if-domain/index";
+import { type WorldModel } from "../../world-model/index";
+/**
+ * Semantic-event type fired by the dispatcher when a listener perceives
+ * a propagated sound. Mirrors `SOUND_EVENT_TYPES.AUDIBILITY_HEARD` in
+ * `@sharpee/stdlib/channels/sound-events`. The constant is duplicated
+ * here as a string literal so the engine package does not depend on
+ * stdlib at compile time (engine → stdlib is the existing dependency
+ * direction; the inverse would be a cycle). The string value is the
+ * contract — both sides must agree.
+ */
+export declare const AUDIBILITY_HEARD_EVENT_TYPE = "sound.audibility.heard";
+/**
+ * Per-turn audibility dispatcher.
+ *
+ * The class shape (rather than a free function) leaves room for a
+ * future propagate-injection point in tests and for caching listener
+ * lookups across multi-action turns. For Phase 6 the dispatcher is a
+ * thin wrapper around `propagate()`; the class structure is the
+ * extension seam for L2's "NPC voice profile" layer.
+ */
+export declare class SoundDispatcher {
+    /**
+     * The propagation function the dispatcher uses. Defaulted to the
+     * production `propagate` from `./propagation`; tests may inject a
+     * fake to isolate dispatcher behavior from edge-graph + Dijkstra
+     * complexity.
+     */
+    private readonly propagate;
+    constructor(propagateFn?: (sound: ISound, listenerId: string, world: WorldModel, timestamp: number) => IAudibilityEvent | null);
+    /**
+     * Dispatch every buffered sound to every listener.
+     *
+     * @param buffer    The per-turn sound buffer; iterated in insertion
+     *                  order. May be empty (quiet turn).
+     * @param world     The world model the propagation function reads
+     *                  from. Must be the same instance the actions
+     *                  mutated during the turn.
+     * @param timestamp The turn-sequence integer the engine assigns to
+     *                  this turn. Used as the `IAudibilityEvent.timestamp`
+     *                  for ordering across multi-emission turns.
+     * @returns         Array of `sound.audibility.heard` events, one per
+     *                  (sound × listener) where `propagate()` returned
+     *                  non-null. Order: outer iteration over the buffer in
+     *                  emission order, inner iteration over listeners
+     *                  sorted by entity id ascending.
+     */
+    dispatch(buffer: readonly ISound[], world: WorldModel, timestamp: number): ISemanticEvent[];
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/sound/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/engine/src/sound/dispatcher.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAA4B,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGjF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAKG;gBAG3B,WAAW,GAAE,CACX,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,KACd,gBAAgB,GAAG,IAAuB;IAKjD;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CACN,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,GAChB,cAAc,EAAE;CAsBpB"}

package/sound/dispatcher.js

@@ -0,0 +1,122 @@
+"use strict";
+// packages/engine/src/sound/dispatcher.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SoundDispatcher = exports.AUDIBILITY_HEARD_EVENT_TYPE = void 0;
+/**
+ * Per-turn audibility dispatcher (ADR-172 Phase 6).
+ *
+ * Closes the loop between `emitSound` (authoring API; Step 6.1) and the
+ * `audibility` channel (Phase 5). For each `ISound` buffered during a
+ * turn, the dispatcher walks every entity carrying `ListenerTrait`,
+ * calls `propagate(sound, listenerId, world, timestamp)`, and emits one
+ * `sound.audibility.heard` `ISemanticEvent` per (sound × listener) pair
+ * that produced a non-null `IAudibilityEvent`.
+ *
+ * The dispatcher is pure: same buffer + same world state + same
+ * timestamp → same event array. Listeners are processed in entity-id
+ * sort order for deterministic event ordering across turns and runs.
+ *
+ * Owner context: `@sharpee/engine` — runtime / sound subsystem.
+ *
+ * Public interface:
+ *   - `class SoundDispatcher` — the dispatcher itself.
+ *   - `SoundDispatcher.dispatch(buffer, world, timestamp)` — produces
+ *     the `sound.audibility.heard` events for the turn.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ * @see ADR-163 — Channel-Service Platform (audibility channel)
+ */
+const core_1 = require("../../core/index.js");
+const world_model_1 = require("../../world-model/index.js");
+const propagation_1 = require("./propagation");
+/**
+ * Semantic-event type fired by the dispatcher when a listener perceives
+ * a propagated sound. Mirrors `SOUND_EVENT_TYPES.AUDIBILITY_HEARD` in
+ * `@sharpee/stdlib/channels/sound-events`. The constant is duplicated
+ * here as a string literal so the engine package does not depend on
+ * stdlib at compile time (engine → stdlib is the existing dependency
+ * direction; the inverse would be a cycle). The string value is the
+ * contract — both sides must agree.
+ */
+exports.AUDIBILITY_HEARD_EVENT_TYPE = 'sound.audibility.heard';
+/**
+ * Per-turn audibility dispatcher.
+ *
+ * The class shape (rather than a free function) leaves room for a
+ * future propagate-injection point in tests and for caching listener
+ * lookups across multi-action turns. For Phase 6 the dispatcher is a
+ * thin wrapper around `propagate()`; the class structure is the
+ * extension seam for L2's "NPC voice profile" layer.
+ */
+class SoundDispatcher {
+    /**
+     * The propagation function the dispatcher uses. Defaulted to the
+     * production `propagate` from `./propagation`; tests may inject a
+     * fake to isolate dispatcher behavior from edge-graph + Dijkstra
+     * complexity.
+     */
+    propagate;
+    constructor(propagateFn = propagation_1.propagate) {
+        this.propagate = propagateFn;
+    }
+    /**
+     * Dispatch every buffered sound to every listener.
+     *
+     * @param buffer    The per-turn sound buffer; iterated in insertion
+     *                  order. May be empty (quiet turn).
+     * @param world     The world model the propagation function reads
+     *                  from. Must be the same instance the actions
+     *                  mutated during the turn.
+     * @param timestamp The turn-sequence integer the engine assigns to
+     *                  this turn. Used as the `IAudibilityEvent.timestamp`
+     *                  for ordering across multi-emission turns.
+     * @returns         Array of `sound.audibility.heard` events, one per
+     *                  (sound × listener) where `propagate()` returned
+     *                  non-null. Order: outer iteration over the buffer in
+     *                  emission order, inner iteration over listeners
+     *                  sorted by entity id ascending.
+     */
+    dispatch(buffer, world, timestamp) {
+        if (buffer.length === 0)
+            return [];
+        const listeners = world
+            .findByTrait(world_model_1.TraitType.LISTENER)
+            .slice()
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        if (listeners.length === 0)
+            return [];
+        const events = [];
+        for (const sound of buffer) {
+            for (const listener of listeners) {
+                const audibility = this.propagate(sound, listener.id, world, timestamp);
+                if (!audibility)
+                    continue;
+                events.push(buildAudibilityEvent(audibility, listener.id));
+            }
+        }
+        return events;
+    }
+}
+exports.SoundDispatcher = SoundDispatcher;
+/**
+ * Build the `sound.audibility.heard` semantic event from a propagation
+ * result and the listener that perceived it.
+ *
+ * `entities` mapping:
+ *  - `actor`    → `sourceEntityId` (who emitted the sound)
+ *  - `location` → `sourceRoomId`   (where the sound came from)
+ *  - `target`   → listenerId       (who heard it)
+ *
+ * The `audibility` channel projection (ADR-163, ADR-172 Phase 5) reads
+ * the `IAudibilityEvent` from `event.data`; `entities` is provided for
+ * downstream filters and handlers that want a fast "who heard / from
+ * where" lookup without re-reading `data`.
+ */
+function buildAudibilityEvent(audibility, listenerId) {
+    return (0, core_1.createEvent)(exports.AUDIBILITY_HEARD_EVENT_TYPE, audibility, {
+        actor: audibility.sourceEntityId,
+        location: audibility.sourceRoomId,
+        target: listenerId,
+    });
+}
+//# sourceMappingURL=dispatcher.js.map

package/sound/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/sound/dispatcher.ts"],"names":[],"mappings":";AAAA,0CAA0C;;;AAE1C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,wCAAiE;AAEjE,sDAAiF;AACjF,+CAA8D;AAE9D;;;;;;;;GAQG;AACU,QAAA,2BAA2B,GAAG,wBAAwB,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAa,eAAe;IAC1B;;;;;OAKG;IACc,SAAS,CAKG;IAE7B,YACE,cAK+B,uBAAgB;QAE/C,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CACN,MAAyB,EACzB,KAAiB,EACjB,SAAiB;QAEjB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEnC,MAAM,SAAS,GAAG,KAAK;aACpB,WAAW,CAAC,uBAAS,CAAC,QAAQ,CAAC;aAC/B,KAAK,EAAE;aACP,IAAI,CAAC,CAAC,CAAW,EAAE,CAAW,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAEhF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEtC,MAAM,MAAM,GAAqB,EAAE,CAAC;QAEpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;gBACxE,IAAI,CAAC,UAAU;oBAAE,SAAS;gBAC1B,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AApED,0CAoEC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,oBAAoB,CAC3B,UAA4B,EAC5B,UAAkB;IAElB,OAAO,IAAA,kBAAW,EAChB,mCAA2B,EAC3B,UAAgD,EAChD;QACE,KAAK,EAAE,UAAU,CAAC,cAAc;QAChC,QAAQ,EAAE,UAAU,CAAC,YAAY;QACjC,MAAM,EAAE,UAAU;KACnB,CACF,CAAC;AACJ,CAAC"}

package/sound/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @sharpee/engine/sound — spatial sound propagation runtime (ADR-172).
+ *
+ * Owner context: engine layer. The propagation function lives here
+ * because it consumes world-model state, doesn't fit in a pure
+ * domain-types layer, and is invoked from the action pipeline (Phase
+ * 6) which is engine-adjacent.
+ *
+ * Public interface:
+ *  - `propagate(sound, listenerId, world, timestamp)` — produce an
+ *    `AudibilityEvent` (or null) for a single listener.
+ *  - `clarityToTier(clarity)` — exposed for testability and for
+ *    composition layers that need to query "what tier does this
+ *    clarity value map to?".
+ *  - `SoundDispatcher` — per-turn fan-out: for each buffered sound,
+ *    propagate to every `ListenerTrait` entity and emit one
+ *    `sound.audibility.heard` semantic event per non-silent result
+ *    (Phase 6 Step 6.2).
+ *  - `AUDIBILITY_HEARD_EVENT_TYPE` — the semantic-event type string
+ *    fired by the dispatcher.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ */
+export { propagate, clarityToTier } from './propagation';
+export { SoundDispatcher, AUDIBILITY_HEARD_EVENT_TYPE } from './dispatcher';
+//# sourceMappingURL=index.d.ts.map

package/sound/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/engine/src/sound/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC"}

package/sound/index.js

@@ -0,0 +1,34 @@
+"use strict";
+// packages/engine/src/sound/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDIBILITY_HEARD_EVENT_TYPE = exports.SoundDispatcher = exports.clarityToTier = exports.propagate = void 0;
+/**
+ * @sharpee/engine/sound — spatial sound propagation runtime (ADR-172).
+ *
+ * Owner context: engine layer. The propagation function lives here
+ * because it consumes world-model state, doesn't fit in a pure
+ * domain-types layer, and is invoked from the action pipeline (Phase
+ * 6) which is engine-adjacent.
+ *
+ * Public interface:
+ *  - `propagate(sound, listenerId, world, timestamp)` — produce an
+ *    `AudibilityEvent` (or null) for a single listener.
+ *  - `clarityToTier(clarity)` — exposed for testability and for
+ *    composition layers that need to query "what tier does this
+ *    clarity value map to?".
+ *  - `SoundDispatcher` — per-turn fan-out: for each buffered sound,
+ *    propagate to every `ListenerTrait` entity and emit one
+ *    `sound.audibility.heard` semantic event per non-silent result
+ *    (Phase 6 Step 6.2).
+ *  - `AUDIBILITY_HEARD_EVENT_TYPE` — the semantic-event type string
+ *    fired by the dispatcher.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ */
+var propagation_1 = require("./propagation");
+Object.defineProperty(exports, "propagate", { enumerable: true, get: function () { return propagation_1.propagate; } });
+Object.defineProperty(exports, "clarityToTier", { enumerable: true, get: function () { return propagation_1.clarityToTier; } });
+var dispatcher_1 = require("./dispatcher");
+Object.defineProperty(exports, "SoundDispatcher", { enumerable: true, get: function () { return dispatcher_1.SoundDispatcher; } });
+Object.defineProperty(exports, "AUDIBILITY_HEARD_EVENT_TYPE", { enumerable: true, get: function () { return dispatcher_1.AUDIBILITY_HEARD_EVENT_TYPE; } });
+//# sourceMappingURL=index.js.map

package/sound/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/sound/index.ts"],"names":[],"mappings":";AAAA,qCAAqC;;;AAErC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,6CAAyD;AAAhD,wGAAA,SAAS,OAAA;AAAE,4GAAA,aAAa,OAAA;AACjC,2CAA4E;AAAnE,6GAAA,eAAe,OAAA;AAAE,yHAAA,2BAA2B,OAAA"}

package/sound/propagation.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Spatial sound propagation function (ADR-172 Phase 3).
+ *
+ * Pure logic: given a `Sound` emission, a listener entity-id, and the
+ * world-model, returns the `AudibilityEvent` the listener perceives —
+ * or `null` if the sound is silent at the listener's location.
+ *
+ * The function is structured around three pieces:
+ *
+ *  1. **Edge-graph construction** (`getAcousticEdges`) — for any room,
+ *     enumerate the rooms it's acoustically connected to, with each
+ *     edge's cost. Today's edge sources are exits-with-doors and walls
+ *     (per ADR-173). Future acoustic conduits ride on the same shape
+ *     without changes here.
+ *
+ *  2. **Path search** (`findShortestAcousticPath`) — Dijkstra from
+ *     source room to listener's room. Path cost = sum of edge costs +
+ *     1 unit per intermediate room. Wall edges traversed are recorded
+ *     so the resulting `AudibilityEvent` can name a wall when the path
+ *     crosses exactly one.
+ *
+ *  3. **Clarity → tier mapping** (`clarityToTier`) — the ADR-172
+ *     audibility-tier table.
+ *
+ * The propagation function does *not* enumerate listeners — that is
+ * Phase 5/6's dispatcher. This file is `propagate(sound, listenerId,
+ * world, timestamp) → event | null`, intended to be called per
+ * listener.
+ *
+ * Owner context: `@sharpee/engine` — runtime / sound subsystem.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ * @see ADR-173 — Wall Adjacency Primitive (substrate)
+ */
+import type { EntityId } from "../../core/index";
+import { type AudibilityTier, type IAudibilityEvent, type ISound } from "../../if-domain/index";
+import { WorldModel } from "../../world-model/index";
+/**
+ * Propagate a sound emission to a single listener.
+ *
+ * Returns an `AudibilityEvent` for the listener if the sound reaches
+ * them at any tier above `silent`; returns `null` if the sound is
+ * silent at the listener's location (no reachable path, cost too high
+ * for the volume budget, or the listener has no resolvable room).
+ *
+ * Same-room emissions short-circuit to `full` audibility regardless of
+ * intervening boundaries (degenerate case from ADR-172 §Propagation
+ * function step 5).
+ *
+ * @param sound        The emission shape.
+ * @param listenerId   The entity id of the listener.
+ * @param world        The world-model carrying rooms, walls, doors,
+ *                     and obstructors.
+ * @param timestamp    Engine-provided turn-sequence integer for event
+ *                     ordering. Phase 6's dispatcher threads this from
+ *                     the turn manager.
+ */
+export declare function propagate(sound: ISound, listenerId: EntityId, world: WorldModel, timestamp: number): IAudibilityEvent | null;
+/**
+ * Map a clarity value (volume budget − accumulated path cost) to the
+ * ADR-172 audibility tier table.
+ *
+ * Exposed for testability and so that future composition layers can
+ * reuse the mapping (e.g., a conversation-choreography layer that
+ * wants to show a "what would the audibility be at this volume from
+ * here?" debug overlay).
+ */
+export declare function clarityToTier(clarity: number): AudibilityTier;
+//# sourceMappingURL=propagation.d.ts.map

package/sound/propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/engine/src/sound/propagation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAUL,UAAU,EACX,MAAM,sBAAsB,CAAC;AAM9B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,QAAQ,EACpB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,IAAI,CAuBzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAM7D"}