@sharpee/stdlib 3.1.0 → 3.3.0

package/validation/command-validator.js

@@ -8,8 +8,17 @@
 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");
+const types_js_1 = require("../scope/types.js");
+const scope_resolver_js_1 = require("../scope/scope-resolver.js");
+/**
+ * Match tiers for name resolution (ADR-231 D3, PIN 2).
+ * EXACT (query text equals full name/alias/type) outranks WORDS (every
+ * query content word matches the entity's vocabulary).
+ */
+const MATCH_TIER_EXACT = 3;
+const MATCH_TIER_WORDS = 2;
+/** Leading articles stripped from query text before matching (D3 defect fix). */
+const QUERY_ARTICLES = new Set(['the', 'a', 'an']);
 /**
  * Enhanced command validator with full entity resolution
  */
@@ -20,10 +29,12 @@ class CommandValidator {
     systemEvents;
     /** Current action ID being validated (for disambiguation scoring) */
     currentActionId;
+    /** The current action's preferredScope, staged for resolveAmbiguity. */
+    currentPreferredScope;
     constructor(world, actionRegistry, scopeResolver) {
         this.world = world;
         this.actionRegistry = actionRegistry;
-        this.scopeResolver = scopeResolver || new scope_resolver_1.StandardScopeResolver(world);
+        this.scopeResolver = scopeResolver || new scope_resolver_js_1.StandardScopeResolver(world);
     }
     /**
      * Set system event source for debug events
@@ -59,8 +70,9 @@ class CommandValidator {
                 }
             };
         }
-        // Store current action ID for disambiguation scoring
+        // Store current action ID + scope preference for disambiguation scoring
         this.currentActionId = actionHandler.id;
+        this.currentPreferredScope = this.getActionMetadata(actionHandler).preferredScope;
         // 2. Resolve direct object if present in parsed command
         let directObject;
         if (command.structure?.directObject) {
@@ -75,7 +87,7 @@ class CommandValidator {
             else {
                 // Normal single-entity resolution
                 const metadata = this.getActionMetadata(actionHandler);
-                const scope = metadata.directObjectScope || types_1.ScopeLevel.VISIBLE;
+                const scope = metadata.directObjectScope || types_js_1.ScopeLevel.VISIBLE;
                 const resolved = this.resolveEntity(nounPhrase, 'direct', scope, command);
                 if (!resolved.success) {
                     return resolved;
@@ -88,7 +100,7 @@ class CommandValidator {
         let indirectObject;
         if (command.structure?.indirectObject) {
             const metadata = this.getActionMetadata(actionHandler);
-            const scope = metadata.indirectObjectScope || types_1.ScopeLevel.VISIBLE;
+            const scope = metadata.indirectObjectScope || types_js_1.ScopeLevel.VISIBLE;
             const resolved = this.resolveEntity(command.structure.indirectObject, 'indirect', scope, command);
             if (!resolved.success) {
                 return resolved;
@@ -100,12 +112,17 @@ class CommandValidator {
         let instrument;
         if (command.instrument) {
             // Instruments are typically carried or reachable
-            const resolved = this.resolveEntity(command.instrument, 'instrument', types_1.ScopeLevel.REACHABLE, command);
+            const resolved = this.resolveEntity(command.instrument, 'instrument', types_js_1.ScopeLevel.REACHABLE, command);
             if (!resolved.success) {
                 return resolved;
             }
             instrument = resolved.value;
         }
+        // 3c. Resolve topic if present (ADR-231 D4): entity-first with text
+        // fallback. Quiet resolution only — a topic NEVER produces
+        // ENTITY_NOT_FOUND or a disambiguation prompt; on miss or tie the
+        // verbatim text flows through with entity undefined.
+        const topic = command.topic ? this.resolveTopic(command.topic.text) : undefined;
         // 4. Check scope constraints based on action metadata
         const metadata = this.getActionMetadata(actionHandler);
         // Check direct object scope
@@ -196,6 +213,7 @@ class CommandValidator {
             directObject,
             indirectObject,
             instrument,
+            topic,
             metadata: {
                 validationTime,
                 warnings: warnings.length > 0 ? warnings : undefined
@@ -235,6 +253,7 @@ class CommandValidator {
             };
         }
         this.currentActionId = actionHandler.id;
+        this.currentPreferredScope = this.getActionMetadata(actionHandler).preferredScope;
         // 2. Resolve direct object - use selection if provided
         let directObject;
         if (command.structure?.directObject) {
@@ -269,7 +288,7 @@ class CommandValidator {
             else {
                 // Normal resolution
                 const metadata = this.getActionMetadata(actionHandler);
-                const scope = metadata.directObjectScope || types_1.ScopeLevel.VISIBLE;
+                const scope = metadata.directObjectScope || types_js_1.ScopeLevel.VISIBLE;
                 const resolved = this.resolveEntity(nounPhrase, 'direct', scope, command);
                 if (!resolved.success) {
                     return resolved;
@@ -304,7 +323,7 @@ class CommandValidator {
             }
             else {
                 const metadata = this.getActionMetadata(actionHandler);
-                const scope = metadata.indirectObjectScope || types_1.ScopeLevel.VISIBLE;
+                const scope = metadata.indirectObjectScope || types_js_1.ScopeLevel.VISIBLE;
                 const resolved = this.resolveEntity(command.structure.indirectObject, 'indirect', scope, command);
                 if (!resolved.success) {
                     return resolved;
@@ -338,13 +357,16 @@ class CommandValidator {
                 };
             }
             else {
-                const resolved = this.resolveEntity(command.instrument, 'instrument', types_1.ScopeLevel.REACHABLE, command);
+                const resolved = this.resolveEntity(command.instrument, 'instrument', types_js_1.ScopeLevel.REACHABLE, command);
                 if (!resolved.success) {
                     return resolved;
                 }
                 instrument = resolved.value;
             }
         }
+        // 3c. Resolve topic if present (ADR-231 D4) — same quiet entity-first
+        // pass as validate(); topics are never disambiguation slots.
+        const topic = command.topic ? this.resolveTopic(command.topic.text) : undefined;
         // 4. Check scope constraints based on action metadata
         const metadata = this.getActionMetadata(actionHandler);
         if (directObject && metadata.directObjectScope) {
@@ -432,6 +454,7 @@ class CommandValidator {
             directObject,
             indirectObject,
             instrument,
+            topic,
             metadata: {
                 validationTime,
                 warnings: warnings.length > 0 ? warnings : undefined
@@ -474,94 +497,34 @@ class CommandValidator {
             }
             // 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;
+        // Tiered word-level candidate search (ADR-231 D3, PIN 2): a candidate
+        // is any entity the noun phrase matches at EXACT tier (full text equals
+        // name/alias/type) or WORDS tier (every query content word matches the
+        // entity's name/alias/adjective vocabulary). This replaces the old
+        // exact-match cascade (full text → head noun → adjective fallback) —
+        // "x key" now finds the brass key with zero authoring, while a query
+        // word matching nothing disqualifies ("x brass sword" never resolves
+        // the brass key).
+        let candidates;
+        // For AWARE scope (hearing/smelling), search all entities except
+        // rooms/player because entities might be in other rooms; scope
+        // filtering below handles perceivability.
+        const needsBroadSearch = requiredScope === types_js_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);
-                });
-            }
+            candidates = this.world.getAllEntities().filter(e => e.type !== 'room' &&
+                e.id !== this.world.getPlayer()?.id &&
+                this.matchEntityName(e, ref) !== null);
         }
         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
-                    });
-                }
-            }
+            candidates = this.findCandidates(ref);
         }
+        this.emitDebugEvent('entity_search', command, {
+            searchTerm: ref.text,
+            candidateCount: candidates.length,
+            strategy: 'tiered_word_match'
+        });
         // 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
-                    });
-                }
-            }
-        }
+        const entitiesInScope = this.filterByScope(candidates, requiredScope);
         // Get detailed scope information for all candidates
         const candidateScopes = [];
         const player = this.world.getPlayer();
@@ -597,8 +560,11 @@ class CommandValidator {
         });
         // 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);
+        // PIN 2 ranking: keep only the dominant (tier, wordsMatched) group.
+        // Higher tier wins outright; within a tier, more matched words win
+        // outright. Only true ties flow into the disambiguation path below;
+        // a single survivor auto-resolves.
+        const viableMatches = this.dominantMatches(scoredMatches);
         if (viableMatches.length === 0) {
             this.emitDebugEvent('validation_error', command, {
                 errorType: 'NO_MATCHES',
@@ -720,71 +686,169 @@ class CommandValidator {
         };
     }
     /**
-     * Find candidate entities by name, type, or synonym for a given search term.
-     * Returns deduplicated results.
+     * Resolve a topic's text against VISIBLE scope, quietly (ADR-231 D4).
+     *
+     * Entity-first with text fallback: reuses the D3 tiered matcher, but a
+     * topic is NEVER an entity slot — no ENTITY_NOT_FOUND, no scope
+     * rejection, no disambiguation prompt. Exactly one dominant in-scope
+     * match carries its EntityId (interceptors and future conversation
+     * systems key on it); a miss or a tie falls back to the verbatim text.
+     *
+     * @param text Verbatim topic text as typed (articles preserved)
+     * @returns The validated topic — `entity` set only on a unique match
      */
-    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);
+    resolveTopic(text) {
+        const words = this.stripLeadingArticles(text.toLowerCase().trim()).split(/\s+/);
+        const ref = {
+            tokens: [],
+            text,
+            head: words[words.length - 1] || text,
+            modifiers: [],
+            articles: [],
+            determiners: [],
+            candidates: [text]
+        };
+        const candidates = this.findCandidates(ref);
+        const inScope = this.filterByScope(candidates, types_js_1.ScopeLevel.VISIBLE);
+        const viable = this.dominantMatches(this.scoreEntities(inScope, ref));
+        if (viable.length === 1) {
+            return { text, entity: viable[0].entity.id };
+        }
+        return { text };
     }
     /**
-     * Get entities by exact name match
+     * Find candidate entities the noun phrase matches at any tier
+     * (ADR-231 D3). Rooms are skipped; the player IS resolvable here: a
+     * player with an IdentityTrait ("yourself", aliases me/self/myself)
+     * must match "examine me", "x yourself", etc. (ISSUE #154).
      */
-    getEntitiesByName(name) {
-        // For now, use findWhere until WorldModel has a name index
-        const normalizedName = name.toLowerCase();
+    findCandidates(ref) {
         return this.world.findWhere(entity => {
-            // Skip rooms. The player IS resolvable here: a player with an
-            // IdentityTrait ("yourself", aliases me/self/myself) must match
-            // "examine me", "x yourself", etc. (ISSUE #154).
             if (entity.type === 'room') {
                 return false;
             }
-            // Check exact name match
-            const entityName = this.getEntityName(entity).toLowerCase();
-            return entityName === normalizedName;
+            return this.matchEntityName(entity, ref) !== null;
         });
     }
     /**
-     * Get entities by type
+     * Match a noun phrase against one entity's naming surface (ADR-231 D3,
+     * PIN 2's tiered model).
+     *
+     * Tier EXACT: the query text — tried with its leading articles restored
+     * first (so proper names beginning with an article-like word survive),
+     * then as parsed, then article-stripped — equals the full name, a full
+     * alias, or the entity type, case-insensitively.
+     *
+     * Tier WORDS: EVERY query content word (stopwords dropped by
+     * `deriveNameVocabulary`) matches a word of the entity's vocabulary
+     * (name content words + alias content words + authored adjectives).
+     * Any query word matching nothing DISQUALIFIES the candidate:
+     * "x brass sword" never resolves to the brass key.
+     *
+     * @returns The tier and matched-word count, or null when neither
+     *   tier matches.
      */
-    getEntitiesByType(type) {
-        const normalizedType = type.toLowerCase();
-        return this.world.findByType(normalizedType);
+    matchEntityName(entity, ref) {
+        const rawText = ref.text?.toLowerCase().trim() || '';
+        if (!rawText) {
+            return null;
+        }
+        // Full-text-first: reconstruct the original query (leading articles the
+        // parser split off) before trying the stripped forms.
+        const articles = (ref.articles || []).map(a => a.toLowerCase());
+        const queries = [];
+        if (articles.length > 0) {
+            queries.push(`${articles.join(' ')} ${rawText}`);
+        }
+        queries.push(rawText);
+        const stripped = this.stripLeadingArticles(rawText);
+        if (!queries.includes(stripped)) {
+            queries.push(stripped);
+        }
+        const name = this.getEntityName(entity).toLowerCase();
+        const aliases = this.getEntitySynonyms(entity).map(s => s.toLowerCase());
+        const wordsMatchedFor = (q) => Math.max(1, (0, world_model_1.deriveNameVocabulary)(q).length);
+        // Tier EXACT — full text equals name, alias, or type
+        for (const query of queries) {
+            if (name === query) {
+                return {
+                    tier: MATCH_TIER_EXACT,
+                    wordsMatched: wordsMatchedFor(query),
+                    reasons: ['exact_name_match']
+                };
+            }
+            if (aliases.includes(query)) {
+                // getEntitySynonyms includes the entity type, so type equality
+                // lands here too (preserves pre-D3 type matching).
+                return {
+                    tier: MATCH_TIER_EXACT,
+                    wordsMatched: wordsMatchedFor(query),
+                    reasons: ['exact_synonym_match']
+                };
+            }
+        }
+        // Tier WORDS — every query content word must match the vocabulary
+        const queryWords = (0, world_model_1.deriveNameVocabulary)(stripped);
+        if (queryWords.length === 0) {
+            return null;
+        }
+        const vocabulary = this.getEntityVocabulary(entity);
+        for (const word of queryWords) {
+            if (!vocabulary.has(word)) {
+                return null; // disqualified — a query word matched nothing
+            }
+        }
+        return {
+            tier: MATCH_TIER_WORDS,
+            wordsMatched: queryWords.length,
+            reasons: queryWords.map(w => `word_match_${w}`)
+        };
     }
     /**
-     * Get entities by synonym
+     * The entity's word-level matching vocabulary (PIN 2): name content
+     * words + alias content words + authored adjectives (per-side for walls
+     * via getEntityAdjectives). Always derived on demand from the CURRENT
+     * name — never stored — so renames can't leave stale vocabulary and
+     * Chord-loaded and TS-authored entities are uniform by construction.
      */
-    getEntitiesBySynonym(synonym) {
-        const normalizedSynonym = synonym.toLowerCase();
-        return this.world.findWhere(entity => {
-            // Skip rooms. The player IS resolvable here so its IdentityTrait
-            // aliases (me/self/myself) match (ISSUE #154).
-            if (entity.type === 'room') {
-                return false;
+    getEntityVocabulary(entity) {
+        const vocabulary = new Set((0, world_model_1.deriveNameVocabulary)(this.getEntityName(entity)));
+        const identity = entity.getTrait(world_model_1.IdentityTrait);
+        if (identity?.aliases) {
+            for (const alias of identity.aliases) {
+                for (const word of (0, world_model_1.deriveNameVocabulary)(alias)) {
+                    vocabulary.add(word);
+                }
             }
-            const synonyms = this.getEntitySynonyms(entity).map(s => s.toLowerCase());
-            return synonyms.includes(normalizedSynonym);
-        });
+        }
+        for (const adjective of this.getEntityAdjectives(entity)) {
+            vocabulary.add(adjective.toLowerCase());
+        }
+        return vocabulary;
     }
     /**
-     * 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
+     * Strip leading articles ("the", "a", "an") from query text, always
+     * keeping at least one word.
      */
-    getEntitiesByAdjective(adjective) {
-        const normalizedAdjective = adjective.toLowerCase();
-        return this.world.findWhere(entity => {
-            // Skip rooms. The player IS resolvable here (ISSUE #154).
-            if (entity.type === 'room') {
-                return false;
-            }
-            const adjectives = this.getEntityAdjectives(entity).map(a => a.toLowerCase());
-            return adjectives.includes(normalizedAdjective);
-        });
+    stripLeadingArticles(text) {
+        const words = text.split(/\s+/);
+        let start = 0;
+        while (start < words.length - 1 && QUERY_ARTICLES.has(words[start])) {
+            start++;
+        }
+        return words.slice(start).join(' ');
+    }
+    /**
+     * Keep only the dominant (tier, wordsMatched) group of an already-sorted
+     * scored list (PIN 2: higher tier wins; within a tier, more matched
+     * words win; only true ties reach disambiguation).
+     */
+    dominantMatches(scored) {
+        if (scored.length <= 1) {
+            return scored;
+        }
+        const top = scored[0];
+        return scored.filter(m => m.tier === top.tier && m.wordsMatched === top.wordsMatched);
     }
     /**
      * Filter entities by scope level
@@ -797,19 +861,19 @@ class CommandValidator {
             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:
+                case types_js_1.ScopeLevel.CARRIED:
+                    return entityScope === types_js_1.ScopeLevel.CARRIED;
+                case types_js_1.ScopeLevel.REACHABLE:
+                    return entityScope === types_js_1.ScopeLevel.CARRIED || entityScope === types_js_1.ScopeLevel.REACHABLE;
+                case types_js_1.ScopeLevel.VISIBLE:
+                    return entityScope === types_js_1.ScopeLevel.CARRIED ||
+                        entityScope === types_js_1.ScopeLevel.REACHABLE ||
+                        entityScope === types_js_1.ScopeLevel.VISIBLE;
+                case types_js_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;
+                    return canHear || canSmell || entityScope >= types_js_1.ScopeLevel.AWARE;
                 default:
                     // Use numeric comparison for other scope levels
                     return entityScope >= scope;
@@ -817,14 +881,17 @@ class CommandValidator {
         });
     }
     /**
-     * Score entities against a reference
+     * Score entities against a reference (ADR-231 D3 tiered model).
+     *
+     * The tier and matched-word count come from `matchEntityName` and carry
+     * PIN 2's ranking; the numeric `score` is the within-tie heuristic
+     * (modifier/visibility/inventory/author scope priority bonuses) that the
+     * normal disambiguation flow uses to break residual ties.
      */
     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 || [];
@@ -835,13 +902,7 @@ class CommandValidator {
             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());
             // ADR-173: walls require strict modifier match. When the user specifies
             // modifiers, a wall whose current-side adjective doesn't match at least
             // one of them is removed from candidacy entirely — falling back on the
@@ -853,43 +914,23 @@ class CommandValidator {
                     continue;
                 }
             }
-            // 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');
-                }
+            // Tiered name match (PIN 2) — no match at either tier disqualifies
+            const match = this.matchEntityName(entity, ref);
+            if (!match) {
+                continue;
             }
-            // 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}`);
+            let score = 10;
+            const matchReasons = [...match.reasons];
+            // Modifier matching — an explicitly specified modifier the entity's
+            // vocabulary covers (adjective, name word, or alias word) marks the
+            // candidate as modifier-consistent for the disambiguation flow.
+            if (modifiers.length > 0) {
+                const vocabulary = this.getEntityVocabulary(entity);
+                for (const modifier of modifiers) {
+                    if (vocabulary.has(modifier.toLowerCase())) {
+                        score += 5;
+                        matchReasons.push(`modifier_match_${modifier}`);
+                    }
                 }
             }
             // Penalty if entity has adjectives that weren't specified
@@ -925,12 +966,16 @@ class CommandValidator {
                     matchReasons.push(`scope_priority_${priority}`);
                 }
             }
-            if (score > 0) {
-                scored.push({ entity, score, matchReasons });
-            }
+            scored.push({
+                entity,
+                tier: match.tier,
+                wordsMatched: match.wordsMatched,
+                score,
+                matchReasons
+            });
         }
-        // Sort by score descending
-        scored.sort((a, b) => b.score - a.score);
+        // Sort by PIN 2 rank (tier, then matched words), then heuristic score
+        scored.sort((a, b) => b.tier - a.tier || b.wordsMatched - a.wordsMatched || b.score - a.score);
         return scored;
     }
     /**
@@ -984,6 +1029,25 @@ class CommandValidator {
                 return perfectMatches[0];
             }
         }
+        // Action scope preference (Phase 6/10): when the action declares a
+        // preferredScope and exactly ONE candidate sits at it, that candidate
+        // wins — "drop book" with the black book in hand and a guidebook on the
+        // floor means the carried one, even though dropping resolves VISIBLE so
+        // its own refusal can speak for un-held targets.
+        if (this.currentPreferredScope !== undefined) {
+            const player = this.world.getPlayer();
+            if (player) {
+                const preferred = matches.filter(m => this.scopeResolver.getScope(player, m.entity) >= this.currentPreferredScope);
+                if (preferred.length === 1) {
+                    this.emitDebugEvent('ambiguity_resolution', command, {
+                        resolved: true,
+                        method: 'action_preferred_scope',
+                        chosen: preferred[0].entity.id
+                    });
+                    return preferred[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) {
@@ -1070,32 +1134,32 @@ class CommandValidator {
         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) {
+            case types_js_1.ScopeLevel.CARRIED:
+                if (entityScope !== types_js_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) {
+            case types_js_1.ScopeLevel.REACHABLE:
+                if (entityScope !== types_js_1.ScopeLevel.CARRIED && entityScope !== types_js_1.ScopeLevel.REACHABLE) {
                     return {
                         success: false,
                         code: 'NOT_REACHABLE'
                     };
                 }
                 break;
-            case types_1.ScopeLevel.VISIBLE:
-                if (entityScope < types_1.ScopeLevel.VISIBLE) {
+            case types_js_1.ScopeLevel.VISIBLE:
+                if (entityScope < types_js_1.ScopeLevel.VISIBLE) {
                     return {
                         success: false,
                         code: 'NOT_VISIBLE'
                     };
                 }
                 break;
-            case types_1.ScopeLevel.AWARE:
-                if (entityScope === types_1.ScopeLevel.UNAWARE) {
+            case types_js_1.ScopeLevel.AWARE:
+                if (entityScope === types_js_1.ScopeLevel.UNAWARE) {
                     return {
                         success: false,
                         code: 'NOT_AWARE'
@@ -1210,8 +1274,8 @@ class CommandValidator {
         return {
             requiresDirectObject: false,
             requiresIndirectObject: false,
-            directObjectScope: types_1.ScopeLevel.VISIBLE,
-            indirectObjectScope: types_1.ScopeLevel.VISIBLE
+            directObjectScope: types_js_1.ScopeLevel.VISIBLE,
+            indirectObjectScope: types_js_1.ScopeLevel.VISIBLE
         };
     }
     /**