@sharpee/core 0.9.56-beta

package/dist/events/event-factory.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Event Factory - Type-safe semantic event creation
+ *
+ * @see ADR-082 for design rationale
+ */
+import { EventDataRegistry, EventType } from './event-registry';
+import { TypedSemanticEvent } from './typed-event';
+import { ISemanticEvent } from './types';
+/**
+ * Options for creating an event.
+ */
+export interface CreateEventOptions {
+    /**
+     * Entities involved in the event.
+     */
+    entities?: ISemanticEvent['entities'];
+    /**
+     * Tags for categorizing the event.
+     */
+    tags?: string[];
+    /**
+     * Priority of the event (higher = more important).
+     */
+    priority?: number;
+    /**
+     * Whether this event should be narrated.
+     */
+    narrate?: boolean;
+    /**
+     * Custom event ID (auto-generated if not provided).
+     */
+    id?: string;
+}
+/**
+ * Create a type-safe semantic event.
+ *
+ * The data parameter is strictly typed based on the event type,
+ * providing compile-time verification of event data.
+ *
+ * @example
+ * ```typescript
+ * // TypeScript enforces correct data shape
+ * const event = createTypedEvent('query.invalid', {
+ *   message: 'Invalid input',
+ *   hint: 'Please try again'
+ * });
+ *
+ * // This would be a compile error:
+ * // createTypedEvent('query.invalid', { wrongField: true });
+ * ```
+ */
+export declare function createTypedEvent<T extends EventType>(type: T, data: EventDataRegistry[T], options?: CreateEventOptions): TypedSemanticEvent<T>;
+/**
+ * Message event variant types.
+ */
+export type MessageVariant = 'success' | 'failure' | 'info' | 'warning' | 'debug';
+/**
+ * Create a message event (convenience helper).
+ *
+ * @example
+ * ```typescript
+ * const event = createMessageEvent('success', 'item_taken', {
+ *   item: 'brass lantern'
+ * });
+ * ```
+ */
+export declare function createMessageEvent(variant: MessageVariant, messageId: string, params?: Record<string, unknown>, options?: CreateEventOptions): TypedSemanticEvent<`message.${MessageVariant}`>;
+/**
+ * Create an empty event (for events with no data).
+ *
+ * @example
+ * ```typescript
+ * const event = createEmptyEvent('platform.quit_cancelled');
+ * ```
+ */
+export declare function createEmptyEvent<T extends EventType>(type: T, options?: CreateEventOptions): TypedSemanticEvent<T>;
+/**
+ * Reset the event counter (useful for testing).
+ */
+export declare function resetEventCounter(): void;
+//# sourceMappingURL=event-factory.d.ts.map

package/dist/events/event-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-factory.d.ts","sourceRoot":"","sources":["../../src/events/event-factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAe,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAIzC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAEtC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,EAClD,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC1B,OAAO,GAAE,kBAAuB,GAC/B,kBAAkB,CAAC,CAAC,CAAC,CAWvB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAElF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,kBAAkB,GAC3B,kBAAkB,CAAC,WAAW,cAAc,EAAE,CAAC,CAGjD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,EAClD,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,kBAAkB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/events/event-factory.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Event Factory - Type-safe semantic event creation
+ *
+ * @see ADR-082 for design rationale
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTypedEvent = createTypedEvent;
+exports.createMessageEvent = createMessageEvent;
+exports.createEmptyEvent = createEmptyEvent;
+exports.resetEventCounter = resetEventCounter;
+let eventCounter = 0;
+/**
+ * Create a type-safe semantic event.
+ *
+ * The data parameter is strictly typed based on the event type,
+ * providing compile-time verification of event data.
+ *
+ * @example
+ * ```typescript
+ * // TypeScript enforces correct data shape
+ * const event = createTypedEvent('query.invalid', {
+ *   message: 'Invalid input',
+ *   hint: 'Please try again'
+ * });
+ *
+ * // This would be a compile error:
+ * // createTypedEvent('query.invalid', { wrongField: true });
+ * ```
+ */
+function createTypedEvent(type, data, options = {}) {
+    return {
+        id: options.id ?? `evt-${Date.now()}-${++eventCounter}`,
+        type,
+        timestamp: Date.now(),
+        data,
+        entities: options.entities ?? {},
+        tags: options.tags,
+        priority: options.priority,
+        narrate: options.narrate
+    };
+}
+/**
+ * Create a message event (convenience helper).
+ *
+ * @example
+ * ```typescript
+ * const event = createMessageEvent('success', 'item_taken', {
+ *   item: 'brass lantern'
+ * });
+ * ```
+ */
+function createMessageEvent(variant, messageId, params, options) {
+    const type = `message.${variant}`;
+    return createTypedEvent(type, { messageId, params }, options);
+}
+/**
+ * Create an empty event (for events with no data).
+ *
+ * @example
+ * ```typescript
+ * const event = createEmptyEvent('platform.quit_cancelled');
+ * ```
+ */
+function createEmptyEvent(type, options) {
+    return createTypedEvent(type, {}, options);
+}
+/**
+ * Reset the event counter (useful for testing).
+ */
+function resetEventCounter() {
+    eventCounter = 0;
+}
+//# sourceMappingURL=event-factory.js.map

package/dist/events/event-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-factory.js","sourceRoot":"","sources":["../../src/events/event-factory.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAwDH,4CAeC;AAiBD,gDAQC;AAUD,4CAKC;AAKD,8CAEC;AAhHD,IAAI,YAAY,GAAG,CAAC,CAAC;AAgCrB;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,gBAAgB,CAC9B,IAAO,EACP,IAA0B,EAC1B,UAA8B,EAAE;IAEhC,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE;QACvD,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,IAAI;QACJ,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;QAChC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC;AAOD;;;;;;;;;GASG;AACH,SAAgB,kBAAkB,CAChC,OAAuB,EACvB,SAAiB,EACjB,MAAgC,EAChC,OAA4B;IAE5B,MAAM,IAAI,GAAG,WAAW,OAAO,EAAiC,CAAC;IACjE,OAAO,gBAAgB,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,MAAM,EAAiB,EAAE,OAAO,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAC9B,IAAO,EACP,OAA4B;IAE5B,OAAO,gBAAgB,CAAC,IAAI,EAAE,EAA0B,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB;IAC/B,YAAY,GAAG,CAAC,CAAC;AACnB,CAAC"}

package/dist/events/event-helpers.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Event Helpers - Type-safe event consumption utilities
+ *
+ * These functions help consumers safely extract typed data from events
+ * without resorting to `as any` casts.
+ *
+ * @see ADR-082 for design rationale
+ */
+import { EventDataRegistry, EventType } from './event-registry';
+import { ISemanticEvent } from './types';
+/**
+ * Check if an event is of a specific type and narrow its type.
+ *
+ * This is a type guard that allows TypeScript to narrow the event
+ * type in conditional branches.
+ *
+ * @example
+ * ```typescript
+ * function processEvent(event: ISemanticEvent) {
+ *   if (isEventType(event, 'query.invalid')) {
+ *     // TypeScript knows event.data is QueryInvalidData
+ *     console.log(event.data.message);
+ *     console.log(event.data.hint);
+ *   }
+ * }
+ * ```
+ */
+export declare function isEventType<T extends EventType>(event: ISemanticEvent, type: T): event is ISemanticEvent & {
+    type: T;
+    data: EventDataRegistry[T];
+};
+/**
+ * Check if an event type starts with a prefix.
+ *
+ * Useful for handling categories of events (e.g., all message.* events).
+ *
+ * @example
+ * ```typescript
+ * if (hasEventPrefix(event, 'message.')) {
+ *   // Handle any message event
+ * }
+ * ```
+ */
+export declare function hasEventPrefix(event: ISemanticEvent, prefix: string): boolean;
+/**
+ * Get typed event data if the event matches the expected type.
+ *
+ * Returns undefined if the event type doesn't match. This is the safe
+ * way to extract data when you're not sure of the event type.
+ *
+ * @example
+ * ```typescript
+ * const data = getEventData(event, 'quit.confirmed');
+ * if (data) {
+ *   console.log(`Final score: ${data.finalScore}`);
+ * }
+ * ```
+ */
+export declare function getEventData<T extends EventType>(event: ISemanticEvent, expectedType: T): EventDataRegistry[T] | undefined;
+/**
+ * Get event data with a fallback for missing properties.
+ *
+ * This is useful when you need default values for optional fields.
+ *
+ * @example
+ * ```typescript
+ * const { message, hint } = getEventDataWithDefaults(
+ *   event,
+ *   'query.invalid',
+ *   { message: 'Invalid response.', hint: undefined }
+ * );
+ * ```
+ */
+export declare function getEventDataWithDefaults<T extends EventType>(event: ISemanticEvent, expectedType: T, defaults: EventDataRegistry[T]): EventDataRegistry[T];
+/**
+ * Assert and get typed event data.
+ *
+ * Throws if the event type doesn't match. Use this when you're certain
+ * of the event type and want a clear error if assumptions are wrong.
+ *
+ * @example
+ * ```typescript
+ * // In a handler that only receives 'quit.confirmed' events
+ * const data = requireEventData(event, 'quit.confirmed');
+ * console.log(`Score: ${data.finalScore}/${data.maxScore}`);
+ * ```
+ */
+export declare function requireEventData<T extends EventType>(event: ISemanticEvent, expectedType: T): EventDataRegistry[T];
+/**
+ * Safely access a property from event data with type inference.
+ *
+ * Returns undefined if the event type doesn't match or the property
+ * doesn't exist.
+ *
+ * @example
+ * ```typescript
+ * const message = getEventProperty(event, 'query.invalid', 'message');
+ * // message is string | undefined
+ * ```
+ */
+export declare function getEventProperty<T extends EventType, K extends keyof EventDataRegistry[T]>(event: ISemanticEvent, expectedType: T, property: K): EventDataRegistry[T][K] | undefined;
+/**
+ * Get event data as a generic record for untyped event access.
+ *
+ * Use this when working with events that aren't yet in the EventDataRegistry.
+ * Prefer using typed helpers (isEventType, getEventData) when the event
+ * type is known.
+ *
+ * @example
+ * ```typescript
+ * const data = getUntypedEventData(event);
+ * if (data.customField) {
+ *   console.log(data.customField);
+ * }
+ * ```
+ */
+export declare function getUntypedEventData(event: ISemanticEvent): Record<string, unknown>;
+//# sourceMappingURL=event-helpers.d.ts.map

package/dist/events/event-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-helpers.d.ts","sourceRoot":"","sources":["../../src/events/event-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAC7C,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,CAAC,GACN,KAAK,IAAI,cAAc,GAAG;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAA;CAAE,CAEnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAE7E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAC9C,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,CAAC,GACd,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,CAKlC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,SAAS,EAC1D,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,CAAC,EACf,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC7B,iBAAiB,CAAC,CAAC,CAAC,CAKtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,EAClD,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,CAAC,GACd,iBAAiB,CAAC,CAAC,CAAC,CAOtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,MAAM,iBAAiB,CAAC,CAAC,CAAC,EAEpC,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,CAAC,EACf,QAAQ,EAAE,CAAC,GACV,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAKrC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB"}

package/dist/events/event-helpers.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Event Helpers - Type-safe event consumption utilities
+ *
+ * These functions help consumers safely extract typed data from events
+ * without resorting to `as any` casts.
+ *
+ * @see ADR-082 for design rationale
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEventType = isEventType;
+exports.hasEventPrefix = hasEventPrefix;
+exports.getEventData = getEventData;
+exports.getEventDataWithDefaults = getEventDataWithDefaults;
+exports.requireEventData = requireEventData;
+exports.getEventProperty = getEventProperty;
+exports.getUntypedEventData = getUntypedEventData;
+/**
+ * Check if an event is of a specific type and narrow its type.
+ *
+ * This is a type guard that allows TypeScript to narrow the event
+ * type in conditional branches.
+ *
+ * @example
+ * ```typescript
+ * function processEvent(event: ISemanticEvent) {
+ *   if (isEventType(event, 'query.invalid')) {
+ *     // TypeScript knows event.data is QueryInvalidData
+ *     console.log(event.data.message);
+ *     console.log(event.data.hint);
+ *   }
+ * }
+ * ```
+ */
+function isEventType(event, type) {
+    return event.type === type;
+}
+/**
+ * Check if an event type starts with a prefix.
+ *
+ * Useful for handling categories of events (e.g., all message.* events).
+ *
+ * @example
+ * ```typescript
+ * if (hasEventPrefix(event, 'message.')) {
+ *   // Handle any message event
+ * }
+ * ```
+ */
+function hasEventPrefix(event, prefix) {
+    return event.type.startsWith(prefix);
+}
+/**
+ * Get typed event data if the event matches the expected type.
+ *
+ * Returns undefined if the event type doesn't match. This is the safe
+ * way to extract data when you're not sure of the event type.
+ *
+ * @example
+ * ```typescript
+ * const data = getEventData(event, 'quit.confirmed');
+ * if (data) {
+ *   console.log(`Final score: ${data.finalScore}`);
+ * }
+ * ```
+ */
+function getEventData(event, expectedType) {
+    if (event.type === expectedType) {
+        return event.data;
+    }
+    return undefined;
+}
+/**
+ * Get event data with a fallback for missing properties.
+ *
+ * This is useful when you need default values for optional fields.
+ *
+ * @example
+ * ```typescript
+ * const { message, hint } = getEventDataWithDefaults(
+ *   event,
+ *   'query.invalid',
+ *   { message: 'Invalid response.', hint: undefined }
+ * );
+ * ```
+ */
+function getEventDataWithDefaults(event, expectedType, defaults) {
+    if (event.type === expectedType && event.data) {
+        return { ...defaults, ...event.data };
+    }
+    return defaults;
+}
+/**
+ * Assert and get typed event data.
+ *
+ * Throws if the event type doesn't match. Use this when you're certain
+ * of the event type and want a clear error if assumptions are wrong.
+ *
+ * @example
+ * ```typescript
+ * // In a handler that only receives 'quit.confirmed' events
+ * const data = requireEventData(event, 'quit.confirmed');
+ * console.log(`Score: ${data.finalScore}/${data.maxScore}`);
+ * ```
+ */
+function requireEventData(event, expectedType) {
+    if (event.type !== expectedType) {
+        throw new Error(`Expected event type '${expectedType}', got '${event.type}'`);
+    }
+    return event.data;
+}
+/**
+ * Safely access a property from event data with type inference.
+ *
+ * Returns undefined if the event type doesn't match or the property
+ * doesn't exist.
+ *
+ * @example
+ * ```typescript
+ * const message = getEventProperty(event, 'query.invalid', 'message');
+ * // message is string | undefined
+ * ```
+ */
+function getEventProperty(event, expectedType, property) {
+    if (event.type === expectedType && event.data) {
+        return event.data[property];
+    }
+    return undefined;
+}
+/**
+ * Get event data as a generic record for untyped event access.
+ *
+ * Use this when working with events that aren't yet in the EventDataRegistry.
+ * Prefer using typed helpers (isEventType, getEventData) when the event
+ * type is known.
+ *
+ * @example
+ * ```typescript
+ * const data = getUntypedEventData(event);
+ * if (data.customField) {
+ *   console.log(data.customField);
+ * }
+ * ```
+ */
+function getUntypedEventData(event) {
+    if (event.data && typeof event.data === 'object') {
+        return event.data;
+    }
+    return {};
+}
+//# sourceMappingURL=event-helpers.js.map

package/dist/events/event-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-helpers.js","sourceRoot":"","sources":["../../src/events/event-helpers.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAsBH,kCAKC;AAcD,wCAEC;AAgBD,oCAQC;AAgBD,4DASC;AAeD,4CAUC;AAcD,4CAYC;AAiBD,kDAOC;AAlKD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,WAAW,CACzB,KAAqB,EACrB,IAAO;IAEP,OAAO,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,cAAc,CAAC,KAAqB,EAAE,MAAc;IAClE,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,YAAY,CAC1B,KAAqB,EACrB,YAAe;IAEf,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC,IAA4B,CAAC;IAC5C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,wBAAwB,CACtC,KAAqB,EACrB,YAAe,EACf,QAA8B;IAE9B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC9C,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAI,KAAK,CAAC,IAA6B,EAAE,CAAC;IAClE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,gBAAgB,CAC9B,KAAqB,EACrB,YAAe;IAEf,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,wBAAwB,YAAY,WAAW,KAAK,CAAC,IAAI,GAAG,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,IAA4B,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,gBAAgB,CAI9B,KAAqB,EACrB,YAAe,EACf,QAAW;IAEX,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC9C,OAAQ,KAAK,CAAC,IAA6B,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,mBAAmB,CACjC,KAAqB;IAErB,IAAI,KAAK,CAAC,IAAI,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC,IAA+B,CAAC;IAC/C,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/events/event-registry.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Event Data Registry - Central type definitions for all semantic events
+ *
+ * This module defines the mapping between event type strings and their
+ * corresponding data shapes. It serves as the single source of truth
+ * for event data types across the Sharpee platform.
+ *
+ * @see ADR-082 for the design rationale
+ *
+ * ## Extensibility
+ *
+ * Packages can extend this registry using TypeScript declaration merging:
+ *
+ * ```typescript
+ * declare module '@sharpee/core' {
+ *   interface EventDataRegistry {
+ *     'my.custom.event': MyCustomData;
+ *   }
+ * }
+ * ```
+ */
+import { EntityId } from '../types/entity';
+/**
+ * Registry mapping event type strings to their data shapes.
+ *
+ * This interface is designed to be extended via declaration merging
+ * by stdlib, stories, and other packages.
+ */
+export interface EventDataRegistry {
+    'query.pending': QueryPendingData;
+    'query.invalid': QueryInvalidData;
+    'query.response': QueryResponseData;
+    'message.success': MessageData;
+    'message.failure': MessageData;
+    'message.info': MessageData;
+    'message.warning': MessageData;
+    'message.debug': MessageData;
+    'game.initializing': EmptyData;
+    'game.initialized': GameInitializedData;
+    'game.starting': EmptyData;
+    'game.started': GameStartedData;
+    'game.ending': GameEndingData;
+    'game.ended': GameEndedData;
+    'game.won': GameEndedData;
+    'game.lost': GameEndedData;
+    'game.quit': EmptyData;
+    'game.aborted': EmptyData;
+    'platform.save_requested': SaveRequestedData;
+    'platform.save_completed': SaveCompletedData;
+    'platform.save_failed': SaveFailedData;
+    'platform.restore_requested': RestoreRequestedData;
+    'platform.restore_completed': RestoreCompletedData;
+    'platform.restore_failed': RestoreFailedData;
+    'platform.quit_requested': EmptyData;
+    'platform.quit_confirmed': QuitConfirmedData;
+    'platform.quit_cancelled': EmptyData;
+    'platform.restart_requested': EmptyData;
+    'platform.restart_completed': EmptyData;
+    'platform.restart_cancelled': EmptyData;
+    'turn.started': TurnData;
+    'turn.ended': TurnData;
+    'quit.confirmed': QuitConfirmedData;
+    'quit.cancelled': EmptyData;
+}
+/**
+ * Empty data for events that carry no payload.
+ */
+export interface EmptyData {
+}
+/**
+ * Standard message event data.
+ */
+export interface MessageData {
+    messageId: string;
+    params?: Record<string, unknown>;
+}
+export interface QueryPendingData {
+    query: {
+        id: string;
+        messageId: string;
+        messageParams?: Record<string, unknown>;
+        options?: string[];
+        validationType?: string;
+    };
+}
+export interface QueryInvalidData {
+    message?: string;
+    hint?: string;
+    queryId?: string;
+}
+export interface QueryResponseData {
+    queryId: string;
+    response: string | number | boolean;
+}
+export interface GameInitializedData {
+    storyId?: string;
+    storyTitle?: string;
+    storyVersion?: string;
+}
+export interface GameStartedData {
+    storyId?: string;
+    storyTitle?: string;
+    initialLocation?: EntityId;
+}
+export interface GameEndingData {
+    reason?: string;
+}
+export interface GameEndedData {
+    finalScore?: number;
+    maxScore?: number;
+    moves?: number;
+    reason?: string;
+    rank?: string;
+}
+export interface SaveRequestedData {
+    slotName?: string;
+}
+export interface SaveCompletedData {
+    slotName?: string;
+    timestamp?: number;
+}
+export interface SaveFailedData {
+    slotName?: string;
+    error?: string;
+}
+export interface RestoreRequestedData {
+    slotName?: string;
+}
+export interface RestoreCompletedData {
+    slotName?: string;
+    timestamp?: number;
+}
+export interface RestoreFailedData {
+    slotName?: string;
+    error?: string;
+}
+export interface QuitConfirmedData {
+    messageId?: string;
+    finalScore?: number;
+    maxScore?: number;
+    moves?: number;
+}
+export interface TurnData {
+    turn: number;
+}
+/**
+ * All known event type strings.
+ */
+export type EventType = keyof EventDataRegistry;
+/**
+ * Get the data type for a specific event type.
+ */
+export type EventDataFor<T extends EventType> = EventDataRegistry[T];
+//# sourceMappingURL=event-registry.d.ts.map

package/dist/events/event-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-registry.d.ts","sourceRoot":"","sources":["../../src/events/event-registry.ts"],"names":[],"mappings":"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"}

package/dist/events/event-registry.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Event Data Registry - Central type definitions for all semantic events
+ *
+ * This module defines the mapping between event type strings and their
+ * corresponding data shapes. It serves as the single source of truth
+ * for event data types across the Sharpee platform.
+ *
+ * @see ADR-082 for the design rationale
+ *
+ * ## Extensibility
+ *
+ * Packages can extend this registry using TypeScript declaration merging:
+ *
+ * ```typescript
+ * declare module '@sharpee/core' {
+ *   interface EventDataRegistry {
+ *     'my.custom.event': MyCustomData;
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=event-registry.js.map

package/dist/events/event-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-registry.js","sourceRoot":"","sources":["../../src/events/event-registry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/events/event-source.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Generic event source infrastructure for the narrative engine.
+ * This provides a simple pub/sub mechanism for any type of event.
+ */
+/**
+ * Generic event source interface for pub/sub pattern
+ */
+export interface IGenericEventSource<T> {
+    /**
+     * Emit an event to all subscribers
+     */
+    emit(event: T): void;
+    /**
+     * Subscribe to events
+     * @returns Unsubscribe function
+     */
+    subscribe(handler: (event: T) => void): () => void;
+}
+/**
+ * Simple synchronous implementation of EventSource
+ */
+export declare class SimpleEventSource<T> implements IGenericEventSource<T> {
+    private handlers;
+    emit(event: T): void;
+    subscribe(handler: (event: T) => void): () => void;
+    /**
+     * Get the current number of subscribers
+     */
+    get subscriberCount(): number;
+    /**
+     * Remove all subscribers
+     */
+    clear(): void;
+}
+/**
+ * Create a new event source for a specific event type
+ */
+export declare function createEventSource<T>(): IGenericEventSource<T>;
+//# sourceMappingURL=event-source.d.ts.map

package/dist/events/event-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-source.d.ts","sourceRoot":"","sources":["../../src/events/event-source.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACpD;AAED;;GAEG;AACH,qBAAa,iBAAiB,CAAC,CAAC,CAAE,YAAW,mBAAmB,CAAC,CAAC,CAAC;IACjE,OAAO,CAAC,QAAQ,CAA8B;IAE9C,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAapB,SAAS,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAYlD;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,KAAK,mBAAmB,CAAC,CAAC,CAAC,CAE7D"}