@sharpee/stdlib 3.0.0 → 3.3.0

package/actions/lifecycle/descriptor.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Interceptor lifecycle descriptors (ADR-228).
+ *
+ * A descriptor is an action's declarative statement of its interceptor
+ * surface: which command entities carry interceptors under which action
+ * ids, in what order they are consulted, and which rare special contracts
+ * apply. The shared lifecycle engine (`lifecycle-engine.ts`) executes the
+ * ADR-228 rulings (D1 veto-only, D2 structured onBlocked, D3 all-entities
+ * fixed order, D4 per-item multi-object) against this declaration — the
+ * action never hand-rolls hook plumbing.
+ *
+ * An action is "wired" for interceptors iff it has a descriptor; the
+ * stdlib wired-action registry (ADR-228 D5) is derived mechanically from
+ * the descriptor table, never hand-maintained.
+ *
+ * Public interface: `ActionLifecycleDescriptor`, `EntitySlotSpec`,
+ * `LifecycleContracts`.
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ */
+import { IFEntity } from '@sharpee/world-model';
+import { ActionContext } from '../enhanced-types.js';
+/**
+ * One consultable entity slot of a command.
+ *
+ * Slots are declared in the published consultation order (ADR-228 D3-B):
+ * direct object → indirect object / instrument → action-specific implicit
+ * entities (e.g. going's door, source room, destination room; exiting's
+ * current container). Validate-phase vetoes stop the chain at the first
+ * vetoing slot; postExecute/postReport run for every slot that survived.
+ *
+ * Both-ids rule (ADR-228 D6): a slot may consult more than one action id
+ * (specific id first — e.g. removing consults `if.action.removing` then
+ * `if.action.taking` on the item). One physical operation can therefore
+ * fire hooks under two ids; a trait should register its interceptor under
+ * exactly one of them to avoid double-mutation.
+ */
+export interface EntitySlotSpec {
+    /**
+     * Slot identity — stable, human-readable, unique within the descriptor
+     * (e.g. 'directObject', 'container', 'item', 'weapon', 'door', 'source',
+     * 'destination'). Used in docs, diagnostics, and tests.
+     */
+    id: string;
+    /**
+     * Action ids to consult on this slot's entity, in consultation order
+     * (specific id before delegated id per D6).
+     */
+    actionIds: string[];
+    /**
+     * Resolve this slot's entity from the command. Return `undefined` when
+     * the slot is not present in this particular command (e.g. no indirect
+     * object) — the slot is then skipped, never an error.
+     *
+     * Implicit-entity slots resolve here too (going's source/destination
+     * rooms, exiting's current container) — resolution is not limited to
+     * parsed command objects.
+     */
+    resolve(context: ActionContext): IFEntity | undefined;
+    /**
+     * Optional seed for the slot's per-consultation sharedData, applied at
+     * resolve time. Used for symmetric cross-entity context (ADR-228 D3
+     * sub-ruling: the item-side hook in putting/inserting receives the
+     * container id, mirroring how the container's hook receives the item id).
+     *
+     * @param context - The action context.
+     * @param entity - This slot's resolved entity.
+     * @param multiObjectItem - In a multi-object per-item resolution (D4),
+     *   the item currently being processed — so a shared slot (e.g. the
+     *   container in "put all in case") can seed per-item context like the
+     *   item id. Undefined for single-object commands and for the item slot
+     *   itself (where `entity` IS the item).
+     */
+    seedData?(context: ActionContext, entity: IFEntity, multiObjectItem?: IFEntity): Record<string, unknown>;
+}
+/**
+ * Rare, explicit special contracts (ADR-228 D7.3). A contract changes the
+ * engine's standard hook semantics for the action and MUST be declared
+ * here — never encoded as a comment or an ad-hoc branch in the action.
+ */
+export interface LifecycleContracts {
+    /**
+     * attacking only: when a combatant target's interceptor implements
+     * postExecute, that hook REPLACES the action's standard combat
+     * resolution instead of running after it. The action reads this flag to
+     * decide whether to run its core execute logic; the engine still runs
+     * the hook itself normally.
+     */
+    postExecuteReplacesCore?: boolean;
+}
+/**
+ * An action's declarative interceptor surface (ADR-228 D0-B).
+ *
+ * Supplied by the action to the lifecycle engine at each phase boundary.
+ * Descriptors are static per action (module-level constants) — anything
+ * command-dependent lives in slot `resolve`/`seedData` functions.
+ */
+export interface ActionLifecycleDescriptor {
+    /**
+     * The action's primary id (e.g. `IFActions.TAKING`). Used for
+     * diagnostics and the D5 registry derivation.
+     */
+    actionId: string;
+    /**
+     * Entity slots in the published consultation order (D3-B): direct
+     * object → indirect/instrument → implicit entities.
+     */
+    slots: EntitySlotSpec[];
+    /** Rare special contracts (D7.3). Omit unless the ADR names one. */
+    contracts?: LifecycleContracts;
+}
+//# sourceMappingURL=descriptor.d.ts.map

package/actions/lifecycle/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;IAEtD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,CACP,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,QAAQ,EAChB,eAAe,CAAC,EAAE,QAAQ,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IAExB,oEAAoE;IACpE,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC"}

package/actions/lifecycle/descriptor.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Interceptor lifecycle descriptors (ADR-228).
+ *
+ * A descriptor is an action's declarative statement of its interceptor
+ * surface: which command entities carry interceptors under which action
+ * ids, in what order they are consulted, and which rare special contracts
+ * apply. The shared lifecycle engine (`lifecycle-engine.ts`) executes the
+ * ADR-228 rulings (D1 veto-only, D2 structured onBlocked, D3 all-entities
+ * fixed order, D4 per-item multi-object) against this declaration — the
+ * action never hand-rolls hook plumbing.
+ *
+ * An action is "wired" for interceptors iff it has a descriptor; the
+ * stdlib wired-action registry (ADR-228 D5) is derived mechanically from
+ * the descriptor table, never hand-maintained.
+ *
+ * Public interface: `ActionLifecycleDescriptor`, `EntitySlotSpec`,
+ * `LifecycleContracts`.
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=descriptor.js.map

package/actions/lifecycle/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/descriptor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/actions/lifecycle/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Interceptor lifecycle engine barrel (ADR-228).
+ *
+ * The shared implementation of the ADR-118 interceptor lifecycle:
+ * descriptors declare an action's interceptor surface; the engine runs
+ * the D1-D4 rulings exactly once. See `lifecycle-engine.ts` for the
+ * contract details.
+ *
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ */
+export { ActionLifecycleDescriptor, EntitySlotSpec, LifecycleContracts } from './descriptor.js';
+export { LifecycleState, ResolvedConsultation, ResolveLifecycleOptions, resolveLifecycle, getLifecycleState, runPreValidate, runPostValidate, runPostExecute, runPostReport, runOnBlocked, blockedMessageId } from './lifecycle-engine.js';
+export { MultiObjectItemState, runMultiObjectValidate, getMultiObjectLifecycle, runMultiObjectExecute, runMultiObjectReport } from './multi-object-lifecycle.js';
+//# sourceMappingURL=index.d.ts.map

package/actions/lifecycle/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,kBAAkB,EACnB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,EACd,aAAa,EACb,YAAY,EACZ,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,6BAA6B,CAAC"}

package/actions/lifecycle/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Interceptor lifecycle engine barrel (ADR-228).
+ *
+ * The shared implementation of the ADR-118 interceptor lifecycle:
+ * descriptors declare an action's interceptor surface; the engine runs
+ * the D1-D4 rulings exactly once. See `lifecycle-engine.ts` for the
+ * contract details.
+ *
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMultiObjectReport = exports.runMultiObjectExecute = exports.getMultiObjectLifecycle = exports.runMultiObjectValidate = exports.blockedMessageId = exports.runOnBlocked = exports.runPostReport = exports.runPostExecute = exports.runPostValidate = exports.runPreValidate = exports.getLifecycleState = exports.resolveLifecycle = void 0;
+var lifecycle_engine_js_1 = require("./lifecycle-engine.js");
+Object.defineProperty(exports, "resolveLifecycle", { enumerable: true, get: function () { return lifecycle_engine_js_1.resolveLifecycle; } });
+Object.defineProperty(exports, "getLifecycleState", { enumerable: true, get: function () { return lifecycle_engine_js_1.getLifecycleState; } });
+Object.defineProperty(exports, "runPreValidate", { enumerable: true, get: function () { return lifecycle_engine_js_1.runPreValidate; } });
+Object.defineProperty(exports, "runPostValidate", { enumerable: true, get: function () { return lifecycle_engine_js_1.runPostValidate; } });
+Object.defineProperty(exports, "runPostExecute", { enumerable: true, get: function () { return lifecycle_engine_js_1.runPostExecute; } });
+Object.defineProperty(exports, "runPostReport", { enumerable: true, get: function () { return lifecycle_engine_js_1.runPostReport; } });
+Object.defineProperty(exports, "runOnBlocked", { enumerable: true, get: function () { return lifecycle_engine_js_1.runOnBlocked; } });
+Object.defineProperty(exports, "blockedMessageId", { enumerable: true, get: function () { return lifecycle_engine_js_1.blockedMessageId; } });
+var multi_object_lifecycle_js_1 = require("./multi-object-lifecycle.js");
+Object.defineProperty(exports, "runMultiObjectValidate", { enumerable: true, get: function () { return multi_object_lifecycle_js_1.runMultiObjectValidate; } });
+Object.defineProperty(exports, "getMultiObjectLifecycle", { enumerable: true, get: function () { return multi_object_lifecycle_js_1.getMultiObjectLifecycle; } });
+Object.defineProperty(exports, "runMultiObjectExecute", { enumerable: true, get: function () { return multi_object_lifecycle_js_1.runMultiObjectExecute; } });
+Object.defineProperty(exports, "runMultiObjectReport", { enumerable: true, get: function () { return multi_object_lifecycle_js_1.runMultiObjectReport; } });
+//# sourceMappingURL=index.js.map

package/actions/lifecycle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAQH,6DAY+B;AAR7B,uHAAA,gBAAgB,OAAA;AAChB,wHAAA,iBAAiB,OAAA;AACjB,qHAAA,cAAc,OAAA;AACd,sHAAA,eAAe,OAAA;AACf,qHAAA,cAAc,OAAA;AACd,oHAAA,aAAa,OAAA;AACb,mHAAA,YAAY,OAAA;AACZ,uHAAA,gBAAgB,OAAA;AAGlB,yEAMqC;AAJnC,mIAAA,sBAAsB,OAAA;AACtB,oIAAA,uBAAuB,OAAA;AACvB,kIAAA,qBAAqB,OAAA;AACrB,iIAAA,oBAAoB,OAAA"}

package/actions/lifecycle/lifecycle-engine.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Interceptor lifecycle engine (ADR-228).
+ *
+ * The single implementation of the ADR-118 interceptor lifecycle. Actions
+ * declare their interceptor surface as an `ActionLifecycleDescriptor` and
+ * call the engine at their four phase boundaries; the engine owns the
+ * rulings exactly once:
+ *
+ * - D1 — veto-only guards: a validate hook acts only when it returns
+ *   `{valid: false}`; any other result (including `{valid: true}`) falls
+ *   through. No hook can skip standard validation or later consultations.
+ *   (The explicit force-allow marker is a reserved, unimplemented
+ *   extension — see ADR-228 D1.)
+ * - D2 — structured onBlocked: `{ override?, emit? }` applied against the
+ *   standard blocked event, which always survives.
+ * - D3 — all command entities consulted in the descriptor's published
+ *   slot order, each consultation with its own sharedData; first veto
+ *   stops the validate chain; postExecute/postReport run for every
+ *   consultation once the action proceeds.
+ * - Override arbitration: at most one consultation may return an
+ *   `override` per report/blocked application — a second is a hard error,
+ *   mirroring ADR-106's "multiple game.message reactions" rule.
+ *
+ * Multi-object commands (D4) run one lifecycle per item via
+ * `multi-object-lifecycle.ts`, built on the same primitives.
+ *
+ * Public interface: `resolveLifecycle`, `getLifecycleState`,
+ * `runPreValidate`, `runPostValidate`, `runPostExecute`, `runPostReport`,
+ * `runOnBlocked`, `LifecycleState`, `ResolvedConsultation`.
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ */
+import { ISemanticEvent } from '@sharpee/core';
+import { IFEntity, InterceptorSharedData } from '@sharpee/world-model';
+import type { ActionInterceptor } from '@sharpee/world-model';
+import { ActionContext, ValidationResult } from '../enhanced-types.js';
+import { ActionLifecycleDescriptor } from './descriptor.js';
+/**
+ * One resolved (entity, actionId) interceptor consultation.
+ *
+ * A slot that consults two action ids (D6 both-ids) yields up to two
+ * consultations; each has its own `data` (D3 sharedData isolation).
+ */
+export interface ResolvedConsultation {
+    /** The descriptor slot this consultation came from. */
+    slotId: string;
+    /** The action id the interceptor was resolved under. */
+    actionId: string;
+    /** The entity whose trait declared the interceptor. */
+    entity: IFEntity;
+    /** The resolved interceptor. */
+    interceptor: ActionInterceptor;
+    /** Per-consultation shared data, isolated from other consultations. */
+    data: InterceptorSharedData;
+}
+/**
+ * The command's resolved lifecycle: the descriptor plus every
+ * consultation found for the command's entities, in consultation order.
+ */
+export interface LifecycleState {
+    descriptor: ActionLifecycleDescriptor;
+    consultations: ResolvedConsultation[];
+}
+/**
+ * Options for `resolveLifecycle`.
+ */
+export interface ResolveLifecycleOptions {
+    /**
+     * Substitute a specific entity for one slot instead of calling its
+     * `resolve` — used by the multi-object helper (D4) to bind each
+     * expanded item to the item slot. The resulting state is NOT stored in
+     * sharedData (per-item states live in the multi-object results).
+     */
+    slotOverride?: {
+        slotId: string;
+        entity: IFEntity;
+    };
+}
+/**
+ * Resolve an action's interceptor consultations for the current command.
+ *
+ * Iterates the descriptor's slots in published order (D3-B); for each
+ * slot that resolves to an entity, consults the world's interceptor
+ * registry under each of the slot's action ids (D6 order). Every match
+ * becomes a `ResolvedConsultation` with fresh sharedData (seeded via the
+ * slot's `seedData`, if any).
+ *
+ * Stores the state in `context.sharedData` (unless `slotOverride` is
+ * used) so later phases can fetch it with `getLifecycleState`.
+ *
+ * @param context - The action context.
+ * @param descriptor - The action's declared interceptor surface.
+ * @param options - See `ResolveLifecycleOptions`.
+ * @returns The resolved lifecycle state (possibly with zero consultations).
+ */
+export declare function resolveLifecycle(context: ActionContext, descriptor: ActionLifecycleDescriptor, options?: ResolveLifecycleOptions): LifecycleState;
+/**
+ * Fetch the lifecycle state stored by `resolveLifecycle` for this command.
+ *
+ * @param context - The action context.
+ * @returns The state, or `undefined` if `resolveLifecycle` has not run.
+ */
+export declare function getLifecycleState(context: ActionContext): LifecycleState | undefined;
+/**
+ * Resolve the message id for a blocked action (ADR-231 D1) — the ONE
+ * place the qualification convention lives.
+ *
+ * Interceptor-originated errors (and helper-produced cross-action keys)
+ * carry `errorQualified: true` and pass through untouched; an action's
+ * own validation errors are qualified as `<action.id>.<error>` exactly
+ * as before. `blocked()` implementations call this instead of building
+ * ids by hand; key shape (dots, hyphens) is NOT the discriminator —
+ * provenance is.
+ *
+ * @param context - The action context (supplies the action id).
+ * @param result - The failed validation result carrying the error key.
+ * @returns The message id to emit from `blocked()`.
+ */
+export declare function blockedMessageId(context: ActionContext, result: ValidationResult): string;
+/**
+ * Run every consultation's `preValidate` hook in order (D3-B).
+ *
+ * First veto wins: returns that veto as a `ValidationResult` and stops
+ * consulting. Returns `null` when no hook vetoes (the action continues
+ * with standard validation — D1: hooks cannot approve, only object).
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ */
+export declare function runPreValidate(context: ActionContext, state: LifecycleState): ValidationResult | null;
+/**
+ * Run every consultation's `postValidate` hook in order (D3-B).
+ *
+ * Canonical placement (ADR-228): after ALL standard validation has
+ * passed. First veto wins; returns `null` when no hook vetoes.
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ */
+export declare function runPostValidate(context: ActionContext, state: LifecycleState): ValidationResult | null;
+/**
+ * Run every consultation's `postExecute` hook in order (D3-B: all
+ * consultations survived validation once the action executed).
+ *
+ * Note the `postExecuteReplacesCore` contract (D7.3) governs whether the
+ * ACTION runs its own core logic — the engine always runs the hooks
+ * themselves normally.
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ */
+export declare function runPostExecute(context: ActionContext, state: LifecycleState): void;
+/**
+ * Run every consultation's `postReport` hook and apply the results to the
+ * action's events.
+ *
+ * At most ONE consultation may return an `override` — a second is a hard
+ * error (throws), mirroring the `InterceptorReportResult` contract's
+ * ADR-106 rule. `emit` effects append in consultation order.
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ * @param events - The action's events array; mutated in place.
+ * @param primaryEventType - The event type an `override` targets.
+ * @param searchFrom - Index in `events` where this report began — override
+ *   targeting searches from here so per-item applications (D4) land on
+ *   the item's own event, not an earlier item's.
+ */
+export declare function runPostReport(context: ActionContext, state: LifecycleState, events: ISemanticEvent[], primaryEventType: string, searchFrom?: number): void;
+/**
+ * Run every consultation's `onBlocked` hook and apply the results to the
+ * action's blocked events (D2: the standard blocked event always
+ * survives; `override` swaps its message, `emit` appends).
+ *
+ * All resolved consultations are notified — including ones the validate
+ * chain never reached — matching the D3 author model ("a clause on any
+ * entity involved in the command fires"). At most one `override` (hard
+ * error otherwise).
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ * @param events - The blocked events array (standard blocked event
+ *   already pushed); mutated in place.
+ * @param blockedEventType - The standard blocked event's type.
+ * @param error - The validation error code the action was blocked with.
+ * @param searchFrom - Index in `events` where this item's blocked report
+ *   began (D4 per-item targeting).
+ */
+export declare function runOnBlocked(context: ActionContext, state: LifecycleState, events: ISemanticEvent[], blockedEventType: string, error: string, searchFrom?: number): void;
+//# sourceMappingURL=lifecycle-engine.d.ts.map

package/actions/lifecycle/lifecycle-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-engine.d.ts","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/lifecycle-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,QAAQ,EACR,qBAAqB,EAGtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAS5D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,MAAM,EAAE,QAAQ,CAAC;IACjB,gCAAgC;IAChC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,uEAAuE;IACvE,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,yBAAyB,CAAC;IACtC,aAAa,EAAE,oBAAoB,EAAE,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,YAAY,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAE,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,yBAAyB,EACrC,OAAO,CAAC,EAAE,uBAAuB,GAChC,cAAc,CAoChB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS,CAEpF;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAGzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,cAAc,GACpB,gBAAgB,GAAG,IAAI,CASzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,cAAc,GACpB,gBAAgB,GAAG,IAAI,CASzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAIlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,cAAc,EAAE,EACxB,gBAAgB,EAAE,MAAM,EACxB,UAAU,GAAE,MAAU,GACrB,IAAI,CAkBN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,cAAc,EAAE,EACxB,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,MAAM,EACb,UAAU,GAAE,MAAU,GACrB,IAAI,CAkBN"}

package/actions/lifecycle/lifecycle-engine.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * Interceptor lifecycle engine (ADR-228).
+ *
+ * The single implementation of the ADR-118 interceptor lifecycle. Actions
+ * declare their interceptor surface as an `ActionLifecycleDescriptor` and
+ * call the engine at their four phase boundaries; the engine owns the
+ * rulings exactly once:
+ *
+ * - D1 — veto-only guards: a validate hook acts only when it returns
+ *   `{valid: false}`; any other result (including `{valid: true}`) falls
+ *   through. No hook can skip standard validation or later consultations.
+ *   (The explicit force-allow marker is a reserved, unimplemented
+ *   extension — see ADR-228 D1.)
+ * - D2 — structured onBlocked: `{ override?, emit? }` applied against the
+ *   standard blocked event, which always survives.
+ * - D3 — all command entities consulted in the descriptor's published
+ *   slot order, each consultation with its own sharedData; first veto
+ *   stops the validate chain; postExecute/postReport run for every
+ *   consultation once the action proceeds.
+ * - Override arbitration: at most one consultation may return an
+ *   `override` per report/blocked application — a second is a hard error,
+ *   mirroring ADR-106's "multiple game.message reactions" rule.
+ *
+ * Multi-object commands (D4) run one lifecycle per item via
+ * `multi-object-lifecycle.ts`, built on the same primitives.
+ *
+ * Public interface: `resolveLifecycle`, `getLifecycleState`,
+ * `runPreValidate`, `runPostValidate`, `runPostExecute`, `runPostReport`,
+ * `runOnBlocked`, `LifecycleState`, `ResolvedConsultation`.
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLifecycle = resolveLifecycle;
+exports.getLifecycleState = getLifecycleState;
+exports.blockedMessageId = blockedMessageId;
+exports.runPreValidate = runPreValidate;
+exports.runPostValidate = runPostValidate;
+exports.runPostExecute = runPostExecute;
+exports.runPostReport = runPostReport;
+exports.runOnBlocked = runOnBlocked;
+const world_model_1 = require("@sharpee/world-model");
+/**
+ * Reserved sharedData key holding the command's resolved lifecycle state.
+ * Actions never read or write this key directly — they hold the state
+ * returned by `resolveLifecycle` or fetch it via `getLifecycleState`.
+ */
+const LIFECYCLE_KEY = '_lifecycle';
+/**
+ * Resolve an action's interceptor consultations for the current command.
+ *
+ * Iterates the descriptor's slots in published order (D3-B); for each
+ * slot that resolves to an entity, consults the world's interceptor
+ * registry under each of the slot's action ids (D6 order). Every match
+ * becomes a `ResolvedConsultation` with fresh sharedData (seeded via the
+ * slot's `seedData`, if any).
+ *
+ * Stores the state in `context.sharedData` (unless `slotOverride` is
+ * used) so later phases can fetch it with `getLifecycleState`.
+ *
+ * @param context - The action context.
+ * @param descriptor - The action's declared interceptor surface.
+ * @param options - See `ResolveLifecycleOptions`.
+ * @returns The resolved lifecycle state (possibly with zero consultations).
+ */
+function resolveLifecycle(context, descriptor, options) {
+    const consultations = [];
+    for (const slot of descriptor.slots) {
+        const isOverrideSlot = options?.slotOverride?.slotId === slot.id;
+        const entity = isOverrideSlot
+            ? options.slotOverride.entity
+            : slot.resolve(context);
+        if (!entity)
+            continue;
+        for (const actionId of slot.actionIds) {
+            const lookup = context.world.getInterceptorForAction(entity, actionId);
+            if (!lookup)
+                continue;
+            // In a per-item resolution (D4), non-item slots' seedData receives
+            // the current item so shared entities (e.g. the container) can seed
+            // per-item context like the item id.
+            const multiObjectItem = !isOverrideSlot ? options?.slotOverride?.entity : undefined;
+            const data = slot.seedData
+                ? { ...slot.seedData(context, entity, multiObjectItem) }
+                : {};
+            consultations.push({
+                slotId: slot.id,
+                actionId,
+                entity,
+                interceptor: lookup.interceptor,
+                data
+            });
+        }
+    }
+    const state = { descriptor, consultations };
+    if (!options?.slotOverride) {
+        context.sharedData[LIFECYCLE_KEY] = state;
+    }
+    return state;
+}
+/**
+ * Fetch the lifecycle state stored by `resolveLifecycle` for this command.
+ *
+ * @param context - The action context.
+ * @returns The state, or `undefined` if `resolveLifecycle` has not run.
+ */
+function getLifecycleState(context) {
+    return context.sharedData[LIFECYCLE_KEY];
+}
+/**
+ * D1 veto test: a hook result acts iff it is non-null AND `valid === false`.
+ * Everything else — null, `{valid: true}`, any truthy shape — falls through.
+ *
+ * Every veto is marked `errorQualified: true` (ADR-231 D1): an
+ * interceptor-originated error key is a fully-qualified message id —
+ * story-registered keys resolve as the author wrote them — and
+ * `blockedMessageId` must never prefix it with the action id.
+ */
+function vetoOf(result) {
+    if (result !== null && result.valid === false) {
+        return { valid: false, error: result.error, errorQualified: true, params: result.params };
+    }
+    return null;
+}
+/**
+ * Resolve the message id for a blocked action (ADR-231 D1) — the ONE
+ * place the qualification convention lives.
+ *
+ * Interceptor-originated errors (and helper-produced cross-action keys)
+ * carry `errorQualified: true` and pass through untouched; an action's
+ * own validation errors are qualified as `<action.id>.<error>` exactly
+ * as before. `blocked()` implementations call this instead of building
+ * ids by hand; key shape (dots, hyphens) is NOT the discriminator —
+ * provenance is.
+ *
+ * @param context - The action context (supplies the action id).
+ * @param result - The failed validation result carrying the error key.
+ * @returns The message id to emit from `blocked()`.
+ */
+function blockedMessageId(context, result) {
+    const error = result.error ?? 'action_failed';
+    return result.errorQualified === true ? error : `${context.action.id}.${error}`;
+}
+/**
+ * Run every consultation's `preValidate` hook in order (D3-B).
+ *
+ * First veto wins: returns that veto as a `ValidationResult` and stops
+ * consulting. Returns `null` when no hook vetoes (the action continues
+ * with standard validation — D1: hooks cannot approve, only object).
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ */
+function runPreValidate(context, state) {
+    for (const c of state.consultations) {
+        if (!c.interceptor.preValidate)
+            continue;
+        const veto = vetoOf(c.interceptor.preValidate(c.entity, context.world, context.player.id, c.data));
+        if (veto)
+            return veto;
+    }
+    return null;
+}
+/**
+ * Run every consultation's `postValidate` hook in order (D3-B).
+ *
+ * Canonical placement (ADR-228): after ALL standard validation has
+ * passed. First veto wins; returns `null` when no hook vetoes.
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ */
+function runPostValidate(context, state) {
+    for (const c of state.consultations) {
+        if (!c.interceptor.postValidate)
+            continue;
+        const veto = vetoOf(c.interceptor.postValidate(c.entity, context.world, context.player.id, c.data));
+        if (veto)
+            return veto;
+    }
+    return null;
+}
+/**
+ * Run every consultation's `postExecute` hook in order (D3-B: all
+ * consultations survived validation once the action executed).
+ *
+ * Note the `postExecuteReplacesCore` contract (D7.3) governs whether the
+ * ACTION runs its own core logic — the engine always runs the hooks
+ * themselves normally.
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ */
+function runPostExecute(context, state) {
+    for (const c of state.consultations) {
+        c.interceptor.postExecute?.(c.entity, context.world, context.player.id, c.data);
+    }
+}
+/**
+ * Run every consultation's `postReport` hook and apply the results to the
+ * action's events.
+ *
+ * At most ONE consultation may return an `override` — a second is a hard
+ * error (throws), mirroring the `InterceptorReportResult` contract's
+ * ADR-106 rule. `emit` effects append in consultation order.
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ * @param events - The action's events array; mutated in place.
+ * @param primaryEventType - The event type an `override` targets.
+ * @param searchFrom - Index in `events` where this report began — override
+ *   targeting searches from here so per-item applications (D4) land on
+ *   the item's own event, not an earlier item's.
+ */
+function runPostReport(context, state, events, primaryEventType, searchFrom = 0) {
+    let overrideSeen = false;
+    for (const c of state.consultations) {
+        if (!c.interceptor.postReport)
+            continue;
+        const result = c.interceptor.postReport(c.entity, context.world, context.player.id, c.data);
+        if (!result)
+            continue;
+        if (result.override) {
+            if (overrideSeen) {
+                throw new Error(`Interceptor lifecycle (${state.descriptor.actionId}): multiple consultations ` +
+                    `returned a postReport override — at most one interceptor may override the ` +
+                    `primary message (slot '${c.slotId}', action '${c.actionId}').`);
+            }
+            overrideSeen = true;
+        }
+        (0, world_model_1.applyInterceptorReportResult)(events, primaryEventType, result, context, { searchFrom });
+    }
+}
+/**
+ * Run every consultation's `onBlocked` hook and apply the results to the
+ * action's blocked events (D2: the standard blocked event always
+ * survives; `override` swaps its message, `emit` appends).
+ *
+ * All resolved consultations are notified — including ones the validate
+ * chain never reached — matching the D3 author model ("a clause on any
+ * entity involved in the command fires"). At most one `override` (hard
+ * error otherwise).
+ *
+ * @param context - The action context.
+ * @param state - The resolved lifecycle state.
+ * @param events - The blocked events array (standard blocked event
+ *   already pushed); mutated in place.
+ * @param blockedEventType - The standard blocked event's type.
+ * @param error - The validation error code the action was blocked with.
+ * @param searchFrom - Index in `events` where this item's blocked report
+ *   began (D4 per-item targeting).
+ */
+function runOnBlocked(context, state, events, blockedEventType, error, searchFrom = 0) {
+    let overrideSeen = false;
+    for (const c of state.consultations) {
+        if (!c.interceptor.onBlocked)
+            continue;
+        const result = c.interceptor.onBlocked(c.entity, context.world, context.player.id, error, c.data);
+        if (!result)
+            continue;
+        if (result.override) {
+            if (overrideSeen) {
+                throw new Error(`Interceptor lifecycle (${state.descriptor.actionId}): multiple consultations ` +
+                    `returned an onBlocked override — at most one interceptor may override the ` +
+                    `blocked message (slot '${c.slotId}', action '${c.actionId}').`);
+            }
+            overrideSeen = true;
+        }
+        (0, world_model_1.applyInterceptorBlockedResult)(events, blockedEventType, result, context, { searchFrom });
+    }
+}
+//# sourceMappingURL=lifecycle-engine.js.map