@sharpee/world-model 0.9.66-beta → 0.9.69-beta

package/capabilities/action-interceptor.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Action Interceptor interface (ADR-118)
+ *
+ * Interceptors allow entities to hook into stdlib action phases
+ * without replacing standard logic. This is the "Before/After" pattern
+ * from Inform 6/7, complementing the full delegation pattern in
+ * capability behaviors.
+ *
+ * Key difference from CapabilityBehavior:
+ * - CapabilityBehavior: Full delegation, trait owns ALL logic (LOWER, RAISE)
+ * - ActionInterceptor: Hooks into phases, action owns core logic (ENTER, PUT)
+ */
+import { IFEntity } from '../entities';
+import { WorldModel } from '../world';
+import { CapabilityEffect } from './types';
+/**
+ * Shared data object for passing data between interceptor phases.
+ * Mirrors CapabilitySharedData pattern from capability-behavior.ts.
+ *
+ * Interceptors can store data here during earlier phases (e.g., postValidate)
+ * and access it in later phases (e.g., postExecute, postReport).
+ */
+export type InterceptorSharedData = Record<string, unknown>;
+/**
+ * Result from interceptor validation hooks.
+ * Returning null means "continue with standard logic".
+ * Returning a result blocks or modifies the action.
+ */
+export interface InterceptorResult {
+    /** Whether the action can proceed */
+    valid: boolean;
+    /** Error code if validation failed (for message lookup) */
+    error?: string;
+    /** Additional context for error messages */
+    params?: Record<string, unknown>;
+}
+/**
+ * Action interceptor interface.
+ *
+ * Interceptors hook into stdlib action phases to customize behavior
+ * without reimplementing standard logic. All hooks are optional.
+ *
+ * Phase order:
+ * 1. preValidate - Before standard validation
+ * 2. (standard validation runs)
+ * 3. postValidate - After standard validation passes
+ * 4. (standard execute runs)
+ * 5. postExecute - After standard execution
+ * 6. (standard report runs)
+ * 7. postReport - Additional effects after standard report
+ *
+ * If validation fails at any point:
+ * - onBlocked - Called instead of execute/report phases
+ *
+ * @example
+ * ```typescript
+ * // Boat puncture interceptor - checks for sharp objects when entering
+ * const InflatableEnteringInterceptor: ActionInterceptor = {
+ *   postValidate(entity, world, actorId, sharedData) {
+ *     const inventory = world.getContents(actorId);
+ *     const sharpObject = inventory.find(item => item.puncturesBoat);
+ *     if (sharpObject) {
+ *       sharedData.willPuncture = true;
+ *       sharedData.punctureItem = sharpObject.name;
+ *     }
+ *     return null; // Allow entering to proceed
+ *   },
+ *
+ *   postExecute(entity, world, actorId, sharedData) {
+ *     if (!sharedData.willPuncture) return;
+ *     // Deflate the boat, eject player
+ *     const trait = entity.get(InflatableTrait);
+ *     trait.isInflated = false;
+ *     world.moveEntity(actorId, world.getLocation(entity.id));
+ *   },
+ *
+ *   postReport(entity, world, actorId, sharedData) {
+ *     if (!sharedData.willPuncture) return [];
+ *     return [createEffect('dungeo.boat.punctured', { item: sharedData.punctureItem })];
+ *   }
+ * };
+ * ```
+ */
+export interface ActionInterceptor {
+    /**
+     * Called BEFORE standard validation.
+     *
+     * Use this to block actions early based on entity-specific conditions.
+     * Return an InterceptorResult to block the action.
+     * Return null to continue with standard validation.
+     *
+     * @example
+     * // Troll blocks entering the Troll Room
+     * preValidate(entity, world, actorId, sharedData) {
+     *   if (trollIsAlive(world)) {
+     *     return { valid: false, error: 'dungeo.troll.blocks_path' };
+     *   }
+     *   return null;
+     * }
+     */
+    preValidate?(entity: IFEntity, world: WorldModel, actorId: string, sharedData: InterceptorSharedData): InterceptorResult | null;
+    /**
+     * Called AFTER standard validation passes.
+     *
+     * Use this to add entity-specific conditions that should block
+     * an otherwise valid action, or to set up data for postExecute.
+     * Return an InterceptorResult to block the action.
+     * Return null to continue with execution.
+     *
+     * @example
+     * // Check if player is carrying something that will puncture the boat
+     * postValidate(entity, world, actorId, sharedData) {
+     *   const sharp = findSharpObject(world, actorId);
+     *   if (sharp) {
+     *     sharedData.willPuncture = true;
+     *     sharedData.punctureItem = sharp.name;
+     *   }
+     *   return null; // Still allow entering
+     * }
+     */
+    postValidate?(entity: IFEntity, world: WorldModel, actorId: string, sharedData: InterceptorSharedData): InterceptorResult | null;
+    /**
+     * Called AFTER standard execution completes.
+     *
+     * Use this to perform additional mutations based on the action.
+     * Cannot prevent the action (use postValidate for that).
+     * Access data stored in sharedData during validation phases.
+     *
+     * @example
+     * // Glacier melts when torch is thrown at it
+     * postExecute(entity, world, actorId, sharedData) {
+     *   if (!sharedData.willMelt) return;
+     *   meltGlacier(world, entity.id);
+     *   openPassage(world, 'glacier-passage');
+     * }
+     */
+    postExecute?(entity: IFEntity, world: WorldModel, actorId: string, sharedData: InterceptorSharedData): void;
+    /**
+     * Called AFTER standard report.
+     *
+     * Return additional effects to emit after the standard effects.
+     * Return empty array if no additional effects needed.
+     *
+     * @example
+     * // Add glacier melting message
+     * postReport(entity, world, actorId, sharedData) {
+     *   if (!sharedData.melted) return [];
+     *   return [createEffect('dungeo.glacier.melted', { messageId: 'dungeo.glacier.melts' })];
+     * }
+     */
+    postReport?(entity: IFEntity, world: WorldModel, actorId: string, sharedData: InterceptorSharedData): CapabilityEffect[];
+    /**
+     * Called when action is blocked (validation failed).
+     *
+     * Use this to provide custom blocked handling for this entity.
+     * Return effects to emit, or null to use standard blocked handling.
+     *
+     * @example
+     * // Custom message when troll blocks entry
+     * onBlocked(entity, world, actorId, error, sharedData) {
+     *   if (error === 'dungeo.troll.blocks_path') {
+     *     return [createEffect('game.message', { messageId: 'dungeo.troll.snarls' })];
+     *   }
+     *   return null; // Use standard blocked handling
+     * }
+     */
+    onBlocked?(entity: IFEntity, world: WorldModel, actorId: string, error: string, sharedData: InterceptorSharedData): CapabilityEffect[] | null;
+}
+//# sourceMappingURL=action-interceptor.d.ts.map

package/capabilities/action-interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-interceptor.d.ts","sourceRoot":"","sources":["../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/capabilities/action-interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,CACV,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,qBAAqB,GAChC,iBAAiB,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,CACX,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,qBAAqB,GAChC,iBAAiB,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,CACV,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,qBAAqB,GAChC,IAAI,CAAC;IAER;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,CACT,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,EAAE,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,CACR,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,EAAE,GAAG,IAAI,CAAC;CAC9B"}

package/capabilities/action-interceptor.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Action Interceptor interface (ADR-118)
+ *
+ * Interceptors allow entities to hook into stdlib action phases
+ * without replacing standard logic. This is the "Before/After" pattern
+ * from Inform 6/7, complementing the full delegation pattern in
+ * capability behaviors.
+ *
+ * Key difference from CapabilityBehavior:
+ * - CapabilityBehavior: Full delegation, trait owns ALL logic (LOWER, RAISE)
+ * - ActionInterceptor: Hooks into phases, action owns core logic (ENTER, PUT)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=action-interceptor.js.map

package/capabilities/action-interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-interceptor.js","sourceRoot":"","sources":["../../../../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/capabilities/action-interceptor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/capabilities/capability-behavior.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Capability Behavior interface (ADR-090)
+ *
+ * Standard interface for behaviors that handle capability dispatch.
+ * Follows the same 4-phase pattern as stdlib actions for consistency.
+ */
+import { IFEntity } from '../entities';
+import { WorldModel } from '../world';
+import { CapabilityValidationResult, CapabilityEffect } from './types';
+/**
+ * Shared data object for passing data between behavior phases.
+ * Mirrors ActionContext.sharedData pattern from stdlib.
+ */
+export type CapabilitySharedData = Record<string, any>;
+/**
+ * Standard interface for capability behaviors.
+ *
+ * Behaviors implement this interface to handle specific capabilities
+ * (action IDs) declared by traits. When a trait declares a capability,
+ * a corresponding behavior must be registered to handle it.
+ *
+ * The 4-phase pattern mirrors stdlib actions:
+ * 1. validate - Check if the action can be performed
+ * 2. execute - Perform mutations (no events)
+ * 3. report - Generate success events
+ * 4. blocked - Generate failure events
+ *
+ * @example
+ * ```typescript
+ * const BasketLoweringBehavior: CapabilityBehavior = {
+ *   validate(entity, world, actorId, sharedData) {
+ *     const trait = entity.get(BasketElevatorTrait);
+ *     if (trait.position === 'bottom') {
+ *       return { valid: false, error: 'dungeo.basket.already_down' };
+ *     }
+ *     return { valid: true };
+ *   },
+ *
+ *   execute(entity, world, actorId, sharedData) {
+ *     const trait = entity.get(BasketElevatorTrait);
+ *     trait.position = 'bottom';
+ *     world.moveEntity(entity.id, trait.bottomRoomId);
+ *     sharedData.playerTransported = true; // Pass data to report()
+ *   },
+ *
+ *   report(entity, world, actorId, sharedData) {
+ *     const transported = sharedData.playerTransported;
+ *     return [createEffect('if.event.lowered', { target: entity.id })];
+ *   },
+ *
+ *   blocked(entity, world, actorId, error, sharedData) {
+ *     return [createEffect('action.blocked', { messageId: error })];
+ *   }
+ * };
+ * ```
+ */
+export interface CapabilityBehavior {
+    /**
+     * Phase 1: Validate whether the action can be performed.
+     *
+     * Check preconditions, state, and constraints. Return validation
+     * result with error code if action cannot proceed.
+     *
+     * @param entity - The entity being acted upon
+     * @param world - The world model for querying state
+     * @param actorId - ID of the actor performing the action
+     * @param sharedData - Mutable object for passing data between phases
+     * @returns Validation result with optional error info
+     */
+    validate(entity: IFEntity, world: WorldModel, actorId: string, sharedData: CapabilitySharedData): CapabilityValidationResult;
+    /**
+     * Phase 2: Execute mutations.
+     *
+     * Perform all state changes. Do NOT emit events here - that's
+     * the report phase's job. This separation enables clean rollback
+     * and consistent event generation.
+     *
+     * @param entity - The entity being acted upon
+     * @param world - The world model for mutations
+     * @param actorId - ID of the actor performing the action
+     * @param sharedData - Mutable object for passing data between phases
+     */
+    execute(entity: IFEntity, world: WorldModel, actorId: string, sharedData: CapabilitySharedData): void;
+    /**
+     * Phase 3: Report success.
+     *
+     * Generate effects describing what happened. Called after
+     * execute() succeeds. Return events with appropriate message IDs.
+     *
+     * @param entity - The entity that was acted upon
+     * @param world - The world model (post-mutation state)
+     * @param actorId - ID of the actor who performed the action
+     * @param sharedData - Mutable object for passing data between phases
+     * @returns Array of effects to emit
+     */
+    report(entity: IFEntity, world: WorldModel, actorId: string, sharedData: CapabilitySharedData): CapabilityEffect[];
+    /**
+     * Phase 4: Report failure.
+     *
+     * Generate effects for when validation fails. Called instead
+     * of execute()/report() when validate() returns invalid.
+     *
+     * @param entity - The entity that couldn't be acted upon
+     * @param world - The world model
+     * @param actorId - ID of the actor who attempted the action
+     * @param error - Error code from validation result
+     * @param sharedData - Mutable object for passing data between phases
+     * @returns Array of effects to emit
+     */
+    blocked(entity: IFEntity, world: WorldModel, actorId: string, error: string, sharedData: CapabilitySharedData): CapabilityEffect[];
+}
+//# sourceMappingURL=capability-behavior.d.ts.map

package/capabilities/capability-behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-behavior.d.ts","sourceRoot":"","sources":["../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/capabilities/capability-behavior.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEvE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,0BAA0B,CAAC;IAE7H;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAEtG;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,gBAAgB,EAAE,CAAC;IAEnH;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,gBAAgB,EAAE,CAAC;CACpI"}

package/capabilities/capability-behavior.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Capability Behavior interface (ADR-090)
+ *
+ * Standard interface for behaviors that handle capability dispatch.
+ * Follows the same 4-phase pattern as stdlib actions for consistency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=capability-behavior.js.map

package/capabilities/capability-behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-behavior.js","sourceRoot":"","sources":["../../../../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/capabilities/capability-behavior.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/capabilities/capability-defaults.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Capability Defaults (ADR-090 Extension)
+ *
+ * Global configuration for how capabilities are resolved when multiple
+ * entities claim the same capability. Stories can override per-registration.
+ */
+/**
+ * Resolution strategy when multiple entities claim the same capability.
+ */
+export type CapabilityResolution = 'first-wins' | 'any-blocks' | 'all-must-pass' | 'highest-priority';
+/**
+ * How the capability validation result affects the action.
+ */
+export type CapabilityMode = 'blocking' | 'advisory' | 'chain';
+/**
+ * Configuration for a capability.
+ */
+export interface CapabilityConfig {
+    /** How to resolve multiple entities claiming this capability */
+    resolution: CapabilityResolution;
+    /** How validation result affects the action */
+    mode: CapabilityMode;
+}
+/**
+ * Define default configuration for a capability.
+ *
+ * Called during platform or story initialization to set how a capability
+ * should behave when multiple entities claim it.
+ *
+ * @param capabilityId - The capability ID (e.g., 'if.scope.visible', 'if.action.taking')
+ * @param config - Partial config, missing values use defaults
+ *
+ * @example
+ * ```typescript
+ * // Visibility should block if ANY entity says it's hidden
+ * defineCapabilityDefaults('if.scope.visible', {
+ *   resolution: 'any-blocks',
+ *   mode: 'blocking'
+ * });
+ * ```
+ */
+export declare function defineCapabilityDefaults(capabilityId: string, config: Partial<CapabilityConfig>): void;
+/**
+ * Get configuration for a capability.
+ *
+ * Returns the registered config or defaults if not registered.
+ *
+ * @param capabilityId - The capability ID
+ * @returns The capability configuration
+ */
+export declare function getCapabilityConfig(capabilityId: string): CapabilityConfig;
+/**
+ * Check if a capability has explicit defaults defined.
+ *
+ * @param capabilityId - The capability ID
+ * @returns true if defaults have been defined
+ */
+export declare function hasCapabilityDefaults(capabilityId: string): boolean;
+/**
+ * Clear all capability defaults (for testing).
+ */
+export declare function clearCapabilityDefaults(): void;
+/**
+ * Get all defined capability defaults (for debugging/introspection).
+ */
+export declare function getAllCapabilityDefaults(): Map<string, CapabilityConfig>;
+//# sourceMappingURL=capability-defaults.d.ts.map

package/capabilities/capability-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-defaults.d.ts","sourceRoot":"","sources":["../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/capabilities/capability-defaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,kBAAkB,CAAC;AAEvB;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,UAAU,GACV,OAAO,CAAC;AAEZ;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,UAAU,EAAE,oBAAoB,CAAC;IACjC,+CAA+C;IAC/C,IAAI,EAAE,cAAc,CAAC;CACtB;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAChC,IAAI,CAKN;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAExE"}

package/capabilities/capability-defaults.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Capability Defaults (ADR-090 Extension)
+ *
+ * Global configuration for how capabilities are resolved when multiple
+ * entities claim the same capability. Stories can override per-registration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineCapabilityDefaults = defineCapabilityDefaults;
+exports.getCapabilityConfig = getCapabilityConfig;
+exports.hasCapabilityDefaults = hasCapabilityDefaults;
+exports.clearCapabilityDefaults = clearCapabilityDefaults;
+exports.getAllCapabilityDefaults = getAllCapabilityDefaults;
+/**
+ * Default configuration used when no specific config is defined.
+ */
+const DEFAULT_CONFIG = {
+    resolution: 'first-wins',
+    mode: 'blocking'
+};
+/**
+ * Registry of capability configurations.
+ */
+const capabilityDefaults = new Map();
+/**
+ * Define default configuration for a capability.
+ *
+ * Called during platform or story initialization to set how a capability
+ * should behave when multiple entities claim it.
+ *
+ * @param capabilityId - The capability ID (e.g., 'if.scope.visible', 'if.action.taking')
+ * @param config - Partial config, missing values use defaults
+ *
+ * @example
+ * ```typescript
+ * // Visibility should block if ANY entity says it's hidden
+ * defineCapabilityDefaults('if.scope.visible', {
+ *   resolution: 'any-blocks',
+ *   mode: 'blocking'
+ * });
+ * ```
+ */
+function defineCapabilityDefaults(capabilityId, config) {
+    capabilityDefaults.set(capabilityId, {
+        resolution: config.resolution ?? DEFAULT_CONFIG.resolution,
+        mode: config.mode ?? DEFAULT_CONFIG.mode
+    });
+}
+/**
+ * Get configuration for a capability.
+ *
+ * Returns the registered config or defaults if not registered.
+ *
+ * @param capabilityId - The capability ID
+ * @returns The capability configuration
+ */
+function getCapabilityConfig(capabilityId) {
+    return capabilityDefaults.get(capabilityId) ?? { ...DEFAULT_CONFIG };
+}
+/**
+ * Check if a capability has explicit defaults defined.
+ *
+ * @param capabilityId - The capability ID
+ * @returns true if defaults have been defined
+ */
+function hasCapabilityDefaults(capabilityId) {
+    return capabilityDefaults.has(capabilityId);
+}
+/**
+ * Clear all capability defaults (for testing).
+ */
+function clearCapabilityDefaults() {
+    capabilityDefaults.clear();
+}
+/**
+ * Get all defined capability defaults (for debugging/introspection).
+ */
+function getAllCapabilityDefaults() {
+    return new Map(capabilityDefaults);
+}
+//# sourceMappingURL=capability-defaults.js.map

package/capabilities/capability-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-defaults.js","sourceRoot":"","sources":["../../../../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/capabilities/capability-defaults.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AA4DH,4DAQC;AAUD,kDAEC;AAQD,sDAEC;AAKD,0DAEC;AAKD,4DAEC;AA3ED;;GAEG;AACH,MAAM,cAAc,GAAqB;IACvC,UAAU,EAAE,YAAY;IACxB,IAAI,EAAE,UAAU;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAA4B,CAAC;AAE/D;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,wBAAwB,CACtC,YAAoB,EACpB,MAAiC;IAEjC,kBAAkB,CAAC,GAAG,CAAC,YAAY,EAAE;QACnC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,cAAc,CAAC,UAAU;QAC1D,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,cAAc,CAAC,IAAI;KACzC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,mBAAmB,CAAC,YAAoB;IACtD,OAAO,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,GAAG,cAAc,EAAE,CAAC;AACvE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CAAC,YAAoB;IACxD,OAAO,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,SAAgB,uBAAuB;IACrC,kBAAkB,CAAC,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,SAAgB,wBAAwB;IACtC,OAAO,IAAI,GAAG,CAAC,kBAAkB,CAAC,CAAC;AACrC,CAAC"}

package/capabilities/capability-helpers.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Capability Helpers (ADR-090)
+ *
+ * Helper functions for working with trait capabilities.
+ * Used by capability-dispatch actions to find and check capabilities.
+ */
+import { ITrait } from '../traits/trait';
+import { IFEntity } from '../entities';
+/**
+ * Find a trait on the entity that declares the given capability.
+ *
+ * Entity resolution (which entity "lower X" refers to) is handled
+ * by the parser using scope math. Once resolved to a specific entity,
+ * this function finds the trait that handles the action.
+ *
+ * @param entity - The entity to search
+ * @param actionId - The action ID (capability) to find
+ * @returns The trait that claims the capability, or undefined
+ *
+ * @example
+ * ```typescript
+ * const trait = findTraitWithCapability(basket, 'if.action.lowering');
+ * if (trait) {
+ *   const behavior = getBehaviorForCapability(trait, 'if.action.lowering');
+ *   // ... dispatch to behavior
+ * }
+ * ```
+ */
+export declare function findTraitWithCapability(entity: IFEntity, actionId: string): ITrait | undefined;
+/**
+ * Check if an entity has any trait claiming a capability.
+ *
+ * @param entity - The entity to check
+ * @param actionId - The action ID (capability) to check for
+ * @returns True if entity has a trait with this capability
+ *
+ * @example
+ * ```typescript
+ * if (hasCapability(entity, 'if.action.lowering')) {
+ *   // Entity can be lowered
+ * }
+ * ```
+ */
+export declare function hasCapability(entity: IFEntity, actionId: string): boolean;
+/**
+ * Get all capabilities declared by an entity's traits.
+ *
+ * @param entity - The entity to inspect
+ * @returns Array of action IDs the entity can handle
+ */
+export declare function getEntityCapabilities(entity: IFEntity): string[];
+/**
+ * Type guard to check if a trait has a specific capability.
+ *
+ * @param trait - The trait to check
+ * @param actionId - The action ID to check for
+ * @param traitType - Optional: specific trait class to narrow to
+ * @returns True if trait has the capability (and is of specified type)
+ *
+ * @example
+ * ```typescript
+ * if (traitHasCapability(trait, 'if.action.lowering', BasketElevatorTrait)) {
+ *   // trait is narrowed to BasketElevatorTrait
+ *   console.log(trait.position);
+ * }
+ * ```
+ */
+export declare function traitHasCapability<T extends ITrait>(trait: ITrait, actionId: string, traitType?: new (...args: any[]) => T): trait is T;
+/**
+ * Find all traits on an entity that have capabilities.
+ *
+ * @param entity - The entity to inspect
+ * @returns Array of traits that declare at least one capability
+ */
+export declare function getCapableTraits(entity: IFEntity): ITrait[];
+//# sourceMappingURL=capability-helpers.d.ts.map

package/capabilities/capability-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-helpers.d.ts","sourceRoot":"","sources":["../../../../../../mnt/c/repotemp/sharpee/packages/world-model/src/capabilities/capability-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAqB,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,QAAQ,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,CAWhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EACjD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GACpC,KAAK,IAAI,CAAC,CAQZ;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,CAK3D"}

package/capabilities/capability-helpers.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Capability Helpers (ADR-090)
+ *
+ * Helper functions for working with trait capabilities.
+ * Used by capability-dispatch actions to find and check capabilities.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findTraitWithCapability = findTraitWithCapability;
+exports.hasCapability = hasCapability;
+exports.getEntityCapabilities = getEntityCapabilities;
+exports.traitHasCapability = traitHasCapability;
+exports.getCapableTraits = getCapableTraits;
+/**
+ * Find a trait on the entity that declares the given capability.
+ *
+ * Entity resolution (which entity "lower X" refers to) is handled
+ * by the parser using scope math. Once resolved to a specific entity,
+ * this function finds the trait that handles the action.
+ *
+ * @param entity - The entity to search
+ * @param actionId - The action ID (capability) to find
+ * @returns The trait that claims the capability, or undefined
+ *
+ * @example
+ * ```typescript
+ * const trait = findTraitWithCapability(basket, 'if.action.lowering');
+ * if (trait) {
+ *   const behavior = getBehaviorForCapability(trait, 'if.action.lowering');
+ *   // ... dispatch to behavior
+ * }
+ * ```
+ */
+function findTraitWithCapability(entity, actionId) {
+    for (const trait of entity.traits.values()) {
+        const traitClass = trait.constructor;
+        if (traitClass.capabilities?.includes(actionId)) {
+            return trait;
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if an entity has any trait claiming a capability.
+ *
+ * @param entity - The entity to check
+ * @param actionId - The action ID (capability) to check for
+ * @returns True if entity has a trait with this capability
+ *
+ * @example
+ * ```typescript
+ * if (hasCapability(entity, 'if.action.lowering')) {
+ *   // Entity can be lowered
+ * }
+ * ```
+ */
+function hasCapability(entity, actionId) {
+    return findTraitWithCapability(entity, actionId) !== undefined;
+}
+/**
+ * Get all capabilities declared by an entity's traits.
+ *
+ * @param entity - The entity to inspect
+ * @returns Array of action IDs the entity can handle
+ */
+function getEntityCapabilities(entity) {
+    const capabilities = [];
+    for (const trait of entity.traits.values()) {
+        const traitClass = trait.constructor;
+        if (traitClass.capabilities) {
+            capabilities.push(...traitClass.capabilities);
+        }
+    }
+    return capabilities;
+}
+/**
+ * Type guard to check if a trait has a specific capability.
+ *
+ * @param trait - The trait to check
+ * @param actionId - The action ID to check for
+ * @param traitType - Optional: specific trait class to narrow to
+ * @returns True if trait has the capability (and is of specified type)
+ *
+ * @example
+ * ```typescript
+ * if (traitHasCapability(trait, 'if.action.lowering', BasketElevatorTrait)) {
+ *   // trait is narrowed to BasketElevatorTrait
+ *   console.log(trait.position);
+ * }
+ * ```
+ */
+function traitHasCapability(trait, actionId, traitType) {
+    const traitClass = trait.constructor;
+    const hasAction = traitClass.capabilities?.includes(actionId) ?? false;
+    if (traitType) {
+        return hasAction && trait instanceof traitType;
+    }
+    return hasAction;
+}
+/**
+ * Find all traits on an entity that have capabilities.
+ *
+ * @param entity - The entity to inspect
+ * @returns Array of traits that declare at least one capability
+ */
+function getCapableTraits(entity) {
+    return Array.from(entity.traits.values()).filter(trait => {
+        const traitClass = trait.constructor;
+        return traitClass.capabilities && traitClass.capabilities.length > 0;
+    });
+}
+//# sourceMappingURL=capability-helpers.js.map