@sharpee/stdlib 3.0.0 → 3.3.0

package/validation/command-validator.d.ts

@@ -6,9 +6,9 @@
  */
 import type { ISystemEvent, IGenericEventSource, Result } from '@sharpee/core';
 import type { IParsedCommand, INounPhrase, IValidatedObjectReference, IValidationError, WorldModel } from '@sharpee/world-model';
-import type { ValidatedCommand } from './types';
-import { ActionRegistry } from '../actions/registry';
-import { ScopeResolver, ScopeLevel } from '../scope/types';
+import type { ValidatedCommand } from './types.js';
+import { ActionRegistry } from '../actions/registry.js';
+import { ScopeResolver, ScopeLevel } from '../scope/types.js';
 /**
  * Action metadata interface for declaring requirements
  */
@@ -18,6 +18,15 @@ export interface ActionMetadata {
     directObjectScope?: ScopeLevel;
     indirectObjectScope?: ScopeLevel;
     validPrepositions?: string[];
+    /**
+     * Disambiguation preference (platform-issue-sweep Phase 6/10): when an
+     * ambiguity ties and EXACTLY ONE candidate sits at this scope level, it
+     * auto-resolves. Lets an action widen its resolution scope (so its own
+     * refusal speaks for out-of-scope targets — e.g. dropping resolves
+     * VISIBLE) without losing the classic preference ("drop book" with a
+     * carried black book and a guidebook on the floor means the carried one).
+     */
+    preferredScope?: ScopeLevel;
 }
 /**
  * Slot types that can have entity selections
@@ -63,6 +72,8 @@ export declare class CommandValidator implements CommandValidator {
     private systemEvents?;
     /** Current action ID being validated (for disambiguation scoring) */
     private currentActionId?;
+    /** The current action's preferredScope, staged for resolveAmbiguity. */
+    private currentPreferredScope?;
     constructor(world: WorldModel, actionRegistry: ActionRegistry, scopeResolver?: ScopeResolver);
     /**
      * Set system event source for debug events
@@ -73,33 +84,74 @@ export declare class CommandValidator implements CommandValidator {
      */
     private resolveEntity;
     /**
-     * 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
+     */
+    private resolveTopic;
+    /**
+     * 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).
      */
-    private findCandidatesByTerm;
+    private findCandidates;
     /**
-     * Get entities by exact name match
+     * 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.
      */
-    private getEntitiesByName;
+    private matchEntityName;
     /**
-     * Get entities by type
+     * 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.
      */
-    private getEntitiesByType;
+    private getEntityVocabulary;
     /**
-     * Get entities by synonym
+     * Strip leading articles ("the", "a", "an") from query text, always
+     * keeping at least one word.
      */
-    private getEntitiesBySynonym;
+    private stripLeadingArticles;
     /**
-     * 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
+     * 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).
      */
-    private getEntitiesByAdjective;
+    private dominantMatches;
     /**
      * Filter entities by scope level
      */
     private filterByScope;
     /**
-     * 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.
      */
     private scoreEntities;
     /**

package/validation/command-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-validator.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee_v2/packages/stdlib/src/validation/command-validator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-validator.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee_v2/packages/stdlib/src/validation/command-validator.ts"],"names":[],"mappings":"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"}