@sharpee/stdlib 0.9.107 → 0.9.109

package/dist/validation/command-validator.js

@@ -0,0 +1,1214 @@
+"use strict";
+/**
+ * Command Validator
+ *
+ * Validates parsed commands against the world model
+ * Resolves entities and checks preconditions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandValidator = void 0;
+const world_model_1 = require("@sharpee/world-model");
+const types_1 = require("../scope/types");
+const scope_resolver_1 = require("../scope/scope-resolver");
+/**
+ * Enhanced command validator with full entity resolution
+ */
+class CommandValidator {
+    world;
+    actionRegistry;
+    scopeResolver;
+    systemEvents;
+    /** Current action ID being validated (for disambiguation scoring) */
+    currentActionId;
+    constructor(world, actionRegistry, scopeResolver) {
+        this.world = world;
+        this.actionRegistry = actionRegistry;
+        this.scopeResolver = scopeResolver || new scope_resolver_1.StandardScopeResolver(world);
+    }
+    /**
+     * Set system event source for debug events
+     */
+    setSystemEventSource(eventSource) {
+        this.systemEvents = eventSource;
+    }
+    /**
+     * Validate parsed command against world state
+     */
+    validate(command) {
+        const startTime = Date.now();
+        const warnings = [];
+        // 1. Validate action exists
+        // First try direct lookup by action ID
+        let actionHandler = this.actionRegistry.get(command.action);
+        // If not found, try to find by pattern (verb)
+        if (!actionHandler) {
+            const verb = command.structure?.verb?.text || command.action;
+            const matches = this.actionRegistry.findByPattern(verb);
+            if (matches.length > 0) {
+                actionHandler = matches[0]; // Take the highest priority match
+            }
+        }
+        if (!actionHandler) {
+            return {
+                success: false,
+                error: {
+                    type: 'VALIDATION_ERROR',
+                    code: 'ACTION_NOT_AVAILABLE',
+                    parsed: command,
+                    details: { action: command.action }
+                }
+            };
+        }
+        // Store current action ID for disambiguation scoring
+        this.currentActionId = actionHandler.id;
+        // 2. Resolve direct object if present in parsed command
+        let directObject;
+        if (command.structure?.directObject) {
+            // ADR-080: Multi-object commands ("get all", "drop all but sword")
+            // Skip single-entity resolution - let the action handle expansion via expandMultiObject()
+            const nounPhrase = command.structure.directObject;
+            if (nounPhrase.isAll || nounPhrase.isList) {
+                // Leave directObject undefined - action will use isMultiObjectCommand()
+                // and expandMultiObject() to handle multiple entities
+                directObject = undefined;
+            }
+            else {
+                // Normal single-entity resolution
+                const metadata = this.getActionMetadata(actionHandler);
+                const scope = metadata.directObjectScope || types_1.ScopeLevel.VISIBLE;
+                const resolved = this.resolveEntity(nounPhrase, 'direct', scope, command);
+                if (!resolved.success) {
+                    return resolved;
+                }
+                directObject = resolved.value;
+            }
+        }
+        // If no direct object in parsed command, that's fine - let the action decide if it needs one
+        // 3. Resolve indirect object if present in parsed command
+        let indirectObject;
+        if (command.structure?.indirectObject) {
+            const metadata = this.getActionMetadata(actionHandler);
+            const scope = metadata.indirectObjectScope || types_1.ScopeLevel.VISIBLE;
+            const resolved = this.resolveEntity(command.structure.indirectObject, 'indirect', scope, command);
+            if (!resolved.success) {
+                return resolved;
+            }
+            indirectObject = resolved.value;
+        }
+        // 3b. Resolve instrument if present in parsed command (ADR-080)
+        // Instruments are tools/weapons marked with .instrument() in grammar patterns
+        let instrument;
+        if (command.instrument) {
+            // Instruments are typically carried or reachable
+            const resolved = this.resolveEntity(command.instrument, 'instrument', types_1.ScopeLevel.REACHABLE, command);
+            if (!resolved.success) {
+                return resolved;
+            }
+            instrument = resolved.value;
+        }
+        // 4. Check scope constraints based on action metadata
+        const metadata = this.getActionMetadata(actionHandler);
+        // Check direct object scope
+        if (directObject && metadata.directObjectScope) {
+            const scopeCheck = this.checkEntityScope(directObject.entity, metadata.directObjectScope, directObject.parsed.text);
+            if (!scopeCheck.success) {
+                return {
+                    success: false,
+                    error: {
+                        type: 'VALIDATION_ERROR',
+                        code: 'ENTITY_NOT_VISIBLE',
+                        parsed: command,
+                        details: {
+                            entity: directObject.entity.id,
+                            entityName: directObject.parsed.text,
+                            scopeCode: scopeCheck.code
+                        }
+                    }
+                };
+            }
+        }
+        // Check indirect object scope
+        if (indirectObject && metadata.indirectObjectScope) {
+            const scopeCheck = this.checkEntityScope(indirectObject.entity, metadata.indirectObjectScope, indirectObject.parsed.text);
+            if (!scopeCheck.success) {
+                return {
+                    success: false,
+                    error: {
+                        type: 'VALIDATION_ERROR',
+                        code: 'ENTITY_NOT_VISIBLE',
+                        parsed: command,
+                        details: {
+                            entity: indirectObject.entity.id,
+                            entityName: indirectObject.parsed.text,
+                            scopeCode: scopeCheck.code
+                        }
+                    }
+                };
+            }
+        }
+        // 5. Check action-specific preconditions
+        const preconditionCheck = this.checkActionPreconditions(actionHandler, directObject?.entity, indirectObject?.entity);
+        if (!preconditionCheck.success) {
+            return {
+                success: false,
+                error: {
+                    type: 'VALIDATION_ERROR',
+                    code: 'PRECONDITION_FAILED',
+                    parsed: command,
+                    details: preconditionCheck.details
+                }
+            };
+        }
+        // Success - build validated command with scope info
+        const validationTime = Date.now() - startTime;
+        // Build scope info for resolved entities
+        const scopeInfo = {};
+        if (directObject) {
+            const player = this.world.getPlayer();
+            const entityScope = this.scopeResolver.getScope(player, directObject.entity);
+            const perceivedBy = this.getPerceivedSenses(player, directObject.entity);
+            scopeInfo.directObject = {
+                level: entityScope,
+                perceivedBy
+            };
+        }
+        if (indirectObject) {
+            const player = this.world.getPlayer();
+            const entityScope = this.scopeResolver.getScope(player, indirectObject.entity);
+            const perceivedBy = this.getPerceivedSenses(player, indirectObject.entity);
+            scopeInfo.indirectObject = {
+                level: entityScope,
+                perceivedBy
+            };
+        }
+        if (instrument) {
+            const player = this.world.getPlayer();
+            const entityScope = this.scopeResolver.getScope(player, instrument.entity);
+            const perceivedBy = this.getPerceivedSenses(player, instrument.entity);
+            scopeInfo.instrument = {
+                level: entityScope,
+                perceivedBy
+            };
+        }
+        const validatedCommand = {
+            parsed: command,
+            actionId: actionHandler.id,
+            directObject,
+            indirectObject,
+            instrument,
+            metadata: {
+                validationTime,
+                warnings: warnings.length > 0 ? warnings : undefined
+            },
+            ...(Object.keys(scopeInfo).length > 0 && { scopeInfo })
+        };
+        return {
+            success: true,
+            value: validatedCommand
+        };
+    }
+    /**
+     * Re-validate a command with explicit entity selections
+     * Used after AMBIGUOUS_ENTITY error when user selects from disambiguation choices
+     */
+    resolveWithSelection(command, selections) {
+        const startTime = Date.now();
+        const warnings = [];
+        // 1. Validate action exists
+        let actionHandler = this.actionRegistry.get(command.action);
+        if (!actionHandler) {
+            const verb = command.structure?.verb?.text || command.action;
+            const matches = this.actionRegistry.findByPattern(verb);
+            if (matches.length > 0) {
+                actionHandler = matches[0];
+            }
+        }
+        if (!actionHandler) {
+            return {
+                success: false,
+                error: {
+                    type: 'VALIDATION_ERROR',
+                    code: 'ACTION_NOT_AVAILABLE',
+                    parsed: command,
+                    details: { action: command.action }
+                }
+            };
+        }
+        this.currentActionId = actionHandler.id;
+        // 2. Resolve direct object - use selection if provided
+        let directObject;
+        if (command.structure?.directObject) {
+            const nounPhrase = command.structure.directObject;
+            // ADR-080: Multi-object commands bypass resolution
+            if (nounPhrase.isAll || nounPhrase.isList) {
+                directObject = undefined;
+            }
+            else if (selections.directObject) {
+                // Use explicit selection
+                const entity = this.world.getEntity(selections.directObject);
+                if (!entity) {
+                    return {
+                        success: false,
+                        error: {
+                            type: 'VALIDATION_ERROR',
+                            code: 'ENTITY_NOT_FOUND',
+                            parsed: command,
+                            details: {
+                                slot: 'directObject',
+                                selectedId: selections.directObject,
+                                reason: 'Selected entity no longer exists'
+                            }
+                        }
+                    };
+                }
+                directObject = {
+                    entity,
+                    parsed: nounPhrase
+                };
+            }
+            else {
+                // Normal resolution
+                const metadata = this.getActionMetadata(actionHandler);
+                const scope = metadata.directObjectScope || types_1.ScopeLevel.VISIBLE;
+                const resolved = this.resolveEntity(nounPhrase, 'direct', scope, command);
+                if (!resolved.success) {
+                    return resolved;
+                }
+                directObject = resolved.value;
+            }
+        }
+        // 3. Resolve indirect object - use selection if provided
+        let indirectObject;
+        if (command.structure?.indirectObject) {
+            if (selections.indirectObject) {
+                const entity = this.world.getEntity(selections.indirectObject);
+                if (!entity) {
+                    return {
+                        success: false,
+                        error: {
+                            type: 'VALIDATION_ERROR',
+                            code: 'ENTITY_NOT_FOUND',
+                            parsed: command,
+                            details: {
+                                slot: 'indirectObject',
+                                selectedId: selections.indirectObject,
+                                reason: 'Selected entity no longer exists'
+                            }
+                        }
+                    };
+                }
+                indirectObject = {
+                    entity,
+                    parsed: command.structure.indirectObject
+                };
+            }
+            else {
+                const metadata = this.getActionMetadata(actionHandler);
+                const scope = metadata.indirectObjectScope || types_1.ScopeLevel.VISIBLE;
+                const resolved = this.resolveEntity(command.structure.indirectObject, 'indirect', scope, command);
+                if (!resolved.success) {
+                    return resolved;
+                }
+                indirectObject = resolved.value;
+            }
+        }
+        // 3b. Resolve instrument - use selection if provided
+        let instrument;
+        if (command.instrument) {
+            if (selections.instrument) {
+                const entity = this.world.getEntity(selections.instrument);
+                if (!entity) {
+                    return {
+                        success: false,
+                        error: {
+                            type: 'VALIDATION_ERROR',
+                            code: 'ENTITY_NOT_FOUND',
+                            parsed: command,
+                            details: {
+                                slot: 'instrument',
+                                selectedId: selections.instrument,
+                                reason: 'Selected entity no longer exists'
+                            }
+                        }
+                    };
+                }
+                instrument = {
+                    entity,
+                    parsed: command.instrument
+                };
+            }
+            else {
+                const resolved = this.resolveEntity(command.instrument, 'instrument', types_1.ScopeLevel.REACHABLE, command);
+                if (!resolved.success) {
+                    return resolved;
+                }
+                instrument = resolved.value;
+            }
+        }
+        // 4. Check scope constraints based on action metadata
+        const metadata = this.getActionMetadata(actionHandler);
+        if (directObject && metadata.directObjectScope) {
+            const scopeCheck = this.checkEntityScope(directObject.entity, metadata.directObjectScope, directObject.parsed.text);
+            if (!scopeCheck.success) {
+                return {
+                    success: false,
+                    error: {
+                        type: 'VALIDATION_ERROR',
+                        code: 'ENTITY_NOT_VISIBLE',
+                        parsed: command,
+                        details: {
+                            entity: directObject.entity.id,
+                            entityName: directObject.parsed.text,
+                            scopeCode: scopeCheck.code
+                        }
+                    }
+                };
+            }
+        }
+        if (indirectObject && metadata.indirectObjectScope) {
+            const scopeCheck = this.checkEntityScope(indirectObject.entity, metadata.indirectObjectScope, indirectObject.parsed.text);
+            if (!scopeCheck.success) {
+                return {
+                    success: false,
+                    error: {
+                        type: 'VALIDATION_ERROR',
+                        code: 'ENTITY_NOT_VISIBLE',
+                        parsed: command,
+                        details: {
+                            entity: indirectObject.entity.id,
+                            entityName: indirectObject.parsed.text,
+                            scopeCode: scopeCheck.code
+                        }
+                    }
+                };
+            }
+        }
+        // 5. Check action-specific preconditions
+        const preconditionCheck = this.checkActionPreconditions(actionHandler, directObject?.entity, indirectObject?.entity);
+        if (!preconditionCheck.success) {
+            return {
+                success: false,
+                error: {
+                    type: 'VALIDATION_ERROR',
+                    code: 'PRECONDITION_FAILED',
+                    parsed: command,
+                    details: preconditionCheck.details
+                }
+            };
+        }
+        // Success - build validated command with scope info
+        const validationTime = Date.now() - startTime;
+        const scopeInfo = {};
+        if (directObject) {
+            const player = this.world.getPlayer();
+            const entityScope = this.scopeResolver.getScope(player, directObject.entity);
+            const perceivedBy = this.getPerceivedSenses(player, directObject.entity);
+            scopeInfo.directObject = {
+                level: entityScope,
+                perceivedBy
+            };
+        }
+        if (indirectObject) {
+            const player = this.world.getPlayer();
+            const entityScope = this.scopeResolver.getScope(player, indirectObject.entity);
+            const perceivedBy = this.getPerceivedSenses(player, indirectObject.entity);
+            scopeInfo.indirectObject = {
+                level: entityScope,
+                perceivedBy
+            };
+        }
+        if (instrument) {
+            const player = this.world.getPlayer();
+            const entityScope = this.scopeResolver.getScope(player, instrument.entity);
+            const perceivedBy = this.getPerceivedSenses(player, instrument.entity);
+            scopeInfo.instrument = {
+                level: entityScope,
+                perceivedBy
+            };
+        }
+        const validatedCommand = {
+            parsed: command,
+            actionId: actionHandler.id,
+            directObject,
+            indirectObject,
+            instrument,
+            metadata: {
+                validationTime,
+                warnings: warnings.length > 0 ? warnings : undefined
+            },
+            ...(Object.keys(scopeInfo).length > 0 && { scopeInfo })
+        };
+        this.emitDebugEvent('entity_resolution', command, {
+            method: 'resolveWithSelection',
+            selections,
+            success: true
+        });
+        return {
+            success: true,
+            value: validatedCommand
+        };
+    }
+    /**
+     * Resolve an entity reference with full matching logic
+     */
+    resolveEntity(ref, objectType, requiredScope, command) {
+        if (!ref) {
+            throw new Error('Cannot resolve undefined reference');
+        }
+        this.emitDebugEvent('entity_resolution', command, {
+            objectType,
+            reference: ref,
+            requiredScope,
+            startTime: Date.now()
+        });
+        // ADR-089: Handle pre-resolved entity ID (from pronoun resolution in parser)
+        if (ref.entityId) {
+            const resolved = this.resolveEntityById(ref.entityId, ref);
+            if (resolved) {
+                this.emitDebugEvent('entity_resolution', command, {
+                    objectType,
+                    preResolvedEntityId: ref.entityId,
+                    entity: resolved.entity.id
+                });
+                return { success: true, value: resolved };
+            }
+            // Entity ID was set but entity not found - fall through to error
+        }
+        // Maximal munch entity resolution (ISSUE-057):
+        // Try full text first (e.g., "brass lantern"), fall back to head noun (e.g., "lantern").
+        // The parser's slot consumer already builds multi-word phrases correctly;
+        // this ensures the validator uses them for entity lookup.
+        const fullText = ref.text;
+        const headNoun = ref.head || ref.text;
+        let candidates = [];
+        let searchTerm = fullText;
+        // For AWARE scope (hearing/smelling), we need to search more broadly
+        // because entities might be in other rooms
+        const needsBroadSearch = requiredScope === types_1.ScopeLevel.AWARE;
+        if (needsBroadSearch) {
+            // For audible/detectable, search all entities (except rooms/player)
+            // and let scope filtering handle visibility
+            candidates = this.world.getAllEntities().filter(e => e.type !== 'room' && e.id !== this.world.getPlayer()?.id);
+            // Filter candidates by name/type/synonym match — try full text first, then head noun
+            candidates = candidates.filter(entity => {
+                const name = this.getEntityName(entity).toLowerCase();
+                const type = entity.type?.toLowerCase() || '';
+                const synonyms = this.getEntitySynonyms(entity).map(s => s.toLowerCase());
+                const fullTextLower = fullText.toLowerCase();
+                return name === fullTextLower || type === fullTextLower || synonyms.includes(fullTextLower);
+            });
+            // Fall back to head noun if full text found nothing
+            if (candidates.length === 0 && headNoun !== fullText) {
+                searchTerm = headNoun;
+                candidates = this.world.getAllEntities().filter(e => e.type !== 'room' && e.id !== this.world.getPlayer()?.id);
+                candidates = candidates.filter(entity => {
+                    const name = this.getEntityName(entity).toLowerCase();
+                    const type = entity.type?.toLowerCase() || '';
+                    const synonyms = this.getEntitySynonyms(entity).map(s => s.toLowerCase());
+                    const headLower = headNoun.toLowerCase();
+                    return name === headLower || type === headLower || synonyms.includes(headLower);
+                });
+            }
+        }
+        else {
+            // Try full text first (maximal munch)
+            candidates = this.findCandidatesByTerm(fullText);
+            this.emitDebugEvent('entity_search', command, {
+                searchTerm: fullText,
+                fullTextCandidates: candidates.length,
+                strategy: 'maximal_munch_full_text'
+            });
+            // Fall back to head noun if full text found nothing and they differ
+            if (candidates.length === 0 && headNoun !== fullText) {
+                searchTerm = headNoun;
+                candidates = this.findCandidatesByTerm(headNoun);
+                this.emitDebugEvent('entity_search', command, {
+                    searchTerm: headNoun,
+                    headNounCandidates: candidates.length,
+                    strategy: 'maximal_munch_head_fallback'
+                });
+            }
+            // Fallback: If no candidates found by name/type/synonym, try adjective search
+            // This handles "press yellow" when yellow is an adjective on "yellow button"
+            if (candidates.length === 0) {
+                const byAdjective = this.getEntitiesByAdjective(searchTerm);
+                if (byAdjective.length > 0) {
+                    candidates = byAdjective;
+                    this.emitDebugEvent('entity_search', command, {
+                        searchTerm,
+                        byAdjective: byAdjective.length,
+                        fallback: true
+                    });
+                }
+            }
+        }
+        // Now filter by scope
+        let entitiesInScope = this.filterByScope(candidates, requiredScope);
+        // Second adjective fallback: if scope filtering eliminated all candidates,
+        // try adjective search and filter those by scope
+        if (entitiesInScope.length === 0 && candidates.length > 0) {
+            const byAdjective = this.getEntitiesByAdjective(searchTerm);
+            if (byAdjective.length > 0) {
+                const adjectiveInScope = this.filterByScope(byAdjective, requiredScope);
+                if (adjectiveInScope.length > 0) {
+                    candidates = byAdjective;
+                    entitiesInScope = adjectiveInScope;
+                    this.emitDebugEvent('entity_search', command, {
+                        searchTerm,
+                        byAdjective: byAdjective.length,
+                        adjectiveInScope: adjectiveInScope.length,
+                        fallbackAfterScope: true
+                    });
+                }
+            }
+        }
+        // Get detailed scope information for all candidates
+        const candidateScopes = [];
+        const player = this.world.getPlayer();
+        if (player) {
+            for (const entity of candidates) {
+                const entityScope = this.scopeResolver.getScope(player, entity);
+                candidateScopes.push({
+                    id: entity.id,
+                    name: this.getEntityName(entity),
+                    type: entity.type,
+                    location: this.world.getLocation(entity.id),
+                    scope: entityScope,
+                    meetsRequired: this.filterByScope([entity], requiredScope).length > 0,
+                    visible: this.isEntityVisible(entity),
+                    reachable: this.isEntityReachable(entity),
+                    touchable: this.isEntityTouchable(entity)
+                });
+            }
+        }
+        this.emitDebugEvent('scope_check', command, {
+            objectType,
+            requiredScope,
+            totalCandidates: candidates.length,
+            entitiesInScope: entitiesInScope.length,
+            candidateScopes,
+            scopeDetails: entitiesInScope.map(e => ({
+                id: e.id,
+                name: this.getEntityName(e),
+                visible: this.isEntityVisible(e),
+                reachable: this.isEntityReachable(e),
+                touchable: this.isEntityTouchable(e)
+            }))
+        });
+        // Score only the entities that are in scope
+        const scoredMatches = this.scoreEntities(entitiesInScope, ref);
+        // Filter out zero-score matches
+        const viableMatches = scoredMatches.filter(m => m.score > 0);
+        if (viableMatches.length === 0) {
+            this.emitDebugEvent('validation_error', command, {
+                errorType: 'NO_MATCHES',
+                reference: ref,
+                scope: requiredScope,
+                checkedEntities: entitiesInScope.length
+            });
+            return {
+                success: false,
+                error: {
+                    type: 'VALIDATION_ERROR',
+                    code: 'ENTITY_NOT_FOUND',
+                    parsed: command,
+                    details: {
+                        searchText: ref.text,
+                        candidates: ref.candidates,
+                        scope: requiredScope
+                    }
+                }
+            };
+        }
+        // Handle ambiguity
+        if (viableMatches.length > 1) {
+            const resolved = this.resolveAmbiguity(viableMatches, ref, command);
+            if (resolved) {
+                return {
+                    success: true,
+                    value: {
+                        entity: resolved.entity,
+                        parsed: ref
+                    }
+                };
+            }
+            // Phase 5: If user specified modifiers (adjectives) but NO candidate matches them,
+            // this is ENTITY_NOT_FOUND (the specific entity doesn't exist), not AMBIGUOUS_ENTITY.
+            // Example: "green ball" when only red and blue balls exist -> ENTITY_NOT_FOUND
+            //
+            // Note: The parser may not always populate modifiers, so we also extract them
+            // by comparing text to head (e.g., "green ball" vs "ball" -> modifier "green")
+            let modifiers = ref.modifiers || [];
+            if (modifiers.length === 0 && ref.text && ref.head) {
+                const head = ref.head.toLowerCase();
+                const words = ref.text.toLowerCase().split(/\s+/).filter(w => w !== head);
+                // Filter out common articles/determiners that aren't adjectives
+                const nonModifiers = ['the', 'a', 'an', 'all', 'some', 'every', 'any', 'my'];
+                modifiers = words.filter(w => !nonModifiers.includes(w));
+            }
+            if (modifiers.length > 0) {
+                const anyModifierMatch = viableMatches.some(m => m.matchReasons.some(r => r.startsWith('modifier_match_')));
+                if (!anyModifierMatch) {
+                    // User asked for specific adjective(s) that no entity has
+                    this.emitDebugEvent('entity_resolution', command, {
+                        objectType,
+                        resolved: false,
+                        reason: 'modifiers_not_matched',
+                        searchText: ref.text,
+                        specifiedModifiers: modifiers
+                    });
+                    return {
+                        success: false,
+                        error: {
+                            type: 'VALIDATION_ERROR',
+                            code: 'ENTITY_NOT_FOUND',
+                            parsed: command,
+                            details: {
+                                searchText: ref.text,
+                                modifiers,
+                                nearMatches: viableMatches.slice(0, 3).map(m => this.getEntityName(m.entity))
+                            }
+                        }
+                    };
+                }
+            }
+            // Still ambiguous - return error with choices for disambiguation prompt
+            // Phase 5: Include entity IDs so caller can re-resolve after user selection
+            const choices = viableMatches.slice(0, 5).map(m => ({
+                id: m.entity.id,
+                name: this.getEntityName(m.entity),
+                description: this.getEntityDescription(m.entity),
+                score: m.score,
+                matchReasons: m.matchReasons
+            }));
+            this.emitDebugEvent('disambiguation_required', command, {
+                objectType,
+                searchText: ref.text,
+                candidateCount: viableMatches.length,
+                topCandidates: choices
+            });
+            return {
+                success: false,
+                error: {
+                    type: 'VALIDATION_ERROR',
+                    code: 'AMBIGUOUS_ENTITY', // Distinct from ENTITY_NOT_FOUND
+                    parsed: command,
+                    details: {
+                        ambiguousEntities: choices,
+                        searchText: ref.text,
+                        matchCount: viableMatches.length,
+                        objectType // 'direct', 'indirect', or 'instrument'
+                    }
+                }
+            };
+        }
+        // Single match
+        const match = viableMatches[0];
+        this.emitDebugEvent('entity_resolution', command, {
+            objectType,
+            resolved: true,
+            entity: match.entity.id,
+            score: match.score,
+            matchReasons: match.matchReasons
+        });
+        return {
+            success: true,
+            value: {
+                entity: match.entity,
+                parsed: ref
+            }
+        };
+    }
+    /**
+     * Find candidate entities by name, type, or synonym for a given search term.
+     * Returns deduplicated results.
+     */
+    findCandidatesByTerm(term) {
+        const byName = this.getEntitiesByName(term);
+        const byType = this.getEntitiesByType(term);
+        const bySynonym = this.getEntitiesBySynonym(term);
+        const candidates = [...byName, ...byType, ...bySynonym];
+        // Remove duplicates
+        return candidates.filter((e, i, arr) => arr.findIndex(x => x.id === e.id) === i);
+    }
+    /**
+     * Get entities by exact name match
+     */
+    getEntitiesByName(name) {
+        // For now, use findWhere until WorldModel has a name index
+        const normalizedName = name.toLowerCase();
+        return this.world.findWhere(entity => {
+            // Skip rooms and player
+            if (entity.type === 'room' || entity.id === this.world.getPlayer()?.id) {
+                return false;
+            }
+            // Check exact name match
+            const entityName = this.getEntityName(entity).toLowerCase();
+            return entityName === normalizedName;
+        });
+    }
+    /**
+     * Get entities by type
+     */
+    getEntitiesByType(type) {
+        const normalizedType = type.toLowerCase();
+        return this.world.findByType(normalizedType);
+    }
+    /**
+     * Get entities by synonym
+     */
+    getEntitiesBySynonym(synonym) {
+        const normalizedSynonym = synonym.toLowerCase();
+        return this.world.findWhere(entity => {
+            // Skip rooms and player
+            if (entity.type === 'room' || entity.id === this.world.getPlayer()?.id) {
+                return false;
+            }
+            const synonyms = this.getEntitySynonyms(entity).map(s => s.toLowerCase());
+            return synonyms.includes(normalizedSynonym);
+        });
+    }
+    /**
+     * Get entities by adjective (fallback for "press yellow" style commands)
+     * When no name/alias match exists, find entities where the search term is an adjective
+     */
+    getEntitiesByAdjective(adjective) {
+        const normalizedAdjective = adjective.toLowerCase();
+        return this.world.findWhere(entity => {
+            // Skip rooms and player
+            if (entity.type === 'room' || entity.id === this.world.getPlayer()?.id) {
+                return false;
+            }
+            const adjectives = this.getEntityAdjectives(entity).map(a => a.toLowerCase());
+            return adjectives.includes(normalizedAdjective);
+        });
+    }
+    /**
+     * Filter entities by scope level
+     */
+    filterByScope(entities, scope) {
+        const player = this.world.getPlayer();
+        if (!player)
+            return [];
+        return entities.filter(entity => {
+            const entityScope = this.scopeResolver.getScope(player, entity);
+            // Check if entity meets the required scope level
+            switch (scope) {
+                case types_1.ScopeLevel.CARRIED:
+                    return entityScope === types_1.ScopeLevel.CARRIED;
+                case types_1.ScopeLevel.REACHABLE:
+                    return entityScope === types_1.ScopeLevel.CARRIED || entityScope === types_1.ScopeLevel.REACHABLE;
+                case types_1.ScopeLevel.VISIBLE:
+                    return entityScope === types_1.ScopeLevel.CARRIED ||
+                        entityScope === types_1.ScopeLevel.REACHABLE ||
+                        entityScope === types_1.ScopeLevel.VISIBLE;
+                case types_1.ScopeLevel.AWARE:
+                    // For aware, check if we can hear or smell it
+                    const canHear = this.scopeResolver.canHear && this.scopeResolver.canHear(player, entity);
+                    const canSmell = this.scopeResolver.canSmell && this.scopeResolver.canSmell(player, entity);
+                    return canHear || canSmell || entityScope >= types_1.ScopeLevel.AWARE;
+                default:
+                    // Use numeric comparison for other scope levels
+                    return entityScope >= scope;
+            }
+        });
+    }
+    /**
+     * Score entities against a reference
+     */
+    scoreEntities(entities, ref) {
+        if (!ref)
+            return [];
+        const scored = [];
+        const fullText = ref.text?.toLowerCase() || '';
+        const headNoun = (ref.head || ref.text).toLowerCase();
+        // Extract modifiers from ref, or infer from text vs head if not set
+        // (The parser may not always populate the modifiers field)
+        let modifiers = ref.modifiers || [];
+        if (modifiers.length === 0 && ref.text && ref.head) {
+            const head = ref.head.toLowerCase();
+            const words = ref.text.toLowerCase().split(/\s+/).filter(w => w !== head);
+            const nonModifiers = ['the', 'a', 'an', 'all', 'some', 'every', 'any', 'my'];
+            modifiers = words.filter(w => !nonModifiers.includes(w));
+        }
+        for (const entity of entities) {
+            let score = 0;
+            const matchReasons = [];
+            // Get entity properties
+            const name = this.getEntityName(entity).toLowerCase();
+            const type = entity.type?.toLowerCase() || '';
+            const adjectives = this.getEntityAdjectives(entity).map(a => a.toLowerCase());
+            const synonyms = this.getEntitySynonyms(entity).map(s => s.toLowerCase());
+            // Full text match scores highest (maximal munch — longer match = more specific)
+            if (fullText && fullText !== headNoun) {
+                if (name === fullText) {
+                    score += 15;
+                    matchReasons.push('full_text_name_match');
+                }
+                else if (synonyms.includes(fullText)) {
+                    score += 12;
+                    matchReasons.push('full_text_synonym_match');
+                }
+            }
+            // Base score for matching the head noun (falls through if full text already matched)
+            if (score === 0) {
+                if (name === headNoun) {
+                    score += 10;
+                    matchReasons.push('exact_name_match');
+                }
+                else if (type === headNoun) {
+                    score += 8;
+                    matchReasons.push('type_match');
+                }
+                else if (synonyms.includes(headNoun)) {
+                    score += 6;
+                    matchReasons.push('synonym_match');
+                }
+                else if (adjectives.includes(headNoun)) {
+                    // Adjective fallback: "press yellow" finds "yellow button"
+                    score += 4;
+                    matchReasons.push('adjective_match');
+                }
+            }
+            // Modifier matching - this is key for disambiguation
+            // If the user specified modifiers, entities that match them score higher
+            for (const modifier of modifiers) {
+                if (adjectives.includes(modifier.toLowerCase())) {
+                    score += 5;
+                    matchReasons.push(`modifier_match_${modifier}`);
+                }
+            }
+            // Penalty if entity has adjectives that weren't specified
+            // This helps "red ball" not match when user just says "ball" if there's also a plain ball
+            if (modifiers.length === 0 && adjectives.length > 0) {
+                score -= 1;
+                matchReasons.push('unspecified_adjectives');
+            }
+            // Visibility bonus
+            if (this.isEntityVisible(entity)) {
+                score += 1;
+                matchReasons.push('visible');
+            }
+            // Reachability bonus
+            if (this.isEntityReachable(entity)) {
+                score += 1;
+                matchReasons.push('reachable');
+            }
+            // In inventory bonus
+            if (this.isInPlayerInventory(entity)) {
+                score += 2;
+                matchReasons.push('in_inventory');
+            }
+            // Author-controlled scope priority (Phase 5 disambiguation)
+            // entity.scope(actionId) returns priority (default 100)
+            // We scale it to add reasonable bonus/penalty (100 = neutral, 150 = +5, 50 = -5)
+            const actionId = this.currentActionId;
+            if (actionId && typeof entity.scope === 'function') {
+                const priority = entity.scope(actionId);
+                const priorityBonus = Math.round((priority - 100) / 10); // 150 -> +5, 50 -> -5
+                if (priorityBonus !== 0) {
+                    score += priorityBonus;
+                    matchReasons.push(`scope_priority_${priority}`);
+                }
+            }
+            if (score > 0) {
+                scored.push({ entity, score, matchReasons });
+            }
+        }
+        // Sort by score descending
+        scored.sort((a, b) => b.score - a.score);
+        return scored;
+    }
+    /**
+     * Resolve ambiguity between multiple matches
+     */
+    resolveAmbiguity(matches, ref, command) {
+        this.emitDebugEvent('ambiguity_resolution', command, {
+            reference: ref,
+            matchCount: matches.length,
+            topMatches: matches.slice(0, 5).map(m => ({
+                entity: m.entity.id,
+                name: this.getEntityName(m.entity),
+                score: m.score,
+                reasons: m.matchReasons
+            }))
+        });
+        // If there's a clear winner (score significantly higher), use it
+        if (matches.length >= 2) {
+            const topScore = matches[0].score;
+            const secondScore = matches[1].score;
+            if (topScore >= secondScore * 1.5) {
+                this.emitDebugEvent('ambiguity_resolution', command, {
+                    resolved: true,
+                    method: 'score_threshold',
+                    chosen: matches[0].entity.id,
+                    scoreGap: topScore - secondScore
+                });
+                return matches[0];
+            }
+        }
+        // If all adjectives match for only one entity, use it
+        // Infer modifiers from text vs head (same logic as scoreEntities)
+        let modifiers = ref?.modifiers || [];
+        if (modifiers.length === 0 && ref?.text && ref?.head) {
+            const head = ref.head.toLowerCase();
+            const words = ref.text.toLowerCase().split(/\s+/).filter(w => w !== head);
+            const nonModifiers = ['the', 'a', 'an', 'all', 'some', 'every', 'any', 'my'];
+            modifiers = words.filter(w => !nonModifiers.includes(w));
+        }
+        if (modifiers.length > 0) {
+            const perfectMatches = matches.filter(m => {
+                const adjectives = this.getEntityAdjectives(m.entity).map(a => a.toLowerCase());
+                return modifiers.every((mod) => adjectives.includes(mod.toLowerCase()));
+            });
+            if (perfectMatches.length === 1) {
+                this.emitDebugEvent('ambiguity_resolution', command, {
+                    resolved: true,
+                    method: 'all_modifiers_match',
+                    chosen: perfectMatches[0].entity.id
+                });
+                return perfectMatches[0];
+            }
+        }
+        // If only one is visible and reachable, use it
+        const reachableMatches = matches.filter(m => this.isEntityVisible(m.entity) && this.isEntityReachable(m.entity));
+        if (reachableMatches.length === 1) {
+            this.emitDebugEvent('ambiguity_resolution', command, {
+                resolved: true,
+                method: 'only_reachable',
+                chosen: reachableMatches[0].entity.id
+            });
+            return reachableMatches[0];
+        }
+        // Unable to resolve automatically
+        this.emitDebugEvent('ambiguity_resolution', command, {
+            resolved: false,
+            method: 'none',
+            remainingCount: matches.length
+        });
+        return null;
+    }
+    /**
+     * Resolve an entity directly by ID
+     * Used after disambiguation when user selects a specific entity
+     */
+    resolveEntityById(entityId, parsed) {
+        const entity = this.world.getEntity(entityId);
+        if (!entity) {
+            return null;
+        }
+        return {
+            entity: entity,
+            parsed
+        };
+    }
+    /**
+     * Check if entity is visible to player
+     */
+    isEntityVisible(entity) {
+        const player = this.world.getPlayer();
+        if (!player)
+            return false;
+        return this.scopeResolver.canSee(player, entity);
+    }
+    /**
+     * Check if entity is reachable by player
+     */
+    isEntityReachable(entity) {
+        const player = this.world.getPlayer();
+        if (!player)
+            return false;
+        return this.scopeResolver.canReach(player, entity);
+    }
+    /**
+     * Check if entity is touchable by player
+     */
+    isEntityTouchable(entity) {
+        // Touchable = reachable and not intangible
+        if (!this.isEntityReachable(entity))
+            return false;
+        // Check for intangible trait
+        if (entity.has && entity.has('intangible'))
+            return false;
+        return true;
+    }
+    /**
+     * Check if entity is in player's inventory
+     */
+    isInPlayerInventory(entity) {
+        const player = this.world.getPlayer();
+        if (!player)
+            return false;
+        const inventory = this.world.getContents(player.id);
+        return inventory.some(e => e.id === entity.id);
+    }
+    /**
+     * Check if entity meets required scope level
+     */
+    checkEntityScope(entity, requiredScope, entityName) {
+        const player = this.world.getPlayer();
+        if (!player) {
+            return {
+                success: false,
+                code: 'NO_PLAYER'
+            };
+        }
+        const entityScope = this.scopeResolver.getScope(player, entity);
+        // Check if entity meets the required scope level
+        switch (requiredScope) {
+            case types_1.ScopeLevel.CARRIED:
+                if (entityScope !== types_1.ScopeLevel.CARRIED) {
+                    return {
+                        success: false,
+                        code: 'NOT_CARRIED'
+                    };
+                }
+                break;
+            case types_1.ScopeLevel.REACHABLE:
+                if (entityScope !== types_1.ScopeLevel.CARRIED && entityScope !== types_1.ScopeLevel.REACHABLE) {
+                    return {
+                        success: false,
+                        code: 'NOT_REACHABLE'
+                    };
+                }
+                break;
+            case types_1.ScopeLevel.VISIBLE:
+                if (entityScope < types_1.ScopeLevel.VISIBLE) {
+                    return {
+                        success: false,
+                        code: 'NOT_VISIBLE'
+                    };
+                }
+                break;
+            case types_1.ScopeLevel.AWARE:
+                if (entityScope === types_1.ScopeLevel.UNAWARE) {
+                    return {
+                        success: false,
+                        code: 'NOT_AWARE'
+                    };
+                }
+                break;
+        }
+        return { success: true };
+    }
+    /**
+     * Get which senses can perceive an entity
+     */
+    getPerceivedSenses(perceiver, entity) {
+        const senses = [];
+        if (this.scopeResolver.canSee(perceiver, entity)) {
+            senses.push('sight');
+        }
+        if (this.scopeResolver.canHear) {
+            if (this.scopeResolver.canHear(perceiver, entity)) {
+                senses.push('hearing');
+            }
+        }
+        if (this.scopeResolver.canSmell) {
+            if (this.scopeResolver.canSmell(perceiver, entity)) {
+                senses.push('smell');
+            }
+        }
+        // Touch is available if entity is reachable
+        if (this.scopeResolver.canReach(perceiver, entity)) {
+            senses.push('touch');
+        }
+        return senses;
+    }
+    /**
+     * Get entity display name
+     */
+    getEntityName(entity) {
+        // IFEntity has a name getter that uses identity trait
+        const name = entity.name;
+        // Handle case where name might be an object (from world model creation)
+        if (typeof name === 'string') {
+            return name;
+        }
+        return entity.type || entity.id;
+    }
+    /**
+     * Get entity description
+     */
+    getEntityDescription(entity) {
+        // IFEntity has a description getter that uses identity trait
+        return entity.description || this.getEntityName(entity);
+    }
+    /**
+     * Get entity adjectives
+     */
+    getEntityAdjectives(entity) {
+        const adjectives = [];
+        // Get identity trait
+        const identity = entity.getTrait(world_model_1.IdentityTrait);
+        if (identity?.adjectives) {
+            adjectives.push(...identity.adjectives);
+        }
+        return adjectives;
+    }
+    /**
+     * Get entity synonyms
+     */
+    getEntitySynonyms(entity) {
+        const synonyms = [];
+        // Get identity trait  
+        // Note: Entities use 'aliases' not 'synonyms' (synonyms are for verbs)
+        const identity = entity.getTrait(world_model_1.IdentityTrait);
+        if (identity?.aliases) {
+            synonyms.push(...identity.aliases);
+        }
+        // Add type as synonym
+        if (entity.type) {
+            synonyms.push(entity.type);
+        }
+        return synonyms;
+    }
+    /**
+     * Get action metadata
+     */
+    getActionMetadata(action) {
+        // Check if action has metadata property with required fields
+        if (action.metadata &&
+            'requiresDirectObject' in action.metadata &&
+            'requiresIndirectObject' in action.metadata) {
+            return action.metadata;
+        }
+        // Default metadata - actions handle their own requirements
+        return {
+            requiresDirectObject: false,
+            requiresIndirectObject: false,
+            directObjectScope: types_1.ScopeLevel.VISIBLE,
+            indirectObjectScope: types_1.ScopeLevel.VISIBLE
+        };
+    }
+    /**
+     * Check action-specific preconditions
+     */
+    checkActionPreconditions(action, directObject, indirectObject) {
+        // If action has a validate method in metadata, use it
+        if (action.metadata && typeof action.metadata.validate === 'function') {
+            return action.metadata.validate(directObject, indirectObject);
+        }
+        // Default - all preconditions pass
+        return { success: true, message: 'OK' };
+    }
+    /**
+     * Emit a debug event
+     */
+    emitDebugEvent(debugType, command, data) {
+        if (!this.systemEvents)
+            return;
+        this.systemEvents.emit({
+            id: `validator_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+            timestamp: Date.now(),
+            subsystem: 'validator',
+            type: debugType,
+            data: {
+                command,
+                ...data
+            }
+        });
+    }
+}
+exports.CommandValidator = CommandValidator;
+//# sourceMappingURL=command-validator.js.map