@sharpee/if-domain 0.9.111 → 1.0.0

package/channels/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @sharpee/if-domain/channels — channel-I/O type contracts.
+ *
+ * Owner context: domain layer. Single canonical home for the channel
+ * type contracts shared across the channel-I/O subsystem (ADR-163 §14
+ * + CLAUDE.md rule 7b).
+ *
+ * Public interface:
+ *
+ * - `IOChannel<T>`, `IChannelRegistry`, `ChannelProduceContext` — the
+ *   closure-per-channel definition contract (ADR-163 §6, §7).
+ * - `ChannelContentType`, `ChannelMode`, `ChannelEmitPolicy` — channel
+ *   configuration enums (§3, §4, §5).
+ * - `ClientCapabilities`, `CapabilityFlag` — capability declaration and
+ *   the gating discriminator (§2, §6).
+ * - `ChannelDefinition`, `HelloPacket`, `CmgtPacket`, `TurnPacket`,
+ *   `CommandPacket`, `WirePacket` — wire-protocol packets (§1, §11).
+ *
+ * @see ADR-163 — Channel-Service Platform
+ */
+export type { ChannelContentType, ChannelMode, ChannelEmitPolicy, ClientCapabilities, CapabilityFlag, ChannelProduceContext, IOChannel, IChannelRegistry, MainEntry, } from './types';
+export type { ChannelDefinition, HelloPacket, CmgtPacket, TurnPacket, CommandPacket, WirePacket, } from './wire';
+//# sourceMappingURL=index.d.ts.map

package/channels/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/if-domain/src/channels/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,SAAS,EACT,gBAAgB,EAChB,SAAS,GACV,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,UAAU,EACV,aAAa,EACb,UAAU,GACX,MAAM,QAAQ,CAAC"}

package/channels/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @sharpee/if-domain/channels — channel-I/O type contracts.
+ *
+ * Owner context: domain layer. Single canonical home for the channel
+ * type contracts shared across the channel-I/O subsystem (ADR-163 §14
+ * + CLAUDE.md rule 7b).
+ *
+ * Public interface:
+ *
+ * - `IOChannel<T>`, `IChannelRegistry`, `ChannelProduceContext` — the
+ *   closure-per-channel definition contract (ADR-163 §6, §7).
+ * - `ChannelContentType`, `ChannelMode`, `ChannelEmitPolicy` — channel
+ *   configuration enums (§3, §4, §5).
+ * - `ClientCapabilities`, `CapabilityFlag` — capability declaration and
+ *   the gating discriminator (§2, §6).
+ * - `ChannelDefinition`, `HelloPacket`, `CmgtPacket`, `TurnPacket`,
+ *   `CommandPacket`, `WirePacket` — wire-protocol packets (§1, §11).
+ *
+ * @see ADR-163 — Channel-Service Platform
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/channels/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/if-domain/src/channels/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/channels/types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * @sharpee/if-domain — channel type contracts (ADR-163, closure-per-channel
+ * model, 2026-05-02 rewrite + 2026-05-03 refinement).
+ *
+ * Owner context: domain layer. These types describe the channel-I/O
+ * contract used by every package that participates in the channel system:
+ *
+ * - `@sharpee/channel-service` runs the closures (`ChannelService.build`).
+ * - `@sharpee/stdlib` defines the standard `IOChannel` instances.
+ * - `@sharpee/engine` composes the registry with the service and emits
+ *   manifest / packet events.
+ * - Consumers (`@sharpee/platform-browser`, multi-user web-client, CLI
+ *   bundle) consume the wire packets via ADR-165 renderers.
+ *
+ * Public interface: the `IOChannel<T>` contract, the `IChannelRegistry`
+ * registry shape, the `ChannelProduceContext` passed to closures, and the
+ * three small enums (`ChannelContentType`, `ChannelMode`,
+ * `ChannelEmitPolicy`) plus `ClientCapabilities` and `CapabilityFlag`.
+ *
+ * No implementation lives here. Per ADR-163 §14 and CLAUDE.md rule 7b:
+ * if-domain is the single home for channel type contracts so co-located
+ * client and server code share them by direct import, not duplication.
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §7, §14
+ */
+import type { ISemanticEvent } from "../../core/index";
+import type { ITextBlock, TextContent } from "../../text-blocks/index";
+/**
+ * Channel content types (ADR-163 §3).
+ *
+ * - `text` — plain string. Renderer writes verbatim or styles.
+ * - `number` — integer or float. Producer emits the number; client formats.
+ * - `json` — structured object. Escape hatch for author-defined surfaces
+ *   and for the platform's `main` channel which carries `MainEntry[]`.
+ */
+export type ChannelContentType = 'text' | 'number' | 'json';
+/**
+ * A single entry in the `main` channel's append-mode value array.
+ *
+ * Each entry corresponds to one `<p>`-equivalent surface in a text
+ * renderer. The wire value of the `main` channel is `MainEntry[]` (the
+ * new entries produced this turn).
+ *
+ * Per the prose-pipeline pre-line removal (session 2026-05-12), every
+ * intra-block `\n` was lifted to a block boundary. Where the former
+ * `\n` was inside a paragraph (book text under its prefix, banner
+ * lines under a title), the second-and-later block carries
+ * `tight: true` and the renderer collapses the inter-paragraph margin
+ * so the lines stack flush.
+ *
+ * Invariant: a `tight` entry must not appear first in a packet — the
+ * renderer relies on a non-tight predecessor in the same packet or in
+ * an already-rendered prior packet.
+ */
+export interface MainEntry {
+    /** Content of this entry — strings and decorations, no `\n` in any string. */
+    readonly content: ReadonlyArray<TextContent>;
+    /** Visual continuation hint. See type-level doc above. */
+    readonly tight?: boolean;
+    /**
+     * Optional semantic CSS class the renderer applies to the rendered
+     * element in addition to `main-entry`. Mirrors `ITextBlock.className`
+     * — used by the prose pipeline to flow per-piece visual identity
+     * through the channel wire to the browser renderer.
+     */
+    readonly className?: string;
+}
+/**
+ * Channel update modes (ADR-163 §4).
+ *
+ * - `replace` — newest value supersedes prior values. Persistent: a
+ *   mid-session join replays the latest value.
+ * - `append` — value added to a chronological list (transcript-shaped).
+ *   Persistent: a mid-session join replays the full list (subject to
+ *   `clear` truncation per §10).
+ * - `event` — transient signal; client renders once and discards. Not
+ *   persisted; mid-session joins do not see prior `event` emissions.
+ */
+export type ChannelMode = 'replace' | 'append' | 'event';
+/**
+ * Per-channel emit policy (ADR-163 §5).
+ *
+ * - `always` — channel populated in every turn packet. `replace` emits
+ *   current value (changed or not); `append` emits any new entries
+ *   (possibly empty array); `event` is the natural exception (only
+ *   emits on fire).
+ * - `sparse` — channel appears only when its value changed (`replace`)
+ *   or new entries were produced (`append`/`event`). Default for
+ *   author-defined channels.
+ */
+export type ChannelEmitPolicy = 'always' | 'sparse';
+/**
+ * Client capabilities declared at session start (ADR-163 §2).
+ *
+ * Fields preserve ADR-101's `ClientCapabilities` interface verbatim so
+ * existing consumers can adopt without rewriting their declarations.
+ *
+ * The `ChannelService` filters capability-gated channels at manifest
+ * production using these flags (`IOChannel.gatedBy`).
+ */
+export interface ClientCapabilities {
+    /** Always true — every Sharpee surface renders text. */
+    readonly text: true;
+    readonly images: boolean;
+    readonly animations: boolean;
+    readonly video: boolean;
+    readonly sound: boolean;
+    readonly music: boolean;
+    readonly speech: boolean;
+    readonly splitPane: boolean;
+    readonly statusBar: boolean;
+    readonly sidebar: boolean;
+    readonly clickableText: boolean;
+    readonly clickableImage: boolean;
+    readonly dragDrop: boolean;
+    readonly transitions: boolean;
+    readonly layers: boolean;
+    readonly customFonts: boolean;
+    readonly screenWidth?: number;
+    readonly screenHeight?: number;
+}
+/**
+ * Subset of `ClientCapabilities` keys that name boolean flags. The
+ * `text` field is always `true`; the dimension fields are numbers.
+ *
+ * `IOChannel.gatedBy` accepts only `CapabilityFlag` values: a channel
+ * cannot gate on `text` (always true) or on screen dimensions (numeric).
+ */
+export type CapabilityFlag = Exclude<{
+    [K in keyof ClientCapabilities]: ClientCapabilities[K] extends boolean ? K : never;
+}[keyof ClientCapabilities], 'text'>;
+/**
+ * Context passed to an `IOChannel.produce` closure (ADR-163 §6).
+ *
+ * The closure receives:
+ *
+ * - `world` — current world state (read-only from the producer's POV).
+ *   Typed as `unknown` here because if-domain cannot import
+ *   `IWorldModel` from `@sharpee/world-model` without creating a cycle
+ *   (world-model depends on if-domain). Consumers in stdlib and engine
+ *   narrow this at the call site:
+ *   ```ts
+ *   produce: (ctx) => {
+ *     const world = ctx.world as IWorldModel;
+ *     return world.getCapability('scoring');
+ *   }
+ *   ```
+ *   The narrowing happens once per channel definition. The trade-off
+ *   keeps if-domain dependency-clean; the alternative (replicating
+ *   `IWorldModel` in if-domain) is a much larger refactor.
+ *
+ * - `events` — semantic events fired during the turn just executed.
+ *   Frozen array; producers must not mutate.
+ *
+ * - `blocks` — text blocks produced by `text-service.processTurn` for
+ *   the turn just executed. Frozen array.
+ *
+ * - `turn` — monotonic turn count for this session. Engine increments.
+ *
+ * - `prevValue` — the value this channel emitted on the previous turn,
+ *   or `undefined` if no prior emission. Closures use this for
+ *   diff-aware emission decisions and for append-mode awareness.
+ *
+ * Closures are pure functions of context. They project; they do not
+ * mutate.
+ */
+export interface ChannelProduceContext {
+    /**
+     * World state for the current turn. Typed `unknown` to avoid an
+     * if-domain → world-model cycle. Consumers cast at the call site.
+     */
+    readonly world: unknown;
+    readonly events: readonly ISemanticEvent[];
+    readonly blocks: readonly ITextBlock[];
+    readonly turn: number;
+    readonly prevValue: unknown | undefined;
+}
+/**
+ * A typed channel definition with embedded producer (ADR-163 §6).
+ *
+ * Channels are objects. They carry identity (`id`), configuration
+ * (`contentType`, `mode`, `emit`, optional `gatedBy`), and a
+ * `produce(ctx)` closure that computes the channel's value for the
+ * current turn.
+ *
+ * The closure return value drives emission semantics:
+ *
+ * - `T` — emit this value.
+ * - `undefined` — skip emission this turn (sparse channels stay quiet;
+ *   always channels re-emit their previous value).
+ * - `null` — emit a hide / stop / clear signal (used by media channels
+ *   per §9 and by `clear` per §12).
+ *
+ * For `append`-mode channels, return an array of new entries (or
+ * `undefined` for "no new entries this turn"). For `replace` or `event`
+ * mode, return a single value (or `undefined`).
+ *
+ * Story override of a standard channel = re-register an `IOChannel`
+ * with the same `id` (last write wins per §6).
+ */
+export interface IOChannel<T = unknown> {
+    readonly id: string;
+    readonly contentType: ChannelContentType;
+    readonly mode: ChannelMode;
+    readonly emit: ChannelEmitPolicy;
+    /** Capability flag this channel is gated by, if any. */
+    readonly gatedBy?: CapabilityFlag;
+    /**
+     * Produce this channel's value for the current turn. See class
+     * comment above for the return-shape contract.
+     */
+    readonly produce: (ctx: ChannelProduceContext) => T | T[] | undefined | null;
+}
+/**
+ * Channel registry contract (ADR-163 §7, §14).
+ *
+ * The registry is a simple keyed collection of `IOChannel` instances.
+ * It does not enforce mode invariants, capability filtering, or
+ * registration order — those are the `ChannelService`'s job.
+ *
+ * `add(channel)` is last-write-wins by `channel.id`: re-registering an
+ * id replaces the prior definition. This is how stories override
+ * standard channels (per §6).
+ *
+ * Implementations live elsewhere:
+ *
+ * - `@sharpee/stdlib` exports a populated `channelRegistry` instance
+ *   with the standard channels pre-registered (per §7).
+ * - Engine bootstrap calls `Story.registerChannels?.(registry)` to let
+ *   stories add or override channels.
+ */
+export interface IChannelRegistry {
+    add(channel: IOChannel): void;
+    get(id: string): IOChannel | undefined;
+    all(): readonly IOChannel[];
+}
+//# sourceMappingURL=types.d.ts.map

package/channels/types.d.ts.map

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

package/channels/types.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * @sharpee/if-domain — channel type contracts (ADR-163, closure-per-channel
+ * model, 2026-05-02 rewrite + 2026-05-03 refinement).
+ *
+ * Owner context: domain layer. These types describe the channel-I/O
+ * contract used by every package that participates in the channel system:
+ *
+ * - `@sharpee/channel-service` runs the closures (`ChannelService.build`).
+ * - `@sharpee/stdlib` defines the standard `IOChannel` instances.
+ * - `@sharpee/engine` composes the registry with the service and emits
+ *   manifest / packet events.
+ * - Consumers (`@sharpee/platform-browser`, multi-user web-client, CLI
+ *   bundle) consume the wire packets via ADR-165 renderers.
+ *
+ * Public interface: the `IOChannel<T>` contract, the `IChannelRegistry`
+ * registry shape, the `ChannelProduceContext` passed to closures, and the
+ * three small enums (`ChannelContentType`, `ChannelMode`,
+ * `ChannelEmitPolicy`) plus `ClientCapabilities` and `CapabilityFlag`.
+ *
+ * No implementation lives here. Per ADR-163 §14 and CLAUDE.md rule 7b:
+ * if-domain is the single home for channel type contracts so co-located
+ * client and server code share them by direct import, not duplication.
+ *
+ * @see ADR-163 — Channel-Service Platform — §6, §7, §14
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/channels/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/if-domain/src/channels/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/channels/wire.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @sharpee/if-domain — channel wire-protocol types (ADR-163 §1, §11).
+ *
+ * Owner context: domain layer. Pure types describing the four packets
+ * that cross the wire between server and client in the channel-I/O
+ * system.
+ *
+ * Public interface (per CLAUDE.md rule 7b): single-user and multi-user
+ * surfaces both import directly from this module. Co-located client and
+ * server code shares the wire contract via direct import to make
+ * protocol drift mechanically impossible.
+ *
+ * Constraint: NO runtime-specific types (no `Buffer`, `fs.Stats`,
+ * `DOMException`, no DOM globals, no Node globals). The module must be
+ * importable by browser, Node, and CLI contexts without dragging in a
+ * runtime they don't have.
+ *
+ * @see ADR-163 — Channel-Service Platform — §1, §3, §4, §5, §11
+ */
+import type { ChannelContentType, ChannelEmitPolicy, ChannelMode, ClientCapabilities } from './types';
+/**
+ * Channel definition as it appears in a CMGT manifest (ADR-163 §11).
+ *
+ * Wire-shaped subset of `IOChannel` — just identity and configuration.
+ * The producer closure does not cross the wire; only its outputs do.
+ *
+ * Mode lives on the channel, not on the rule (ADR-163 §4). A channel
+ * always behaves the same way regardless of which `IOChannel` produced
+ * it, and clients dispatch on the manifest entry alone.
+ */
+export interface ChannelDefinition {
+    /** Channel id. String — no integer packing. */
+    readonly id: string;
+    /** Content type carried by emissions on this channel. */
+    readonly contentType: ChannelContentType;
+    /** Update mode (replace / append / event). */
+    readonly mode: ChannelMode;
+    /**
+     * Emit policy. Optional in the wire shape because authors may omit
+     * it on `IOChannel` registration; the platform standard channels
+     * default to `'always'` and author channels default to `'sparse'`.
+     */
+    readonly emit?: ChannelEmitPolicy;
+}
+/**
+ * Hello packet — client → server at session start (ADR-163 §1, §2).
+ *
+ * Single-user runtimes synthesize a hello internally. In transport-
+ * attached deployments (ADR-164) the client transmits one over the wire.
+ * Either way, the `ChannelService` may not emit `cmgt` until a hello
+ * has been registered for the session (bootstrap-order invariant per
+ * §11).
+ */
+export interface HelloPacket {
+    readonly kind: 'hello';
+    readonly capabilities: ClientCapabilities;
+}
+/**
+ * CMGT (channel-management) packet — server → client (ADR-163 §1, §11).
+ *
+ * Pure schema; no values. The manifest is per-client — derived from the
+ * union of registered channels filtered by the client's capability
+ * declaration (per §6, §11).
+ */
+export interface CmgtPacket {
+    readonly kind: 'cmgt';
+    /**
+     * Wire protocol version. Initial value `1`. Bumped on breaking shape
+     * changes to packet kinds or `ChannelDefinition` fields. Additive
+     * channels do not bump version.
+     */
+    readonly protocol_version: number;
+    /**
+     * Capability-filtered channel definitions for this client.
+     */
+    readonly channels: ReadonlyArray<ChannelDefinition>;
+}
+/**
+ * Turn packet — server → client per turn (ADR-163 §1).
+ *
+ * The payload is a record keyed by channel id. Per-channel emit policy
+ * (§5) governs which channel keys appear: `'always'` channels appear
+ * every turn, `'sparse'` channels appear only on change.
+ *
+ * Append-mode payload values carry NEW ENTRIES THIS TURN ONLY, not the
+ * accumulated list (§5). The renderer is responsible for accumulation.
+ */
+export interface TurnPacket {
+    readonly kind: 'turn';
+    /**
+     * Turn identifier — opaque string. Used for re-emission identity
+     * (§14) and for transcript ordering in downstream consumers.
+     */
+    readonly turn_id: string;
+    /**
+     * Channel-keyed payload. Channel ids map to type-specific values:
+     * text channels carry strings, number channels carry numbers, json
+     * channels carry arbitrary objects (or `null` for replace-mode
+     * media channels signaling stop/hide per §7).
+     */
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+/**
+ * Command packet — client → server per input (ADR-163 §1, §9).
+ *
+ * UI gestures (hotspot click, drag-drop, custom widget) are synthesized
+ * into command packets indistinguishable from typed input. The boundary
+ * rule (§9): if the action would change what the engine sees on the
+ * next turn, it is a `CommandPacket`; otherwise it is renderer-local
+ * and never reaches the wire.
+ */
+export interface CommandPacket {
+    readonly kind: 'command';
+    readonly text: string;
+}
+/**
+ * Wire packet discriminated union — every packet that crosses the wire.
+ *
+ * Decoders pattern-match on `kind` to dispatch.
+ */
+export type WirePacket = HelloPacket | CmgtPacket | TurnPacket | CommandPacket;
+//# sourceMappingURL=wire.d.ts.map

package/channels/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/if-domain/src/channels/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACrD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,UAAU,GACV,UAAU,GACV,aAAa,CAAC"}

package/channels/wire.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @sharpee/if-domain — channel wire-protocol types (ADR-163 §1, §11).
+ *
+ * Owner context: domain layer. Pure types describing the four packets
+ * that cross the wire between server and client in the channel-I/O
+ * system.
+ *
+ * Public interface (per CLAUDE.md rule 7b): single-user and multi-user
+ * surfaces both import directly from this module. Co-located client and
+ * server code shares the wire contract via direct import to make
+ * protocol drift mechanically impossible.
+ *
+ * Constraint: NO runtime-specific types (no `Buffer`, `fs.Stats`,
+ * `DOMException`, no DOM globals, no Node globals). The module must be
+ * importable by browser, Node, and CLI contexts without dragging in a
+ * runtime they don't have.
+ *
+ * @see ADR-163 — Channel-Service Platform — §1, §3, §4, §5, §11
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=wire.js.map

package/channels/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/if-domain/src/channels/wire.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/index.d.ts

@@ -13,4 +13,6 @@ export * from './parser-contracts';
 export * from './vocabulary-contracts';
 export * from './grammar';
 export * from './prompt';
+export * from './channels';
+export * from './sound';
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/if-domain/src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,UAAU,CAAC;AAGzB,cAAc,aAAa,CAAC;AAG5B,cAAc,WAAW,CAAC;AAG1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAG3C,cAAc,oBAAoB,CAAC;AAGnC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,WAAW,CAAC;AAG1B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/if-domain/src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,UAAU,CAAC;AAGzB,cAAc,aAAa,CAAC;AAG5B,cAAc,WAAW,CAAC;AAG1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAG3C,cAAc,oBAAoB,CAAC;AAGnC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,WAAW,CAAC;AAG1B,cAAc,UAAU,CAAC;AAGzB,cAAc,YAAY,CAAC;AAG3B,cAAc,SAAS,CAAC"}

package/index.js

@@ -37,4 +37,8 @@ __exportStar(require("./vocabulary-contracts"), exports);
 __exportStar(require("./grammar"), exports);
 // Prompt types (ADR-137)
 __exportStar(require("./prompt"), exports);
+// Channel-I/O type contracts (ADR-163)
+__exportStar(require("./channels"), exports);
+// Spatial sound propagation contracts (ADR-172)
+__exportStar(require("./sound"), exports);
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/if-domain/src/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;AAEH,gBAAgB;AAChB,2CAAyB;AAEzB,mBAAmB;AACnB,8CAA4B;AAE5B,sBAAsB;AACtB,4CAA0B;AAE1B,+BAA+B;AAC/B,sDAAoC;AACpC,6DAA2C;AAE3C,mBAAmB;AACnB,qDAAmC;AAEnC,uBAAuB;AACvB,yDAAuC;AAEvC,iBAAiB;AACjB,4CAA0B;AAE1B,yBAAyB;AACzB,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/if-domain/src/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;AAEH,gBAAgB;AAChB,2CAAyB;AAEzB,mBAAmB;AACnB,8CAA4B;AAE5B,sBAAsB;AACtB,4CAA0B;AAE1B,+BAA+B;AAC/B,sDAAoC;AACpC,6DAA2C;AAE3C,mBAAmB;AACnB,qDAAmC;AAEnC,uBAAuB;AACvB,yDAAuC;AAEvC,iBAAiB;AACjB,4CAA0B;AAE1B,yBAAyB;AACzB,2CAAyB;AAEzB,uCAAuC;AACvC,6CAA2B;AAE3B,gDAAgD;AAChD,0CAAwB"}

package/language-provider.d.ts

@@ -70,6 +70,12 @@ export interface LanguageProvider {
      * @returns Array of action IDs
      */
     getSupportedActions?(): string[];
+    /**
+     * Get all registered message IDs and their text.
+     * Used by tooling (VS Code extension) for language introspection.
+     * @returns Map of message ID to text, or undefined if not supported
+     */
+    getAllMessages?(): Map<string, string>;
 }
 /**
  * Language provider registry interface

package/language-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"language-provider.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/if-domain/src/language-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAE1D;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC;IAEpE;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAEvC;;;;OAIG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAEzD;;;OAGG;IACH,mBAAmB,CAAC,IAAI,MAAM,EAAE,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE3C;;;;OAIG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAExD;;;;OAIG;IACH,UAAU,IAAI,gBAAgB,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvC;;;OAGG;IACH,qBAAqB,IAAI,MAAM,EAAE,CAAC;CACnC"}
+{"version":3,"file":"language-provider.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/if-domain/src/language-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAE1D;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC;IAEpE;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAEvC;;;;OAIG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAEzD;;;OAGG;IACH,mBAAmB,CAAC,IAAI,MAAM,EAAE,CAAC;IAEjC;;;;OAIG;IACH,cAAc,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE3C;;;;OAIG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAExD;;;;OAIG;IACH,UAAU,IAAI,gBAAgB,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvC;;;OAGG;IACH,qBAAqB,IAAI,MAAM,EAAE,CAAC;CACnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sharpee/if-domain",
-  "version": "0.9.111",
+  "version": "1.0.0",
   "description": "Core domain model and contracts for Sharpee Interactive Fiction Platform",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -12,7 +12,8 @@
     }
   },
   "dependencies": {
-    "@sharpee/core": "^0.9.111"
+    "@sharpee/core": "^1.0.0",
+    "@sharpee/text-blocks": "^1.0.0"
   },
   "keywords": [
     "interactive-fiction",

package/sound/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @sharpee/if-domain/sound — spatial sound propagation type contracts.
+ *
+ * Owner context: domain layer. Single canonical home for the sound
+ * type contracts shared between emission (stdlib), propagation (engine),
+ * and rendering (lang-{locale}, audio-capable clients).
+ *
+ * Public interface:
+ *
+ *  - `VolumeTier`, `VOLUME_TIER_BUDGETS` — emission-side volume tier set.
+ *  - `AudibilityTier` — listener-side audibility tier set.
+ *  - `SoundKind` — semantic classifier string.
+ *  - `ISoundContent` — optional structured content payload.
+ *  - `ISound` — emission shape for `context.emitSound`.
+ *  - `IAudibilityEvent` — per-listener delivery shape produced by
+ *    propagation and routed through the sound channel.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ */
+export * from './types';
+//# 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/if-domain/src/sound/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,cAAc,SAAS,CAAC"}

package/sound/index.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * @sharpee/if-domain/sound — spatial sound propagation type contracts.
+ *
+ * Owner context: domain layer. Single canonical home for the sound
+ * type contracts shared between emission (stdlib), propagation (engine),
+ * and rendering (lang-{locale}, audio-capable clients).
+ *
+ * Public interface:
+ *
+ *  - `VolumeTier`, `VOLUME_TIER_BUDGETS` — emission-side volume tier set.
+ *  - `AudibilityTier` — listener-side audibility tier set.
+ *  - `SoundKind` — semantic classifier string.
+ *  - `ISoundContent` — optional structured content payload.
+ *  - `ISound` — emission shape for `context.emitSound`.
+ *  - `IAudibilityEvent` — per-listener delivery shape produced by
+ *    propagation and routed through the sound channel.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/sound/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/if-domain/src/sound/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;;;;;;;;;;;;;;AAEH,0CAAwB"}

package/sound/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @file Sound and AudibilityEvent domain types (ADR-172).
+ *
+ * The wire-level contract between sound emission, propagation, and
+ * rendering. This file defines:
+ *
+ *  - `VolumeTier` — the discrete emission-volume tier set
+ *    (whisper / subdued / normal / raised / shouting) with platform
+ *    propagation budgets.
+ *  - `AudibilityTier` — the discrete listener-side tier set
+ *    (silent / presence-only / fragments / muffled / full).
+ *  - `Sound` — the emission shape an action constructs and hands to
+ *    `context.emitSound` (Phase 6).
+ *  - `AudibilityEvent` — the per-listener delivery shape produced by
+ *    the propagation function (Phase 3) and routed through the sound
+ *    channel (Phase 5).
+ *
+ * No behavior — pure shapes. Propagation logic lands in
+ * `@sharpee/engine` (Phase 3); trait definitions land in
+ * `@sharpee/world-model` (Phase 2). Both depend on this file.
+ *
+ * Owner context: `@sharpee/if-domain` — domain-layer contracts.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ * @see ADR-173 — Wall Adjacency Primitive (substrate this rides on)
+ */
+import type { EntityId } from "../../core/index";
+/**
+ * The five discrete volume tiers an emitter may declare. Ordered from
+ * quietest to loudest. Each tier has an integer propagation budget (see
+ * `VOLUME_TIER_BUDGETS`); the propagation algorithm subtracts accumulated
+ * path cost from this budget to compute clarity at each listener.
+ *
+ * Discrete tiers are deliberate over continuous numeric volumes: authoring
+ * is qualitative, prose layers render per-tier, and continuous values
+ * invite balance tuning that produces no gameplay value.
+ */
+export type VolumeTier = 'whisper' | 'subdued' | 'normal' | 'raised' | 'shouting';
+/**
+ * Platform-default propagation budgets per volume tier (ADR-172). Stories
+ * that want a different acoustic register (a horror story with sound that
+ * carries unnaturally far, a soundproofed-bunker setting) override this
+ * table without the platform code changing.
+ *
+ * The budget is consumed against accumulated path cost during propagation;
+ * negative remainders below 1 collapse to `silent`.
+ */
+export declare const VOLUME_TIER_BUDGETS: Readonly<Record<VolumeTier, number>>;
+/**
+ * The five discrete audibility tiers the propagation function reports per
+ * listener. `silent` means the listener does not perceive the sound and
+ * receives no event; the other four are delivered as `AudibilityEvent`s
+ * with rendering modulated by tier.
+ *
+ *  - `presence-only` — the listener knows a sound occurred (kind, rough
+ *    direction) but no content passes.
+ *  - `fragments`     — partial content; key words, broken phrases.
+ *  - `muffled`       — full content, rendered with distortion framing at
+ *    the prose layer.
+ *  - `full`          — verbatim; clean reception.
+ */
+export type AudibilityTier = 'silent' | 'presence-only' | 'fragments' | 'muffled' | 'full';
+/**
+ * A sound's *kind*: a coarse semantic classifier the rendering layer uses
+ * to pick per-`(kind, audibility_tier)` prose defaults. New kinds are
+ * added as the platform grows; this is a string union, not a closed enum,
+ * to keep the type extensible to story-level kinds.
+ *
+ * Examples chosen from ADR-172's running examples; this list is *not*
+ * exhaustive and not part of the platform contract — story code may pass
+ * any string here, with the language layer falling through to a generic
+ * default if no per-kind prose is registered.
+ */
+export type SoundKind = string;
+/**
+ * Optional structured content for a sound. Content-bearing sounds carry
+ * a content payload that audibility tier modulates: at `full` the content
+ * is verbatim; at `muffled` it's distorted; at `fragments` only key
+ * fragments pass; at `presence-only` no content passes (the listener
+ * only knows the sound happened).
+ *
+ * The shape carries a `messageId` (resolved by the language layer) and
+ * optional `params` for templating. Pattern-as-content (knock codes,
+ * rhythmic taps) is *not* a separate dimension — it composes through
+ * the same content + tier pipeline, with the language layer rendering
+ * pattern degradation per tier.
+ */
+export interface ISoundContent {
+    /** Message ID resolved by the language layer (e.g. story-authored line ID). */
+    messageId: string;
+    /** Optional params for the message template; keys depend on the messageId. */
+    params?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The emission shape an action hands to the platform's sound dispatcher.
+ *
+ * `sourceLocation` is the room-id the sound originates from; the
+ * propagation function uses it as the path-search root. `sourceEntity`
+ * is the entity that produced the sound (an actor, a device, an
+ * inanimate object) — propagation does not consult it, but downstream
+ * handlers and prose templates may.
+ *
+ * `kind` is the semantic classifier (see `SoundKind`). `volumeTier` is
+ * the emission-side tier (see `VolumeTier`). `content` is optional;
+ * sounds without content are *ambient* (a gunshot, breaking glass, a
+ * closing door) and the prose layer renders the sound itself rather
+ * than its content.
+ */
+export interface ISound {
+    readonly sourceLocation: EntityId;
+    readonly sourceEntity: EntityId;
+    readonly kind: SoundKind;
+    readonly volumeTier: VolumeTier;
+    readonly content?: ISoundContent;
+}
+/**
+ * The per-listener event the propagation function produces and the sound
+ * channel routes. Carries enough context for both prose rendering and
+ * audio-cue mapping.
+ *
+ *  - `sourceRoomId`   — room-id where the sound was emitted.
+ *  - `targetRoomId`   — room-id the listener is in when the sound reaches
+ *                       them (typically the listener's current room).
+ *  - `wallId`         — the wall entity-id whose acoustic cost contributed
+ *                       to the lowest-cost path, when the path crosses one
+ *                       wall. Optional — may be absent for paths that go
+ *                       through doors, conduits, or are within the same
+ *                       room. Future ADRs may extend this to a path of
+ *                       crossings; today the field is single-valued for
+ *                       common single-hop cases.
+ *  - `sourceEntityId` — the entity that emitted the sound (mirrors
+ *                       `Sound.sourceEntity`).
+ *  - `kind`           — the sound's kind, copied from the emission.
+ *  - `volumeTier`     — the emission's volume tier, copied as-emitted.
+ *  - `audibilityTier` — the propagation result for this listener.
+ *                       Never `silent`: silent results suppress event
+ *                       delivery entirely (no `AudibilityEvent` is
+ *                       produced).
+ *  - `content`        — copied from the emission iff content-bearing.
+ *  - `timestamp`      — engine-provided turn-sequence integer for ordering.
+ *
+ * The prose layer maps `(kind, audibilityTier)` to a default rendering
+ * pattern; stories override per-kind. The audio-channel renderer maps
+ * `audibilityTier` to a playback volume via ADR-169's fade infrastructure.
+ *
+ * Adding fields to this interface requires a future ADR — it is the
+ * contract L2+ ADRs (NPC voice, conversation choreography, stealth
+ * observation) ride on.
+ */
+export interface IAudibilityEvent {
+    readonly sourceRoomId: EntityId;
+    readonly targetRoomId: EntityId;
+    readonly wallId?: EntityId;
+    readonly sourceEntityId: EntityId;
+    readonly kind: SoundKind;
+    readonly volumeTier: VolumeTier;
+    /** Always one of the *delivered* tiers — never `'silent'`. */
+    readonly audibilityTier: Exclude<AudibilityTier, 'silent'>;
+    readonly content?: ISoundContent;
+    readonly timestamp: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/sound/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/if-domain/src/sound/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAM9C;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAMnE,CAAC;AAMH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,eAAe,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAM3F;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;CAClC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/sound/types.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * @file Sound and AudibilityEvent domain types (ADR-172).
+ *
+ * The wire-level contract between sound emission, propagation, and
+ * rendering. This file defines:
+ *
+ *  - `VolumeTier` — the discrete emission-volume tier set
+ *    (whisper / subdued / normal / raised / shouting) with platform
+ *    propagation budgets.
+ *  - `AudibilityTier` — the discrete listener-side tier set
+ *    (silent / presence-only / fragments / muffled / full).
+ *  - `Sound` — the emission shape an action constructs and hands to
+ *    `context.emitSound` (Phase 6).
+ *  - `AudibilityEvent` — the per-listener delivery shape produced by
+ *    the propagation function (Phase 3) and routed through the sound
+ *    channel (Phase 5).
+ *
+ * No behavior — pure shapes. Propagation logic lands in
+ * `@sharpee/engine` (Phase 3); trait definitions land in
+ * `@sharpee/world-model` (Phase 2). Both depend on this file.
+ *
+ * Owner context: `@sharpee/if-domain` — domain-layer contracts.
+ *
+ * @see ADR-172 — Spatial Sound Propagation
+ * @see ADR-173 — Wall Adjacency Primitive (substrate this rides on)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOLUME_TIER_BUDGETS = void 0;
+/**
+ * Platform-default propagation budgets per volume tier (ADR-172). Stories
+ * that want a different acoustic register (a horror story with sound that
+ * carries unnaturally far, a soundproofed-bunker setting) override this
+ * table without the platform code changing.
+ *
+ * The budget is consumed against accumulated path cost during propagation;
+ * negative remainders below 1 collapse to `silent`.
+ */
+exports.VOLUME_TIER_BUDGETS = Object.freeze({
+    whisper: 1,
+    subdued: 2,
+    normal: 5,
+    raised: 7,
+    shouting: 9,
+});
+//# sourceMappingURL=types.js.map

package/sound/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/if-domain/src/sound/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAoBH;;;;;;;;GAQG;AACU,QAAA,mBAAmB,GAAyC,MAAM,CAAC,MAAM,CAAC;IACrF,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,CAAC;CACZ,CAAC,CAAC"}