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

package/dist/esm/core/execution/ExecutionRuntimeContext.js

@@ -1,12 +1,743 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useMemo } from 'react';
+import { NavigationContentType, } from '../../core/navigation/navigation.schemas.js';
 export var ExecutionAnchorSource;
 (function (ExecutionAnchorSource) {
     ExecutionAnchorSource["PARENT_RESOURCE_REQUIREMENT"] = "parent-resource-requirement";
     ExecutionAnchorSource["ADDITIONAL_RESOURCE_REQUIREMENT"] = "additional-resource-requirement";
 })(ExecutionAnchorSource || (ExecutionAnchorSource = {}));
+/** @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 var ExecutionParticipationPrefetchIntent;
+(function (ExecutionParticipationPrefetchIntent) {
+    ExecutionParticipationPrefetchIntent["INITIAL"] = "initial";
+    ExecutionParticipationPrefetchIntent["REFRESH"] = "refresh";
+})(ExecutionParticipationPrefetchIntent || (ExecutionParticipationPrefetchIntent = {}));
+/**
+ * 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 function assertExecutionPendingPrefetchShape(prefetch) {
+    if (!Array.isArray(prefetch.participationRefs) || prefetch.participationRefs.length === 0) {
+        throw new Error('[ExecutionView] ExecutionPendingPrefetch must carry at least one participation ref. '
+            + 'A prefetch with no refs cannot be narrowed to per-ref UX. '
+            + 'If the work is not tied to any participation, do not register it as a participation prefetch.');
+    }
+    if (typeof prefetch.resourceType !== 'string' || prefetch.resourceType.length === 0) {
+        throw new Error('[ExecutionView] ExecutionPendingPrefetch must carry a non-empty `resourceType` '
+            + 'so per-resource UI filtering composes uniformly with the pending-action tier.');
+    }
+    if (prefetch.intent !== ExecutionParticipationPrefetchIntent.INITIAL
+        && prefetch.intent !== ExecutionParticipationPrefetchIntent.REFRESH) {
+        throw new Error('[ExecutionView] ExecutionPendingPrefetch.intent must be one of '
+            + '`INITIAL` | `REFRESH` so renderers can distinguish full-screen '
+            + 'vs background hydration UX without a side-channel flag.');
+    }
+}
+/** @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 var ExecutionDirtyMarkerScope;
+(function (ExecutionDirtyMarkerScope) {
+    ExecutionDirtyMarkerScope["EMBEDDED_CONTENT"] = "embedded-content";
+    ExecutionDirtyMarkerScope["LOCAL_PANE"] = "local-pane";
+    ExecutionDirtyMarkerScope["CUSTOM"] = "custom";
+})(ExecutionDirtyMarkerScope || (ExecutionDirtyMarkerScope = {}));
+/**
+ * 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 function assertExecutionDirtyMarkerShape(marker) {
+    if (marker.scope === ExecutionDirtyMarkerScope.LOCAL_PANE) {
+        const candidate = marker;
+        if (typeof candidate.paneId !== 'string' || candidate.paneId.length === 0) {
+            throw new Error('[ExecutionView] LOCAL_PANE-scoped dirty marker must carry a non-empty `paneId` '
+                + 'so the shell can auto-clear it on pane transitions. '
+                + 'Use scope=CUSTOM for markers that should outlive any single pane.');
+        }
+    }
+}
+/**
+ * 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 function assertExecutionLocalPanePayloadIsNotEmbeddableContent(payload) {
+    if (payload === null || typeof payload !== 'object') {
+        return;
+    }
+    const candidate = payload;
+    if (candidate.contentType === NavigationContentType.RESOURCE_OPERATION) {
+        throw new Error('[ExecutionView] localPane payload must not be an ExecutionEmbeddableContent. '
+            + 'Resource-operation content belongs in the embedded-content slot. '
+            + 'Use openEmbeddedContent() or execution.actions.operation(...).embed() instead.');
+    }
+}
+/**
+ * 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 function assertExecutionEmbeddableContent(content) {
+    if (!content || content.contentType !== NavigationContentType.RESOURCE_OPERATION) {
+        throw new Error('[ExecutionView] embeddedContent.content must be a '
+            + 'NavigationContent.RESOURCE_OPERATION. Non-resource-operation '
+            + 'navigation content must go through delegateToParent() (the app router), '
+            + 'not the execution shell\'s embed slot.');
+    }
+}
+/** @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 var ExecutionFailedActionScope;
+(function (ExecutionFailedActionScope) {
+    ExecutionFailedActionScope["EMBEDDED_CONTENT"] = "embedded-content";
+    ExecutionFailedActionScope["LOCAL_PANE"] = "local-pane";
+    ExecutionFailedActionScope["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.
+     */
+    ExecutionFailedActionScope["PARTICIPATION_PREFETCH"] = "participation-prefetch";
+})(ExecutionFailedActionScope || (ExecutionFailedActionScope = {}));
+/**
+ * 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 function assertExecutionFailedActionShape(failedAction) {
+    if (failedAction.scope === ExecutionFailedActionScope.LOCAL_PANE) {
+        const candidate = failedAction;
+        if (typeof candidate.paneId !== 'string' || candidate.paneId.length === 0) {
+            throw new Error('[ExecutionView] LOCAL_PANE-scoped failed action must carry a non-empty `paneId` '
+                + 'so the shell can auto-clear it on pane transitions. '
+                + 'Use scope=CUSTOM for failures that should outlive any single pane.');
+        }
+    }
+    if (failedAction.scope === ExecutionFailedActionScope.PARTICIPATION_PREFETCH) {
+        const candidate = failedAction;
+        if (typeof candidate.prefetchKey !== 'string' || candidate.prefetchKey.length === 0) {
+            throw new Error('[ExecutionView] PARTICIPATION_PREFETCH-scoped failed action must carry a '
+                + 'non-empty `prefetchKey` so the shell can auto-clear it on the next '
+                + 'successful prefetch settle for the same key. '
+                + 'Use scope=CUSTOM for failures that should outlive any single prefetch unit.');
+        }
+    }
+}
 export const ExecutionRuntimeContext = createContext(undefined);
-export const ExecutionRuntimeProvider = ({ children, viewDefinition, contextResourceIdentifiers, runtimeInstanceId, navigationZone, doOperation, navigation, anchor, runtimeState, }) => {
+/**
+ * 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 function assertExecutionRuntimeContext(context) {
+    if (!context) {
+        throw new Error('Execution runtime context must be used within an ExecutionRuntimeProvider.');
+    }
+    return context;
+}
+export const ExecutionRuntimeProvider = ({ children, viewDefinition, contextResourceIdentifiers, runtimeInstanceId, navigationZone, doOperation, navigation, anchor, participations, runtimeState, }) => {
     const value = useMemo(() => ({
         viewDefinition,
         contextResourceIdentifiers,
@@ -15,8 +746,9 @@ export const ExecutionRuntimeProvider = ({ children, viewDefinition, contextReso
         doOperation,
         navigation,
         anchor,
+        participations,
         runtimeState,
-    }), [viewDefinition, contextResourceIdentifiers, runtimeInstanceId, navigationZone, doOperation, navigation, anchor, runtimeState]);
+    }), [viewDefinition, contextResourceIdentifiers, runtimeInstanceId, navigationZone, doOperation, navigation, anchor, participations, runtimeState]);
     return (_jsx(ExecutionRuntimeContext.Provider, { value: value, children: children }));
 };
-//# sourceMappingURL=ExecutionRuntimeContext.js.map
+//# sourceMappingURL=ExecutionRuntimeContext.js.map