@sharpee/stdlib 2.2.0 → 3.1.0

package/actions/lifecycle/lifecycle-engine.js

@@ -0,0 +1,247 @@
+"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.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.
+ */
+function vetoOf(result) {
+    if (result !== null && result.valid === false) {
+        return { valid: false, error: result.error, params: result.params };
+    }
+    return null;
+}
+/**
+ * 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

package/actions/lifecycle/lifecycle-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-engine.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/lifecycle-engine.ts"],"names":[],"mappings":"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"}

package/actions/lifecycle/multi-object-lifecycle.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Multi-object interceptor lifecycle (ADR-228 D4).
+ *
+ * Runs the FULL interceptor lifecycle per expanded item of a multi-object
+ * command ("take all", "put all in case"): resolve → preValidate →
+ * standard per-item validation → postValidate per item; postExecute /
+ * postReport per successful item; onBlocked per failed item. Actions
+ * supply only their standard per-item logic as callbacks — the hook
+ * plumbing lives here exactly once, so the bypass class the ADR-118 audit
+ * found (putting/dropping multi paths skipping all five hooks; taking
+ * skipping onBlocked) cannot silently recur.
+ *
+ * Aggregated output is preserved: the action's report callbacks push
+ * their own events; the engine applies each item's hook results against
+ * that item's own events via `searchFrom` targeting.
+ *
+ * Public interface: `runMultiObjectValidate`, `runMultiObjectExecute`,
+ * `runMultiObjectReport`, `getMultiObjectLifecycle`,
+ * `MultiObjectItemState`.
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ */
+import { ISemanticEvent } from '@sharpee/core';
+import { IFEntity } from '@sharpee/world-model';
+import { ActionContext, ValidationResult } from '../enhanced-types';
+import { ActionLifecycleDescriptor } from './descriptor';
+import { LifecycleState } from './lifecycle-engine';
+/**
+ * One item's lifecycle through a multi-object command.
+ *
+ * `itemData` is the action's per-item scratch space (previous location,
+ * implicit-removal flags, ...) — the analogue of single-object
+ * sharedData, isolated per item.
+ */
+export interface MultiObjectItemState {
+    entity: IFEntity;
+    /** True when the item passed hooks + standard validation. */
+    success: boolean;
+    /** Validation error code when `success` is false. */
+    error?: string;
+    /** Error params when `success` is false. */
+    errorParams?: Record<string, unknown>;
+    /** The item's resolved interceptor consultations (own sharedData each). */
+    state: LifecycleState;
+    /** Action-owned per-item scratch data. */
+    itemData: Record<string, unknown>;
+}
+/**
+ * Validate every expanded item through its full lifecycle (D4).
+ *
+ * Per item, in order: resolve consultations (the descriptor's
+ * `multiObjectSlotId`-designated slot binds to the item) → preValidate
+ * hooks (veto fails the item) → `validateItem` (standard validation) →
+ * postValidate hooks (veto fails the item). A failed item never blocks
+ * the others — per-item success/failure is recorded for the execute and
+ * report phases.
+ *
+ * Stores the resulting array in `context.sharedData` and returns it.
+ *
+ * @param context - The action context.
+ * @param descriptor - The action's declared interceptor surface. Its slot
+ *   with id `multiObjectSlotId` is bound to each item in turn.
+ * @param multiObjectSlotId - Id of the slot that carries each expanded
+ *   item (usually the direct-object slot).
+ * @param items - The expanded entities of the multi-object command.
+ * @param validateItem - The action's standard single-item validation.
+ * @returns Per-item lifecycle states, in `items` order.
+ */
+export declare function runMultiObjectValidate(context: ActionContext, descriptor: ActionLifecycleDescriptor, multiObjectSlotId: string, items: IFEntity[], validateItem: (context: ActionContext, item: IFEntity, itemData: Record<string, unknown>) => ValidationResult): MultiObjectItemState[];
+/**
+ * Fetch the per-item states stored by `runMultiObjectValidate`.
+ *
+ * @param context - The action context.
+ * @returns The item states, or `undefined` if the command was not
+ *   validated as a multi-object command.
+ */
+export declare function getMultiObjectLifecycle(context: ActionContext): MultiObjectItemState[] | undefined;
+/**
+ * Execute every successful item: the action's `executeItem`, then that
+ * item's postExecute hooks (D4 — hooks fire per item, so e.g. a trophy
+ * case's postExecute awards score for EVERY deposited treasure).
+ *
+ * @param context - The action context.
+ * @param itemStates - The states from `runMultiObjectValidate`.
+ * @param executeItem - The action's standard single-item mutation.
+ */
+export declare function runMultiObjectExecute(context: ActionContext, itemStates: MultiObjectItemState[], executeItem: (context: ActionContext, item: IFEntity, itemData: Record<string, unknown>) => void): void;
+/**
+ * Report every item: successes via `reportSuccess` + postReport hooks,
+ * failures via `reportBlocked` + onBlocked hooks (D4 closes the audit's
+ * take-all-loses-onBlocked gap).
+ *
+ * Each item's hook results are applied with `searchFrom` set to the index
+ * where that item's events began, so overrides land on the item's own
+ * event even though all items share one events array (aggregated output).
+ *
+ * @param context - The action context.
+ * @param itemStates - The states from `runMultiObjectValidate`.
+ * @param events - The action's events array; mutated in place.
+ * @param primaryEventType - Event type a success `override` targets.
+ * @param blockedEventType - Event type a blocked `override` targets.
+ * @param reportSuccess - Pushes the item's standard success event(s).
+ * @param reportBlocked - Pushes the item's standard blocked event.
+ */
+export declare function runMultiObjectReport(context: ActionContext, itemStates: MultiObjectItemState[], events: ISemanticEvent[], primaryEventType: string, blockedEventType: string, reportSuccess: (context: ActionContext, item: IFEntity, itemData: Record<string, unknown>, events: ISemanticEvent[]) => void, reportBlocked: (context: ActionContext, item: IFEntity, error: string, errorParams: Record<string, unknown> | undefined, events: ISemanticEvent[]) => void): void;
+//# sourceMappingURL=multi-object-lifecycle.d.ts.map

package/actions/lifecycle/multi-object-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-object-lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/multi-object-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EACL,cAAc,EAOf,MAAM,oBAAoB,CAAC;AAS5B;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,QAAQ,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,2EAA2E;IAC3E,KAAK,EAAE,cAAc,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,yBAAyB,EACrC,iBAAiB,EAAE,MAAM,EACzB,KAAK,EAAE,QAAQ,EAAE,EACjB,YAAY,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,gBAAgB,GAC5G,oBAAoB,EAAE,CA2BxB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,oBAAoB,EAAE,GAAG,SAAS,CAElG;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,oBAAoB,EAAE,EAClC,WAAW,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAC/F,IAAI,CAMN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,oBAAoB,EAAE,EAClC,MAAM,EAAE,cAAc,EAAE,EACxB,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,IAAI,EAC5H,aAAa,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,IAAI,GACzJ,IAAI,CAWN"}

package/actions/lifecycle/multi-object-lifecycle.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Multi-object interceptor lifecycle (ADR-228 D4).
+ *
+ * Runs the FULL interceptor lifecycle per expanded item of a multi-object
+ * command ("take all", "put all in case"): resolve → preValidate →
+ * standard per-item validation → postValidate per item; postExecute /
+ * postReport per successful item; onBlocked per failed item. Actions
+ * supply only their standard per-item logic as callbacks — the hook
+ * plumbing lives here exactly once, so the bypass class the ADR-118 audit
+ * found (putting/dropping multi paths skipping all five hooks; taking
+ * skipping onBlocked) cannot silently recur.
+ *
+ * Aggregated output is preserved: the action's report callbacks push
+ * their own events; the engine applies each item's hook results against
+ * that item's own events via `searchFrom` targeting.
+ *
+ * Public interface: `runMultiObjectValidate`, `runMultiObjectExecute`,
+ * `runMultiObjectReport`, `getMultiObjectLifecycle`,
+ * `MultiObjectItemState`.
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMultiObjectValidate = runMultiObjectValidate;
+exports.getMultiObjectLifecycle = getMultiObjectLifecycle;
+exports.runMultiObjectExecute = runMultiObjectExecute;
+exports.runMultiObjectReport = runMultiObjectReport;
+const lifecycle_engine_1 = require("./lifecycle-engine");
+/**
+ * Reserved sharedData key holding the command's per-item lifecycle states.
+ * Actions never touch this key directly — they hold the array returned by
+ * `runMultiObjectValidate` or fetch it via `getMultiObjectLifecycle`.
+ */
+const MULTI_LIFECYCLE_KEY = '_lifecycleMulti';
+/**
+ * Validate every expanded item through its full lifecycle (D4).
+ *
+ * Per item, in order: resolve consultations (the descriptor's
+ * `multiObjectSlotId`-designated slot binds to the item) → preValidate
+ * hooks (veto fails the item) → `validateItem` (standard validation) →
+ * postValidate hooks (veto fails the item). A failed item never blocks
+ * the others — per-item success/failure is recorded for the execute and
+ * report phases.
+ *
+ * Stores the resulting array in `context.sharedData` and returns it.
+ *
+ * @param context - The action context.
+ * @param descriptor - The action's declared interceptor surface. Its slot
+ *   with id `multiObjectSlotId` is bound to each item in turn.
+ * @param multiObjectSlotId - Id of the slot that carries each expanded
+ *   item (usually the direct-object slot).
+ * @param items - The expanded entities of the multi-object command.
+ * @param validateItem - The action's standard single-item validation.
+ * @returns Per-item lifecycle states, in `items` order.
+ */
+function runMultiObjectValidate(context, descriptor, multiObjectSlotId, items, validateItem) {
+    const results = items.map((item) => {
+        const state = (0, lifecycle_engine_1.resolveLifecycle)(context, descriptor, {
+            slotOverride: { slotId: multiObjectSlotId, entity: item }
+        });
+        const itemData = {};
+        const preVeto = (0, lifecycle_engine_1.runPreValidate)(context, state);
+        if (preVeto) {
+            return { entity: item, success: false, error: preVeto.error, errorParams: preVeto.params, state, itemData };
+        }
+        const standard = validateItem(context, item, itemData);
+        if (!standard.valid) {
+            return { entity: item, success: false, error: standard.error, errorParams: standard.params, state, itemData };
+        }
+        const postVeto = (0, lifecycle_engine_1.runPostValidate)(context, state);
+        if (postVeto) {
+            return { entity: item, success: false, error: postVeto.error, errorParams: postVeto.params, state, itemData };
+        }
+        return { entity: item, success: true, state, itemData };
+    });
+    context.sharedData[MULTI_LIFECYCLE_KEY] = results;
+    return results;
+}
+/**
+ * Fetch the per-item states stored by `runMultiObjectValidate`.
+ *
+ * @param context - The action context.
+ * @returns The item states, or `undefined` if the command was not
+ *   validated as a multi-object command.
+ */
+function getMultiObjectLifecycle(context) {
+    return context.sharedData[MULTI_LIFECYCLE_KEY];
+}
+/**
+ * Execute every successful item: the action's `executeItem`, then that
+ * item's postExecute hooks (D4 — hooks fire per item, so e.g. a trophy
+ * case's postExecute awards score for EVERY deposited treasure).
+ *
+ * @param context - The action context.
+ * @param itemStates - The states from `runMultiObjectValidate`.
+ * @param executeItem - The action's standard single-item mutation.
+ */
+function runMultiObjectExecute(context, itemStates, executeItem) {
+    for (const itemState of itemStates) {
+        if (!itemState.success)
+            continue;
+        executeItem(context, itemState.entity, itemState.itemData);
+        (0, lifecycle_engine_1.runPostExecute)(context, itemState.state);
+    }
+}
+/**
+ * Report every item: successes via `reportSuccess` + postReport hooks,
+ * failures via `reportBlocked` + onBlocked hooks (D4 closes the audit's
+ * take-all-loses-onBlocked gap).
+ *
+ * Each item's hook results are applied with `searchFrom` set to the index
+ * where that item's events began, so overrides land on the item's own
+ * event even though all items share one events array (aggregated output).
+ *
+ * @param context - The action context.
+ * @param itemStates - The states from `runMultiObjectValidate`.
+ * @param events - The action's events array; mutated in place.
+ * @param primaryEventType - Event type a success `override` targets.
+ * @param blockedEventType - Event type a blocked `override` targets.
+ * @param reportSuccess - Pushes the item's standard success event(s).
+ * @param reportBlocked - Pushes the item's standard blocked event.
+ */
+function runMultiObjectReport(context, itemStates, events, primaryEventType, blockedEventType, reportSuccess, reportBlocked) {
+    for (const itemState of itemStates) {
+        const searchFrom = events.length;
+        if (itemState.success) {
+            reportSuccess(context, itemState.entity, itemState.itemData, events);
+            (0, lifecycle_engine_1.runPostReport)(context, itemState.state, events, primaryEventType, searchFrom);
+        }
+        else {
+            reportBlocked(context, itemState.entity, itemState.error ?? '', itemState.errorParams, events);
+            (0, lifecycle_engine_1.runOnBlocked)(context, itemState.state, events, blockedEventType, itemState.error ?? '', searchFrom);
+        }
+    }
+}
+//# sourceMappingURL=multi-object-lifecycle.js.map

package/actions/lifecycle/multi-object-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-object-lifecycle.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/multi-object-lifecycle.ts"],"names":[],"mappings":"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"}

package/actions/lifecycle/registry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Wired-action registry (ADR-228 D5).
+ *
+ * The descriptor table: every standard action's `ActionLifecycleDescriptor`,
+ * collected in one place, plus the set of interceptor-consulting action ids
+ * derived mechanically from it. The table IS the source of truth — an action
+ * is "wired" iff its descriptor appears here, and the id set is never
+ * hand-maintained. Consumers (the Chord story-loader's load-time fail-fast,
+ * tooling, tests) read the derived set to decide whether an interceptor
+ * registered under a given action id will ever be consulted.
+ *
+ * Public interface: `actionLifecycleDescriptors`,
+ * `interceptorConsultingActionIds`.
+ * Owner: stdlib standard-action infrastructure (ADR-228).
+ *
+ * NOTE: this module is deliberately NOT exported from `./index.ts` (the
+ * lifecycle barrel) — actions import that barrel, and this module imports
+ * the actions, so routing it through the barrel would create an import
+ * cycle. It is exported from the actions barrel (`../index.ts`) instead.
+ */
+import { ActionLifecycleDescriptor } from './descriptor';
+/**
+ * The descriptor table: all 37 entity-keyed standard actions (33 per
+ * ADR-228 Consequences + cutting per ADR-230 D3c + digging + asking/telling per
+ * ADR-230 Phase 6). Structural exemptions
+ * (no entity to key on: about, waiting, looking, … and the full-delegation
+ * capability actions lowering/raising) are absent by design — see ADR-228
+ * Context.
+ */
+export declare const actionLifecycleDescriptors: readonly ActionLifecycleDescriptor[];
+/**
+ * Every action id under which some wired action consults interceptors —
+ * the union of all descriptors' slot actionIds (mechanically derived; the
+ * both-ids delegation seams of ADR-228 D6 and implicit-entity ids like
+ * `if.action.entering_room` fall out of the slots, not a hand-kept list).
+ * An interceptor registered under an id NOT in this set will never fire.
+ */
+export declare const interceptorConsultingActionIds: ReadonlySet<string>;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../../../../../repos/sharpee_v2/packages/stdlib/src/actions/lifecycle/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAwCzD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,yBAAyB,EAsCzE,CAAC;AAiBH;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAI9D,CAAC"}