@sharpee/engine 3.0.0 → 3.3.0

package/game-engine.js

@@ -10,24 +10,25 @@ exports.splitChainedInput = splitChainedInput;
 const world_model_1 = require("@sharpee/world-model");
 const event_processor_1 = require("@sharpee/event-processor");
 const stdlib_1 = require("@sharpee/stdlib");
-const prose_pipeline_1 = require("./prose-pipeline");
+const index_js_1 = require("./prose-pipeline/index.js");
 const text_blocks_1 = require("@sharpee/text-blocks");
 const channel_service_1 = require("@sharpee/channel-service");
 const core_1 = require("@sharpee/core");
 const plugins_1 = require("@sharpee/plugins");
-const scene_evaluation_plugin_1 = require("./scene-evaluation-plugin");
-const types_1 = require("./types");
-const narrative_1 = require("./narrative");
-const snippet_validation_1 = require("./snippet-validation");
-const command_executor_1 = require("./command-executor");
-const action_context_factory_1 = require("./action-context-factory");
-const sound_1 = require("./sound");
-const turn_event_processor_1 = require("./turn-event-processor");
-const parser_interface_1 = require("./parser-interface");
-const language_provider_interface_1 = require("./language-provider-interface");
-const vocabulary_manager_1 = require("./vocabulary-manager");
-const save_restore_service_1 = require("./save-restore-service");
-const turn_event_processor_2 = require("./turn-event-processor");
+const scene_evaluation_plugin_js_1 = require("./scene-evaluation-plugin.js");
+const types_js_1 = require("./types.js");
+const index_js_2 = require("./narrative/index.js");
+const snippet_validation_js_1 = require("./snippet-validation.js");
+const combatant_health_validation_js_1 = require("./combatant-health-validation.js");
+const command_executor_js_1 = require("./command-executor.js");
+const action_context_factory_js_1 = require("./action-context-factory.js");
+const index_js_3 = require("./sound/index.js");
+const turn_event_processor_js_1 = require("./turn-event-processor.js");
+const parser_interface_js_1 = require("./parser-interface.js");
+const language_provider_interface_js_1 = require("./language-provider-interface.js");
+const vocabulary_manager_js_1 = require("./vocabulary-manager.js");
+const save_restore_service_js_1 = require("./save-restore-service.js");
+const turn_event_processor_js_2 = require("./turn-event-processor.js");
 /**
  * Conservative client-capability profile used when `start()` is called
  * without an explicit `capabilities` option. Mirrors a CLI / text-only
@@ -96,8 +97,16 @@ class GameEngine {
      * room for future extension seams (e.g., custom propagate injection
      * via `setSoundDispatcher` in tests).
      */
-    soundDispatcher = new sound_1.SoundDispatcher();
+    soundDispatcher = new index_js_3.SoundDispatcher();
     random;
+    /**
+     * Dedicated action RNG stream (ADR-231 D6), exposed to actions as
+     * `ActionContext.random`. A separate instance from `random` (the
+     * turn-plugin stream) so plugin draws can never shift action rolls;
+     * its seed rides the save blob (`IEngineState.actionRngSeed`) so
+     * post-restore action outcomes replay deterministically.
+     */
+    actionRandom;
     narrativeSettings;
     // Alternate input mode handlers (ADR-137)
     inputModeHandlers = new Map();
@@ -187,29 +196,37 @@ class GameEngine {
             });
         });
         this.pluginRegistry = new plugins_1.PluginRegistry();
-        this.pluginRegistry.register(new scene_evaluation_plugin_1.SceneEvaluationPlugin());
+        this.pluginRegistry.register(new scene_evaluation_plugin_js_1.SceneEvaluationPlugin());
         this.random = (0, core_1.createSeededRandom)();
-        this.narrativeSettings = (0, narrative_1.buildNarrativeSettings)(); // Default: 2nd person
+        // ADR-231 D6: dedicated action stream — unseeded construction gives a
+        // time-based initial seed (same pattern as `random` above)
+        this.actionRandom = (0, core_1.createSeededRandom)();
+        this.narrativeSettings = (0, index_js_2.buildNarrativeSettings)(); // Default: 2nd person
         // Initialize extracted services (Phase 4 remediation)
-        this.vocabularyManager = (0, vocabulary_manager_1.createVocabularyManager)();
-        this.saveRestoreService = (0, save_restore_service_1.createSaveRestoreService)({
+        this.vocabularyManager = (0, vocabulary_manager_js_1.createVocabularyManager)();
+        this.saveRestoreService = (0, save_restore_service_js_1.createSaveRestoreService)({
             maxSnapshots: this.config.maxUndoSnapshots ?? 10
         });
-        this.turnEventProcessor = (0, turn_event_processor_2.createTurnEventProcessor)(this.perceptionService);
+        this.turnEventProcessor = (0, turn_event_processor_js_2.createTurnEventProcessor)(this.perceptionService);
         // Set provided dependencies
         this.languageProvider = options.language;
         this.parser = options.parser;
-        this.textService = new prose_pipeline_1.ProsePipeline(this.languageProvider, this.world);
+        this.textService = new index_js_1.ProsePipeline(this.languageProvider, this.world);
         // Update action registry with language provider
         this.actionRegistry.setLanguageProvider(this.languageProvider);
         // Wire parser with platform events if supported
-        if (this.parser && (0, parser_interface_1.hasPlatformEventEmitter)(this.parser)) {
+        if (this.parser && (0, parser_interface_js_1.hasPlatformEventEmitter)(this.parser)) {
             this.parser.setPlatformEventEmitter((event) => {
                 this.platformEvents.addEvent(event);
             });
         }
         // Create command executor with dependencies
-        this.commandExecutor = (0, command_executor_1.createCommandExecutor)(this.world, this.actionRegistry, this.eventProcessor, this.parser, this.systemEventSource);
+        this.commandExecutor = (0, command_executor_js_1.createCommandExecutor)(this.world, this.actionRegistry, this.eventProcessor, this.parser, this.systemEventSource, this.actionRandom);
+        // ADR-224: auto-register the deadly-room death transformer so every story
+        // (TS or Chord) gets the deadly-room verb-allowlist / probabilistic hazard for
+        // free — no story wiring needed. It early-returns when the player's room has no
+        // DeadlyRoomTrait, and uses the engine's seeded RNG for the `chance` variant.
+        this.commandExecutor.registerParsedCommandTransformer((0, stdlib_1.createDeadlyRoomTransformer)(this.random));
         // Query handling is now managed by the platform layer
         // Platform owns the QueryManager and handles all queries
         // Note: game.initialized event is emitted in start() to avoid race condition
@@ -224,7 +241,7 @@ class GameEngine {
         this.emitGameEvent(loadingEvent);
         this.story = story;
         // Build narrative settings from story config (ADR-089)
-        this.narrativeSettings = (0, narrative_1.buildNarrativeSettings)(story.config.narrative);
+        this.narrativeSettings = (0, index_js_2.buildNarrativeSettings)(story.config.narrative);
         // Create player first so initializeWorld() can place them
         const newPlayer = story.createPlayer(this.world);
         this.context.player = newPlayer;
@@ -248,7 +265,9 @@ class GameEngine {
         story.initializeWorld(this.world);
         // ADR-209 AC-5: fail load synchronously (naming room and marker) if any
         // snippet-bearing room's description carries an unbound {snippet:name}.
-        (0, snippet_validation_1.validateRoomSnippets)(this.world);
+        (0, snippet_validation_js_1.validateRoomSnippets)(this.world);
+        // ADR-226 AC-7: every combatant must carry the HealthTrait combat operates on.
+        (0, combatant_health_validation_js_1.validateCombatantHealth)(this.world);
         // Configure language provider with narrative settings (ADR-089)
         this.configureLanguageProviderNarrative(newPlayer);
         // Update metadata
@@ -628,6 +647,30 @@ class GameEngine {
         });
         this.emit('channel:packet', packet, turn);
     }
+    /**
+     * Resume a stopped engine without touching world state.
+     *
+     * The post-mortem revival seam: after `stop('defeat')`, a harness (or a
+     * story resurrection policy) that has restored the world to a live-player
+     * snapshot — e.g. the transcript-tester's RETRY block via
+     * `world.loadJSON()` — needs turn execution back without any world
+     * teardown (a full reboot would clear the world it just restored).
+     * Flips `running` back on; emits nothing, rebuilds nothing.
+     *
+     * No-op when already running. Throws if the engine was never started
+     * (no command executor) — resuming presumes a completed `start()`.
+     */
+    resume() {
+        if (this.running) {
+            return;
+        }
+        // The channel service exists only once start() has completed — resuming
+        // an engine that never started would bypass the whole bootstrap order.
+        if (!this.channelService) {
+            throw new Error('Engine must have been started before it can resume');
+        }
+        this.running = true;
+    }
     /**
      * Stop the game engine
      */
@@ -674,41 +717,22 @@ class GameEngine {
         this.emit('game:over', this.context);
     }
     /**
-     * Restart the game from scratch.
+     * Build the restart acknowledgment event (ADR-248).
      *
-     * Clears the world, resets engine state, and re-initializes the story.
-     * Called from both processMetaPlatformOperation and processPlatformOperations.
+     * On confirmed restart the engine does NOT rebuild in place — it renders
+     * this acknowledgment ("The story restarts.") in the final packet, then
+     * stops with reason 'restart'; the client owns the reboot via its own
+     * boot path. No pre-emptive restart_completed(true) is emitted: the new
+     * boot's opening banner is the success signal.
      */
-    async restartGame() {
-        if (!this.story)
-            return;
-        // Stop engine if running
-        if (this.running) {
-            this.stop();
-        }
-        // Reset pronoun context
-        if (this.parser && (0, parser_interface_1.hasPronounContext)(this.parser)) {
-            this.parser.resetPronounContext();
-        }
-        // Clear world state (entities, spatial index, relationships, etc.)
-        this.world.clear();
-        // Reset engine context
-        this.context.currentTurn = 1;
-        this.context.history = [];
-        this.context.metadata.started = new Date();
-        this.context.metadata.lastPlayed = new Date();
-        // Clear engine bookkeeping
-        this.turnEvents.clear();
-        this.pendingPlatformOps = [];
-        this.soundBuffer.length = 0;
-        this.saveRestoreService.clearUndoSnapshots();
-        this.hasEmittedInitialized = false;
-        // Clear plugin registry so story can re-register plugins
-        this.pluginRegistry.clear();
-        // Re-initialize the story (creates entities, player, custom actions, etc.)
-        this.setStory(this.story);
-        // Start the engine (emits game.initialized + game.started)
-        this.start();
+    createRestartAckEvent() {
+        return {
+            id: `restart_ack_${Date.now()}`,
+            type: 'game.message',
+            timestamp: Date.now(),
+            data: { messageId: 'if.action.restarting.game_restarting' },
+            entities: {}
+        };
     }
     /**
      * Execute a turn
@@ -726,7 +750,7 @@ class GameEngine {
         // the line, matching player expectations from Inform-style interpreters.
         // Skipped while an alternate input mode is active (ADR-137) — mode
         // handlers own the raw line, punctuation and all.
-        if (typeof input === 'string' && !this.world.getStateValue(types_1.INPUT_MODE_STATE_KEY)) {
+        if (typeof input === 'string' && !this.world.getStateValue(types_js_1.INPUT_MODE_STATE_KEY)) {
             const statements = splitChainedInput(input);
             if (statements.length > 1) {
                 let result;
@@ -785,7 +809,7 @@ class GameEngine {
         }
         this.emit('turn:start', turn, input);
         // Check for alternate input mode (ADR-137)
-        const activeModeId = this.world.getStateValue(types_1.INPUT_MODE_STATE_KEY);
+        const activeModeId = this.world.getStateValue(types_js_1.INPUT_MODE_STATE_KEY);
         if (activeModeId) {
             const handler = this.inputModeHandlers.get(activeModeId);
             if (handler) {
@@ -800,7 +824,7 @@ class GameEngine {
             if (this.parser) {
                 // Set world context for parser
                 const player = this.world.getPlayer();
-                if (player && (0, parser_interface_1.hasWorldContext)(this.parser)) {
+                if (player && (0, parser_interface_js_1.hasWorldContext)(this.parser)) {
                     const playerLocation = this.world.getLocation(player.id) || '';
                     this.parser.setWorldContext(this.world, player.id, playerLocation);
                 }
@@ -843,7 +867,7 @@ class GameEngine {
                 locationId: playerLocation
             };
             // Store events for this turn (process through enrichment pipeline)
-            let semanticEvents = result.events.map(e => (0, turn_event_processor_1.processEvent)(e, enrichmentContext));
+            let semanticEvents = result.events.map(e => (0, turn_event_processor_js_1.processEvent)(e, enrichmentContext));
             // Apply perception filtering if service is configured
             // This transforms events based on what the player can perceive
             if (this.perceptionService) {
@@ -865,7 +889,7 @@ class GameEngine {
             if (result.success) {
                 this.updateCommandHistory(result, input, turn);
                 // Update pronoun context for "it"/"them"/"him"/"her" resolution (ADR-089)
-                if (this.parser && (0, parser_interface_1.hasPronounContext)(this.parser) && result.validatedCommand) {
+                if (this.parser && (0, parser_interface_js_1.hasPronounContext)(this.parser) && result.validatedCommand) {
                     this.parser.updatePronounContext(result.validatedCommand, turn);
                 }
             }
@@ -900,6 +924,16 @@ class GameEngine {
                 const playerLocation = this.world.getLocation(this.context.player.id);
                 // Plugin tick loop (ADR-120)
                 // Plugins run in priority order (NPC at 100, state machines at 75, scheduler at 50)
+                //
+                // actionResult.success must reflect GENUINE action success (Phase 7):
+                // result.success only checks for action.error events, but modern
+                // blocked() paths reuse the primary event type with blocked:true /
+                // failed:true — a refused action would otherwise report success and
+                // (e.g.) advance state-machine transitions it never earned.
+                const actionRefused = semanticEvents.some(e => {
+                    const data = e.data;
+                    return data?.blocked === true || data?.failed === true;
+                });
                 const pluginContext = {
                     world: this.world,
                     turn,
@@ -908,7 +942,7 @@ class GameEngine {
                     random: this.random,
                     actionResult: {
                         actionId: result.actionId || '',
-                        success: result.success,
+                        success: result.success && !actionRefused,
                         targetId: result.validatedCommand?.directObject?.entity?.id,
                     },
                     actionEvents: semanticEvents,
@@ -979,6 +1013,13 @@ class GameEngine {
                 // channels still re-emit.
                 this.emitChannelPacket(turnEvents, blocks, turn);
             }
+            // Detect a canonical player-death event (ADR-224) *before* the turn's
+            // events are cleared below. The death may have been emitted this turn by
+            // the action, an interceptor, or a scheduler daemon — all have landed in
+            // this turn's event stream by now, and story policy (event handlers in the
+            // executor + state-machine plugins in the tick loop above) has already had
+            // its "first crack" to veto by resetting the player's HealthTrait.
+            const deathCause = this.playerDeathCauseThisTurn(turn);
             // Clear turn events after processing to prevent accumulation on same turn (meta commands)
             this.turnEvents.set(turn, []);
             // Emit completion
@@ -988,6 +1029,14 @@ class GameEngine {
                 this.stop('victory', victoryDetails);
                 return result;
             }
+            // Route a still-dead player to game.lost. Only if the player's *derived*
+            // life-state is still dead do we end the game — the re-check of live state,
+            // not the event's `terminal` flag, is the engine's final word (ADR-224
+            // Q-2, AC-3). A story reincarnation policy that cleared `dead` above wins.
+            if (deathCause !== undefined && this.isPlayerDead()) {
+                this.stop('defeat', { reason: 'You have died.', cause: deathCause });
+                return result;
+            }
             // Check for game over via story.isComplete()
             if (this.isGameOver()) {
                 // Check if it's a victory (story completed successfully)
@@ -1078,7 +1127,7 @@ class GameEngine {
             }
             // Create action context for meta-command execution
             const scopeResolver = (0, stdlib_1.createScopeResolver)(this.world);
-            const actionContext = (0, action_context_factory_1.createActionContext)(this.world, this.context, command, action, scopeResolver);
+            const actionContext = (0, action_context_factory_js_1.createActionContext)(this.world, this.context, command, action, scopeResolver, undefined, this.actionRandom);
             // Run action's four-phase pattern
             const actionValidation = action.validate(actionContext);
             let actionEvents;
@@ -1244,20 +1293,19 @@ class GameEngine {
             }
             case core_1.PlatformEventType.RESTART_REQUESTED: {
                 const context = platformOp.payload.context;
-                if (this.saveRestoreHooks?.onRestartRequested) {
-                    const shouldRestart = await this.saveRestoreHooks.onRestartRequested(context);
-                    if (shouldRestart) {
-                        await this.restartGame();
-                        completionEvents.push((0, core_1.createRestartCompletedEvent)(true));
-                    }
-                    else {
-                        completionEvents.push((0, core_1.createRestartCompletedEvent)(false));
-                    }
+                const shouldRestart = this.saveRestoreHooks?.onRestartRequested
+                    ? await this.saveRestoreHooks.onRestartRequested(context)
+                    : true; // No restart hook — auto-confirm
+                if (shouldRestart) {
+                    // ADR-248: ack in the final packet, then stop('restart'). The
+                    // client's hook is the reboot trigger; the stop reason is
+                    // bookkeeping. No restart_completed(true) — the reboot's opening
+                    // banner is the success signal.
+                    completionEvents.push(this.createRestartAckEvent());
+                    this.stop('restart');
                 }
                 else {
-                    // No restart hook — auto-confirm
-                    await this.restartGame();
-                    completionEvents.push((0, core_1.createRestartCompletedEvent)(true));
+                    completionEvents.push((0, core_1.createRestartCompletedEvent)(false));
                 }
                 break;
             }
@@ -1383,7 +1431,7 @@ class GameEngine {
      */
     configureLanguageProviderNarrative(player) {
         // Check if language provider supports narrative settings
-        if (!this.languageProvider || !(0, language_provider_interface_1.hasNarrativeSettings)(this.languageProvider)) {
+        if (!this.languageProvider || !(0, language_provider_interface_js_1.hasNarrativeSettings)(this.languageProvider)) {
             return;
         }
         // Build narrative context for language provider
@@ -1424,11 +1472,11 @@ class GameEngine {
             throw new Error(`Cannot sync player state: entity '${newPlayerId}' not found`);
         }
         this.context.player = newPlayer;
-        if (this.parser && (0, parser_interface_1.hasWorldContext)(this.parser)) {
+        if (this.parser && (0, parser_interface_js_1.hasWorldContext)(this.parser)) {
             const playerLocation = this.world.getLocation(newPlayerId) || '';
             this.parser.setWorldContext(this.world, newPlayerId, playerLocation);
         }
-        if (this.parser && (0, parser_interface_1.hasPronounContext)(this.parser)) {
+        if (this.parser && (0, parser_interface_js_1.hasPronounContext)(this.parser)) {
             this.parser.resetPronounContext();
         }
         this.updateScopeVocabulary();
@@ -1440,6 +1488,23 @@ class GameEngine {
     getPluginRegistry() {
         return this.pluginRegistry;
     }
+    /**
+     * The negotiated client capabilities for this session (ADR-216): the
+     * `client has <capability>` predicate reads these live, and channel
+     * gating uses the same flags at manifest time. Text-only before
+     * `start({ capabilities })` runs or when none were negotiated.
+     */
+    getClientCapabilities() {
+        return this.clientCapabilities ?? exports.DEFAULT_TEXT_CAPABILITIES;
+    }
+    /**
+     * Get the dedicated action RNG stream (ADR-231 D6). Part of the
+     * ISaveRestoreStateProvider contract — the save service persists this
+     * stream's seed and the restore path re-seeds it.
+     */
+    getActionRandom() {
+        return this.actionRandom;
+    }
     /**
      * Get event processor for handler registration (ADR-075)
      */
@@ -1675,7 +1740,7 @@ class GameEngine {
             playerId: this.context.player.id,
             locationId: playerLocation ?? undefined
         };
-        let processed = events.map(e => (0, turn_event_processor_1.processEvent)(e, enrichmentContext));
+        let processed = events.map(e => (0, turn_event_processor_js_1.processEvent)(e, enrichmentContext));
         if (this.perceptionService) {
             processed = this.perceptionService.filterEvents(processed, this.context.player, this.world);
         }
@@ -1986,10 +2051,14 @@ class GameEngine {
                             shouldRestart = await this.saveRestoreHooks.onRestartRequested(context);
                         }
                         if (shouldRestart) {
-                            const completionEvent = (0, core_1.createRestartCompletedEvent)(true);
-                            this.eventSource.emit(completionEvent);
-                            this.emit('event', completionEvent);
-                            await this.restartGame();
+                            // ADR-248: ack in the final packet, then stop('restart').
+                            // No restart_completed(true) — the client reboots and its
+                            // opening banner is the success signal.
+                            const ackEvent = this.createRestartAckEvent();
+                            this.eventSource.emit(ackEvent);
+                            this.turnEvents.get(currentTurn)?.push(ackEvent);
+                            this.emit('event', ackEvent);
+                            this.stop('restart');
                         }
                         else {
                             const cancelEvent = (0, core_1.createRestartCompletedEvent)(false);
@@ -2118,6 +2187,37 @@ class GameEngine {
         // Default: game never ends
         return false;
     }
+    /**
+     * The `cause` of a canonical player-death event (ADR-224) emitted during the
+     * given turn, or `undefined` if the player did not die this turn. Scans the
+     * turn's accumulated events, so it sees deaths from the action, interceptors,
+     * and scheduler daemons alike. When several fire in one turn (rare), the first
+     * is authoritative — `killPlayer` is idempotent, so later calls emit nothing.
+     * @param turn the turn number whose events to scan
+     */
+    playerDeathCauseThisTurn(turn) {
+        const events = this.turnEvents.get(turn) || [];
+        for (const event of events) {
+            if (event.type === stdlib_1.PLAYER_DIED_EVENT) {
+                const cause = event.data?.cause;
+                return typeof cause === 'string' ? cause : 'unknown';
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Whether the player is currently dead by their derived `HealthTrait` state
+     * (ADR-226/ADR-224). A player with no `HealthTrait` is alive by default (the
+     * opt-in rule) — `killPlayer` lazily attaches one, so a real death always has a
+     * trait to read. This is the engine's "final word" after story policy has run.
+     */
+    isPlayerDead() {
+        const player = this.context.player;
+        if (!player)
+            return false;
+        const health = player.get(world_model_1.TraitType.HEALTH);
+        return health ? !world_model_1.HealthBehavior.isAlive(health) : false;
+    }
     /**
      * Add event listener
      */