@sharpee/stdlib 0.9.60-beta

package/dist/services/scoring/scoring-service.d.ts

@@ -0,0 +1,185 @@
+/**
+ * ScoringService - Event-based scoring service (ADR-085)
+ *
+ * Features:
+ * - Centralized scoring definitions (sourceId → points, reasonMessageId, category)
+ * - Deduplication via scored sources Set
+ * - Message IDs for all text (i18n-ready via TextService)
+ * - Optional: stories can disable scoring entirely
+ *
+ * @see ADR-085 Event-Based Scoring System
+ */
+import { IWorldModel } from '@sharpee/world-model';
+/**
+ * Entry in the score history
+ */
+export interface ScoreEntry {
+    points: number;
+    sourceId: string;
+    reasonMessageId: string;
+    timestamp: number;
+}
+/**
+ * Rank definition mapping score thresholds to message IDs
+ */
+export interface RankDefinition {
+    threshold: number;
+    /** Message ID looked up via TextService (not the actual text) */
+    messageId: string;
+    /** Legacy: direct name string (deprecated, use messageId) */
+    name?: string;
+}
+/**
+ * Scoring definition for a single scoring source
+ */
+export interface ScoringDefinition {
+    /** Points awarded for this source */
+    points: number;
+    /** Message ID for reason text (looked up via TextService) */
+    reasonMessageId: string;
+    /** Category for grouping/reporting */
+    category: 'treasure' | 'puzzle' | 'exploration' | 'action';
+}
+/**
+ * Configuration for creating a ScoringService
+ */
+export interface ScoringServiceConfig {
+    /** Maximum possible score */
+    maxScore: number;
+    /** Whether scoring is enabled (default: true) */
+    enabled?: boolean;
+    /** Rank definitions (threshold → messageId) */
+    ranks?: RankDefinition[];
+    /** Scoring definitions (sourceId → definition) */
+    definitions?: Record<string, ScoringDefinition>;
+}
+/**
+ * Scoring service interface (ADR-085)
+ */
+export interface IScoringService {
+    /** Whether scoring is enabled */
+    isEnabled(): boolean;
+    /** Get the current score */
+    getScore(): number;
+    /** Get the maximum possible score */
+    getMaxScore(): number;
+    /** Set the maximum score (for dynamic max like Dungeo's hidden points) */
+    setMaxScore(max: number): void;
+    /** Get the current move count */
+    getMoves(): number;
+    /** Increment the move counter */
+    incrementMoves(): void;
+    /** Get rank message ID based on current score (TextService looks up actual text) */
+    getRankMessageId(): string;
+    /** Legacy: Get rank name string (deprecated, use getRankMessageId) */
+    getRank(): string;
+    /** Check if a source has already been scored */
+    hasScored(sourceId: string): boolean;
+    /** Process a score gain by sourceId (looks up points from definitions, returns false if already scored) */
+    scorePoints(sourceId: string): boolean;
+    /** Process a score loss by sourceId (or override with explicit points) */
+    losePoints(sourceId: string, overridePoints?: number): void;
+    /** Get scoring definition for a sourceId */
+    getDefinition(sourceId: string): ScoringDefinition | undefined;
+    /** Register or update a scoring definition */
+    registerDefinition(sourceId: string, definition: ScoringDefinition): void;
+    /** Get all scored source IDs (for save/restore) */
+    getScoredSources(): string[];
+    /** Restore scored sources (for save/restore) */
+    restoreScoredSources(sources: string[]): void;
+    /** Get the score history */
+    getHistory(): ScoreEntry[];
+    /** Legacy: Add points directly (deprecated, use scorePoints with sourceId) */
+    addPoints(points: number, reason?: string): void;
+}
+/**
+ * Default rank definitions with message IDs
+ */
+export declare const DEFAULT_RANKS: RankDefinition[];
+/**
+ * Default scoring service implementation (ADR-085)
+ *
+ * Reads and writes scoring data from the SCORING capability.
+ * Stories can extend this class to add custom scoring logic.
+ */
+export declare class ScoringService implements IScoringService {
+    protected world: IWorldModel;
+    protected config: ScoringServiceConfig;
+    protected definitions: Map<string, ScoringDefinition>;
+    protected enabled: boolean;
+    constructor(world: IWorldModel, config?: ScoringServiceConfig);
+    /**
+     * Check if scoring is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get the current score
+     */
+    getScore(): number;
+    /**
+     * Get the maximum possible score
+     */
+    getMaxScore(): number;
+    /**
+     * Set the maximum score (for dynamic max like Dungeo's hidden points)
+     */
+    setMaxScore(max: number): void;
+    /**
+     * Get the current move count
+     */
+    getMoves(): number;
+    /**
+     * Increment the move counter
+     */
+    incrementMoves(): void;
+    /**
+     * Get rank message ID based on current score
+     */
+    getRankMessageId(): string;
+    /**
+     * Legacy: Get rank name string (deprecated, use getRankMessageId)
+     */
+    getRank(): string;
+    /**
+     * Check if a source has already been scored
+     */
+    hasScored(sourceId: string): boolean;
+    /**
+     * Process a score gain by sourceId
+     * Returns false if already scored or no definition found
+     */
+    scorePoints(sourceId: string): boolean;
+    /**
+     * Process a score loss by sourceId (or override with explicit points)
+     */
+    losePoints(sourceId: string, overridePoints?: number): void;
+    /**
+     * Get scoring definition for a sourceId
+     */
+    getDefinition(sourceId: string): ScoringDefinition | undefined;
+    /**
+     * Register or update a scoring definition
+     */
+    registerDefinition(sourceId: string, definition: ScoringDefinition): void;
+    /**
+     * Get all scored source IDs (for save/restore)
+     */
+    getScoredSources(): string[];
+    /**
+     * Restore scored sources (for save/restore)
+     */
+    restoreScoredSources(sources: string[]): void;
+    /**
+     * Get the score history
+     */
+    getHistory(): ScoreEntry[];
+    /**
+     * Legacy: Add points directly (deprecated, use scorePoints with sourceId)
+     */
+    addPoints(points: number, reason?: string): void;
+    /**
+     * Get the scoring capability data
+     */
+    protected getScoringData(): Record<string, any> | null;
+}
+//# sourceMappingURL=scoring-service.d.ts.map

package/dist/services/scoring/scoring-service.d.ts.map

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

package/dist/services/scoring/scoring-service.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * ScoringService - Event-based scoring service (ADR-085)
+ *
+ * Features:
+ * - Centralized scoring definitions (sourceId → points, reasonMessageId, category)
+ * - Deduplication via scored sources Set
+ * - Message IDs for all text (i18n-ready via TextService)
+ * - Optional: stories can disable scoring entirely
+ *
+ * @see ADR-085 Event-Based Scoring System
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScoringService = exports.DEFAULT_RANKS = void 0;
+const world_model_1 = require("@sharpee/world-model");
+/**
+ * Default rank definitions with message IDs
+ */
+exports.DEFAULT_RANKS = [
+    { threshold: 0, messageId: 'if.rank.beginner', name: 'Beginner' },
+    { threshold: 50, messageId: 'if.rank.novice', name: 'Novice' },
+    { threshold: 100, messageId: 'if.rank.amateur', name: 'Amateur' },
+    { threshold: 200, messageId: 'if.rank.experienced', name: 'Experienced' },
+    { threshold: 350, messageId: 'if.rank.expert', name: 'Expert' },
+    { threshold: 500, messageId: 'if.rank.master', name: 'Master' },
+];
+/**
+ * Default scoring service implementation (ADR-085)
+ *
+ * Reads and writes scoring data from the SCORING capability.
+ * Stories can extend this class to add custom scoring logic.
+ */
+class ScoringService {
+    world;
+    config;
+    definitions = new Map();
+    enabled;
+    constructor(world, config = { maxScore: 350 }) {
+        this.world = world;
+        this.config = config;
+        this.enabled = config.enabled ?? true;
+        // Initialize capability data if needed
+        const scoring = this.getScoringData();
+        if (scoring) {
+            if (scoring.maxScore === undefined) {
+                scoring.maxScore = config.maxScore;
+            }
+            if (scoring.scoredSources === undefined) {
+                scoring.scoredSources = [];
+            }
+        }
+        // Load definitions from config
+        if (config.definitions) {
+            for (const [sourceId, def] of Object.entries(config.definitions)) {
+                this.definitions.set(sourceId, def);
+            }
+        }
+    }
+    /**
+     * Check if scoring is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get the current score
+     */
+    getScore() {
+        const scoring = this.getScoringData();
+        return scoring?.scoreValue ?? 0;
+    }
+    /**
+     * Get the maximum possible score
+     */
+    getMaxScore() {
+        const scoring = this.getScoringData();
+        return scoring?.maxScore ?? this.config.maxScore;
+    }
+    /**
+     * Set the maximum score (for dynamic max like Dungeo's hidden points)
+     */
+    setMaxScore(max) {
+        const scoring = this.getScoringData();
+        if (scoring) {
+            scoring.maxScore = max;
+        }
+    }
+    /**
+     * Get the current move count
+     */
+    getMoves() {
+        const scoring = this.getScoringData();
+        return scoring?.moves ?? 0;
+    }
+    /**
+     * Increment the move counter
+     */
+    incrementMoves() {
+        const scoring = this.getScoringData();
+        if (!scoring)
+            return;
+        scoring.moves = (scoring.moves || 0) + 1;
+    }
+    /**
+     * Get rank message ID based on current score
+     */
+    getRankMessageId() {
+        const score = this.getScore();
+        const ranks = this.config.ranks ?? exports.DEFAULT_RANKS;
+        let currentRank = ranks[0]?.messageId ?? 'if.rank.beginner';
+        for (const rank of ranks) {
+            if (score >= rank.threshold) {
+                currentRank = rank.messageId;
+            }
+        }
+        return currentRank;
+    }
+    /**
+     * Legacy: Get rank name string (deprecated, use getRankMessageId)
+     */
+    getRank() {
+        const score = this.getScore();
+        const ranks = this.config.ranks ?? exports.DEFAULT_RANKS;
+        let currentRank = ranks[0]?.name ?? 'Beginner';
+        for (const rank of ranks) {
+            if (score >= rank.threshold) {
+                currentRank = rank.name ?? rank.messageId;
+            }
+        }
+        return currentRank;
+    }
+    /**
+     * Check if a source has already been scored
+     */
+    hasScored(sourceId) {
+        const scoring = this.getScoringData();
+        return scoring?.scoredSources?.includes(sourceId) ?? false;
+    }
+    /**
+     * Process a score gain by sourceId
+     * Returns false if already scored or no definition found
+     */
+    scorePoints(sourceId) {
+        if (!this.enabled)
+            return false;
+        // Check for duplicate scoring
+        if (this.hasScored(sourceId)) {
+            return false;
+        }
+        // Look up definition
+        const definition = this.definitions.get(sourceId);
+        if (!definition) {
+            // No definition found - log warning but don't fail
+            console.warn(`ScoringService: No definition found for sourceId "${sourceId}"`);
+            return false;
+        }
+        const scoring = this.getScoringData();
+        if (!scoring)
+            return false;
+        // Mark as scored
+        if (!scoring.scoredSources) {
+            scoring.scoredSources = [];
+        }
+        scoring.scoredSources.push(sourceId);
+        // Add points
+        scoring.scoreValue = (scoring.scoreValue || 0) + definition.points;
+        // Add to history
+        if (!scoring.scoreHistory) {
+            scoring.scoreHistory = [];
+        }
+        scoring.scoreHistory.push({
+            points: definition.points,
+            sourceId,
+            reasonMessageId: definition.reasonMessageId,
+            timestamp: Date.now(),
+        });
+        return true;
+    }
+    /**
+     * Process a score loss by sourceId (or override with explicit points)
+     */
+    losePoints(sourceId, overridePoints) {
+        if (!this.enabled)
+            return;
+        const scoring = this.getScoringData();
+        if (!scoring)
+            return;
+        // Determine points to lose
+        let points = overridePoints;
+        let reasonMessageId = 'if.score.lost';
+        if (points === undefined) {
+            const definition = this.definitions.get(sourceId);
+            if (definition) {
+                points = definition.points;
+                reasonMessageId = definition.reasonMessageId;
+            }
+            else {
+                console.warn(`ScoringService: No definition found for sourceId "${sourceId}" and no overridePoints provided`);
+                return;
+            }
+        }
+        // Subtract points (can go negative)
+        scoring.scoreValue = (scoring.scoreValue || 0) - points;
+        // Add to history (negative points)
+        if (!scoring.scoreHistory) {
+            scoring.scoreHistory = [];
+        }
+        scoring.scoreHistory.push({
+            points: -points,
+            sourceId,
+            reasonMessageId,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Get scoring definition for a sourceId
+     */
+    getDefinition(sourceId) {
+        return this.definitions.get(sourceId);
+    }
+    /**
+     * Register or update a scoring definition
+     */
+    registerDefinition(sourceId, definition) {
+        this.definitions.set(sourceId, definition);
+    }
+    /**
+     * Get all scored source IDs (for save/restore)
+     */
+    getScoredSources() {
+        const scoring = this.getScoringData();
+        return scoring?.scoredSources ?? [];
+    }
+    /**
+     * Restore scored sources (for save/restore)
+     */
+    restoreScoredSources(sources) {
+        const scoring = this.getScoringData();
+        if (scoring) {
+            scoring.scoredSources = [...sources];
+        }
+    }
+    /**
+     * Get the score history
+     */
+    getHistory() {
+        const scoring = this.getScoringData();
+        return scoring?.scoreHistory ?? [];
+    }
+    /**
+     * Legacy: Add points directly (deprecated, use scorePoints with sourceId)
+     */
+    addPoints(points, reason) {
+        const scoring = this.getScoringData();
+        if (!scoring)
+            return;
+        scoring.scoreValue = (scoring.scoreValue || 0) + points;
+        // Add to history if reason provided
+        if (reason) {
+            if (!scoring.scoreHistory) {
+                scoring.scoreHistory = [];
+            }
+            scoring.scoreHistory.push({
+                points,
+                sourceId: 'legacy',
+                reasonMessageId: reason,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    /**
+     * Get the scoring capability data
+     */
+    getScoringData() {
+        return this.world.getCapability(world_model_1.StandardCapabilities.SCORING) ?? null;
+    }
+}
+exports.ScoringService = ScoringService;
+//# sourceMappingURL=scoring-service.js.map

package/dist/services/scoring/scoring-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring-service.js","sourceRoot":"","sources":["../../../src/services/scoring/scoring-service.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,162 @@
+/**
+ * Command Validator
+ *
+ * Validates parsed commands against the world model
+ * Resolves entities and checks preconditions
+ */
+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';
+/**
+ * Action metadata interface for declaring requirements
+ */
+export interface ActionMetadata {
+    requiresDirectObject: boolean;
+    requiresIndirectObject: boolean;
+    directObjectScope?: ScopeLevel;
+    indirectObjectScope?: ScopeLevel;
+    validPrepositions?: string[];
+}
+/**
+ * Slot types that can have entity selections
+ */
+export type EntitySlot = 'directObject' | 'indirectObject' | 'instrument';
+/**
+ * Entity selections for disambiguation resolution
+ */
+export type EntitySelections = Partial<Record<EntitySlot, string>>;
+/**
+ * Validator interface - resolves entities and checks preconditions
+ */
+export interface CommandValidator {
+    /**
+     * Validate parsed command against world state
+     * @param command Parsed command to validate
+     * @returns Validated command or validation error
+     */
+    validate(command: IParsedCommand): Result<ValidatedCommand, IValidationError>;
+    /**
+     * Re-validate a command with explicit entity selections
+     * Used after AMBIGUOUS_ENTITY error when user selects from disambiguation choices
+     *
+     * @param command Original parsed command
+     * @param selections Map of slot to selected entity ID
+     * @returns Validated command or validation error
+     *
+     * @example
+     * // After receiving AMBIGUOUS_ENTITY for "take apple"
+     * const result = validator.resolveWithSelection(command, {
+     *   directObject: 'red-apple-001'  // User selected the red apple
+     * });
+     */
+    resolveWithSelection(command: IParsedCommand, selections: EntitySelections): Result<ValidatedCommand, IValidationError>;
+}
+/**
+ * Enhanced command validator with full entity resolution
+ */
+export declare class CommandValidator implements CommandValidator {
+    private world;
+    private actionRegistry;
+    private scopeResolver;
+    private systemEvents?;
+    /** Current action ID being validated (for disambiguation scoring) */
+    private currentActionId?;
+    constructor(world: WorldModel, actionRegistry: ActionRegistry, scopeResolver?: ScopeResolver);
+    /**
+     * Set system event source for debug events
+     */
+    setSystemEventSource(eventSource: IGenericEventSource<ISystemEvent> | undefined): void;
+    /**
+     * Resolve an entity reference with full matching logic
+     */
+    private resolveEntity;
+    /**
+     * Get entities by exact name match
+     */
+    private getEntitiesByName;
+    /**
+     * Get entities by type
+     */
+    private getEntitiesByType;
+    /**
+     * Get entities by synonym
+     */
+    private getEntitiesBySynonym;
+    /**
+     * 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
+     */
+    private getEntitiesByAdjective;
+    /**
+     * Filter entities by scope level
+     */
+    private filterByScope;
+    /**
+     * Score entities against a reference
+     */
+    private scoreEntities;
+    /**
+     * Resolve ambiguity between multiple matches
+     */
+    private resolveAmbiguity;
+    /**
+     * Resolve an entity directly by ID
+     * Used after disambiguation when user selects a specific entity
+     */
+    resolveEntityById(entityId: string, parsed: INounPhrase): IValidatedObjectReference | null;
+    /**
+     * Check if entity is visible to player
+     */
+    private isEntityVisible;
+    /**
+     * Check if entity is reachable by player
+     */
+    private isEntityReachable;
+    /**
+     * Check if entity is touchable by player
+     */
+    private isEntityTouchable;
+    /**
+     * Check if entity is in player's inventory
+     */
+    private isInPlayerInventory;
+    /**
+     * Check if entity meets required scope level
+     */
+    private checkEntityScope;
+    /**
+     * Get which senses can perceive an entity
+     */
+    private getPerceivedSenses;
+    /**
+     * Get entity display name
+     */
+    private getEntityName;
+    /**
+     * Get entity description
+     */
+    private getEntityDescription;
+    /**
+     * Get entity adjectives
+     */
+    private getEntityAdjectives;
+    /**
+     * Get entity synonyms
+     */
+    private getEntitySynonyms;
+    /**
+     * Get action metadata
+     */
+    private getActionMetadata;
+    /**
+     * Check action-specific preconditions
+     */
+    private checkActionPreconditions;
+    /**
+     * Emit a debug event
+     */
+    private emitDebugEvent;
+}
+//# sourceMappingURL=command-validator.d.ts.map

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

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