@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/execution/ExecutionRuntimeContext.d.ts

@@ -1,8 +1,9 @@
 import React from 'react';
-import type { ExecutionViewDefinition } from '../../core/config/execution-view.schemas.js';
-import type { ResourceRegistryContextType } from '../../core/resources/ResourceRegistryContext.js';
-import type { NavigateOptions } from '../../core/navigation/useNavigationController.js';
-import type { NavigationContent, NavigationInitiatorContext, NavigationZone } from '../../core/navigation/navigation.schemas.js';
+import type { ExecutionViewDefinition } from '../../core/config/execution-view.schemas';
+import type { ResourceRegistryContextType } from '../../core/resources/ResourceRegistryContext';
+import type { NavigateOptions } from '../../core/navigation/useNavigationController';
+import { NavigationContentType, type NavigationContent, type NavigationInitiatorContext, type NavigationZone } from '../../core/navigation/navigation.schemas';
+import type { ResolvedExecutionParticipation } from './execution-participation.utils';
 export declare enum ExecutionAnchorSource {
     PARENT_RESOURCE_REQUIREMENT = "parent-resource-requirement",
     ADDITIONAL_RESOURCE_REQUIREMENT = "additional-resource-requirement"
@@ -26,22 +27,1062 @@ export interface ExecutionLocalPaneState {
     payload?: unknown;
 }
 /**
- * Minimal runtime state for the first routed execution host slice.
+ * @wildo_source:part:start saas.frontend.execution-view.loading-aggregation facet:layer:frontend facet:family:execution-view
  *
- * This starts with only local pane state so the framework can already own one
- * execution-local interaction channel without pretending the full slot/choreography
- * runtime is finished.
+ * Execution-shell loading aggregation.
+ *
+ * The execution shell publishes **one** authoritative loading signal per
+ * runtime-instance, aggregating only what the shell itself truthfully owns.
+ * Consumers get a single `execution.loading` surface instead of re-authoring
+ * spinner state for every action button.
+ *
+ * What the aggregator owns (and why):
+ *
+ * - **Pending execute actions.** Every `execute()` on a resource-operation
+ *   action verb runs through the shell's `doOperation()` bridge. The shell
+ *   registers a `ExecutionPendingAction` before the call and clears it on
+ *   settle (success *or* failure).
+ * - **Participation prefetch entries.** A second tier for in-flight async
+ *   hydration of one or more execution participations. Wired in Slice H as
+ *   scaffolding ahead of a real producer (no in-tree producer exists today
+ *   because participation resolution is fully synchronous), so a future
+ *   async participation source can register prefetches without re-shaping
+ *   the public `ExecutionLoadingValue` surface. Spec lives at the
+ *   `participation-prefetch` sub-anchor below.
+ *
+ * What the aggregator intentionally does **not** own:
+ *
+ * - **Embedded-content layout loading.** The embedded slot mounts a
+ *   `ResourceOperationSurface`, which has its own internal read/write
+ *   loading contract. The execution shell does not shadow or duplicate that
+ *   contract; `hasEmbeddedContent` alone is not a loading signal.
+ * - **Router-delegated content.** Once `delegateToParent(...)` fires, the
+ *   execution view has yielded ownership. Any downstream loading lives on
+ *   the router's navigation stack.
+ * - **Consumer-pushed phases.** App code cannot register synthetic "phase"
+ *   entries to make `isBusy` reflect a multi-step workflow it owns. Every
+ *   tier is shell-owned (see invariant #1) — that constraint is what makes
+ *   the aggregator's truthfulness portable across consumers.
+ *
+ * Contract invariants:
+ *
+ * 1. **Shell-owned tracking only.** The aggregator is populated exclusively
+ *    by shell-owned hooks (`execute()` for the pending-action tier; future
+ *    framework-owned participation resolvers for the participation-prefetch
+ *    tier). App code must not push entries into it directly — the
+ *    `begin/endPendingAction` and `begin/endParticipationPrefetch` helpers
+ *    on `ExecutionNavigationValue` are internal plumbing.
+ * 2. **Settle always clears.** Every `beginPendingAction` /
+ *    `beginParticipationPrefetch` has a matching `endPendingAction` /
+ *    `endParticipationPrefetch`, called in the promise's `finally` path.
+ *    Rejections clear the entry just like resolutions.
+ * 3. **Per-runtime-instance scope.** The aggregator lives on the execution
+ *    runtime, not globally. Two execution views mounted in the same app do
+ *    not share pending-action or prefetch state.
+ * 4. **Orthogonal to the three-zone contract.** Pending actions and prefetches
+ *    are operational telemetry, not a fourth navigation zone. They coexist
+ *    with `embeddedContent` and `localPane` on `ExecutionRuntimeState` but
+ *    do not represent child intent.
+ * 5. **`isBusy` aggregates every tier.**
+ *    `execution.loading.isBusy = pendingActions.length > 0 ||
+ *    participationPrefetchActions.length > 0`. The renderer-facing label
+ *    "anything in flight" stays honest as new tiers are added. Per-tier
+ *    narrowing is reached via `isPending(...)` (execute actions) and
+ *    `isParticipationPrefetching(...)` (prefetches) explicitly.
+ */
+export interface ExecutionPendingAction {
+    /**
+     * Stable id for the pending action. Generated by the shell at `begin` time
+     * so `end` can clear the matching entry even if the caller forgets it.
+     */
+    actionRuntimeId: string;
+    /** Canonical `operationPathKey` the shell passed to `doOperation()`. */
+    operationPathKey: string;
+    /** Resource the action targets, for per-resource UI filtering. */
+    resourceType: string;
+    /** Operation identifier (e.g. `READ`, `UPDATE`, dictionary key). */
+    operationId: string;
+    /** `Date.now()` when tracking began — useful for stale-spinner detection. */
+    startedAt: number;
+}
+/** @wildo_source:part:end saas.frontend.execution-view.loading-aggregation */
+/**
+ * @wildo_source:part:start saas.frontend.execution-view.loading-aggregation.participation-prefetch facet:layer:frontend facet:family:execution-view
+ *
+ * Execution-shell loading aggregation — participation-prefetch tier (Slice H).
+ *
+ * Sub-anchor of `saas.frontend.execution-view.loading-aggregation`. Defines
+ * the loading aggregator's second tier: in-flight async hydration of one or
+ * more execution participations.
+ *
+ * **First producer landed in Slice K.** `resolveExecutionParticipations(...)`
+ * itself is still synchronous (a pure derivation from `viewDefinition` +
+ * `registry` + `anchor` + `contextResourceIdentifiers`), but the first
+ * concrete producer for this tier ships as a pair of consumer-callable
+ * hooks — `useExecutionParticipationPrefetch` (generic primitive) and
+ * `useExecutionParticipationDataPrefetch` (opinionated wrapper). They
+ * orchestrate `doOperation()`-driven async data fetches around the
+ * `beginParticipationPrefetch` / `endParticipationPrefetch` lifecycle
+ * helpers below. See the
+ * `loading-aggregation.participation-prefetch.shell-data-hydrator`
+ * sub-anchor (immediately after this one) for the producer-side contract.
+ * Future async participation sources (e.g. a relationship-projection
+ * participation that needs to fetch the source resource's data to
+ * disambiguate the projection edge, or a future "lazy participation"
+ * mode that hydrates an aliased identifier from a remote call) can
+ * register through the same `beginParticipationPrefetch` /
+ * `endParticipationPrefetch` seam without re-shaping the public
+ * `ExecutionLoadingValue` surface.
+ *
+ * **What a "participation prefetch" is.** A bounded async unit of work
+ * whose purpose is to hydrate the data backing one or more participation
+ * refs *before* the consuming custom view treats those participations as
+ * fully resolved. Examples that would qualify (none exist today):
+ *
+ * - A relationship-projection participation that needs the source
+ *   resource's data to pick the right edge — the helper
+ *   `resolveExecutionParticipations` already accepts a
+ *   `sourceResourceDataByParticipationRef` parameter, but it is unused at
+ *   the `ExecutionView` call site because no async source feeds it.
+ * - A future "participation lazy-binding" mode where an anchor or
+ *   requirement participation hydrates an aliased identifier from a remote
+ *   call instead of from URL/ambient scope.
+ *
+ * Things that are NOT participation prefetches and must not be registered
+ * here (parent invariant #1 plus tier-specific clarifications):
+ *
+ * - Consumer-driven graph reads via
+ *   `useExecution().actions.operation(...).execute()`. Those are pending
+ *   execute actions and live in the `pendingActions` tier already (and
+ *   carry their own `operationPathKey` correlation key, which prefetches
+ *   intentionally do not).
+ * - Embedded-layout internal loading. Owned by the embed slot's own
+ *   contract; the parent anchor explicitly excludes it.
+ * - Workflow / multi-step phases authored by the consumer. The aggregator
+ *   does not accept consumer pushes; a consumer that wants a "view is
+ *   warming up" boolean composes one in its own `useState` from
+ *   `execution.loading.isParticipationPrefetching(...)` plus its own
+ *   bookkeeping.
+ *
+ * **Intent classification.** Each entry carries an
+ * `ExecutionParticipationPrefetchIntent`:
+ *
+ * - `INITIAL` — first-time hydration during shell bootstrap. Renderers
+ *   typically gate the entire view on this (full-screen skeleton).
+ * - `REFRESH` — re-hydration of an already-resolved participation
+ *   (background revalidation). Renderers typically render through with a
+ *   subtle indicator. Distinct from `INITIAL` so consumers can tell the
+ *   two apart without authoring a side-channel boolean.
+ *
+ * **Aggregation into `isBusy` (parent invariant #5).** Prefetch entries
+ * count toward `execution.loading.isBusy` exactly like pending execute
+ * actions. Per-tier narrowing is reached via the dedicated
+ * `isParticipationPrefetching(predicate?)` helper on
+ * `ExecutionLoadingValue` (no overlap with `isPending(...)` which stays
+ * about execute actions).
+ *
+ * **Producer registration.** Producers call the low-level
+ * `beginParticipationPrefetch` / `endParticipationPrefetch` helpers
+ * directly on `ExecutionNavigationValue` (mirrors the Slice B
+ * `beginPendingAction` / `endPendingAction` pattern). The Slice K hooks
+ * (`useExecutionParticipationPrefetch` /
+ * `useExecutionParticipationDataPrefetch`) are the framework-shipped
+ * wrappers around this seam — they own begin/end pairing, cancellation
+ * via `AbortController`, latest-error surfacing, and the optional
+ * bridge to `execution.errors.failedActions` (with the dedicated
+ * `PARTICIPATION_PREFETCH` scope and `clearFailedActionsForPrefetchKey`
+ * auto-prune lifecycle). Custom producers (e.g. a future shell-owned
+ * lazy-participation resolver) call the raw helpers directly and MUST
+ * pair every begin with a matching end inside a `try`/`finally` so
+ * parent invariant #2 ("settle always clears") holds for this tier too.
+ *
+ * Contract invariants (specialization of the parent anchor's invariants):
+ *
+ * 1. **Producer-minted ids; same-id re-register is idempotent-by-overwrite.**
+ *    `prefetchRuntimeId` is minted by the producer (in contrast to
+ *    `actionRuntimeId`, which the shell mints at the `doOperation()` bridge).
+ *    The shell does not de-duplicate semantically distinct units that happen
+ *    to share an id — calling `beginParticipationPrefetch` with an existing
+ *    id REPLACES the prior entry (last-write-wins). Producers MUST mint a
+ *    fresh id per in-flight unit so the timeline (start time, intent,
+ *    participation refs) is not silently overwritten by a concurrent unit
+ *    that happened to recycle the id.
+ * 2. **Non-empty participation refs.** `participationRefs` MUST contain at
+ *    least one ref. A prefetch that hydrates "no participation" has no
+ *    correlation handle and would be invisible to per-ref UX.
+ *    `assertExecutionPendingPrefetchShape` rejects empty arrays at the
+ *    nav helper boundary so dynamic callers (test mocks, deserialized
+ *    state, future authored hydrators) cannot bypass this.
+ *
+ *    **Not validated against `viewDefinition.participations`.** The shape
+ *    guard intentionally does not check that each ref exists in the
+ *    resolved participations registry. Doing so would couple this seam
+ *    to the view-definition layer (the nav helpers don't currently
+ *    receive the view definition), and would forbid producers from
+ *    pre-registering prefetches for participations that materialize
+ *    after the prefetch begins (a plausible pattern for the future
+ *    "participation lazy-binding" mode mentioned above). When the first
+ *    real producer ships, re-evaluate this trade-off — until then the
+ *    consequence of a typoed ref is "the entry will register but no
+ *    `isParticipationPrefetching((p) => p.participationRefs.includes(...))`
+ *    predicate will ever match", which is observable in renderer UX and
+ *    therefore self-correcting.
+ * 3. **Resource type required.** The `resourceType` field mirrors
+ *    `ExecutionPendingAction.resourceType` so per-resource UI filtering
+ *    (e.g. "is anything tasks-related loading?") composes uniformly across
+ *    both tiers.
+ * 4. **Intent must be a known value.** `INITIAL` or `REFRESH`. Unknown
+ *    intents would silently bypass renderer narrowing UX.
+ *    `assertExecutionPendingPrefetchShape` enforces this.
+ *
+ *    **Acknowledged rot risk.** The `INITIAL`/`REFRESH` vocabulary was
+ *    pinned ahead of any real producer (Slice H scaffolding). Plausible
+ *    additions a real producer might want — `BACKGROUND_SYNC` (idle-time
+ *    revalidation), `LAZY_HYDRATE` (visibility-triggered), `RETRY` (after
+ *    a failure) — would extend the enum additively. If a producer's
+ *    needed dimension does not fit the enum at all (e.g. priority,
+ *    cancellability), revisit `intent`'s shape rather than overload it.
+ */
+export declare enum ExecutionParticipationPrefetchIntent {
+    INITIAL = "initial",
+    REFRESH = "refresh"
+}
+export interface ExecutionPendingPrefetch {
+    /**
+     * Stable id for this in-flight prefetch entry. **Minted by the producer**
+     * (in contrast to `actionRuntimeId`, which the shell mints at the
+     * `doOperation()` bridge). Same-id re-register is idempotent-by-overwrite:
+     * the shell REPLACES the prior entry rather than de-duplicating two
+     * semantically distinct units. Producers MUST mint a fresh id per
+     * in-flight unit so the timeline is preserved — see invariant #1 in the
+     * sub-anchor JSDoc above.
+     */
+    prefetchRuntimeId: string;
+    /**
+     * Participation refs whose data is being hydrated by this prefetch.
+     * Multiple refs are allowed: one fetch can resolve several participations
+     * (e.g. a relationship-projection that needs both endpoints).
+     *
+     * Must contain at least one ref — a prefetch with no refs cannot be
+     * narrowed to per-ref UX and is a contract bug. Enforced at the nav
+     * helper boundary by `assertExecutionPendingPrefetchShape`.
+     */
+    participationRefs: readonly string[];
+    /**
+     * Primary resource type being hydrated. Mirrors
+     * `ExecutionPendingAction.resourceType` so per-resource UI filtering
+     * composes uniformly across both tiers of the loading aggregator.
+     */
+    resourceType: string;
+    /**
+     * Whether this is the first-time hydration (`INITIAL`) or a background
+     * re-hydration (`REFRESH`). Lets renderers distinguish "full-screen
+     * skeleton" vs "subtle indicator" without a side-channel boolean.
+     */
+    intent: ExecutionParticipationPrefetchIntent;
+    /** `Date.now()` when tracking began. */
+    startedAt: number;
+    /** Optional human-readable label ("Loading task graph"). Opaque to the shell. */
+    label?: string;
+}
+/**
+ * Belt-and-braces runtime check that an `ExecutionPendingPrefetch` entry
+ * is well-formed. Mirrors `assertExecutionDirtyMarkerShape` /
+ * `assertExecutionFailedActionShape` — exists for dynamic callers (test
+ * mocks, deserialized state, future authored hydrators) where the type
+ * may have been widened via `as`/`unknown`.
+ *
+ * Throws synchronously when:
+ * - `participationRefs` is missing or empty (would render the entry
+ *   un-narrowable for per-ref UX);
+ * - `resourceType` is missing or empty (breaks per-resource UI filtering
+ *   uniformity with the pending-action tier);
+ * - `intent` is not a known `ExecutionParticipationPrefetchIntent` value
+ *   (would silently bypass renderer narrowing UX).
+ */
+export declare function assertExecutionPendingPrefetchShape(prefetch: ExecutionPendingPrefetch): void;
+/** @wildo_source:part:end saas.frontend.execution-view.loading-aggregation.participation-prefetch */
+/**
+ * @wildo_source:part:start saas.frontend.execution-view.loading-aggregation.participation-prefetch.shell-data-hydrator facet:layer:frontend facet:family:execution-view facet:kind:contract facet:audience:framework-author
+ *
+ * First concrete producer for the participation-prefetch tier (Slice K).
+ *
+ * Sub-anchor of `loading-aggregation.participation-prefetch`. Defines the
+ * contract for the framework-shipped producer pair:
+ *
+ * - **`useExecutionParticipationPrefetch`** — generic primitive hook. Owns
+ *   the begin/end pairing for `ExecutionPendingPrefetch` entries, the
+ *   `AbortController`-driven cancellation on unmount / re-run, the
+ *   stable per-mount `prefetchKey`, and the optional bridge of failures
+ *   into `execution.errors.failedActions` under
+ *   `ExecutionFailedActionScope.PARTICIPATION_PREFETCH`. Consumers
+ *   provide an async `run({ signal })` callback that performs the actual
+ *   work — typical use is a `doOperation()` invocation, but the hook is
+ *   intentionally fetch-mechanism-agnostic so future producers (a
+ *   relationship-projection source-resource hydrator, a lazy-binding
+ *   resolver) can reuse the same lifecycle plumbing without adopting
+ *   `doOperation()` semantics they do not need.
+ *
+ * - **`useExecutionParticipationDataPrefetch`** — opinionated wrapper over
+ *   the primitive that targets the most common case: hydrate a single
+ *   participation's resource data via `doOperation()` (the canonical
+ *   READ operation for the resolved resource type). Consumers pass
+ *   `{ participationRef, intent }` and receive
+ *   `{ data, isLoading, error, refetch, prefetchKey }`. The wrapper
+ *   threads `intent`, computes the operation path key from the
+ *   participation's resource type, supplies the AbortController, and
+ *   defaults `bridgeFailuresToShellAggregator` per-intent (see invariant
+ *   #6 below).
+ *
+ * **Why two layers (decision: layered API).** A single opinionated hook
+ * would force every future producer (relationship-projection hydrator,
+ * lazy-binding resolver, …) to either go through the same READ-shaped
+ * `doOperation()` path or drop to the raw nav helpers and duplicate the
+ * lifecycle plumbing. A single primitive-only hook would push the
+ * "fetch a participation's data" boilerplate (operation path key
+ * derivation, intent-driven bridge default, single-ref shape) onto every
+ * call site of the most common case. Layering the two solves both:
+ * primitive owns lifecycle, wrapper owns the canonical fetch shape, and
+ * consumers pick whichever level matches their use case. Rejected
+ * alternatives: (a) primitive only — common-case boilerplate cost,
+ * (b) wrapper only — fetch-mechanism rot risk for future producers,
+ * (c) wrapper as method on `useExecution()` — would couple the public
+ * `useExecution()` surface to a single fetch shape and obscure the
+ * primitive seam.
+ *
+ * **Why call `doOperation()` directly, not `actions.operation().execute()`
+ * (decision: `fetch-doOperation-direct`).** `actions.operation().execute()`
+ * registers a `pendingAction` in the *execute-action* tier, which would
+ * double-count the same logical work in `loading.isBusy` (once via the
+ * pending action, once via the prefetch entry) and would trigger the
+ * shell's failure-handling-contract bridge for both tiers. The wrapper
+ * therefore calls `navigation.doOperation(...)` directly inside the
+ * `run({ signal })` callback, keeping the prefetch tier semantically
+ * separate from the execute-action tier. The action-status snapshot's
+ * JSDoc already documents that prefetches don't carry an
+ * `operationPathKey` correlation key — this is the producer side of
+ * that decision: prefetches are not "actions" the framework can retry
+ * via `action.retry()`; they are revalidation cycles the consumer
+ * controls via `refetch()`. Rejected alternative: route through
+ * `execute()` for "free" outcome emission and consistency — the
+ * double-tier accounting and re-emit risk outweigh the consistency win.
+ *
+ * Contract invariants (specialization of the parent sub-anchor's
+ * invariants):
+ *
+ * 1. **Stable `prefetchKey` per logical unit.** The hook caches a
+ *    `prefetchKey` per mount (typically derived from the consumer's
+ *    keying inputs — resource type + participation ref + intent — or
+ *    explicitly authored). The same key is reused across consecutive
+ *    `refetch()` cycles so the shell's
+ *    `clearFailedActionsForPrefetchKey(key)` verb can drop matching
+ *    entries on the next successful settle. Distinct from
+ *    `prefetchRuntimeId`, which rotates on every fire so the parent
+ *    sub-anchor's invariant #1 ("producer-minted ids; same-id
+ *    re-register is idempotent-by-overwrite") is honored without the
+ *    consumer having to think about it.
+ *
+ * 2. **One in-flight unit per hook instance.** A new `run()` while a
+ *    prior one is in flight aborts the prior `AbortController` and
+ *    `endParticipationPrefetch`es the prior `prefetchRuntimeId` before
+ *    minting a fresh id and beginning the new unit. Prevents two
+ *    concurrent units from accumulating in `pendingPrefetches` for the
+ *    same logical key (which would inflate `isBusy` and confuse
+ *    per-ref UX). Consumers who legitimately want parallel hydration
+ *    of distinct participations mount distinct hook instances — one
+ *    instance per logical unit is the framework rule, mirroring the
+ *    `useEffect`-per-effect pattern.
+ *
+ * 3. **Settle always clears (parent invariant #2 specialization).** The
+ *    primitive's `try`/`finally` around the consumer's `run(...)`
+ *    guarantees `endParticipationPrefetch(prefetchRuntimeId)` runs on
+ *    success, throw, AND `AbortError`. On unmount, the cleanup branch
+ *    aborts the controller and ends the prefetch synchronously — the
+ *    in-flight `doOperation()` rejection arrives later in a no-op
+ *    settle (the runtime id is already gone, so `endParticipationPrefetch`
+ *    is a no-op per the public JSDoc).
+ *
+ * 4. **Stale-while-revalidate for `REFRESH`.** When `intent === REFRESH`,
+ *    the wrapper keeps the prior `data` value visible while the new
+ *    fetch is in flight (returning `{ data: <stale>, isLoading: true,
+ *    error }`). When `intent === INITIAL`, `data` is `undefined` until
+ *    the first successful settle. This split mirrors the parent
+ *    sub-anchor's intent classification ("full-screen skeleton" vs
+ *    "subtle indicator") on the data side.
+ *
+ * 5. **Latest-error surfacing.** The hook always surfaces the *latest*
+ *    settle's `error` (or `undefined` on success) in its return value —
+ *    `error` is reset to `undefined` on every successful settle and is
+ *    set to the rejection on every failed one. This is the consumer's
+ *    primary error-display channel; the optional shell-aggregator
+ *    bridge (next invariant) is for cross-component aggregation and
+ *    persistent failure history.
+ *
+ * 6. **Optional shell-aggregator bridge (`bridgeFailuresToShellAggregator`).**
+ *    When `true` (the wrapper's default for `INITIAL`, opt-in for
+ *    `REFRESH`), failures are also captured via
+ *    `execution.errors.capture({ scope: PARTICIPATION_PREFETCH,
+ *    prefetchKey, ... })`, where they participate in the cross-component
+ *    `failedActions` aggregator and auto-prune on the next successful
+ *    settle for the same key (via
+ *    `clearFailedActionsForPrefetchKey(prefetchKey)`, called by the hook).
+ *    When `false`, failures are surfaced only via the hook's `error`
+ *    return value — the right choice for "background revalidation that
+ *    must not raise a global banner". The default split (INITIAL=true,
+ *    REFRESH=false in the wrapper) reflects the typical UX: an initial
+ *    hydration failure is noteworthy enough to surface globally; a
+ *    silent revalidation failure usually is not. The primitive defaults
+ *    to `false` (consumers explicitly opt in) because it has no
+ *    intent-aware default to lean on.
+ *
+ * 7. **No retry verb.** Refetch is the only retry pattern. The hook
+ *    exposes `refetch()` (re-runs with the same inputs); the shell does
+ *    not synthesize a `retry()` analog of the action-status one because
+ *    prefetches don't carry an `operationPathKey` correlation key (see
+ *    `ExecutionOperationActionStatus.isPending` JSDoc on the per-tier
+ *    separation). Consumers wanting "clear failure + refetch" call
+ *    `refetch()` — the bridge auto-prunes the prior failure on
+ *    successful settle.
+ *
+ * 8. **`PARTICIPATION_PREFETCH` scope is dedicated.** Failures bridged
+ *    by these hooks land under `ExecutionFailedActionScope.PARTICIPATION_PREFETCH`
+ *    (NOT `CUSTOM`), which is auto-cleared by
+ *    `clearFailedActionsForPrefetchKey(prefetchKey)`. This is the
+ *    fourth scope and exists specifically because the auto-prune
+ *    lifecycle (per-key on successful settle) is genuinely distinct
+ *    from the zone-transition-based pruning of `EMBEDDED_CONTENT` /
+ *    `LOCAL_PANE` and the manual-only model of `CUSTOM`. See the
+ *    failure-handling-contract anchor for the full scope vocabulary.
+ *
+ * **Where it composes with the rest of the shell.** A consumer view that
+ * needs to hydrate a participation's data ahead of an interaction (the
+ * Slice K dogfood: chrome banner showing `todoList.name`, inspector
+ * node hover prewarming the inspector pane) calls
+ * `useExecutionParticipationDataPrefetch({ participationRef, intent })`
+ * and threads the returned `{ data, isLoading, error }` into its UI.
+ * Per-tier loading questions still flow through the public aggregator:
+ * `execution.loading.isParticipationPrefetching((p) =>
+ * p.participationRefs.includes(ref))` answers "is *this ref* being
+ * hydrated?" from the chrome's perspective without knowing which hook
+ * mounted the prefetch.
+ *
+ * @wildo_source:part:end saas.frontend.execution-view.loading-aggregation.participation-prefetch.shell-data-hydrator
+ */
+/**
+ * @wildo_source:part:start saas.frontend.execution-view.dirty-state-contract facet:layer:frontend facet:family:execution-view
+ *
+ * Execution-shell dirty-state contract.
+ *
+ * The execution shell aggregates **authored** dirty-state markers — one per
+ * distinguishable unsaved surface — so consumers can query a single truthful
+ * `execution.dirty` signal before kicking zone transitions (close the embed,
+ * replace the embed, switch panes, delegate to the router). The shell does
+ * **not** enforce modals or block transitions; it only publishes the markers.
+ * UX decisions (confirm dialog, toast, ignore) live with the consumer.
+ *
+ * Publisher / subscriber model (mirrors the loading-aggregation tier):
+ *
+ * - **Publishers** are whoever owns the unsaved state. Today that's either a
+ *   custom component rendering zone-B content with editable fields, or an
+ *   adapter wrapping an RMM-backed embedded edit surface (zone A). Publishers
+ *   call `execution.dirty.mark({ markerId, scope, label?, paneId? })` on
+ *   first edit and `execution.dirty.clear(markerId)` on save/discard.
+ * - **Subscribers** (the execution view renderer, the shell's transition
+ *   verbs) read `execution.dirty.markers` / `execution.dirty.isAnyDirty` and
+ *   author UX accordingly.
+ *
+ * Why the shell doesn't query the embedded layout directly: the shell does
+ * not hold a reference to the embedded layout's RMM instance — that
+ * `ResourceMutationManager` lives inside the `ResourceOperationSurface` and
+ * exposes `hasUnsavedChanges` only through `useResourceMutationManager`
+ * subscribers, not through a cross-layer observable. Adding a cross-reach
+ * would couple the shell to a specific mutation manager implementation. The
+ * publish/subscribe contract keeps the boundary clean.
+ *
+ * **Scopes** classify a marker's lifecycle so the shell can safely auto-clean
+ * without asking the publisher. Scope is not purely decorative — it drives
+ * the auto-cleanup invariant below:
+ *
+ * - `EMBEDDED_CONTENT` — the unsaved state belongs to the current embed
+ *   slot. When the slot empties (close, replace), the marker is auto-cleared
+ *   because the layout that authored it is gone by definition.
+ * - `LOCAL_PANE` — the unsaved state belongs to the currently-open
+ *   `localPane`. When the pane closes or a *different* `paneId` opens, the
+ *   marker is auto-cleared. If the publisher wants the draft to survive
+ *   pane-id transitions, it should use `CUSTOM` scope.
+ * - `CUSTOM` — consumer-owned lifecycle. The shell never auto-clears these.
+ *   Used for draft state that outlives any single zone transition (e.g.
+ *   a top-level side panel authored by the custom component itself).
+ *
+ * Contract invariants:
+ *
+ * 1. **Publisher owns mark/clear.** The shell never synthesizes markers — no
+ *    "auto-mark on first type" magic. Publishers call `mark()` explicitly,
+ *    and symmetrically call `clear()` on save or discard.
+ * 2. **Auto-cleanup at zone boundaries.** `closeEmbeddedContent`/
+ *    `openEmbeddedContent` clear all `EMBEDDED_CONTENT`-scoped markers;
+ *    `closeLocalPane`/`openLocalPane` clear all `LOCAL_PANE`-scoped markers
+ *    whose `paneId` no longer matches the active pane. `CUSTOM` markers are
+ *    untouched.
+ * 3. **Stable marker ids.** `markerId` must be stable across re-renders of
+ *    the same publisher — re-marking an existing id is idempotent (replaces
+ *    the entry, does not produce a duplicate).
+ * 4. **Shell is informative, not restrictive.** Transition verbs
+ *    (`closeEmbeddedContent`, `openEmbeddedContent`, `delegateToParent`) do
+ *    *not* block on dirty state. Consumers read `isAnyDirty` and author
+ *    their own confirm flow before calling the transition. Making the shell
+ *    block would force a modal UX the framework cannot reasonably author
+ *    centrally.
+ * 5. **Per-runtime-instance scope.** The aggregator lives on
+ *    `ExecutionRuntimeState`, not globally. Two execution views mounted in
+ *    the same app do not share dirty markers.
+ * 6. **Orthogonal to other shell tiers.** Dirty state is not a navigation
+ *    zone (three-zone contract) nor operational telemetry (loading
+ *    aggregation). It is its own shell tier with its own invariants.
+ */
+export declare enum ExecutionDirtyMarkerScope {
+    EMBEDDED_CONTENT = "embedded-content",
+    LOCAL_PANE = "local-pane",
+    CUSTOM = "custom"
+}
+/**
+ * Common shape for every dirty marker, regardless of scope.
+ *
+ * Intentionally not exported on its own — consumers use the
+ * `ExecutionDirtyMarker` discriminated union below so the type system
+ * enforces "LOCAL_PANE markers carry a `paneId`" without requiring
+ * defensive `!== undefined` checks at every read site.
+ */
+interface ExecutionDirtyMarkerBase {
+    /**
+     * Stable publisher-authored id. Re-marking the same id is idempotent —
+     * the entry is replaced, not duplicated. Typically derived from a
+     * resource identity (e.g. `embed:tasks:task-1:UPDATE`) or a pane-scoped
+     * key (e.g. `pane:todo-inspector:draft`).
+     */
+    markerId: string;
+    /**
+     * Optional human-readable reason ("Unsaved task changes", "Draft
+     * description"). Consumers may surface it in confirm dialogs or ambient
+     * badges; the shell treats it as opaque metadata.
+     */
+    label?: string;
+    /** `Date.now()` when the marker was first registered. */
+    markedAt: number;
+}
+/**
+ * Discriminated union of dirty markers.
+ *
+ * The discriminant `scope` makes "`paneId` is required for `LOCAL_PANE`
+ * markers, absent on the others" a compile-time invariant — there is no
+ * `paneId?` escape hatch on the non-pane variants. Combined with the
+ * runtime assertion `assertExecutionDirtyMarkerShape`, dynamic callers
+ * (test mocks, deserialized state, authored dictionaries) cannot collapse
+ * the variants either.
+ */
+export type ExecutionDirtyMarker = (ExecutionDirtyMarkerBase & {
+    scope: ExecutionDirtyMarkerScope.EMBEDDED_CONTENT;
+}) | (ExecutionDirtyMarkerBase & {
+    scope: ExecutionDirtyMarkerScope.LOCAL_PANE;
+    paneId: string;
+}) | (ExecutionDirtyMarkerBase & {
+    scope: ExecutionDirtyMarkerScope.CUSTOM;
+});
+/**
+ * Belt-and-braces runtime check that a `ExecutionDirtyMarker` matches its
+ * discriminant invariants. The type layer already enforces these for
+ * statically-shaped callers; this assertion exists for dynamic callers
+ * (test mocks, deserialized payloads, authored dictionaries) where the
+ * type may have been widened via `as`/`unknown`.
+ *
+ * Throws synchronously when a `LOCAL_PANE` marker is registered without a
+ * `paneId` — the only invariant that cannot be expressed any other way.
+ */
+export declare function assertExecutionDirtyMarkerShape(marker: ExecutionDirtyMarker): void;
+/** @wildo_source:part:end saas.frontend.execution-view.dirty-state-contract */
+/**
+ * Contract for content that an execution view is allowed to embed inside its
+ * own shell. Today only `NavigationContent.RESOURCE_OPERATION` is embeddable,
+ * so consumers cannot stuff arbitrary navigation content into the slot.
+ *
+ * Naming note: this is the `Embeddable*` contract (what *can* be embedded),
+ * not an `Embedded*` state. Once the runtime actually holds an instance, it
+ * lives in `ExecutionEmbeddedContentState`.
+ */
+export type ExecutionEmbeddableContent = Extract<NavigationContent, {
+    contentType: NavigationContentType.RESOURCE_OPERATION;
+}>;
+/**
+ * State of the execution view's single embedded-content slot.
+ *
+ * The shell guarantees only one embedded surface is mounted at a time.
+ * `navigationInitiator` preserves the same provenance
+ * (`sourceZone`, `launcher`, `sourceOperation`, `sourceRelationship`) a
+ * router-delegated surface would receive, so embedded and routed surfaces
+ * behave identically downstream.
+ */
+export interface ExecutionEmbeddedContentState {
+    content: ExecutionEmbeddableContent;
+    navigationInitiator?: NavigationInitiatorContext;
+}
+/**
+ * @wildo_source:part:start saas.frontend.execution-view.three-zone-contract facet:layer:frontend facet:family:execution-view
+ *
+ * Three-zone contract for execution-view child intent.
+ *
+ * An execution view has exactly three zones where frontend-only state and
+ * child navigation intent can live. Each zone has a **distinct semantic
+ * purpose**, and a consumer must pick exactly one per intent. The zones are
+ * not stylistic variants — collapsing any two into each other destroys the
+ * execution shell's ability to reason about what it owns vs what the router
+ * owns.
+ *
+ * | Zone | Lives in | Payload | Owner | Purpose |
+ * |---|---|---|---|---|
+ * | **A. `embeddedContent`** | `ExecutionRuntimeState` | `ExecutionEmbeddableContent` (`NavigationContent.RESOURCE_OPERATION` only) | Execution shell (`ExecutionView`) | Mount a downstream resource-operation surface inside the shell instead of delegating to the router (the "embed" seam) |
+ * | **B. `localPane`** | `ExecutionRuntimeState` | `{ paneId: string; payload?: unknown }` — renderer-opaque data, **never** `NavigationContent` | Custom component (the view's own `viewComponent`) | Ephemeral shell state — inspectors, drawers, selection metadata. Not navigation content. |
+ * | **C. `delegateToParent`** | App router (parent navigation stack) | Any `NavigationContent` | App router | Yield control to the router. The execution view loses the screen for this intent. |
+ *
+ * Invariants that make this a contract, not three coincidental state fields:
+ *
+ * 1. **Mutual exclusivity by purpose.** A single intent picks exactly one
+ *    zone. "Open a read surface next to the current view" is zone A. "Remember
+ *    which node the user clicked" is zone B. "Send the user back to the home
+ *    page" is zone C.
+ * 2. **No content-type confusion.** Zone A is resource-operation-only (typed
+ *    as `ExecutionEmbeddableContent`). Zone B's `payload` is **not**
+ *    `NavigationContent` — if a consumer finds itself tempted to put
+ *    `{ contentType: NavigationContentType.RESOURCE_OPERATION, ... }` into a
+ *    pane payload, that intent belongs in zone A. Zone C is the only zone
+ *    that accepts arbitrary `NavigationContent`, and it hands it off.
+ * 3. **Shell owns the shell.** Zones A and B both live in
+ *    `ExecutionRuntimeState`, but the rendering responsibility differs:
+ *    `ExecutionView` renders zone A (including the close affordance);
+ *    the custom component renders zone B itself using the pane state it
+ *    authored. Consumers never reinvent the zone A shell.
+ * 4. **One slot per zone.** Zones A and B are single-slot. Opening a new
+ *    embed replaces the previous one; opening a new pane replaces the
+ *    previous one. If a surface truly needs "many open inspectors at once",
+ *    that's renderer state inside a single pane payload, not multiple panes.
+ * 5. **Provenance parity.** Zones A and C both thread
+ *    `NavigationInitiatorContext` (`sourceZone`, `launcher`, `sourceOperation`,
+ *    `sourceRelationship`) — see the embedding-principle anchor at
+ *    `saas.frontend.execution-view.navigation-handling-and-embedding`. An
+ *    embedded read surface behaves indistinguishably from a routed read
+ *    surface of the same resource.
+ * 6. **Defensive validation at the zone boundary.** The runtime fails fast
+ *    when a caller misroutes an intent — `openLocalPane` rejects payloads
+ *    shaped like `ExecutionEmbeddableContent` and `openEmbeddedContent`
+ *    rejects non-`RESOURCE_OPERATION` content — see
+ *    `assertExecutionLocalPanePayloadIsNotEmbeddableContent` and
+ *    `assertExecutionEmbeddableContent` below. These assertions are
+ *    belt-and-braces over the type layer; they exist so dynamic callers (test
+ *    mocks, deserialized state, authored dictionaries) cannot silently collapse
+ *    the zones.
  */
 export interface ExecutionRuntimeState {
+    embeddedContent: ExecutionEmbeddedContentState | null;
     localPane: ExecutionLocalPaneState | null;
+    /**
+     * Pending shell-tracked actions keyed by `actionRuntimeId`. See the
+     * loading-aggregation anchor above — this is operational telemetry, not
+     * a navigation zone.
+     */
+    pendingActions: Record<string, ExecutionPendingAction>;
+    /**
+     * In-flight participation prefetch entries keyed by `prefetchRuntimeId`.
+     * See the `loading-aggregation.participation-prefetch` sub-anchor above.
+     * Today this slot is wired but not populated — no in-tree producer
+     * registers prefetches because participation resolution is fully
+     * synchronous. The slot exists so that the day a real async producer
+     * materializes, the public `ExecutionLoadingValue` can expose
+     * `participationPrefetchActions` / `isAnyParticipationPrefetching` /
+     * `isParticipationPrefetching(...)` without re-shaping the API.
+     */
+    participationPrefetchActions: Record<string, ExecutionPendingPrefetch>;
+    /**
+     * Authored dirty-state markers keyed by `markerId`. See the
+     * dirty-state-contract anchor above — scope-based auto-cleanup applies at
+     * zone transitions but the shell never synthesizes or forces-blocks on
+     * these markers.
+     */
+    dirtyMarkers: Record<string, ExecutionDirtyMarker>;
+    /**
+     * Captured failed-action entries keyed by `failureRuntimeId`. See the
+     * failure-handling-contract anchor — scope-based auto-cleanup mirrors
+     * `dirtyMarkers`; the shell captures and bridges, but does not retry or
+     * suppress consumer error UX.
+     */
+    failedActions: Record<string, ExecutionFailedAction>;
 }
+/**
+ * Validates that a `localPane` payload is not accidentally an
+ * `ExecutionEmbeddableContent`. See the three-zone contract above: zone B
+ * payloads are renderer-opaque data, not navigation content.
+ *
+ * Throws with a message pointing the caller to
+ * `openEmbeddedContent`/`execution.actions.operation(...).embed()` when a
+ * misroute is detected. No-op for normal renderer payloads.
+ */
+export declare function assertExecutionLocalPanePayloadIsNotEmbeddableContent(payload: unknown): void;
+/**
+ * Validates that a value claimed to be `ExecutionEmbeddableContent` truly is
+ * one. Today that means `contentType === NavigationContent.RESOURCE_OPERATION`;
+ * see the three-zone contract above.
+ *
+ * The type layer already enforces this, so this assertion is belt-and-braces
+ * for dynamic callers (test mocks, deserialized content, authored action
+ * dictionaries) where the type may have been widened via `as`/`unknown`.
+ */
+export declare function assertExecutionEmbeddableContent(content: ExecutionEmbeddableContent): void;
+/** @wildo_source:part:end saas.frontend.execution-view.three-zone-contract */
+/**
+ * @wildo_source:part:start saas.frontend.execution-view.outcome-emission-contract facet:layer:frontend facet:family:execution-view
+ *
+ * Execution-shell operation-outcome emission contract.
+ *
+ * The execution shell is a **canonical producer** on the app-level
+ * `FrontendEvents` bus (`EventBus`) for every successful `.execute()` call.
+ * It does *not* introduce a parallel execution-scoped outcome bus — the
+ * framework already has one (`RESOURCE_OPERATION_EXECUTED` + `RESOURCE_REFRESH`
+ * consumed by `NotificationContext`, `WebSocketEventBridge`, `useListInvalidation`,
+ * and `resourceRefreshEvent` subscribers). A second bus would double-plumb the
+ * same signal and force every subscriber to learn two APIs.
+ *
+ * Emission site: `useExecution().execute()` → `emitResourceOperationOutcome`
+ * (see `execution-outcome-emission.utils.ts`). Payloads mirror
+ * `useResourceOperationActions.handleExecuteOperation` exactly, so
+ * execution-shell-driven operations are indistinguishable from
+ * resource-layout-driven ones on the wire.
+ *
+ * Contract invariants:
+ *
+ * 1. **Single canonical bus.** No new public surface on `useExecution()` for
+ *    outcomes. Consumers subscribe via `useEventBus` / `useEventSubscription`
+ *    just like for any other operation producer. An execution-local bus
+ *    would hide signals from app-global subscribers (toast policy, WS bridge,
+ *    analytics) that must see every operation.
+ *
+ * 2. **Emit `RESOURCE_OPERATION_EXECUTED` unconditionally on success.**
+ *    Every resolved `.execute()` is a canonical operation-outcome event.
+ *    `NotificationContext` does *not* subscribe to this event (it is under
+ *    `NEED_REFRESH`, not `NOTIFY_USER`), so emitting for READ / LIST / custom
+ *    operations never produces unintended toasts. User-visible toasts travel
+ *    on `NOTIFY_RESOURCE_*`, which the backend drives.
+ *
+ * 3. **Emit `RESOURCE_REFRESH` only for real mutations + WS disconnected.**
+ *    Gate: `shouldEmitResourceRefreshAfterDirectOperation(operation)
+ *    && !isWebSocketConnected`. When the WS bridge is up it pushes refreshes
+ *    natively; emitting from here too would double-fire every listener.
+ *    Non-mutating operations (READ / LIST / custom) never trigger list
+ *    refreshes — refresh is an authored consequence of data change, not a
+ *    signal of "some operation happened".
+ *
+ * 4. **Silent on failure.** Rejected promises do *not* emit an outcome
+ *    event — subscribers use `.catch()` or the `NOTIFY_RESOURCE_ERROR`
+ *    channel for failure UX. Emitting a failure variant here would force a
+ *    specific error-UX on every consumer, which mirrors the dirty-state
+ *    contract's "informative, not restrictive" stance.
+ *
+ * 5. **Emission before settle.** Emit fires *inside* the `try` block, *before*
+ *    the `finally` clause calls `endPendingAction`. Subscribers that check
+ *    `execution.loading.isBusy` during their handler therefore still see
+ *    `true` — this matches `runPostOperationEffects` in
+ *    `useResourceOperationActions`, which runs before its own
+ *    `isExecuting = false` cleanup.
+ *
+ * 6. **Payload parity with canonical.** Shape, field names, and optional
+ *    discriminator threading must match the emissions from
+ *    `useResourceOperationActions` / `ResourceLayout_Update`. Any drift is a
+ *    bug — downstream subscribers rely on a single uniform payload across
+ *    producers.
+ */
+/** @wildo_source:part:end saas.frontend.execution-view.outcome-emission-contract */
+/**
+ * @wildo_source:part:start saas.frontend.execution-view.failure-handling-contract facet:layer:frontend facet:family:execution-view
+ *
+ * Execution-shell failure-handling contract.
+ *
+ * The execution shell aggregates **failed actions** as a symmetric counterpart
+ * to the loading-aggregation tier (Slice B) and the outcome-emission tier
+ * (Slice D). Every `useExecution().execute()` rejection — and any
+ * consumer-authored failure (render-adjacent caught exceptions, manual
+ * `errors.capture(...)` calls) — is captured into a single shell-owned bag of
+ * `ExecutionFailedAction` entries. Consumers read `execution.errors` to drive
+ * inline retry UX without rebuilding ad hoc per-component error state.
+ *
+ * What this tier owns (and why):
+ *
+ * - **Captured failures.** The shell's `execute()` catch path captures the
+ *   raw error alongside the originating action's identity (`actionRuntimeId`,
+ *   `operationPathKey`, `resourceType`, `operationId`) so consumers can render
+ *   targeted "Retry CREATE on Task" affordances instead of generic banners.
+ * - **Conditional bridge to the canonical bus.** Most rejections come from
+ *   the HTTP layer, which has *already* been processed by
+ *   `errorManagement.handleHttpError(...)` (built a `WildoError_Frontend`,
+ *   applied the configured behavior, conditionally emitted `ERROR_OCCURED`
+ *   based on the per-status policy and the request's `silent` flag). The
+ *   shell detects this via the `error.wildoError` marker that
+ *   `wildo-http-client` attaches and **defers to that upstream processing
+ *   instead of re-emitting**. Synchronous throws and non-axios rejections
+ *   (no `wildoError`) are bridged once via `errorManagement.handleError(...)`
+ *   so global subscribers (`GlobalErrorHandler`, `NotificationContext` for
+ *   `NOTIFY_RESOURCE_ERROR`) still see them.
+ *
+ *   Note: HTTP rejections marked by `wildo-http-client` may not have
+ *   actually emitted to the bus (silent requests, `emitEvent: false` in
+ *   the per-status matrix). The shell honors that consumer-requested
+ *   silence rather than re-emitting on its own — see
+ *   `markedByHttpClient` vs. `bridgedByExecutionShell` on
+ *   `ExecutionFailedAction` for the truthful per-entry provenance.
+ *
+ * What this tier intentionally does **not** own:
+ *
+ * - **A second error bus.** The framework already has `ERROR_OCCURED`,
+ *   `NOTIFY_RESOURCE_ERROR`, and `NOTIFY_CUSTOM_ERROR` on the canonical bus.
+ *   Adding an execution-scoped error stream would force consumers to learn
+ *   two APIs and would hide failures from app-global subscribers.
+ * - **A new render-error boundary.** Render crashes inside the execution view
+ *   surface through the existing application `ErrorBoundary` (see
+ *   `core/errors/ErrorBoundary.tsx`) which already emits `ERROR_OCCURED` and
+ *   renders the canonical `AppLayout_ErrorBoundary` fallback. The execution
+ *   shell wraps its content in that boundary instead of reinventing one.
+ * - **Built-in retry orchestration.** The shell exposes failed-action
+ *   metadata; the consumer owns the retry call site. A built-in
+ *   `retry()` would have to re-author the original action verb (which the
+ *   shell does not retain), and would obscure idempotency / context-refresh
+ *   decisions that only the consumer can make. Consumers retry by re-invoking
+ *   the same action verb after `clear(failureRuntimeId)`.
+ *
+ * **Scopes** classify a failure's lifecycle so the shell can safely
+ * auto-clean without asking the publisher. They mirror
+ * `ExecutionDirtyMarkerScope` exactly to keep the mental model uniform:
+ *
+ * - `EMBEDDED_CONTENT` — the failure belongs to the current embed slot.
+ *   Auto-cleared on `openEmbeddedContent` / `closeEmbeddedContent`.
+ * - `LOCAL_PANE` — the failure belongs to the currently-open `localPane`.
+ *   Auto-cleared on pane close, or when a different `paneId` opens.
+ * - `CUSTOM` — consumer-owned lifecycle. Default for all `execute()`-captured
+ *   failures (the shell does not know which zone the consumer's action verb
+ *   belongs to). The shell never auto-clears these.
+ * - `PARTICIPATION_PREFETCH` — the failure originated from the participation-
+ *   prefetch tier (Slice K's first producer). Auto-cleared on the next
+ *   *successful* prefetch with the same `prefetchKey`. The 4th scope was
+ *   added rather than overloading `CUSTOM` because the auto-prune lifecycle
+ *   is genuinely distinct: prefetch failures live in a "stale-data
+ *   indicator" UX where the next successful refetch implicitly resolves
+ *   them, whereas `CUSTOM` failures persist until consumer-cleared. Carries
+ *   a `prefetchKey: string` discriminant payload — the consumer-authored
+ *   stable identity (NOT the per-run `prefetchRuntimeId` which rotates per
+ *   in-flight unit) — so the shell's `clearFailedActionsForPrefetchKey(key)`
+ *   verb can target the right entries on settle. See the
+ *   `loading-aggregation.participation-prefetch.shell-data-hydrator`
+ *   sub-anchor for the producer-side contract this scope serves.
+ *
+ * Contract invariants:
+ *
+ * 1. **Capture always, bridge at most once.** Every `execute()` rejection
+ *    produces exactly one `ExecutionFailedAction` entry. The shell calls
+ *    `errorManagement.handleError(...)` only when no upstream layer has
+ *    already processed the error (detected via the `error.wildoError`
+ *    marker that `wildo-http-client.handleHttpError` attaches). The shell
+ *    never re-bridges an HTTP-marked error even if that upstream processing
+ *    suppressed emission via `silent` or `emitEvent: false` — honoring
+ *    consumer-requested silence is part of the contract. Each captured
+ *    entry records `markedByHttpClient` and `bridgedByExecutionShell`
+ *    truthfully so consumers can reason about provenance per entry.
+ * 2. **Re-throw after capture.** `execute()` re-throws the original error
+ *    after capturing + (conditionally) bridging, so consumer `.catch()`
+ *    handlers and `await`-style call sites still observe the rejection.
+ *    The shell augments the canonical contract; it does not swallow it.
+ * 3. **Capture happens before pending clears, but the renderer sees both
+ *    in the same React commit.** Mechanically the `catch` block runs
+ *    `captureFailedAction(...)` then re-throws, after which the `finally`
+ *    block runs `endPendingAction(...)`. React batches the resulting
+ *    `setState` updates inside the same microtask, so consumers render
+ *    with `pending=false` and `errored=true` simultaneously — there is no
+ *    intermediate "still-pending-but-already-failed" state visible to a
+ *    rendered component. (Subscribers that observe state through refs or
+ *    custom selectors during the catch microtask may briefly see both
+ *    flags true; that path is shell-internal plumbing only.)
+ * 4. **Auto-cleanup at zone boundaries (and at prefetch settle).**
+ *    `openEmbeddedContent`/`closeEmbeddedContent` clear all
+ *    `EMBEDDED_CONTENT`-scoped failures; `openLocalPane`/`closeLocalPane`
+ *    clear all `LOCAL_PANE`-scoped failures whose `paneId` no longer matches
+ *    the active pane; `PARTICIPATION_PREFETCH`-scoped failures are cleared
+ *    by `clearFailedActionsForPrefetchKey(prefetchKey)` (called by the
+ *    Slice K hooks on the next *successful* settle of the same prefetch
+ *    unit). `CUSTOM` failures are untouched by every auto-cleanup path —
+ *    the shell never collects them on its own. This mirrors the
+ *    dirty-state contract auto-cleanup so consumers reason about all tiers
+ *    with the same scope vocabulary, just with one extra trigger
+ *    (per-`prefetchKey` settle) for the prefetch lifecycle.
+ * 5. **Stable failure ids.** `failureRuntimeId` is generated by the shell at
+ *    capture time. Re-capturing an `originatingActionRuntimeId` (e.g.
+ *    consumer retried, action failed again) produces a *new* failure entry
+ *    rather than mutating the prior one — the timeline is preserved so
+ *    consumers can render attempt count or last-attempt-time UX.
+ * 6. **Per-runtime-instance scope.** The aggregator lives on
+ *    `ExecutionRuntimeState`, not globally. Two execution views mounted in
+ *    the same app do not share failed-action state.
+ * 7. **Shell is informative, not restrictive.** Capturing a failure does
+ *    *not* alter execution lifecycle, block transitions, or veto subsequent
+ *    `execute()` calls. UX (banner vs. toast vs. inline retry button) is
+ *    owned by the consumer.
+ */
+export declare enum ExecutionFailedActionScope {
+    EMBEDDED_CONTENT = "embedded-content",
+    LOCAL_PANE = "local-pane",
+    CUSTOM = "custom",
+    /**
+     * Slice K — failure originated from the participation-prefetch tier
+     * (the shell-data-hydrator producer hooks). Carries a discriminant
+     * `prefetchKey: string` so the shell can auto-prune on the next
+     * successful prefetch with the same key. See the
+     * `loading-aggregation.participation-prefetch.shell-data-hydrator`
+     * sub-anchor for the producer-side contract.
+     */
+    PARTICIPATION_PREFETCH = "participation-prefetch"
+}
+/**
+ * Common shape for every captured failure entry, regardless of scope.
+ *
+ * Intentionally not exported on its own — consumers use the
+ * `ExecutionFailedAction` discriminated union below so the type system
+ * enforces "LOCAL_PANE entries carry a `paneId`" without requiring
+ * defensive `!== undefined` checks at every read site.
+ */
+interface ExecutionFailedActionBase {
+    /**
+     * Stable id for the failed action entry. Generated by the shell at capture
+     * time, distinct from the originating `actionRuntimeId` so re-attempts
+     * produce fresh entries.
+     */
+    failureRuntimeId: string;
+    /**
+     * Mirrors `ExecutionPendingAction.actionRuntimeId` for `execute()`-captured
+     * failures. Absent for consumer-authored captures via
+     * `execution.errors.capture(...)` that did not originate from the shell's
+     * `execute()` bridge.
+     *
+     * **Informational only — no first-class selector today.** The shell
+     * does not expose a `errors.findByOriginatingAction(actionRuntimeId)`
+     * helper because no in-tree consumer needs it yet (the dogfood derives
+     * `latestFailure` purely from `capturedAt`). Consumers that want to
+     * correlate a failure entry to a specific pending action can do so via
+     * `errors.isErrored((entry) => entry.originatingActionRuntimeId === id)`
+     * or by filtering `errors.failedActions` directly. A dedicated selector
+     * will be added the first time per-button retry UX dogfoods this field.
+     */
+    originatingActionRuntimeId?: string;
+    /** Canonical operation path key, when available. */
+    operationPathKey?: string;
+    /** Resource the failed action targeted, when available. */
+    resourceType?: string;
+    /** Operation identifier the failed action invoked, when available. */
+    operationId?: string;
+    /** `Date.now()` when capture happened. */
+    capturedAt: number;
+    /**
+     * Mirrors the originating pending action's `startedAt` so consumers can
+     * render duration-aware UX. Absent for consumer-authored captures.
+     */
+    startedAt?: number;
+    /**
+     * Raw error reference. Consumers may inspect `error.wildoError` (set by
+     * `wildo-http-client`) for typed metadata, but the shell does not normalize
+     * the shape — keeping the original preserves whatever upstream provenance
+     * the rejected value carried (stack traces for `Error` instances, typed
+     * payloads for HTTP-marked errors, primitive values when the call site
+     * threw something exotic).
+     */
+    error: unknown;
+    /**
+     * Optional human-readable label ("Could not load todo graph"). Consumers
+     * may render it inline; the shell treats it as opaque metadata.
+     */
+    label?: string;
+    /**
+     * `true` when the originating error carries the `wildoError` marker
+     * stamped by `wildo-http-client.handleHttpError`. That marker means an
+     * upstream layer already classified the error and applied its configured
+     * behavior (potentially emitting `ERROR_OCCURED`, potentially staying
+     * silent if the request opted in or the per-status policy disabled
+     * emission). The shell defers to that processing instead of re-bridging.
+     */
+    markedByHttpClient: boolean;
+    /**
+     * `true` when this capture site invoked `errorManagement.handleError(...)`
+     * itself. The shell sets this:
+     * - `true` for `execute()` rejections without `markedByHttpClient`.
+     * - `false` for `execute()` rejections WITH `markedByHttpClient` (deferred
+     *   to upstream).
+     * - `true`/`false` per `bridgeToCanonicalBus` opt-out for
+     *   `execution.errors.capture(...)` calls.
+     *
+     * Note: `bridgedByExecutionShell === true` does not strictly guarantee
+     * an `ERROR_OCCURED` event was emitted — `errorManagement.handleError`
+     * may itself drop emission for silent contexts. Consumers needing the
+     * ground truth of "was a canonical event emitted" should subscribe to
+     * `FrontendEvents.ERROR_OCCURED` directly rather than infer it from this
+     * flag.
+     */
+    bridgedByExecutionShell: boolean;
+}
+/**
+ * Discriminated union of captured failure entries.
+ *
+ * The discriminant `scope` makes "`paneId` is required for `LOCAL_PANE`
+ * entries, absent on the others" a compile-time invariant. Combined with
+ * the runtime assertion `assertExecutionFailedActionShape`, dynamic
+ * callers (test mocks, deserialized state, authored dictionaries) cannot
+ * collapse the variants either.
+ */
+export type ExecutionFailedAction = (ExecutionFailedActionBase & {
+    scope: ExecutionFailedActionScope.EMBEDDED_CONTENT;
+}) | (ExecutionFailedActionBase & {
+    scope: ExecutionFailedActionScope.LOCAL_PANE;
+    paneId: string;
+}) | (ExecutionFailedActionBase & {
+    scope: ExecutionFailedActionScope.CUSTOM;
+}) | (ExecutionFailedActionBase & {
+    scope: ExecutionFailedActionScope.PARTICIPATION_PREFETCH;
+    /**
+     * Stable consumer-authored identity for the prefetch unit. Distinct
+     * from the per-run `prefetchRuntimeId` (which rotates on every fire);
+     * the same `prefetchKey` is reused across consecutive settle cycles
+     * of the same logical prefetch so the shell's
+     * `clearFailedActionsForPrefetchKey(key)` verb can drop matching
+     * entries on the next successful settle.
+     */
+    prefetchKey: string;
+});
+/**
+ * Belt-and-braces runtime check that an `ExecutionFailedAction` matches
+ * its discriminant invariants. The type layer already enforces these for
+ * statically-shaped callers; this assertion exists for dynamic callers
+ * (test mocks, deserialized payloads, authored dictionaries) where the
+ * type may have been widened via `as`/`unknown`.
+ *
+ * Throws synchronously when a `LOCAL_PANE` entry is captured without a
+ * `paneId` — the only invariant that cannot be expressed any other way.
+ */
+export declare function assertExecutionFailedActionShape(failedAction: ExecutionFailedAction): void;
+/** @wildo_source:part:end saas.frontend.execution-view.failure-handling-contract */
 /**
  * Minimal execution navigation contract for the first routed host slice.
  *
  * The execution runtime deliberately reuses the existing navigation controller
  * instead of introducing a second navigation stack owner.
  */
+/**
+ * Navigation primitives exposed to the execution shell and the unified
+ * `useExecution()` API. These are the two handling modes plus the local-pane
+ * seam — intentionally small so the shell owns a single decision point per
+ * action verb.
+ */
 export interface ExecutionNavigationValue {
+    /** Yield the target navigation content to the app router ("parent" stack). */
     delegateToParent: (options: {
         content: NavigationContent;
         urlPath?: string;
@@ -49,8 +1090,75 @@ export interface ExecutionNavigationValue {
         relationshipTransition?: NavigateOptions['relationshipTransition'];
         initiator?: Omit<NavigationInitiatorContext, 'sourceZone'>;
     }) => void;
+    /** Mount the embeddable content inside the execution shell's single slot. */
+    openEmbeddedContent: (embeddedContent: ExecutionEmbeddedContentState) => void;
+    /** Clear the execution shell's embedded-content slot. */
+    closeEmbeddedContent: () => void;
     openLocalPane: (paneId: string, payload?: unknown) => void;
     closeLocalPane: () => void;
+    /**
+     * Register a shell-tracked pending action. Internal plumbing — app code
+     * must not call this directly; `useExecution()`'s `execute()` verb wires
+     * it from the `doOperation()` bridge. See the loading-aggregation anchor.
+     */
+    beginPendingAction: (action: ExecutionPendingAction) => void;
+    /** Clear a shell-tracked pending action by `actionRuntimeId`. */
+    endPendingAction: (actionRuntimeId: string) => void;
+    /**
+     * Register a shell-tracked participation prefetch. Internal plumbing
+     * intended for future framework-owned async participation resolvers;
+     * no in-tree producer calls it today because participation resolution
+     * is fully synchronous. See the
+     * `loading-aggregation.participation-prefetch` sub-anchor for the
+     * contract (intent classification, settle-always-clears, non-empty
+     * `participationRefs`, …) — the runtime guard
+     * `assertExecutionPendingPrefetchShape` runs at this seam so dynamic
+     * callers cannot bypass shape invariants.
+     */
+    beginParticipationPrefetch: (prefetch: ExecutionPendingPrefetch) => void;
+    /**
+     * Clear a shell-tracked participation prefetch by `prefetchRuntimeId`.
+     * No-op when the id is unknown (mirrors `endPendingAction`).
+     */
+    endParticipationPrefetch: (prefetchRuntimeId: string) => void;
+    /**
+     * Register or update a dirty-state marker. Re-marking the same `markerId`
+     * is idempotent (replaces the entry). See the dirty-state-contract anchor.
+     */
+    markDirty: (marker: ExecutionDirtyMarker) => void;
+    /** Clear a dirty-state marker by `markerId`. No-op if the id is unknown. */
+    clearDirty: (markerId: string) => void;
+    /**
+     * Drop every registered dirty marker. Mirrors `clearAllFailedActions` so
+     * the shell's two consumer-authored aggregator tiers (dirty / errors)
+     * expose the same bulk-clear primitive. Typical use: a top-level "Discard
+     * all unsaved edits" affordance in the consumer view.
+     */
+    clearAllDirty: () => void;
+    /**
+     * Capture a failed action entry (shell-internal plumbing for `execute()`'s
+     * catch path, or consumer-driven via `execution.errors.capture`). See the
+     * failure-handling-contract anchor.
+     */
+    captureFailedAction: (failedAction: ExecutionFailedAction) => void;
+    /** Clear a captured failure by `failureRuntimeId`. No-op if unknown. */
+    clearFailedAction: (failureRuntimeId: string) => void;
+    /** Clear every captured failure. */
+    clearAllFailedActions: () => void;
+    /**
+     * Drop every `PARTICIPATION_PREFETCH`-scoped failure whose `prefetchKey`
+     * matches `prefetchKey`. Internal plumbing called by the Slice K
+     * producer hooks (`useExecutionParticipationPrefetch` /
+     * `useExecutionParticipationDataPrefetch`) on a successful settle so a
+     * stale failure indicator from a previous attempt clears the moment the
+     * next attempt succeeds — no consumer cleanup required. Other scopes
+     * are untouched. See the
+     * `loading-aggregation.participation-prefetch.shell-data-hydrator`
+     * sub-anchor for the full producer contract and
+     * `pruneFailedActionsForPrefetchSettlement` in
+     * `execution-failure-handling.utils.ts` for the prune semantics.
+     */
+    clearFailedActionsForPrefetchKey: (prefetchKey: string) => void;
 }
 /**
  * Minimal runtime context carried by the framework-owned execution host.
@@ -72,6 +1180,7 @@ export interface ExecutionRuntimeContextValue {
     doOperation: ResourceRegistryContextType['doOperation'];
     navigation: ExecutionNavigationValue;
     anchor: ExecutionAnchor | null;
+    participations: Record<string, ResolvedExecutionParticipation>;
     runtimeState: ExecutionRuntimeState;
 }
 export interface ExecutionRuntimeProviderProps {
@@ -83,8 +1192,19 @@ export interface ExecutionRuntimeProviderProps {
     doOperation: ResourceRegistryContextType['doOperation'];
     navigation: ExecutionNavigationValue;
     anchor: ExecutionAnchor | null;
+    participations: Record<string, ResolvedExecutionParticipation>;
     runtimeState: ExecutionRuntimeState;
 }
 export declare const ExecutionRuntimeContext: React.Context<ExecutionRuntimeContextValue>;
+/**
+ * Asserts that a resolved `ExecutionRuntimeContext` value is present.
+ *
+ * Intentionally written as a non-hook assertion so consumers can inline
+ * `useContext(ExecutionRuntimeContext)` at the call site without paying for a
+ * dedicated custom hook wrapper. This keeps the public hook surface minimal
+ * while preserving the "must be used inside a provider" safety check.
+ */
+export declare function assertExecutionRuntimeContext(context: ExecutionRuntimeContextValue | undefined): ExecutionRuntimeContextValue;
 export declare const ExecutionRuntimeProvider: React.FC<ExecutionRuntimeProviderProps>;
+export {};
 //# sourceMappingURL=ExecutionRuntimeContext.d.ts.map