@sharpee/world-model 0.9.60-beta

package/dist/capabilities/entity-builder.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type-Safe Entity Builder (ADR-090)
+ *
+ * Builder pattern for creating entities with compile-time capability
+ * conflict detection. When two traits claim the same capability,
+ * TypeScript will error (and runtime will throw as backup).
+ */
+import { IFEntity } from '../entities';
+import { ITrait } from '../traits/trait';
+/**
+ * Type-safe entity builder that tracks claimed capabilities.
+ *
+ * Provides runtime checks for capability conflicts. TypeScript's
+ * type system can catch conflicts at compile time when traits
+ * declare capabilities with `as const`.
+ *
+ * @example
+ * ```typescript
+ * const basket = new EntityBuilder(entity)
+ *   .add(new IdentityTrait({ name: 'basket' }))
+ *   .add(new ContainerTrait())
+ *   .add(new BasketElevatorTrait({ ... }))  // claims: lowering, raising
+ *   .build();
+ *
+ * // Runtime error - duplicate capability:
+ * const bad = new EntityBuilder(entity)
+ *   .add(new BasketElevatorTrait({ ... }))  // claims: lowering
+ *   .add(new MirrorPoleTrait({ ... }))      // also claims: lowering
+ *   .build();  // throws!
+ * ```
+ */
+export declare class EntityBuilder {
+    private entity;
+    private claimedCaps;
+    constructor(entity: IFEntity);
+    /**
+     * Add a trait to the entity.
+     *
+     * Checks for capability conflicts at runtime. If two traits
+     * claim the same capability, throws an error.
+     *
+     * @param trait - The trait to add
+     * @returns This builder for chaining
+     * @throws Error if capability conflict detected
+     */
+    add<T extends ITrait>(trait: T): this;
+    /**
+     * Build and return the entity.
+     */
+    build(): IFEntity;
+    /**
+     * Get all capabilities claimed so far.
+     */
+    getClaimedCapabilities(): string[];
+    /**
+     * Find which trait claimed a capability.
+     */
+    private findTraitWithCapability;
+}
+/**
+ * Create an entity builder for type-safe trait composition.
+ *
+ * This is a convenience function that wraps an existing entity
+ * in a builder. Use when you want capability conflict checking.
+ *
+ * @param entity - The entity to wrap
+ * @returns A new EntityBuilder
+ *
+ * @example
+ * ```typescript
+ * const basket = buildEntity(world.createEntity('basket', EntityType.CONTAINER))
+ *   .add(new IdentityTrait({ name: 'rusty iron basket' }))
+ *   .add(new ContainerTrait({ capacity: { maxItems: 10 } }))
+ *   .add(new BasketElevatorTrait({ ... }))
+ *   .build();
+ * ```
+ */
+export declare function buildEntity(entity: IFEntity): EntityBuilder;
+//# sourceMappingURL=entity-builder.d.ts.map

package/dist/capabilities/entity-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-builder.d.ts","sourceRoot":"","sources":["../../src/capabilities/entity-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,MAAM,EAAqB,MAAM,iBAAiB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,WAAW,CAAqB;gBAE5B,MAAM,EAAE,QAAQ;IAI5B;;;;;;;;;OASG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAyBrC;;OAEG;IACH,KAAK,IAAI,QAAQ;IAIjB;;OAEG;IACH,sBAAsB,IAAI,MAAM,EAAE;IAIlC;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAShC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,GAAG,aAAa,CAE3D"}

package/dist/capabilities/entity-builder.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Type-Safe Entity Builder (ADR-090)
+ *
+ * Builder pattern for creating entities with compile-time capability
+ * conflict detection. When two traits claim the same capability,
+ * TypeScript will error (and runtime will throw as backup).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityBuilder = void 0;
+exports.buildEntity = buildEntity;
+/**
+ * Type-safe entity builder that tracks claimed capabilities.
+ *
+ * Provides runtime checks for capability conflicts. TypeScript's
+ * type system can catch conflicts at compile time when traits
+ * declare capabilities with `as const`.
+ *
+ * @example
+ * ```typescript
+ * const basket = new EntityBuilder(entity)
+ *   .add(new IdentityTrait({ name: 'basket' }))
+ *   .add(new ContainerTrait())
+ *   .add(new BasketElevatorTrait({ ... }))  // claims: lowering, raising
+ *   .build();
+ *
+ * // Runtime error - duplicate capability:
+ * const bad = new EntityBuilder(entity)
+ *   .add(new BasketElevatorTrait({ ... }))  // claims: lowering
+ *   .add(new MirrorPoleTrait({ ... }))      // also claims: lowering
+ *   .build();  // throws!
+ * ```
+ */
+class EntityBuilder {
+    entity;
+    claimedCaps = new Set();
+    constructor(entity) {
+        this.entity = entity;
+    }
+    /**
+     * Add a trait to the entity.
+     *
+     * Checks for capability conflicts at runtime. If two traits
+     * claim the same capability, throws an error.
+     *
+     * @param trait - The trait to add
+     * @returns This builder for chaining
+     * @throws Error if capability conflict detected
+     */
+    add(trait) {
+        const traitClass = trait.constructor;
+        const newCaps = traitClass.capabilities ?? [];
+        // Check for capability conflicts
+        for (const cap of newCaps) {
+            if (this.claimedCaps.has(cap)) {
+                // Find which trait already claimed it
+                const existingTrait = this.findTraitWithCapability(cap);
+                const existingType = existingTrait
+                    ? existingTrait.constructor.type
+                    : 'unknown';
+                throw new Error(`Entity "${this.entity.id}": capability "${cap}" already claimed by trait "${existingType}". ` +
+                    `New trait "${traitClass.type}" cannot also claim it.`);
+            }
+            this.claimedCaps.add(cap);
+        }
+        this.entity.add(trait);
+        return this;
+    }
+    /**
+     * Build and return the entity.
+     */
+    build() {
+        return this.entity;
+    }
+    /**
+     * Get all capabilities claimed so far.
+     */
+    getClaimedCapabilities() {
+        return Array.from(this.claimedCaps);
+    }
+    /**
+     * Find which trait claimed a capability.
+     */
+    findTraitWithCapability(capability) {
+        for (const trait of this.entity.traits.values()) {
+            const traitClass = trait.constructor;
+            if (traitClass.capabilities?.includes(capability)) {
+                return trait;
+            }
+        }
+        return undefined;
+    }
+}
+exports.EntityBuilder = EntityBuilder;
+/**
+ * Create an entity builder for type-safe trait composition.
+ *
+ * This is a convenience function that wraps an existing entity
+ * in a builder. Use when you want capability conflict checking.
+ *
+ * @param entity - The entity to wrap
+ * @returns A new EntityBuilder
+ *
+ * @example
+ * ```typescript
+ * const basket = buildEntity(world.createEntity('basket', EntityType.CONTAINER))
+ *   .add(new IdentityTrait({ name: 'rusty iron basket' }))
+ *   .add(new ContainerTrait({ capacity: { maxItems: 10 } }))
+ *   .add(new BasketElevatorTrait({ ... }))
+ *   .build();
+ * ```
+ */
+function buildEntity(entity) {
+    return new EntityBuilder(entity);
+}
+//# sourceMappingURL=entity-builder.js.map

package/dist/capabilities/entity-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-builder.js","sourceRoot":"","sources":["../../src/capabilities/entity-builder.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAoHH,kCAEC;AAjHD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,aAAa;IAChB,MAAM,CAAW;IACjB,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IAExC,YAAY,MAAgB;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;OASG;IACH,GAAG,CAAmB,KAAQ;QAC5B,MAAM,UAAU,GAAG,KAAK,CAAC,WAAgC,CAAC;QAC1D,MAAM,OAAO,GAAG,UAAU,CAAC,YAAY,IAAI,EAAE,CAAC;QAE9C,iCAAiC;QACjC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9B,sCAAsC;gBACtC,MAAM,aAAa,GAAG,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC;gBACxD,MAAM,YAAY,GAAG,aAAa;oBAChC,CAAC,CAAE,aAAa,CAAC,WAAiC,CAAC,IAAI;oBACvD,CAAC,CAAC,SAAS,CAAC;gBAEd,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,+BAA+B,YAAY,KAAK;oBAC9F,cAAc,UAAU,CAAC,IAAI,yBAAyB,CACvD,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,sBAAsB;QACpB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACK,uBAAuB,CAAC,UAAkB;QAChD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YAChD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAgC,CAAC;YAC1D,IAAI,UAAU,CAAC,YAAY,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAClD,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AArED,sCAqEC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,WAAW,CAAC,MAAgB;IAC1C,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC"}

package/dist/capabilities/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Capability Dispatch System (ADR-090)
+ *
+ * Entity-centric action dispatch where traits declare capabilities
+ * (action IDs they respond to) and behaviors implement the logic.
+ */
+export { CapabilityValidationResult, CapabilityEffect, createEffect } from './types';
+export { CapabilityBehavior, CapabilitySharedData } from './capability-behavior';
+export { TraitBehaviorBinding, BehaviorRegistrationOptions, registerCapabilityBehavior, getBehaviorForCapability, getBehaviorBinding, hasCapabilityBehavior, unregisterCapabilityBehavior, clearCapabilityRegistry, getAllCapabilityBindings } from './capability-registry';
+export { CapabilityResolution, CapabilityMode, CapabilityConfig, defineCapabilityDefaults, getCapabilityConfig, hasCapabilityDefaults, clearCapabilityDefaults, getAllCapabilityDefaults } from './capability-defaults';
+export { findTraitWithCapability, hasCapability, getEntityCapabilities, traitHasCapability, getCapableTraits } from './capability-helpers';
+export { EntityBuilder, buildEntity } from './entity-builder';
+//# sourceMappingURL=index.d.ts.map

package/dist/capabilities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,YAAY,EACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,aAAa,EACb,WAAW,EACZ,MAAM,kBAAkB,CAAC"}

package/dist/capabilities/index.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Capability Dispatch System (ADR-090)
+ *
+ * Entity-centric action dispatch where traits declare capabilities
+ * (action IDs they respond to) and behaviors implement the logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEntity = exports.EntityBuilder = exports.getCapableTraits = exports.traitHasCapability = exports.getEntityCapabilities = exports.hasCapability = exports.findTraitWithCapability = exports.getAllCapabilityDefaults = exports.clearCapabilityDefaults = exports.hasCapabilityDefaults = exports.getCapabilityConfig = exports.defineCapabilityDefaults = exports.getAllCapabilityBindings = exports.clearCapabilityRegistry = exports.unregisterCapabilityBehavior = exports.hasCapabilityBehavior = exports.getBehaviorBinding = exports.getBehaviorForCapability = exports.registerCapabilityBehavior = exports.createEffect = void 0;
+// Types
+var types_1 = require("./types");
+Object.defineProperty(exports, "createEffect", { enumerable: true, get: function () { return types_1.createEffect; } });
+// Registry
+var capability_registry_1 = require("./capability-registry");
+Object.defineProperty(exports, "registerCapabilityBehavior", { enumerable: true, get: function () { return capability_registry_1.registerCapabilityBehavior; } });
+Object.defineProperty(exports, "getBehaviorForCapability", { enumerable: true, get: function () { return capability_registry_1.getBehaviorForCapability; } });
+Object.defineProperty(exports, "getBehaviorBinding", { enumerable: true, get: function () { return capability_registry_1.getBehaviorBinding; } });
+Object.defineProperty(exports, "hasCapabilityBehavior", { enumerable: true, get: function () { return capability_registry_1.hasCapabilityBehavior; } });
+Object.defineProperty(exports, "unregisterCapabilityBehavior", { enumerable: true, get: function () { return capability_registry_1.unregisterCapabilityBehavior; } });
+Object.defineProperty(exports, "clearCapabilityRegistry", { enumerable: true, get: function () { return capability_registry_1.clearCapabilityRegistry; } });
+Object.defineProperty(exports, "getAllCapabilityBindings", { enumerable: true, get: function () { return capability_registry_1.getAllCapabilityBindings; } });
+// Defaults and configuration
+var capability_defaults_1 = require("./capability-defaults");
+Object.defineProperty(exports, "defineCapabilityDefaults", { enumerable: true, get: function () { return capability_defaults_1.defineCapabilityDefaults; } });
+Object.defineProperty(exports, "getCapabilityConfig", { enumerable: true, get: function () { return capability_defaults_1.getCapabilityConfig; } });
+Object.defineProperty(exports, "hasCapabilityDefaults", { enumerable: true, get: function () { return capability_defaults_1.hasCapabilityDefaults; } });
+Object.defineProperty(exports, "clearCapabilityDefaults", { enumerable: true, get: function () { return capability_defaults_1.clearCapabilityDefaults; } });
+Object.defineProperty(exports, "getAllCapabilityDefaults", { enumerable: true, get: function () { return capability_defaults_1.getAllCapabilityDefaults; } });
+// Helpers
+var capability_helpers_1 = require("./capability-helpers");
+Object.defineProperty(exports, "findTraitWithCapability", { enumerable: true, get: function () { return capability_helpers_1.findTraitWithCapability; } });
+Object.defineProperty(exports, "hasCapability", { enumerable: true, get: function () { return capability_helpers_1.hasCapability; } });
+Object.defineProperty(exports, "getEntityCapabilities", { enumerable: true, get: function () { return capability_helpers_1.getEntityCapabilities; } });
+Object.defineProperty(exports, "traitHasCapability", { enumerable: true, get: function () { return capability_helpers_1.traitHasCapability; } });
+Object.defineProperty(exports, "getCapableTraits", { enumerable: true, get: function () { return capability_helpers_1.getCapableTraits; } });
+// Entity builder
+var entity_builder_1 = require("./entity-builder");
+Object.defineProperty(exports, "EntityBuilder", { enumerable: true, get: function () { return entity_builder_1.EntityBuilder; } });
+Object.defineProperty(exports, "buildEntity", { enumerable: true, get: function () { return entity_builder_1.buildEntity; } });
+//# sourceMappingURL=index.js.map

package/dist/capabilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,QAAQ;AACR,iCAIiB;AADf,qGAAA,YAAY,OAAA;AAMd,WAAW;AACX,6DAU+B;AAP7B,iIAAA,0BAA0B,OAAA;AAC1B,+HAAA,wBAAwB,OAAA;AACxB,yHAAA,kBAAkB,OAAA;AAClB,4HAAA,qBAAqB,OAAA;AACrB,mIAAA,4BAA4B,OAAA;AAC5B,8HAAA,uBAAuB,OAAA;AACvB,+HAAA,wBAAwB,OAAA;AAG1B,6BAA6B;AAC7B,6DAS+B;AAL7B,+HAAA,wBAAwB,OAAA;AACxB,0HAAA,mBAAmB,OAAA;AACnB,4HAAA,qBAAqB,OAAA;AACrB,8HAAA,uBAAuB,OAAA;AACvB,+HAAA,wBAAwB,OAAA;AAG1B,UAAU;AACV,2DAM8B;AAL5B,6HAAA,uBAAuB,OAAA;AACvB,mHAAA,aAAa,OAAA;AACb,2HAAA,qBAAqB,OAAA;AACrB,wHAAA,kBAAkB,OAAA;AAClB,sHAAA,gBAAgB,OAAA;AAGlB,iBAAiB;AACjB,mDAG0B;AAFxB,+GAAA,aAAa,OAAA;AACb,6GAAA,WAAW,OAAA"}

package/dist/capabilities/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Capability dispatch types (ADR-090)
+ *
+ * Types for entity-centric action dispatch where traits declare
+ * which verbs/actions they respond to.
+ */
+/**
+ * Result from capability behavior validation.
+ * Mirrors stdlib's ValidationResult for consistency.
+ */
+export interface CapabilityValidationResult {
+    /** Whether the behavior can execute */
+    valid: boolean;
+    /** Error code if validation failed (for message lookup) */
+    error?: string;
+    /** Additional context for error messages */
+    params?: Record<string, any>;
+    /** Data to pass to execute/report phases */
+    data?: Record<string, any>;
+}
+/**
+ * Effect returned by capability behaviors.
+ * Simplified version - actual emit() is in event-processor.
+ */
+export interface CapabilityEffect {
+    /** Event type (e.g., 'if.event.lowered', 'action.blocked') */
+    type: string;
+    /** Event payload */
+    payload: Record<string, any>;
+}
+/**
+ * Helper to create effects (mirrors event-processor's emit)
+ */
+export declare function createEffect(type: string, payload: Record<string, any>): CapabilityEffect;
+//# sourceMappingURL=types.d.ts.map

package/dist/capabilities/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/capabilities/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,gBAAgB,CAEzF"}

package/dist/capabilities/types.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Capability dispatch types (ADR-090)
+ *
+ * Types for entity-centric action dispatch where traits declare
+ * which verbs/actions they respond to.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEffect = createEffect;
+/**
+ * Helper to create effects (mirrors event-processor's emit)
+ */
+function createEffect(type, payload) {
+    return { type, payload };
+}
+//# sourceMappingURL=types.js.map

package/dist/capabilities/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/capabilities/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AA+BH,oCAEC;AALD;;GAEG;AACH,SAAgB,YAAY,CAAC,IAAY,EAAE,OAA4B;IACrE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC"}

package/dist/commands/command-types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Command processing error types and result types
+ */
+import type { IParseError } from './parsed-command';
+import type { IValidationError, IValidatedCommand } from './validated-command';
+/**
+ * Errors that can occur during execution
+ */
+export interface IExecutionError {
+    type: 'EXECUTION_ERROR';
+    code: 'HANDLER_ERROR' | 'EVENT_GENERATION_FAILED' | 'STATE_CORRUPTION';
+    message: string;
+    validated: IValidatedCommand;
+    error?: Error;
+}
+/**
+ * Union type for all command processing errors
+ */
+export type CommandError = IParseError | IValidationError | IExecutionError;
+/**
+ * Result type for command processing phases
+ */
+export type CommandResult<T, E = CommandError> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: E;
+};
+//# sourceMappingURL=command-types.d.ts.map

package/dist/commands/command-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-types.d.ts","sourceRoot":"","sources":["../../src/commands/command-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,eAAe,GAAG,yBAAyB,GAAG,kBAAkB,CAAC;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAE5E;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,IACzC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC"}

package/dist/commands/command-types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Command processing error types and result types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=command-types.js.map

package/dist/commands/command-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-types.js","sourceRoot":"","sources":["../../src/commands/command-types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/commands/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Command types for the IF command processing pipeline
+ */
+export * from './parsed-command';
+export * from './validated-command';
+export * from './command-types';
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}

package/dist/commands/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Command types for the IF command processing pipeline
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./parsed-command"), exports);
+__exportStar(require("./validated-command"), exports);
+__exportStar(require("./command-types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,mDAAiC;AACjC,sDAAoC;AACpC,kDAAgC"}

package/dist/commands/parsed-command.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Command types for the parsing phase
+ * These types represent the syntactic structure of commands
+ * without any world knowledge or entity resolution
+ */
+export interface IParsedObjectReference {
+    /** Original text from input */
+    text: string;
+    /** Possible vocabulary matches */
+    candidates: string[];
+    /** Optional modifiers (adjectives, etc.) */
+    modifiers?: string[];
+}
+export interface IParsedCommandV1 {
+    /** Raw input text */
+    rawInput: string;
+    /** Identified action verb */
+    action: string;
+    /** Direct object if present */
+    directObject?: IParsedObjectReference;
+    /** Indirect object if present */
+    indirectObject?: IParsedObjectReference;
+    /** Preposition if present */
+    preposition?: string;
+    /** Additional parsed elements */
+    extras?: Record<string, any>;
+}
+/**
+ * Parts of speech classification
+ */
+export declare enum PartOfSpeech {
+    VERB = "VERB",
+    NOUN = "NOUN",
+    ADJECTIVE = "ADJECTIVE",
+    ARTICLE = "ARTICLE",
+    PREPOSITION = "PREPOSITION",
+    PRONOUN = "PRONOUN",
+    DETERMINER = "DETERMINER",
+    CONJUNCTION = "CONJUNCTION",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Token candidate from vocabulary
+ */
+export interface ITokenCandidate {
+    /** Vocabulary ID */
+    id: string;
+    /** Type in vocabulary (verb, noun, etc.) */
+    type: string;
+    /** Confidence score */
+    confidence: number;
+}
+/**
+ * Individual token with full information
+ */
+export interface IToken {
+    /** Original word as typed */
+    word: string;
+    /** Normalized form (lowercase, etc.) */
+    normalized: string;
+    /** Character position in original input */
+    position: number;
+    /** Length of the token */
+    length: number;
+    /** Possible parts of speech */
+    partOfSpeech: PartOfSpeech[];
+    /** Vocabulary candidates for this token */
+    candidates: ITokenCandidate[];
+}
+/**
+ * Verb phrase structure
+ */
+export interface IVerbPhrase {
+    /** Indices into token array */
+    tokens: number[];
+    /** Original text (e.g., "look at") */
+    text: string;
+    /** Main verb */
+    head: string;
+    /** Verb particles ("at" in "look at") */
+    particles?: string[];
+}
+/**
+ * Noun phrase structure with all information preserved
+ */
+export interface INounPhrase {
+    /** Indices into token array */
+    tokens: number[];
+    /** Original complete text (e.g., "the small red ball") */
+    text: string;
+    /** Head noun ("ball") */
+    head: string;
+    /** Modifiers/adjectives ("small", "red") */
+    modifiers: string[];
+    /** Articles ("the", "a", "an") */
+    articles: string[];
+    /** Determiners ("all", "every", "some") */
+    determiners: string[];
+    /** Vocabulary candidates for the head noun */
+    candidates: string[];
+    /** True if this represents "all" (e.g., "take all") */
+    isAll?: boolean;
+    /** True if this is a list of objects (e.g., "take knife and lamp") */
+    isList?: boolean;
+    /** Individual items when isList is true */
+    items?: INounPhrase[];
+    /** Pre-resolved entity ID (e.g., when "it" was resolved during parsing) */
+    entityId?: string;
+    /** True if this noun phrase was a pronoun (e.g., "it", "them") */
+    wasPronoun?: boolean;
+}
+/**
+ * Preposition phrase structure
+ */
+export interface IPrepPhrase {
+    /** Indices into token array */
+    tokens: number[];
+    /** Preposition text */
+    text: string;
+}
+/**
+ * Result of parsing phase - rich structure with all information preserved
+ */
+export interface IParsedCommand {
+    /** Raw input text exactly as typed */
+    rawInput: string;
+    /** All tokens with position and classification */
+    tokens: IToken[];
+    /** Structured command components */
+    structure: {
+        /** Verb phrase */
+        verb: IVerbPhrase;
+        /** Direct object noun phrase */
+        directObject?: INounPhrase;
+        /** Preposition phrase */
+        preposition?: IPrepPhrase;
+        /** Indirect object noun phrase */
+        indirectObject?: INounPhrase;
+    };
+    /** Which grammar pattern matched (e.g., "VERB_NOUN_PREP_NOUN") */
+    pattern: string;
+    /** Parser confidence in this interpretation */
+    confidence: number;
+    /** Identified action (for compatibility) */
+    action: string;
+    /** Additional parsed elements */
+    extras?: Record<string, any>;
+    /** Raw text slot values (for patterns with .text() slots or :slot... syntax) */
+    textSlots?: Map<string, string>;
+    /** Excluded noun phrases for "all but X" patterns */
+    excluded?: INounPhrase[];
+    /** Instrument noun phrase for "with/through/using" clauses */
+    instrument?: INounPhrase;
+    /** Typed slot values for non-entity slots (number, ordinal, direction, etc.) */
+    typedSlots?: Map<string, import('@sharpee/if-domain').TypedSlotValue>;
+    /** Vocabulary slot matches (from .fromVocabulary() patterns) */
+    vocabularySlots?: Map<string, import('@sharpee/if-domain').GrammarVocabularyMatch>;
+    /** Matched manner adverb (from .manner() patterns) - feeds intention.manner */
+    manner?: string;
+}
+/**
+ * Parse error codes
+ *
+ * Error hierarchy (most specific to least):
+ * - NO_VERB: Empty or no verb detected
+ * - UNKNOWN_VERB: First word isn't a known verb
+ * - MISSING_OBJECT: Verb needs a direct object
+ * - MISSING_INDIRECT: Verb needs an indirect object (where/what)
+ * - ENTITY_NOT_FOUND: Object name not recognized
+ * - SCOPE_VIOLATION: Object exists but can't be accessed
+ * - AMBIGUOUS_INPUT: Multiple valid interpretations
+ * - UNKNOWN_COMMAND: Generic fallback (legacy)
+ * - INVALID_SYNTAX: Generic fallback (legacy)
+ */
+export type ParseErrorCode = 'NO_VERB' | 'UNKNOWN_VERB' | 'MISSING_OBJECT' | 'MISSING_INDIRECT' | 'ENTITY_NOT_FOUND' | 'SCOPE_VIOLATION' | 'AMBIGUOUS_INPUT' | 'UNKNOWN_COMMAND' | 'INVALID_SYNTAX';
+/**
+ * Errors that can occur during parsing
+ */
+export interface IParseError {
+    type: 'PARSE_ERROR';
+    code: ParseErrorCode;
+    /** Message ID for lang layer lookup (e.g., 'parser.error.unknownVerb') */
+    messageId: string;
+    /** Fallback message if lang layer lookup fails */
+    message: string;
+    /** Original input */
+    input: string;
+    /** Character position of error (if applicable) */
+    position?: number;
+    /** Recognized verb (if any) */
+    verb?: string;
+    /** The word that failed (for ENTITY_NOT_FOUND, UNKNOWN_VERB) */
+    failedWord?: string;
+    /** Which slot failed (directObject, indirectObject) */
+    slot?: string;
+    /** Suggestion for correction */
+    suggestion?: string;
+    /** For AMBIGUOUS_INPUT: the candidates */
+    candidates?: Array<{
+        entityId: string;
+        label: string;
+    }>;
+}
+//# sourceMappingURL=parsed-command.d.ts.map

package/dist/commands/parsed-command.d.ts.map

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

package/dist/commands/parsed-command.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Command types for the parsing phase
+ * These types represent the syntactic structure of commands
+ * without any world knowledge or entity resolution
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PartOfSpeech = void 0;
+// New rich information-preserving types
+/**
+ * Parts of speech classification
+ */
+var PartOfSpeech;
+(function (PartOfSpeech) {
+    PartOfSpeech["VERB"] = "VERB";
+    PartOfSpeech["NOUN"] = "NOUN";
+    PartOfSpeech["ADJECTIVE"] = "ADJECTIVE";
+    PartOfSpeech["ARTICLE"] = "ARTICLE";
+    PartOfSpeech["PREPOSITION"] = "PREPOSITION";
+    PartOfSpeech["PRONOUN"] = "PRONOUN";
+    PartOfSpeech["DETERMINER"] = "DETERMINER";
+    PartOfSpeech["CONJUNCTION"] = "CONJUNCTION";
+    PartOfSpeech["UNKNOWN"] = "UNKNOWN";
+})(PartOfSpeech || (exports.PartOfSpeech = PartOfSpeech = {}));
+//# sourceMappingURL=parsed-command.js.map