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

package/dist/esm/core/execution/execution-failure-handling.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-failure-handling.utils.js","sourceRoot":"","sources":["../../../../../src/core/execution/execution-failure-handling.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  assertExecutionFailedActionShape,\n  ExecutionFailedActionScope,\n  type ExecutionFailedAction,\n  type ExecutionRuntimeState,\n} from './ExecutionRuntimeContext';\n\n/**\n * Drop every captured failure whose `scope` matches `scope`. Used on\n * embedded-content transitions (open replace or close) to honor the\n * failure-handling contract's auto-cleanup invariant — the publisher for\n * those failures is, by definition, gone once the slot changes.\n *\n * Mirrors `pruneDirtyMarkersForScopeChange` exactly so consumers reason about\n * dirty markers and failed actions with the same scope vocabulary.\n *\n * Returns the same reference when no entry matches, so React state setters\n * can short-circuit and avoid redundant re-renders.\n *\n * See the `saas.frontend.execution-view.failure-handling-contract` anchor in\n * `ExecutionRuntimeContext.tsx` for the full contract.\n */\nexport function pruneFailedActionsForScopeChange(\n  previous: ExecutionRuntimeState['failedActions'],\n  scope: ExecutionFailedActionScope,\n): ExecutionRuntimeState['failedActions'] {\n  let mutated = false;\n  const next: ExecutionRuntimeState['failedActions'] = {};\n  for (const [failureRuntimeId, failedAction] of Object.entries(previous)) {\n    if (failedAction.scope === scope) {\n      mutated = true;\n      continue;\n    }\n    next[failureRuntimeId] = failedAction;\n  }\n  return mutated ? next : previous;\n}\n\n/**\n * Drop `LOCAL_PANE`-scoped failures whose `paneId` does not match the\n * currently-active `nextPaneId` (`null` when the pane closes). `CUSTOM`- and\n * `EMBEDDED_CONTENT`-scoped failures are untouched; only the pane tier is\n * auto-cleaned here.\n *\n * Mirrors `pruneDirtyMarkersForPaneTransition` exactly. The discriminated\n * union on `ExecutionFailedAction` guarantees that any `LOCAL_PANE` entry\n * carries a `paneId`, so the comparison is meaningful — there is no\n * \"missing paneId silently falls through\" failure mode.\n *\n * Returns the same reference when no entry matches, so React state setters\n * can short-circuit and avoid redundant re-renders.\n */\nexport function pruneFailedActionsForPaneTransition(\n  previous: ExecutionRuntimeState['failedActions'],\n  nextPaneId: string | null,\n): ExecutionRuntimeState['failedActions'] {\n  let mutated = false;\n  const next: ExecutionRuntimeState['failedActions'] = {};\n  for (const [failureRuntimeId, failedAction] of Object.entries(previous)) {\n    if (\n      failedAction.scope === ExecutionFailedActionScope.LOCAL_PANE\n      && failedAction.paneId !== nextPaneId\n    ) {\n      mutated = true;\n      continue;\n    }\n    next[failureRuntimeId] = failedAction;\n  }\n  return mutated ? next : previous;\n}\n\n/**\n * Detects whether the rejected error carries the `wildoError` marker that\n * `wildo-http-client.handleHttpError(...)` attaches to every HTTP-layer\n * failure. The marker means an upstream layer **already classified and\n * processed** this error (built a `WildoError_Frontend`, applied the\n * configured per-status behavior, conditionally emitted `ERROR_OCCURED`\n * based on the request's `silent` flag and the per-status `emitEvent`\n * policy).\n *\n * The execution shell uses this to decide whether to re-bridge the error\n * via `errorManagement.handleError(...)`: when the marker is present, the\n * shell defers to that upstream processing instead of re-emitting. That\n * decision honors a consumer-requested silence even when no event was\n * actually emitted — the shell does not paper over intentional silence by\n * re-emitting on its own.\n *\n * The duck-type check requires `wildoError` to be a non-null object so a\n * plain `{ wildoError: 'string' }` value cannot accidentally trigger the\n * deferral path.\n */\nexport function isErrorMarkedByHttpClient(error: unknown): boolean {\n  if (!error || typeof error !== 'object') {\n    return false;\n  }\n  const candidate = error as { wildoError?: unknown };\n  return typeof candidate.wildoError === 'object' && candidate.wildoError !== null;\n}\n\n/**\n * Convenience helper for tests and `execution.errors.capture(...)` callers\n * that want to stamp a failed-action entry without authoring `capturedAt`\n * inline. Defaults `scope` to `CUSTOM`, `markedByHttpClient` to the result\n * of `isErrorMarkedByHttpClient(error)`, and `bridgedByExecutionShell` to\n * `false` so consumer captures are explicit about whether they pre-bridged.\n *\n * Discriminated input enforces \"`paneId` is required for `LOCAL_PANE`\n * entries\" at compile time and runtime (`assertExecutionFailedActionShape`).\n */\nexport type BuildExecutionFailedActionInput = {\n  failureRuntimeId: string;\n  error: unknown;\n  originatingActionRuntimeId?: string;\n  operationPathKey?: string;\n  resourceType?: string;\n  operationId?: string;\n  capturedAt?: number;\n  startedAt?: number;\n  label?: string;\n  markedByHttpClient?: boolean;\n  bridgedByExecutionShell?: boolean;\n} & (\n  | { scope?: ExecutionFailedActionScope.CUSTOM }\n  | { scope: ExecutionFailedActionScope.EMBEDDED_CONTENT }\n  | { scope: ExecutionFailedActionScope.LOCAL_PANE; paneId: string }\n  | { scope: ExecutionFailedActionScope.PARTICIPATION_PREFETCH; prefetchKey: string }\n);\n\nexport function buildExecutionFailedAction(\n  input: BuildExecutionFailedActionInput,\n): ExecutionFailedAction {\n  const markedByHttpClient = input.markedByHttpClient ?? isErrorMarkedByHttpClient(input.error);\n  const bridgedByExecutionShell = input.bridgedByExecutionShell ?? false;\n  const baseFields = {\n    failureRuntimeId: input.failureRuntimeId,\n    error: input.error,\n    originatingActionRuntimeId: input.originatingActionRuntimeId,\n    operationPathKey: input.operationPathKey,\n    resourceType: input.resourceType,\n    operationId: input.operationId,\n    capturedAt: input.capturedAt ?? Date.now(),\n    startedAt: input.startedAt,\n    label: input.label,\n    markedByHttpClient,\n    bridgedByExecutionShell,\n  };\n  // Narrow on the discriminant `input.scope` itself rather than a hoisted\n  // copy, so TypeScript flows the union narrowing into each branch and\n  // `input.paneId` / `input.prefetchKey` resolve without a cast. Mirrors\n  // `buildExecutionDirtyMarker` exactly — same job, same idiom, no escape\n  // hatch into `as`.\n  let built: ExecutionFailedAction;\n  if (input.scope === ExecutionFailedActionScope.LOCAL_PANE) {\n    built = { ...baseFields, scope: input.scope, paneId: input.paneId };\n  } else if (input.scope === ExecutionFailedActionScope.EMBEDDED_CONTENT) {\n    built = { ...baseFields, scope: input.scope };\n  } else if (input.scope === ExecutionFailedActionScope.PARTICIPATION_PREFETCH) {\n    built = { ...baseFields, scope: input.scope, prefetchKey: input.prefetchKey };\n  } else {\n    built = { ...baseFields, scope: ExecutionFailedActionScope.CUSTOM };\n  }\n  assertExecutionFailedActionShape(built);\n  return built;\n}\n\n/**\n * Drop `PARTICIPATION_PREFETCH`-scoped failures whose `prefetchKey` matches\n * the just-settled prefetch unit. Other scopes are untouched.\n *\n * Called by the Slice K hooks (`useExecutionParticipationPrefetch` /\n * `useExecutionParticipationDataPrefetch`) on a successful settle, so a\n * stale failure indicator from a previous attempt clears the moment the\n * next attempt succeeds — no consumer plumbing required.\n *\n * Returns the same reference when no entry matches, so React state setters\n * can short-circuit and avoid redundant re-renders.\n *\n * See the `loading-aggregation.participation-prefetch.shell-data-hydrator`\n * sub-anchor for the producer-side contract this helper serves, and the\n * `saas.frontend.execution-view.failure-handling-contract` anchor for the\n * scope-vocabulary it slots into.\n */\nexport function pruneFailedActionsForPrefetchSettlement(\n  previous: ExecutionRuntimeState['failedActions'],\n  prefetchKey: string,\n): ExecutionRuntimeState['failedActions'] {\n  let mutated = false;\n  const next: ExecutionRuntimeState['failedActions'] = {};\n  for (const [failureRuntimeId, failedAction] of Object.entries(previous)) {\n    if (\n      failedAction.scope === ExecutionFailedActionScope.PARTICIPATION_PREFETCH\n      && failedAction.prefetchKey === prefetchKey\n    ) {\n      mutated = true;\n      continue;\n    }\n    next[failureRuntimeId] = failedAction;\n  }\n  return mutated ? next : previous;\n}\n"]}

package/dist/esm/core/execution/execution-outcome-emission.utils.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Helpers for the execution shell's canonical operation-outcome emission.
+ *
+ * See `saas.frontend.execution-view.outcome-emission-contract` in
+ * `ExecutionRuntimeContext.tsx` for the shell invariants. This file is pure —
+ * the shell wiring lives in `useExecution().execute()`, which calls into
+ * `emitResourceOperationOutcome` after `doOperation` resolves successfully.
+ *
+ * The payloads here deliberately mirror the shape emitted by
+ * `useResourceOperationActions.handleExecuteOperation` so every downstream
+ * subscriber (`NotificationContext`, `WebSocketEventBridge`, list-refresh
+ * listeners, analytics hooks) treats execution-shell-driven operations
+ * identically to resource-layout-driven ones. Any drift between the two
+ * emission sites is a bug.
+ */
+import { FrontendEvents, type FrontendEventPayloads } from '../../core/events/events.frontend.schemas';
+import type { AnyFrontendResourceConfiguration, FrontendResourceConfiguration_Operation, FrontendResourceOperationContext, FrontendResourcesRegistry } from '../../core/resources/resources.frontend.schemas';
+/**
+ * Minimal duck-typed shape of a resource configuration as seen by the
+ * outcome-emission helper. We only need the `operations` list to discover
+ * LIST sibling operations for refresh targeting; widening to the full
+ * `FrontendResourceConfiguration` generic parameters just to satisfy the
+ * Zod variance dance would make callers chase generics for zero payoff.
+ */
+export interface ResourceConfigurationOperationsSource {
+    operations?: readonly FrontendResourceConfiguration_Operation[];
+}
+type EmitFn = <K extends FrontendEvents>(event: K, payload: FrontendEventPayloads[K]) => void;
+export interface EmitResourceOperationOutcomeParams {
+    emit: EmitFn;
+    /**
+     * The resolved resource configuration (duck-typed — we only read
+     * `.operations`). Used to discover LIST sibling operations for refresh
+     * targeting. When undefined (registry miss), refresh falls back to a
+     * synthetic default LIST operation — this mirrors the canonical pattern
+     * and keeps the signal alive even when the resource config is partial.
+     */
+    resourceConfig?: AnyFrontendResourceConfiguration | ResourceConfigurationOperationsSource;
+    registry?: FrontendResourcesRegistry;
+    resourceType: string;
+    operation: FrontendResourceConfiguration_Operation;
+    resourceContext: FrontendResourceOperationContext;
+    /**
+     * Whether the resource WebSocket bridge is currently connected. Connected
+     * sessions let the bridge own refresh delivery for direct mutations,
+     * including generated PDF regeneration.
+     */
+    isWebSocketConnected: boolean;
+    result?: unknown;
+}
+/**
+ * Emit the canonical frontend events after a successful `.execute()`.
+ *
+ * Emission order + rules:
+ *
+ * 1. **`RESOURCE_REFRESH`** — emitted for direct mutations when the WebSocket
+ *    bridge is disconnected. Connected sessions let the WebSocket bridge own
+ *    refresh fan-out, which avoids duplicate refetches for generated PDF
+ *    regeneration when the backend emits the normal resource update event.
+ *
+ * 2. **`RESOURCE_OPERATION_EXECUTED`** — emitted unconditionally on success.
+ *    This is the canonical "an operation just completed" signal consumed by
+ *    analytics, refetch, and side-effect subscribers. `NotificationContext`
+ *    does *not* subscribe to this event (it is categorised under
+ *    `NEED_REFRESH`, not `NOTIFY_USER`), so emitting for reads / lists never
+ *    produces unintended toasts. User-visible toasts travel on the separate
+ *    `NOTIFY_RESOURCE_*` channel fed by backend notifications.
+ *
+ * Failure path: this helper is *not* called on rejection. The execution
+ * shell lets the promise surface errors to the caller; consumers can
+ * `.catch()` or subscribe to `NOTIFY_RESOURCE_ERROR`. Emitting a failure
+ * variant here would force a specific error-UX on every consumer — the
+ * shell stays informative only, matching the dirty-state contract's
+ * "informative, not restrictive" stance.
+ *
+ * Ordering vs `ExecutionPendingAction`: callers are required to fire this
+ * helper *inside* the `try` block, *before* the `finally` clears the
+ * pending entry. Subscribers observing `execution.loading.isBusy` at
+ * emission time therefore still see `true` — this matches
+ * `useResourceOperationActions.runPostOperationEffects`, which also runs
+ * before its own `isExecuting = false` cleanup.
+ */
+export declare function emitResourceOperationOutcome(params: EmitResourceOperationOutcomeParams): void;
+export {};
+//# sourceMappingURL=execution-outcome-emission.utils.d.ts.map

package/dist/esm/core/execution/execution-outcome-emission.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-outcome-emission.utils.d.ts","sourceRoot":"","sources":["../../../../../src/core/execution/execution-outcome-emission.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC3B,MAAM,yDAAyD,CAAC;AAcjE,OAAO,KAAK,EACV,gCAAgC,EAChC,uCAAuC,EACvC,gCAAgC,EAChC,yBAAyB,EAC1B,MAAM,+DAA+D,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,qCAAqC;IACpD,UAAU,CAAC,EAAE,SAAS,uCAAuC,EAAE,CAAC;CACjE;AAED,KAAK,MAAM,GAAG,CAAC,CAAC,SAAS,cAAc,EACrC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAC9B,IAAI,CAAC;AAEV,MAAM,WAAW,kCAAkC;IACjD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,gCAAgC,GAAG,qCAAqC,CAAC;IAC1F,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,uCAAuC,CAAC;IACnD,eAAe,EAAE,gCAAgC,CAAC;IAClD;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,kCAAkC,GACzC,IAAI,CAwIN"}

package/dist/esm/core/execution/execution-outcome-emission.utils.js

@@ -0,0 +1,161 @@
+/**
+ * Helpers for the execution shell's canonical operation-outcome emission.
+ *
+ * See `saas.frontend.execution-view.outcome-emission-contract` in
+ * `ExecutionRuntimeContext.tsx` for the shell invariants. This file is pure —
+ * the shell wiring lives in `useExecution().execute()`, which calls into
+ * `emitResourceOperationOutcome` after `doOperation` resolves successfully.
+ *
+ * The payloads here deliberately mirror the shape emitted by
+ * `useResourceOperationActions.handleExecuteOperation` so every downstream
+ * subscriber (`NotificationContext`, `WebSocketEventBridge`, list-refresh
+ * listeners, analytics hooks) treats execution-shell-driven operations
+ * identically to resource-layout-driven ones. Any drift between the two
+ * emission sites is a bug.
+ */
+import { CoreResourceOperation } from '@wildo-ai/saas-models';
+import { FrontendEvents, } from '../../core/events/events.frontend.schemas.js';
+import { getOperationsForCoreSemantic, isGeneratedFileRegenerateOperation, readResourceOperationExecutedDiscriminator, shouldEmitResourceRefreshAfterDirectOperation, } from '../../core/resources/operation-semantics.frontend.utils.js';
+import { operationInitiatorParametersSatisfied } from '../../core/resources/operation-initiator-satisfaction.frontend.utils.js';
+import { FrontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
+import { normalizeContextResourceIdentifiersForOutcome, normalizeContextResourceIdentifiersForTransport, } from '../../core/resources/context-resource-identifiers.frontend.utils.js';
+import { isFrontendOperationAddressableForCurrentContext } from '../../core/resources/resource-addressability.frontend.utils.js';
+/**
+ * Emit the canonical frontend events after a successful `.execute()`.
+ *
+ * Emission order + rules:
+ *
+ * 1. **`RESOURCE_REFRESH`** — emitted for direct mutations when the WebSocket
+ *    bridge is disconnected. Connected sessions let the WebSocket bridge own
+ *    refresh fan-out, which avoids duplicate refetches for generated PDF
+ *    regeneration when the backend emits the normal resource update event.
+ *
+ * 2. **`RESOURCE_OPERATION_EXECUTED`** — emitted unconditionally on success.
+ *    This is the canonical "an operation just completed" signal consumed by
+ *    analytics, refetch, and side-effect subscribers. `NotificationContext`
+ *    does *not* subscribe to this event (it is categorised under
+ *    `NEED_REFRESH`, not `NOTIFY_USER`), so emitting for reads / lists never
+ *    produces unintended toasts. User-visible toasts travel on the separate
+ *    `NOTIFY_RESOURCE_*` channel fed by backend notifications.
+ *
+ * Failure path: this helper is *not* called on rejection. The execution
+ * shell lets the promise surface errors to the caller; consumers can
+ * `.catch()` or subscribe to `NOTIFY_RESOURCE_ERROR`. Emitting a failure
+ * variant here would force a specific error-UX on every consumer — the
+ * shell stays informative only, matching the dirty-state contract's
+ * "informative, not restrictive" stance.
+ *
+ * Ordering vs `ExecutionPendingAction`: callers are required to fire this
+ * helper *inside* the `try` block, *before* the `finally` clears the
+ * pending entry. Subscribers observing `execution.loading.isBusy` at
+ * emission time therefore still see `true` — this matches
+ * `useResourceOperationActions.runPostOperationEffects`, which also runs
+ * before its own `isExecuting = false` cleanup.
+ */
+export function emitResourceOperationOutcome(params) {
+    const { emit, resourceConfig, registry, resourceType, operation, resourceContext, isWebSocketConnected, result, } = params;
+    const successDiscriminator = readResourceOperationExecutedDiscriminator(resourceContext.additionalContext);
+    const isGeneratedFileRegenerate = isGeneratedFileRegenerateOperation(operation);
+    const normalizedTransportContext = normalizeContextResourceIdentifiersForTransport(resourceContext.contextResourceIdentifiers);
+    const normalizedOutcomeContext = normalizeContextResourceIdentifiersForOutcome({
+        contextResourceIdentifiers: resourceContext.contextResourceIdentifiers,
+        resourceType,
+        result,
+    });
+    if (!isWebSocketConnected && shouldEmitResourceRefreshAfterDirectOperation(operation)) {
+        const siblingOperations = resourceConfig?.operations
+            ? [...resourceConfig.operations]
+            : [];
+        const contextualParameters = registry
+            ? FrontendResourceUtils.buildContextualParameters(resourceContext.contextResourceIdentifiers, registry)
+            : {};
+        const listOperations = getOperationsForCoreSemantic(siblingOperations, CoreResourceOperation.LIST).filter((listOperation) => operationInitiatorParametersSatisfied({
+            operation: listOperation,
+            contextResourceIdentifiers: resourceContext.contextResourceIdentifiers,
+            contextualParameters,
+        }));
+        const { [resourceType]: _self, ...parentScopeIdentifiers } = normalizedTransportContext;
+        const refreshTargets = listOperations.length > 0
+            ? listOperations
+            : [null];
+        for (const listOperation of refreshTargets) {
+            const listOperationContext = listOperation
+                ?? { operationIdentifier: CoreResourceOperation.LIST };
+            emit(FrontendEvents.RESOURCE_REFRESH, {
+                resourceType,
+                operationIdentifier: String(listOperationContext.operationIdentifier ?? CoreResourceOperation.LIST),
+                operation: listOperationContext,
+                variantType: listOperation?.variantType,
+                isOperationDefault: listOperation?.isOperationDefault ?? true,
+                isBulkOperation: listOperation?.isBulkOperation ?? false,
+                variantKey: listOperation?.variantKey,
+                contextResourceIdentifiers: parentScopeIdentifiers,
+                parentResourcesRequirements: resourceContext.parentResourcesRequirements,
+                ...(successDiscriminator ? { optionalDiscriminator: successDiscriminator } : {}),
+            });
+        }
+        if (isGeneratedFileRegenerate) {
+            const readOperations = getOperationsForCoreSemantic(siblingOperations, CoreResourceOperation.READ, {
+                requireAddressable: true,
+            }).filter((readOperation) => resourceConfig && registry
+                ? isFrontendOperationAddressableForCurrentContext({
+                    resourceConfig: resourceConfig,
+                    operation: readOperation,
+                    registry,
+                    hasResourceId: normalizedOutcomeContext[resourceType] !== undefined,
+                    contextResourceIdentifiers: normalizedOutcomeContext,
+                    contextualParameters: registry
+                        ? FrontendResourceUtils.buildContextualParameters(normalizedOutcomeContext, registry)
+                        : contextualParameters,
+                })
+                : true);
+            const readRefreshTargets = readOperations.length > 0
+                ? readOperations
+                : [null];
+            const emittedReadOperationKeys = new Set();
+            for (const readOperation of readRefreshTargets) {
+                const readOperationContext = readOperation
+                    ?? { operationIdentifier: CoreResourceOperation.READ };
+                const readOperationKey = [
+                    FrontendResourceUtils.getInstance().getResourceId(normalizedOutcomeContext[resourceType]),
+                    String(readOperationContext.operationIdentifier),
+                    readOperationContext.variantType ?? '',
+                    readOperationContext.variantKey ?? '',
+                    readOperationContext.isBulkOperation ?? false,
+                ].join(':');
+                if (emittedReadOperationKeys.has(readOperationKey)) {
+                    continue;
+                }
+                emittedReadOperationKeys.add(readOperationKey);
+                emit(FrontendEvents.RESOURCE_REFRESH, {
+                    resourceType,
+                    operationIdentifier: String(readOperationContext.operationIdentifier ?? CoreResourceOperation.READ),
+                    operation: readOperationContext,
+                    variantType: readOperation?.variantType,
+                    isOperationDefault: readOperation?.isOperationDefault ?? true,
+                    isBulkOperation: readOperation?.isBulkOperation ?? false,
+                    variantKey: readOperation?.variantKey,
+                    contextResourceIdentifiers: normalizedOutcomeContext,
+                    parentResourcesRequirements: resourceContext.parentResourcesRequirements,
+                    ...(successDiscriminator ? { optionalDiscriminator: successDiscriminator } : {}),
+                });
+            }
+        }
+    }
+    emit(FrontendEvents.RESOURCE_OPERATION_EXECUTED, {
+        resourceType,
+        operationIdentifier: String(operation.operationIdentifier),
+        operation,
+        variantType: operation.variantType,
+        isOperationDefault: operation.isOperationDefault ?? true,
+        isBulkOperation: operation.isBulkOperation ?? false,
+        variantKey: operation.variantKey,
+        contextResourceIdentifiers: normalizedOutcomeContext,
+        parentResourcesRequirements: resourceContext.parentResourcesRequirements,
+        resultSummary: typeof result === 'object' && result !== null
+            ? result
+            : undefined,
+        ...(successDiscriminator ? { optionalDiscriminator: successDiscriminator } : {}),
+    });
+}
+//# sourceMappingURL=execution-outcome-emission.utils.js.map

package/dist/esm/core/execution/execution-outcome-emission.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-outcome-emission.utils.js","sourceRoot":"","sources":["../../../../../src/core/execution/execution-outcome-emission.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Helpers for the execution shell's canonical operation-outcome emission.\n *\n * See `saas.frontend.execution-view.outcome-emission-contract` in\n * `ExecutionRuntimeContext.tsx` for the shell invariants. This file is pure —\n * the shell wiring lives in `useExecution().execute()`, which calls into\n * `emitResourceOperationOutcome` after `doOperation` resolves successfully.\n *\n * The payloads here deliberately mirror the shape emitted by\n * `useResourceOperationActions.handleExecuteOperation` so every downstream\n * subscriber (`NotificationContext`, `WebSocketEventBridge`, list-refresh\n * listeners, analytics hooks) treats execution-shell-driven operations\n * identically to resource-layout-driven ones. Any drift between the two\n * emission sites is a bug.\n */\n\nimport { CoreResourceOperation } from '@wildo-ai/saas-models';\nimport {\n  FrontendEvents,\n  type FrontendEventPayloads,\n} from '~wildo-frontend-lib/core/events/events.frontend.schemas';\nimport {\n  getOperationsForCoreSemantic,\n  isGeneratedFileRegenerateOperation,\n  readResourceOperationExecutedDiscriminator,\n  shouldEmitResourceRefreshAfterDirectOperation,\n} from '~wildo-frontend-lib/core/resources/operation-semantics.frontend.utils';\nimport { operationInitiatorParametersSatisfied } from '~wildo-frontend-lib/core/resources/operation-initiator-satisfaction.frontend.utils';\nimport { FrontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\nimport {\n  normalizeContextResourceIdentifiersForOutcome,\n  normalizeContextResourceIdentifiersForTransport,\n} from '~wildo-frontend-lib/core/resources/context-resource-identifiers.frontend.utils';\nimport { isFrontendOperationAddressableForCurrentContext } from '~wildo-frontend-lib/core/resources/resource-addressability.frontend.utils';\nimport type {\n  AnyFrontendResourceConfiguration,\n  FrontendResourceConfiguration_Operation,\n  FrontendResourceOperationContext,\n  FrontendResourcesRegistry,\n} from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\n\n/**\n * Minimal duck-typed shape of a resource configuration as seen by the\n * outcome-emission helper. We only need the `operations` list to discover\n * LIST sibling operations for refresh targeting; widening to the full\n * `FrontendResourceConfiguration` generic parameters just to satisfy the\n * Zod variance dance would make callers chase generics for zero payoff.\n */\nexport interface ResourceConfigurationOperationsSource {\n  operations?: readonly FrontendResourceConfiguration_Operation[];\n}\n\ntype EmitFn = <K extends FrontendEvents>(\n  event: K,\n  payload: FrontendEventPayloads[K],\n) => void;\n\nexport interface EmitResourceOperationOutcomeParams {\n  emit: EmitFn;\n  /**\n   * The resolved resource configuration (duck-typed — we only read\n   * `.operations`). Used to discover LIST sibling operations for refresh\n   * targeting. When undefined (registry miss), refresh falls back to a\n   * synthetic default LIST operation — this mirrors the canonical pattern\n   * and keeps the signal alive even when the resource config is partial.\n   */\n  resourceConfig?: AnyFrontendResourceConfiguration | ResourceConfigurationOperationsSource;\n  registry?: FrontendResourcesRegistry;\n  resourceType: string;\n  operation: FrontendResourceConfiguration_Operation;\n  resourceContext: FrontendResourceOperationContext;\n  /**\n   * Whether the resource WebSocket bridge is currently connected. Connected\n   * sessions let the bridge own refresh delivery for direct mutations,\n   * including generated PDF regeneration.\n   */\n  isWebSocketConnected: boolean;\n  result?: unknown;\n}\n\n/**\n * Emit the canonical frontend events after a successful `.execute()`.\n *\n * Emission order + rules:\n *\n * 1. **`RESOURCE_REFRESH`** — emitted for direct mutations when the WebSocket\n *    bridge is disconnected. Connected sessions let the WebSocket bridge own\n *    refresh fan-out, which avoids duplicate refetches for generated PDF\n *    regeneration when the backend emits the normal resource update event.\n *\n * 2. **`RESOURCE_OPERATION_EXECUTED`** — emitted unconditionally on success.\n *    This is the canonical \"an operation just completed\" signal consumed by\n *    analytics, refetch, and side-effect subscribers. `NotificationContext`\n *    does *not* subscribe to this event (it is categorised under\n *    `NEED_REFRESH`, not `NOTIFY_USER`), so emitting for reads / lists never\n *    produces unintended toasts. User-visible toasts travel on the separate\n *    `NOTIFY_RESOURCE_*` channel fed by backend notifications.\n *\n * Failure path: this helper is *not* called on rejection. The execution\n * shell lets the promise surface errors to the caller; consumers can\n * `.catch()` or subscribe to `NOTIFY_RESOURCE_ERROR`. Emitting a failure\n * variant here would force a specific error-UX on every consumer — the\n * shell stays informative only, matching the dirty-state contract's\n * \"informative, not restrictive\" stance.\n *\n * Ordering vs `ExecutionPendingAction`: callers are required to fire this\n * helper *inside* the `try` block, *before* the `finally` clears the\n * pending entry. Subscribers observing `execution.loading.isBusy` at\n * emission time therefore still see `true` — this matches\n * `useResourceOperationActions.runPostOperationEffects`, which also runs\n * before its own `isExecuting = false` cleanup.\n */\nexport function emitResourceOperationOutcome(\n  params: EmitResourceOperationOutcomeParams,\n): void {\n  const {\n    emit,\n    resourceConfig,\n    registry,\n    resourceType,\n    operation,\n    resourceContext,\n    isWebSocketConnected,\n    result,\n  } = params;\n\n  const successDiscriminator = readResourceOperationExecutedDiscriminator(\n    resourceContext.additionalContext,\n  );\n\n  const isGeneratedFileRegenerate = isGeneratedFileRegenerateOperation(operation);\n  const normalizedTransportContext = normalizeContextResourceIdentifiersForTransport(\n    resourceContext.contextResourceIdentifiers,\n  );\n  const normalizedOutcomeContext = normalizeContextResourceIdentifiersForOutcome({\n    contextResourceIdentifiers: resourceContext.contextResourceIdentifiers,\n    resourceType,\n    result,\n  });\n  if (!isWebSocketConnected && shouldEmitResourceRefreshAfterDirectOperation(operation)) {\n    const siblingOperations = resourceConfig?.operations\n      ? [...resourceConfig.operations]\n      : [];\n    const contextualParameters = registry\n      ? FrontendResourceUtils.buildContextualParameters(resourceContext.contextResourceIdentifiers, registry)\n      : {};\n    const listOperations = getOperationsForCoreSemantic(\n      siblingOperations,\n      CoreResourceOperation.LIST,\n    ).filter((listOperation) =>\n      operationInitiatorParametersSatisfied({\n        operation: listOperation,\n        contextResourceIdentifiers: resourceContext.contextResourceIdentifiers,\n        contextualParameters,\n      })\n    );\n    const { [resourceType]: _self, ...parentScopeIdentifiers } = normalizedTransportContext;\n    const refreshTargets = listOperations.length > 0\n      ? listOperations\n      : [null];\n\n    for (const listOperation of refreshTargets) {\n      const listOperationContext = listOperation\n        ?? ({ operationIdentifier: CoreResourceOperation.LIST } as FrontendResourceConfiguration_Operation);\n      emit(FrontendEvents.RESOURCE_REFRESH, {\n        resourceType,\n        operationIdentifier: String(listOperationContext.operationIdentifier ?? CoreResourceOperation.LIST),\n        operation: listOperationContext,\n        variantType: listOperation?.variantType,\n        isOperationDefault: listOperation?.isOperationDefault ?? true,\n        isBulkOperation: listOperation?.isBulkOperation ?? false,\n        variantKey: listOperation?.variantKey,\n        contextResourceIdentifiers: parentScopeIdentifiers,\n        parentResourcesRequirements: resourceContext.parentResourcesRequirements,\n        ...(successDiscriminator ? { optionalDiscriminator: successDiscriminator } : {}),\n      } as FrontendEventPayloads[FrontendEvents.RESOURCE_REFRESH]);\n    }\n\n    if (isGeneratedFileRegenerate) {\n      const readOperations = getOperationsForCoreSemantic(\n        siblingOperations,\n        CoreResourceOperation.READ,\n        {\n          requireAddressable: true,\n        },\n      ).filter((readOperation) =>\n        resourceConfig && registry\n          ? isFrontendOperationAddressableForCurrentContext({\n            resourceConfig: resourceConfig as AnyFrontendResourceConfiguration,\n            operation: readOperation,\n            registry,\n            hasResourceId: normalizedOutcomeContext[resourceType] !== undefined,\n            contextResourceIdentifiers: normalizedOutcomeContext,\n            contextualParameters: registry\n              ? FrontendResourceUtils.buildContextualParameters(normalizedOutcomeContext, registry)\n              : contextualParameters,\n          })\n          : true\n      );\n      const readRefreshTargets = readOperations.length > 0\n        ? readOperations\n        : [null];\n      const emittedReadOperationKeys = new Set<string>();\n\n      for (const readOperation of readRefreshTargets) {\n        const readOperationContext = readOperation\n          ?? ({ operationIdentifier: CoreResourceOperation.READ } as FrontendResourceConfiguration_Operation);\n        const readOperationKey = [\n          FrontendResourceUtils.getInstance().getResourceId(normalizedOutcomeContext[resourceType]),\n          String(readOperationContext.operationIdentifier),\n          readOperationContext.variantType ?? '',\n          readOperationContext.variantKey ?? '',\n          readOperationContext.isBulkOperation ?? false,\n        ].join(':');\n        if (emittedReadOperationKeys.has(readOperationKey)) {\n          continue;\n        }\n        emittedReadOperationKeys.add(readOperationKey);\n\n        emit(FrontendEvents.RESOURCE_REFRESH, {\n          resourceType,\n          operationIdentifier: String(readOperationContext.operationIdentifier ?? CoreResourceOperation.READ),\n          operation: readOperationContext,\n          variantType: readOperation?.variantType,\n          isOperationDefault: readOperation?.isOperationDefault ?? true,\n          isBulkOperation: readOperation?.isBulkOperation ?? false,\n          variantKey: readOperation?.variantKey,\n          contextResourceIdentifiers: normalizedOutcomeContext,\n          parentResourcesRequirements: resourceContext.parentResourcesRequirements,\n          ...(successDiscriminator ? { optionalDiscriminator: successDiscriminator } : {}),\n        } as FrontendEventPayloads[FrontendEvents.RESOURCE_REFRESH]);\n      }\n    }\n  }\n\n  emit(FrontendEvents.RESOURCE_OPERATION_EXECUTED, {\n    resourceType,\n    operationIdentifier: String(operation.operationIdentifier),\n    operation,\n    variantType: operation.variantType,\n    isOperationDefault: operation.isOperationDefault ?? true,\n    isBulkOperation: operation.isBulkOperation ?? false,\n    variantKey: operation.variantKey,\n    contextResourceIdentifiers: normalizedOutcomeContext,\n    parentResourcesRequirements: resourceContext.parentResourcesRequirements,\n    resultSummary: typeof result === 'object' && result !== null\n      ? result as Record<string, unknown>\n      : undefined,\n    ...(successDiscriminator ? { optionalDiscriminator: successDiscriminator } : {}),\n  } as FrontendEventPayloads[FrontendEvents.RESOURCE_OPERATION_EXECUTED]);\n}\n"]}

package/dist/esm/core/execution/execution-participation.utils.d.ts

@@ -0,0 +1,125 @@
+import { Resources_SharedUtils, type ResourceRelationship, type ResourceType } from '@wildo-ai/saas-models';
+import { ExecutionParticipationSource, type ExecutionViewDefinition } from '../../core/config/execution-view.schemas';
+import type { FrontendResource_ParentResourceRequirement } from '../../core/resources/resource-path.frontend.schemas';
+import type { FrontendResourceOperationContext, FrontendResourcesRegistry } from '../../core/resources/resources.frontend.schemas';
+export type ExecutionParticipationContextValue = FrontendResourceOperationContext['contextResourceIdentifiers'][string];
+export declare enum ExecutionParticipationValueShape {
+    SINGLE = "single",
+    ARRAY = "array"
+}
+export type ResolvedExecutionParticipation = {
+    ref: string;
+    source: ExecutionParticipationSource.ANCHOR;
+    resourceType: ResourceType;
+    bindingKey: string;
+    requirement?: FrontendResource_ParentResourceRequirement;
+    contextValue: ExecutionParticipationContextValue;
+} | {
+    ref: string;
+    source: ExecutionParticipationSource.PARENT_RESOURCE_REQUIREMENT | ExecutionParticipationSource.ADDITIONAL_RESOURCE_REQUIREMENT;
+    requirement: FrontendResource_ParentResourceRequirement;
+    contextValue?: ExecutionParticipationContextValue;
+} | {
+    ref: string;
+    source: ExecutionParticipationSource.RELATIONSHIP_PROJECTION;
+    fromParticipationRef: string;
+    relationship: ResourceRelationship;
+    currentResourceType: ResourceType;
+};
+interface ResolveExecutionParticipationsParams {
+    viewDefinition: ExecutionViewDefinition;
+    registry: FrontendResourcesRegistry;
+    anchor?: {
+        mainResourceType: string;
+        mainResourceId: string;
+        bindingKey: string;
+    } | null;
+    contextResourceIdentifiers?: Record<string, ExecutionParticipationContextValue>;
+    explicitContextResourceIdentifiers?: Record<string, ExecutionParticipationContextValue>;
+    sourceResourceDataByParticipationRef?: Record<string, Record<string, unknown> | undefined>;
+}
+/**
+ * Resolve authored execution participations into thin runtime handles.
+ *
+ * Important design constraints:
+ * - anchor/requirement participations preserve the original context value shape
+ * - relationship projections keep compiled relationship handles instead of
+ *   copying semantics/FK metadata into the public runtime type
+ * - ambiguous matches fail closed rather than choosing one edge implicitly
+ */
+export declare function resolveExecutionParticipations(params: ResolveExecutionParticipationsParams): Record<string, ResolvedExecutionParticipation>;
+export declare function getExecutionParticipationContextValue(participation: ResolvedExecutionParticipation): ExecutionParticipationContextValue | undefined;
+export declare function getExecutionParticipationResourceType(participation: ResolvedExecutionParticipation): ResourceType;
+export declare function getExecutionParticipationResourceId(participation: ResolvedExecutionParticipation): string | undefined;
+export declare function getExecutionParticipationRequirement(participation: ResolvedExecutionParticipation): FrontendResource_ParentResourceRequirement | undefined;
+export declare function getExecutionParticipationRelationship(participation: ResolvedExecutionParticipation): ResourceRelationship | undefined;
+export declare function getExecutionParticipationRelationshipSemantics(participation: ResolvedExecutionParticipation): ReturnType<typeof Resources_SharedUtils.getResolvedRelationshipSemantics> | undefined;
+export declare function getExecutionParticipationForeignKeyIdentity(participation: ResolvedExecutionParticipation, allResourceFieldIdentifiers: FrontendResourcesRegistry['allResourceFieldIdentifiers']): ReturnType<typeof Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity> | undefined;
+export declare function getExecutionParticipationEdgeKey(participation: ResolvedExecutionParticipation, registry: FrontendResourcesRegistry): string | undefined;
+export declare function getExecutionParticipationValueShape(participation: ResolvedExecutionParticipation): ExecutionParticipationValueShape;
+/**
+ * Build the canonical resource-context slot for one resolved execution participation.
+ *
+ * This is the resource-context analogue of
+ * `buildExecutionParticipationContextualParameters()`: it preserves the semantic
+ * `resourceType -> id | { fieldIdentifier, resourceId }` shape used across the
+ * frontend runtime so execution consumers can embed ordinary resource surfaces
+ * without hand-authoring alias metadata.
+ */
+export declare function buildExecutionParticipationContextIdentifier(params: {
+    participation: ResolvedExecutionParticipation;
+    registry: FrontendResourcesRegistry;
+}): FrontendResourceOperationContext['contextResourceIdentifiers'][string] | undefined;
+/**
+ * Build transport-ready contextual parameters from selected participations.
+ *
+ * Unlike ordinary `contextResourceIdentifiers`, execution participations are
+ * addressed by authored refs rather than by resource-type keys. This bridge keeps
+ * the same physical output contract (`fieldIdentifier -> id`) while resolving the
+ * appropriate field identifier from each participation's canonical requirement or
+ * registry metadata.
+ */
+export declare function buildExecutionParticipationContextualParameters(params: {
+    participationRefs: string[];
+    participations: Record<string, ResolvedExecutionParticipation>;
+    registry: FrontendResourcesRegistry;
+}): Record<string, string | number>;
+/**
+ * Derived, renderer-facing snapshot of a single resolved execution
+ * participation.
+ *
+ * Bundles the main derived runtime facts (resource id, value shape, context
+ * identifier, relationship, edge key) into one object so renderers do not have
+ * to re-assemble the same derivations for every participation they consume.
+ */
+export interface ExecutionParticipationHandle {
+    participation: ResolvedExecutionParticipation;
+    resourceType: ResourceType;
+    resourceId?: string;
+    valueShape: ExecutionParticipationValueShape;
+    contextValue?: ExecutionParticipationContextValue;
+    contextIdentifier?: FrontendResourceOperationContext['contextResourceIdentifiers'][string];
+    requirement?: FrontendResource_ParentResourceRequirement;
+    /**
+     * Derived relationship semantics (nature, handling, direction) for
+     * relationship-projected participations. This is the renderer-facing
+     * contract; use `rawRelationship` when you need the underlying
+     * `ResourceRelationship`.
+     */
+    relationship?: ReturnType<typeof getExecutionParticipationRelationshipSemantics>;
+    /** Raw compiled `ResourceRelationship` edge. Prefer `relationship` for rendering decisions. */
+    rawRelationship?: ResourceRelationship;
+    edgeKey?: string;
+}
+/**
+ * Pure builder for an `ExecutionParticipationHandle`.
+ *
+ * This is intentionally hook-free so it can be composed inside `useMemo(...)`
+ * call sites without forcing a dedicated custom hook per consumer.
+ */
+export declare function buildExecutionParticipationHandle(params: {
+    participation: ResolvedExecutionParticipation;
+    registry: FrontendResourcesRegistry;
+}): ExecutionParticipationHandle;
+export {};
+//# sourceMappingURL=execution-participation.utils.d.ts.map

package/dist/esm/core/execution/execution-participation.utils.d.ts.map

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