@odigos/ui-kit 0.0.249 → 0.0.251

package/docs/api-context.md

@@ -0,0 +1,687 @@
+# API Context Refactor — PLAT-1062
+
+> **Linear**: [PLAT-1062](https://linear.app/odigos/issue/PLAT-1062/introduce-odigosapicontext-in-ui-kit-to-replace-per-container-api-prop)
+> **Scope**: `@odigos/ui-kit`, `odigos/frontend/webapp`, `odigos-enterprise/central-ui`
+
+## TL;DR
+
+- **Apollo moved into the kit.** The two host apps no longer construct an `ApolloClient` — the kit's `<OdigosApiProvider>` owns it and is configured by the host via a small `ApolloConfig` shape.
+- **Containers fetch their own data.** Every `_v2` container that previously took a forest of API-function props now consumes `useOdigosApi()` / `useApiQuery(key)` from the kit's API context. Pages collapse to one-liners.
+- **Hosts ship a thin adapter** (~250 lines) mapping GraphQL documents to typed `Operation` slots. No more 16 CRUD hooks per host (`useSourceCRUD`, `useDestinationCRUD`, …).
+- **Apollo cache is the entity store.** The kit's `useEntityStore` Zustand store is gone — sources/destinations/actions/rules/namespaces all flow through Apollo's normalized cache via `useApiQuery('GET_X', …, { fetchPolicy: 'cache-first' })`. Mutations call `runMutation` then `await fetchAll()`; cache writes broadcast to every active subscriber.
+- **Uniform API surface.** `useOdigosApi()` returns `{ sourcesApi, destinationsApi, actionsApi, instrumentationRulesApi, …, capabilities, resetCache }` — every entity-list namespace exposes `{ items, loading, fetchAll, … }`. No aliasing on destructure, no stuttery `sourcesApi.sources`.
+- **Strict types end-to-end.** ~80 named `OdigosApiOperations` slots, each typed as `Operation<TData, TVars>`. Zero `any`, zero envelope/bare unions, zero `unknown` data fields at the public hook surface.
+- **Storybook is production-unaware.** The kit's runtime has no mock context, no interceptor hooks. The Storybook mock provider uses a custom Apollo `ApolloLink` that intercepts stub queries with predefined data.
+- **Mock data lives in `.storybook/`.** `src/mock-data/` was relocated; production builds never touch it.
+
+---
+
+## Why
+
+Before this refactor, the same shape repeated everywhere:
+
+1. **Each host app declared its own Apollo client and graphql operations.** Two near-duplicate Apollo configs, two near-duplicate sets of typed `gql` documents.
+2. **Each host app owned 16 CRUD hooks** (`useSourceCRUD`, `useDestinationCRUD`, `useActionCRUD`, `useInstrumentationRuleCRUD`, etc.). Each hook re-implemented optimistic updates, notifications, and progress tracking against the kit's `useEntityStore`.
+3. **A separate Zustand entity store mirrored Apollo.** `useEntityStore` held sources/destinations/actions/rules/namespaces with bespoke `setEntities` / `addEntities` / `removeEntities` / `setEntitiesLoading` mutators. Domain hooks pushed query results into it; SSE handlers patched per-id; consumers subscribed via selectors. Two layers of caching, two sets of write paths to keep in sync.
+4. **Each `_v2` container received API functions as props.** A typical drawer took 5–15 callbacks (`fetchById`, `update`, `restartWorkloads`, `fetchPeerSources`, …). Pages hand-wired dozens of props per container.
+5. **API functions were drilled through nested components.** `<EditSourceDrawer>` → `<Profiling>` → `<FlameGraphCanvas>` carried `fetchProfilingSlots` / `enableProfiling` / `fetchSourceProfiling` purely to satisfy the leaf.
+6. **Types diverged.** Each host had its own `Workload` / `Destination` / `Action` types; the kit's mock types didn't match wire types; envelope vs bare result shapes leaked into containers as runtime narrowing.
+
+The user-facing symptom: **adding a new operation required touching 5 places** — host's gql doc + host's CRUD hook + host's page + kit's container prop + kit's container body. Container changes routinely required correlated host changes. Two host apps duplicated the same plumbing 80% verbatim.
+
+---
+
+## Architecture: Before / After
+
+### Before — duplicated host-side plumbing, deep prop drilling, two caches
+
+```mermaid
+graph TB
+    subgraph "Each host app"
+        AC[ApolloClient]
+        H1[useSourceCRUD]
+        H2[useDestinationCRUD]
+        H3[useActionCRUD]
+        H4[13 more CRUD hooks]
+    end
+
+    subgraph "Kit"
+        ENTITY[useEntityStore<br/>Zustand mirror]
+    end
+
+    AC --> H1
+    AC --> H2
+    AC --> H3
+    AC --> H4
+    H1 -->|setEntities| ENTITY
+    H2 -->|setEntities| ENTITY
+    H3 -->|setEntities| ENTITY
+    H4 -->|setEntities| ENTITY
+
+    subgraph "Page"
+        H1 --> P[Page wires<br/>40+ props]
+        H2 --> P
+        H3 --> P
+        H4 --> P
+        ENTITY -->|selector| P
+    end
+
+    P -->|"fetchAll, persist,<br/>update, refresh, …"| C1[Overview container]
+    P -->|"fetchById, update,<br/>fetchPeerSources, …"| C2[EditSourceDrawer]
+    C2 -->|"fetchK8sManifest"| L1[Debug tab]
+    C2 -->|"fetchProfilingSlots,<br/>enableProfiling, …"| L2[Profiling tab]
+    C2 -->|"fetchPeerSources"| L3[Peers tab]
+```
+
+### After — single source of truth in the kit, one cache
+
+```mermaid
+graph TB
+    subgraph "Host adapter (one file, ~250 LOC)"
+        ADAPTER[OdigosApiAdapter]
+        OPS[Operations map]
+        APOLLO_CONFIG[ApolloConfig]
+        ADAPTER --> OPS
+        ADAPTER --> APOLLO_CONFIG
+    end
+
+    subgraph "Kit"
+        ADAPTER --> PROVIDER[OdigosApiProvider]
+        PROVIDER --> APOLLO["ApolloClient<br/>(normalized cache)"]
+        PROVIDER --> CTX[OdigosApiContext]
+        CTX --> HOOK1["useOdigosApi()<br/>sourcesApi.items, fetchAll, …"]
+        CTX --> HOOK2["useApiQuery('GET_X')"]
+        CTX --> HOOK3["useApiMutation('CREATE_X')"]
+        HOOK1 -.reads / writes.-> APOLLO
+        HOOK2 -.reads / writes.-> APOLLO
+        HOOK3 -.writes.-> APOLLO
+    end
+
+    subgraph "Pages"
+        PAGE1[Overview page<br/>1 line]
+        PAGE2[Settings page<br/>1 line]
+        PAGE3[Sampling page<br/>1 line]
+    end
+
+    HOOK2 --> CONTAINER[Containers]
+    HOOK1 --> CONTAINER
+    HOOK3 --> CONTAINER
+    CONTAINER --> PAGE1
+    CONTAINER --> PAGE2
+    CONTAINER --> PAGE3
+```
+
+Pages went from `<Overview metrics={…} effectiveConfig={…} workloads={…} {/* ~12 more props */} />` to `<Overview />`. Every fetch lives inside the container that consumes the data, and every consumer reads through Apollo's cache — there's no second store to keep in sync.
+
+---
+
+## Key concepts
+
+### `Operation<TData, TVars>`
+
+The atomic unit of data exchange. A host adapter declares one `Operation` per logical query/mutation:
+
+```typescript
+export interface Operation<TData = unknown, TVars = unknown> {
+  /** Apollo document. May be a function of context for versioned-query maps. */
+  document: DocumentNode | ((ctx: OperationContext) => DocumentNode | undefined);
+
+  /** Massage variables before they hit the wire. */
+  transformVariables?(vars: TVars, ctx: OperationContext): unknown;
+
+  /** Massage the raw Apollo response before it reaches the consumer. */
+  transformResult?(raw: unknown, ctx: OperationContext): TData | undefined;
+
+  /** Per-op ApolloClient override (multi-endpoint use cases). */
+  client?: ApolloClient<unknown>;
+
+  // …multi-fetch variants for fan-out…
+}
+```
+
+The function-shaped `document` is the lever that lets central-ui swap GraphQL strings per platform/version (`PlatformType.K8s` v1.20 vs `PlatformType.Vm` v0.6.0) without the kit knowing how versioning works. The kit's `pickByPlatform()` and `versionedDocument()` helpers ([platform-helpers.ts](../src/contexts/odigos-api/platform-helpers.ts)) cover the common shapes.
+
+### `OdigosApiOperations` — typed slot map
+
+The aggregate. Every operation has an explicit `<TData, TVars>`:
+
+```typescript
+export interface OdigosApiOperations {
+  // sources
+  GET_WORKLOADS: Operation<GetWorkloadsData, GetWorkloadsVars | undefined>;
+  GET_WORKLOADS_BY_IDS: Operation<GetWorkloadsByIdsData, GetWorkloadsByIdsVars>;
+  PERSIST_SOURCES: Operation<unknown, PersistSourcesVars>;
+  UPDATE_SOURCE: Operation<{ updateK8sActualSource: boolean }, UpdateSourceVars>;
+
+  // destinations
+  TEST_DESTINATION_CONNECTION: Operation<TestConnectionResponse, TestDestinationConnectionVars>;
+
+  // …~80 slots total…
+
+  // tokens — bare slot, adapter flattens the wire envelope via transformResult
+  GET_TOKENS?: Operation<TokenPayload[], undefined>;
+
+  // config — bare FetchedConfig, slot type lives in the kit
+  GET_CONFIG?: Operation<FetchedConfig, undefined>;
+
+  // Mutation vars are wire-shaped — they match the GraphQL mutation's
+  // declared `($variable: Type)` exactly so consumers don't have to
+  // shape-shift in calling code.
+  DELETE_ACTION: Operation<unknown, DeleteActionVars>; // { id, actionType }
+  UPDATE_LOCAL_UI_CONFIG?: Operation<unknown, UpdateLocalUiConfigVars>; // { config: LocalUiConfigInput }
+  UPDATE_DATA_STREAM: Operation<unknown, UpdateDataStreamVars>; // { id, dataStream }
+}
+```
+
+Operations marked `?` are optional. Host adapters that don't support an op simply omit it; the kit's [capabilities deriver](../src/contexts/odigos-api/capabilities.ts) reads slot presence to decide which UI affordances to show (`canCreateAction`, `canFetchSnapshots`, `canTestDestinationConnection`, etc.).
+
+#### Variance trick — method shorthand
+
+`Operation`'s callbacks are declared with method-shorthand (`fn(args): R`) rather than property syntax (`fn: (args) => R`). TypeScript checks method shorthand **bivariantly**, so a host adapter's tightly-typed `Operation<MyData, MyVars>` can be assigned into the aggregate slot without strict-contravariance friction on `TVars`. Without this, the slot map would force every operation to use `any` for variables.
+
+### `<OdigosApiAdapter>` — host's only integration point
+
+A host's full integration shrinks to one file:
+
+```typescript
+// odigos/frontend/webapp/lib/odigos-api-adapter.tsx (sketch)
+const operations: OdigosApiOperations = {
+  GET_WORKLOADS: { document: GET_WORKLOADS },
+  CREATE_DESTINATION: { document: CREATE_DESTINATION },
+  GET_K8S_MANIFEST: {
+    document: GET_K8S_MANIFEST,
+    // The wire returns `{ k8sManifest: string }` (or the legacy
+    // `k8sActualManifest`/`manifest` shapes); the kit's slot is bare
+    // `string`. Walk every accepted name so the consumer never has
+    // to runtime-narrow the envelope.
+    transformResult: (raw) => {
+      const obj = raw as { k8sManifest?: string; k8sActualManifest?: string; manifest?: string };
+      return obj?.k8sManifest ?? obj?.k8sActualManifest ?? obj?.manifest;
+    },
+  },
+  // …
+};
+
+export default function OdigosApiAdapter({ children, context }) {
+  const { token, isLoading } = useCSRF();
+  const ready = IS_LOCAL || !isLoading;
+
+  const apolloConfig = useMemo(() => ({
+    httpUrl: API.GRAPHQL,
+    csrfHeader: () => token ? { 'X-CSRF-Token': token } : {},
+    addTypename: false,
+  }), [token]);
+
+  // CRITICAL: gate the provider behind the CSRF bootstrap. Without
+  // the gate, the kit's domain hooks fire `useApiQuery(…cache-first)`
+  // on mount and the request goes out before `csrfHeader()` has a
+  // token to inject. Use `useState(!IS_LOCAL)` for `isLoading` in
+  // the CSRF hook so the very first render reports the loading
+  // state and the gate doesn't briefly mount the provider with a
+  // null token.
+  if (!ready) return <Loader />;
+
+  return (
+    <OdigosApiProvider apolloConfig={apolloConfig} operations={operations} context={context}>
+      {children}
+    </OdigosApiProvider>
+  );
+}
+```
+
+Central-ui's adapter is similar but uses a `wrapRemote(versionedQuery, extract?)` helper to wrap each slot in a `REMOTE_FETCH` proxy call, with versioned-query resolution driven off the active proxy's reported version. The `extract` callback is the same idea as `transformResult` above — it normalizes per-op envelopes to the kit's bare slot shape.
+
+#### Provider-mounting gotcha — every page that calls `useApiQuery` / `useOdigosApi` must be inside `<OdigosApiAdapter>`
+
+The kit's `useOdigosApiInternal()` hook _throws_ if it can't find an `<OdigosApiProvider>` above it. That includes anything that goes through it transitively: `useOdigosApi`, `useApiQuery`, `useApiLazyQuery`, `useApiMutation`. The error is `[ui-kit] useOdigosApi() / useXxxApi() called outside of <OdigosApiProvider>`.
+
+In Next.js app-router setups, this is easy to miss. If your app routes look like:
+
+```
+app/
+  layout.tsx         ← root layout (no adapter)
+  page.tsx           ← root page (calls useConfig() to redirect)
+  (v2)/
+    layout.tsx       ← mounts <OdigosApiAdapter>
+    overview/page.tsx
+    …
+  (setup)/
+    layout.tsx       ← mounts <OdigosApiAdapter>
+    onboarding/page.tsx
+```
+
+The `app/page.tsx` ("root page") is rendered with only `app/layout.tsx` above it — neither of the route-group layouts apply. If that page calls `useConfig` (or any kit hook), it crashes the moment it's rendered. Wrap it inline:
+
+```tsx
+// app/page.tsx
+function Redirect() {
+  const { config } = useConfig();
+  // …
+}
+
+export default function App() {
+  return (
+    <OdigosApiAdapter>
+      <Redirect />
+    </OdigosApiAdapter>
+  );
+}
+```
+
+Pre-refactor this worked because the host kept its own `<ApolloProvider>` in `app/layout.tsx`; after the kit took over Apollo, the kit's provider only mounts where the host explicitly puts it.
+
+#### Adapter checklist: matching wire shapes to kit slots
+
+The most common bugs in adapters come from mismatched wire-shape ↔ kit-slot envelopes. Use this as a sanity sweep when adding or auditing slots:
+
+| Slot                                                                                  | Kit-slot shape                                             | Wire shape (current backend)                                         | Adapter must                                                                                                                                                      |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET_WORKLOADS`                                                                       | `{ workloads: Workload[] }`                                | `{ workloads: [...] }`                                               | pass through                                                                                                                                                      |
+| `GET_DESTINATIONS` / `GET_ACTIONS` / `GET_INSTRUMENTATION_RULES` / `GET_DATA_STREAMS` | `{ computePlatform?: { x }, x? }`                          | `{ computePlatform: { x: [...] } }`                                  | pass through                                                                                                                                                      |
+| `GET_NAMESPACES_WITH_WORKLOADS`                                                       | `{ namespaces?: Namespace[] }`                             | `{ namespaces: [...] }` (v1.20+)                                     | pass through                                                                                                                                                      |
+| `GET_TOKENS`                                                                          | bare `TokenPayload[]`                                      | `{ computePlatform: { apiTokens: [...] } }`                          | extract `apiTokens` (note: NOT `tokens`)                                                                                                                          |
+| `GET_CONFIG`                                                                          | bare `FetchedConfig`                                       | `{ config: { … } }`                                                  | extract `config`                                                                                                                                                  |
+| `GET_EFFECTIVE_CONFIG`                                                                | bare `EffectiveConfig`                                     | `{ effectiveConfig: { … } }`                                         | extract `effectiveConfig`                                                                                                                                         |
+| `GET_K8S_MANIFEST`                                                                    | bare `string`                                              | `{ k8sManifest: "…" }`                                               | extract `k8sManifest`                                                                                                                                             |
+| `GET_GATEWAY_INFO`                                                                    | bare `GatewayInfo`                                         | `{ gatewayDeploymentInfo: { … } }`                                   | extract `gatewayDeploymentInfo`                                                                                                                                   |
+| `GET_NODE_COLLECTOR_INFO`                                                             | bare `NodeCollectoInfo`                                    | `{ odigletDaemonSetInfo: { … } }`                                    | extract `odigletDaemonSetInfo`                                                                                                                                    |
+| `GET_NODE_COLLECTOR_PODS`                                                             | bare `PodInfo[]`                                           | `{ odigletPods: [...] }`                                             | extract `odigletPods`                                                                                                                                             |
+| `GET_COLLECTOR_POD_INFO`                                                              | bare `ExtendedPodInfo`                                     | `{ collectorPod: { … } }`                                            | extract `collectorPod`                                                                                                                                            |
+| `GET_DATA_STREAMS`                                                                    | `{ dataStreams? } \| { computePlatform: { dataStreams } }` | `{ computePlatform: { dataStreams: [...] } }`                        | pass through (kit hook reads either path); the `useDataStreamsApi` hook auto-fetches via `useApiQuery` and bridges into `useDataStreamStore` for legacy consumers |
+| `GET_SOURCE_PROFILING`                                                                | bare `SourceProfilingResult`                               | `{ computePlatform: { source: { profiling: {…} } } }`                | walk `computePlatform.source.profiling`                                                                                                                           |
+| `GET_SAMPLING_RULES`                                                                  | `{ samplingRules, k8sHealthProbesConfig }`                 | `{ sampling: { rules, configs.effective.k8sHealthProbesSampling } }` | flatten `sampling.rules` and `sampling.configs.effective.k8sHealthProbesSampling`                                                                                 |
+| `GET_SERVICE_MAP`                                                                     | `{ serviceMap?: ServiceMapSources }`                       | `{ getServiceMap: { services: [...] } }`                             | flatten to `{ serviceMap: services }`                                                                                                                             |
+| `GET_DIAGNOSE`                                                                        | `DiagnoseResult` (bare)                                    | `{ diagnose: { stats, … } }`                                         | extract `diagnose`                                                                                                                                                |
+
+Mutation variables follow the same logic — declare `Vars` shapes that match what the wire's `mutation(...)` declaration expects, NOT the prettier shape the consumer code wants:
+
+| Slot                                                          | Kit-slot vars                                   | Wire variables                                                  | Notes                                                                                                                                        |
+| ------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DELETE_ACTION`                                               | `{ id: string; actionType: string }`            | `($id: ID!, $actionType: String!)`                              | Pass the `Action.type` enum value as `actionType`                                                                                            |
+| `UPDATE_LOCAL_UI_CONFIG`                                      | `{ config: LocalUiConfigInput }`                | `($config: LocalUiConfigInput!)`                                | Wrap, don't spread                                                                                                                           |
+| `UPDATE_LOCAL_UI_SAMPLING_CONFIG`                             | `{ config: SamplingK8sHealthConfigInput }`      | `($config: SamplingConfigInput)`                                | Wrap, don't spread                                                                                                                           |
+| `UPDATE_DATA_STREAM`                                          | `{ id: string; dataStream: DataStream }`        | `($id: ID!, $dataStream: DataStreamInput!)`                     | The data stream's `name` doubles as wire `id`                                                                                                |
+| `DELETE_DATA_STREAM`                                          | `{ id: string }`                                | `($id: ID!)`                                                    | Same — name is id                                                                                                                            |
+| `CREATE_INSTRUMENTATION_RULE` / `UPDATE_INSTRUMENTATION_RULE` | input includes `sourceScopes` (kit spec shape)  | `InstrumentationRuleInput` declares `sourcesScopes` (row array) | Kit's `useInstrumentationRulesApi` runs `adaptInstrumentationRuleInputForWire` for both directions; adapters don't need extra plumbing here. |
+| `GET_DIAGNOSE`                                                | `{ input: DiagnoseFormData; dryRun?: boolean }` | `($input: DiagnoseInput!, $dryRun: Boolean)`                    | `useDescribeApi.downloadDiagnose(formData)` wraps internally — adapters don't need to do anything beyond `transformResult` for the response. |
+
+When in doubt, copy a working query from the host's existing GraphQL files and `console.log` the raw `apolloClient.query(...)` response — what comes back is exactly what `transformResult(raw, ctx)` receives.
+
+#### Why we don't add identity `transformResult` to _every_ slot
+
+A reasonable defensive instinct is: "let's add a `transformResult` to every operation, even when the wire shape already matches the kit slot, so future shape drifts surface in one place." We've considered this and chose not to. Identity transforms add noise without catching anything — if the wire silently switches `gatewayInfo` to `gatewayDeploymentInfo`, the identity transform `(raw) => raw` still passes through and the consumer still breaks downstream. The bug surfaces in the same place either way: in the consumer.
+
+The actual safety nets are:
+
+1. **Strict slot types — no `unknown`, no `any`.** Every `OdigosApiOperations[K]` declares `Operation<TData, TVars>` with concrete `TData` / `TVars` types — including mutation result types like `CreateActionResult = { createAction: Action }`, `DeleteActionResult = { deleteAction: boolean }`, and so on. Adapters that produce the wrong shape get a TypeScript error at the slot assignment. The few `unknown`s that remain in the kit's internals are inherent type-erasure boundaries and are documented inline:
+   - `transformResult?(raw: unknown, …)` — Apollo's response is opaque from the kit's perspective; the adapter narrows it.
+   - `messageFromError(e: unknown)` — error catching.
+   - `ApolloClient<unknown>` — Apollo's cache-shape generic; `unknown` is the safe pass-through.
+   - `Operation['document']` and the kit's K-distributed-union collapse (`AnyOp = Operation<unknown, unknown>`) — type-level inference helpers, never observed by adapter authors or container consumers.
+2. **Mutation `Vars` types match wire variables exactly.** `DeleteActionVars` is `{ id, actionType }` because the wire is `mutation($id: ID!, $actionType: String!)`. `UpdateLocalUiConfigVars` is `{ config: LocalUiConfigInput }` because the wire wraps the input under `$config`. No "spread the form data flat" — every mutation's `TVars` is a literal mirror of its `mutation(…)` declaration.
+3. **The wire-shape table above** — when adding a new slot, scan it for the matching row. If your wire returns something different, write a `transformResult`.
+4. **Domain-hook guards** — for the rare slot whose wire shape varies across versions (e.g. `GET_DESTINATIONS` returning `{ computePlatform: { destinations } }` on most backends and a flat shape on some), the kit's domain hook reads `data.computePlatform?.destinations ?? data.destinations ?? []` so either shape works.
+
+Add a `transformResult` _only_ when the wire shape doesn't already match the slot's `TData`. Otherwise leave the slot as `{ document }` and trust the type system.
+
+---
+
+## Hooks — declarative + imperative
+
+The kit ships two access patterns; containers pick whichever fits.
+
+### Declarative — `useApiQuery` / `useApiLazyQuery` / `useApiMutation`
+
+Apollo-backed hooks layered on top of `useQuery` / `useLazyQuery` / `useMutation`. Slot types drive everything — no `<TData, TVars>` generics at the call site:
+
+```typescript
+// Inside any kit container
+const {
+  data: gatewayInfo,
+  loading,
+  error,
+  refetch,
+} = useApiQuery('GET_GATEWAY_INFO', undefined, {
+  pollInterval: 3_000,
+  skip: !visible,
+});
+
+const [updateToken, { loading: saving }] = useApiMutation('UPDATE_TOKEN', {
+  refetchQueries: ['GET_TOKENS'],
+});
+```
+
+`useApiQuery` consults the operations map, applies `transformVariables` / `transformResult` automatically, and returns `{ data: SlotData<K>, loading, error, refetch, unsupported }`. The `unsupported` flag is `true` when the host adapter omitted the slot — containers either render an "operation not supported" UI or hide the affordance via `capabilities.canX`.
+
+### Imperative — `useOdigosApi()` + per-domain APIs
+
+For places that need both a cached list and dispatchable methods (event handlers, side-effect chains, drawers):
+
+```typescript
+// Subscribe to the entity lists this view actually reads.
+const { sourcesApi } = useOdigosApi({ subscribe: ['sources'] });
+
+// Cached list — read-only, kept fresh by Apollo's cache + SSE-driven refetch.
+const { items: sources, loading } = sourcesApi;
+
+const onClick = async () => {
+  await sourcesApi.update(sourceId, formData);
+  // sourcesApi.update internally awaits fetchAll() → cache write
+  // → broadcast → every active `useApiQuery('GET_WORKLOADS')` re-renders.
+};
+```
+
+Every entity-list namespace (`sourcesApi`, `destinationsApi`, `actionsApi`, `instrumentationRulesApi`, `namespacesApi`, `dataStreamsApi`) follows the same `{ items, loading, fetchAll, … }` shape. The `*Api` suffix on the top-level keys means destructuring stays rename-free even when the consumer has a local `sources` / `destinations` variable.
+
+#### `subscribe` opt-in — the six entity-list domains
+
+The six entity-list domain APIs (`sourcesApi`, `destinationsApi`, `actionsApi`, `instrumentationRulesApi`, `namespacesApi`, `dataStreamsApi`) own a `useApiQuery('GET_…')` subscription that auto-fetches and broadcasts to every consumer. **Without an explicit opt-in those subscriptions stay `skip: true`** — calling `useOdigosApi()` from a page that only needs `configApi` (e.g. `/settings`) does NOT trigger every list query. Containers that read `.items` / `.loading` MUST list the domains they need:
+
+```typescript
+// Module-level constant so the array reference is stable across renders.
+const SUBSCRIBE_ENTITIES: SubscribableDomain[] = ['sources', 'destinations', 'actions', 'rules'];
+
+export const Columns: FC = () => {
+  const { sourcesApi, destinationsApi, actionsApi, instrumentationRulesApi } = useOdigosApi({
+    subscribe: SUBSCRIBE_ENTITIES,
+  });
+  const { items: sources, loading: sourcesLoading } = sourcesApi;
+  // …
+};
+```
+
+Symptoms of forgetting the opt-in: empty lists in the UI, `loading` permanently `false`, no auto-refresh on SSE. The fix is always to add the missing domain key. Containers that only call imperative methods (create / update / delete / fetchAll) leave the option off entirely — the domain still exposes those methods, just without the auto-fetch.
+
+| Container                               | Subscribes to                                     |
+| --------------------------------------- | ------------------------------------------------- |
+| `_v2/overview/columns`                  | `['sources', 'destinations', 'actions', 'rules']` |
+| `_v2/overview/drawers`                  | `['sources']`                                     |
+| `_v2/overview/filters`                  | `['sources', 'namespaces']`                       |
+| `_v2/overview/search`                   | `['sources', 'destinations', 'actions', 'rules']` |
+| `_v2/overview/data-stream-select`       | `['dataStreams']`                                 |
+| `_v2/sampling-rules`                    | `['sources']`                                     |
+| `service-map`                           | `['sources']`                                     |
+| `_v2/_drawers/edit-source-drawer/peers` | `['sources']`                                     |
+| `_v2/_drawers/system-drawer/diagnose`   | `['namespaces']`                                  |
+| `contexts/destination-form-context`     | `['destinations']`                                |
+
+The full surface returned by `useOdigosApi()`:
+
+```typescript
+const {
+  sourcesApi, // { items, loading, fetchAll, fetchByTargets, fetchById, persist, update, … }
+  destinationsApi, // { items, loading, fetchAll, create, update, remove, testConnection, … }
+  actionsApi, // { items, loading, fetchAll, create, update, remove }
+  instrumentationRulesApi, // { items, loading, fetchAll, create, update, remove }
+  namespacesApi, // { items, loading, fetchAll, persist }
+  dataStreamsApi, // { items, loading, fetchAll, create, update, remove }
+  k8sManifestApi,
+  configApi,
+  describeApi,
+  tokensApi,
+  metricsApi,
+  serviceMapApi,
+  profilingApi,
+  collectorsApi,
+  samplingApi,
+  snapshotsApi,
+  capabilities, // canCreateAction, canFetchSnapshots, canTestDestinationConnection, …
+  resetCache, // wipes Apollo's cache (used on proxy switch in central-ui)
+} = useOdigosApi();
+```
+
+Both declarative and imperative paths share the same `runner.ts` dispatcher under the hood — same `transformVariables` / `transformResult` / `client` flow, same graceful "operation not configured" fallback when a slot is absent, same Apollo cache.
+
+---
+
+## Data flow — Apollo cache as the entity store
+
+The deleted `useEntityStore` Zustand store used to be the kit's mirror of every entity list. It's gone. Apollo's normalized cache is now the single source of truth, and the kit's domain hooks read/write through it directly.
+
+```mermaid
+graph LR
+    subgraph "Kit domain hook (e.g. useSourcesApi)"
+        SUB["useApiQuery('GET_WORKLOADS')<br/>fetchPolicy: cache-first"]
+        FETCH["fetchAll() / fetchByTargets() / fetchById()"]
+        MUT["update / persist / restartWorkloads / …"]
+    end
+
+    SUB -->|"items, loading"| CONSUMER1[Container A]
+    SUB -.shared cache.-> SUB2["useApiQuery('GET_WORKLOADS')<br/>(in another consumer)"]
+    SUB2 -->|"items, loading"| CONSUMER2[Container B]
+
+    CACHE[("Apollo<br/>normalized<br/>cache")]
+    SUB <-->|reads| CACHE
+    FETCH -->|"runQuery<br/>(network-only)"| CACHE
+    MUT -->|"runMutation<br/>then await fetchAll()"| CACHE
+    SSE[Host SSE handler] -->|"sourcesApi.fetchAll()"| CACHE
+    PROXY[Proxy switch<br/>central-ui] -->|"resetCache()"| CACHE
+
+    CACHE -.broadcast.-> SUB
+    CACHE -.broadcast.-> SUB2
+```
+
+**Reads.** Every consumer of `useOdigosApi().sourcesApi` registers an Apollo observer of `GET_WORKLOADS` via `useApiQuery`. The first observer fetches over the network, every subsequent one hits the shared cache (`fetchPolicy: 'cache-first'`). Cache writes broadcast — when _any_ refetch lands, every observer re-renders with the new list.
+
+**Writes.** Mutations call `runMutation` and `await fetchAll()` immediately after success. The runner's `client.query({ fetchPolicy: 'network-only' })` writes the response into the cache, which broadcasts. Every container that reads `sourcesApi.items` updates within one render — no Zustand selector hop, no manual `setEntities`. Apollo's request dedup keeps the cost of "fan-out from one mutation" at a single network round-trip.
+
+**SSE.** Both host SSE handlers (`useSSE.ts`) drop their old `useEntityStore` imports and refresh through the same `sourcesApi.fetchAll()` / `destinationsApi.fetchAll()` entry points. The deleted-target eviction primitive is gone — for an envelope-aware kit (central-ui's `REMOTE_FETCH` makes generic `cache.modify` impractical), refetching the canonical list is simpler and the result is identical.
+
+**Reset.** Central-ui's `useProxy.resetStores()` calls `useOdigosApi().resetCache()` when switching between proxies (and on every out-of-proxy navigation). `resetCache()` delegates to `client.cache.reset()` — **not** `client.clearStore()`. This matters: `clearStore()` aborts every in-flight query, rejecting it with Apollo error #42 ("Store reset while query was in flight"). Because central-ui resets on out-of-proxy navigation, that abort raced with the legitimate out-of-proxy queries still loading on the same render (`GetSystemConfig`, `GetHealth`, `GetComputePlatforms`) and surfaced them as confusing network/CORS-looking errors plus an error toast. `cache.reset()` wipes the cache and broadcasts to active watchers (they re-render empty and re-fetch on next access) but leaves in-flight requests alone — they write into the freshly-reset cache when they resolve.
+
+**Precondition guards (`Operation.canRun`).** An `Operation` may declare `canRun?(ctx): boolean`. When it returns `false`, `useApiQuery` / `useApiLazyQuery` / `useApiMutation` skip the dispatch (no network request, no Apollo observer) and the imperative `runQuery` / `runMutation` short-circuit to `{ data: undefined }` with no error (so domain hooks don't toast). central-ui sets `canRun: (ctx) => !!ctx.proxyID && !!getVersionedQuery(...)` on every `REMOTE_FETCH`-backed op: out-of-proxy pages have no selected proxy, so without the guard the kit would fire an empty `RemoteFetch($proxyID, $query, $variables)` with both required vars missing. The multi-cluster fan-out path (`runMulti` / `transformVariablesMulti`) is scoped by explicit `proxyIDs` and intentionally bypasses `canRun`, so connections-scope bulk drawers keep working even though `ctx.proxyID` is empty there.
+
+> **Optimistic instrument-on-form-submit lag.** The previous version of `prepareSourcePayloads` accepted Zustand mutators and patched the entity store optimistically before the mutation resolved. That path is gone — the mutation now fires, then `await fetchAll()` refreshes (~200–500ms total). Per-adapter `cache.modify` plumbing would reinstate optimism, but central-ui's opaque `REMOTE_FETCH` envelope makes it more code than it's worth. The 5s SSE debounce that previously masked the optimistic pattern is no longer the critical path either — the post-mutation refetch arrives well before SSE.
+
+---
+
+## Migration patterns
+
+### Container migration — 10 props → 1 hook
+
+**Before:**
+
+```typescript
+interface OverviewProps {
+  metrics: Metrics;
+  effectiveConfig?: EffectiveConfig;
+  fetchAll: () => Promise<void>;
+  fetchPeerSources: (s: string) => Promise<...>;
+  updateSource: (id, payload) => Promise<...>;
+  // …12 more callbacks
+}
+
+export const Overview: FC<OverviewProps> = (props) => { … };
+```
+
+**After:**
+
+```typescript
+export interface OverviewProps {} // Empty
+export const Overview: FC<OverviewProps> = () => {
+  const { sourcesApi, destinationsApi, capabilities } = useOdigosApi();
+  const { items: sources, loading: sourcesLoading } = sourcesApi;
+  const { items: destinations } = destinationsApi;
+
+  const { data: metrics } = useApiQuery('GET_METRICS', undefined, { pollInterval: 10_000 });
+  // …
+};
+```
+
+### Page shrink — data plumbing → one-liner
+
+**Before** (`app/(v2)/overview/page.tsx`):
+
+```typescript
+'use client';
+export default function Page() {
+  const { metrics } = useMetrics();
+  const { effectiveConfig } = useEffectiveConfig();
+  const sources = useSources();
+  const namespaces = useNamespaces();
+  // …+ 12 hook calls + correlated state
+  return <Overview metrics={metrics} effectiveConfig={effectiveConfig} workloads={…} {/* …more */} />;
+}
+```
+
+**After:**
+
+```typescript
+'use client';
+export default function Page() {
+  return <Overview />;
+}
+```
+
+The 4 webapp pages (`/overview`, `/settings`, `/sampling`, `/service-map`) collapsed to one-liners. Same on central-ui.
+
+### Storybook — mocks via `parameters.api`
+
+Stories pass mock data through Storybook's `parameters` (NOT `args` — args spread into the rendered component as unknown props):
+
+```typescript
+export const Default = Template.bind({});
+Default.parameters = {
+  api: {
+    queries: {
+      GET_GATEWAY_INFO: MOCK_GATEWAY_INFO,
+      GET_GATEWAY_PODS: MOCK_GATEWAY_PODS,
+    },
+  },
+};
+
+export const Loading = Template.bind({});
+Loading.parameters = { api: { loading: ['GET_METRICS'] } };
+
+export const Error = Template.bind({});
+Error.parameters = { api: { errors: { GET_DESTINATIONS: 'Forbidden' } } };
+```
+
+The Storybook decorator translates `parameters.api` into a custom Apollo `ApolloLink` that resolves stub queries with the predefined data. **No production code knows mocks exist.**
+
+---
+
+## Mock architecture
+
+### Production — kit hooks talk to real Apollo
+
+```mermaid
+graph LR
+    Container -->|useApiQuery| Hook[useApiQuery]
+    Hook -->|operations map| Slot[Operation slot]
+    Slot -->|document, transforms| Apollo[Apollo useQuery]
+    Apollo -->|HTTP| Backend[GraphQL backend]
+```
+
+The kit's `use-api-query.ts` has zero knowledge of mocks. No interceptor context, no `if (mockState)` branches.
+
+### Storybook — Apollo Link intercepts at the network boundary
+
+```mermaid
+graph LR
+    Container -->|useApiQuery| Hook[useApiQuery]
+    Hook -->|operations: stub ops| Slot[Stub Operation]
+    Slot -->|stub gql doc| Apollo[Apollo useQuery]
+    Apollo -->|operationName: GET_X| Link[Custom ApolloLink]
+    Link -->|matches mock| Resolve["Observable.of #123 data: MOCK_X #125"]
+```
+
+The Storybook mock provider builds a real `ApolloClient` whose only `Link` is a custom one that reads `operation.operationName` and returns:
+
+- a never-completing `Observable` (loading)
+- an error `Observable` (errors)
+- `Observable.of({ data: { mockData: <data> } })` (queries)
+
+It also builds stub `OdigosApiOperations` whose document operation-names match the slot keys, so when `useApiQuery('GET_GATEWAY_INFO')` fires, the link sees `operationName: 'GET_GATEWAY_INFO'` and routes to the right mock.
+
+The kit's hooks therefore go through their **real** Apollo path even in Storybook — same `useQuery` calls, same `transformResult`. Only the network is replaced.
+
+---
+
+## VM / cloud flexibility
+
+The `Operation` shape is platform-aware enough to absorb divergent backend schemas without "weird mappings" in the kit:
+
+```typescript
+import { dialects } from '@odigos/vmagent-api-apollo-client/registry';
+import { versionedDocument, vmDialectMap, pickByPlatform } from '@odigos/ui-kit/contexts/odigos-api';
+
+const operations: OdigosApiOperations = {
+  GET_WORKLOADS: {
+    document: versionedDocument({
+      [PlatformType.K8s]: { 'v1.20': K8S_GET_WORKLOADS_V1_20, 'v1.16': K8S_GET_WORKLOADS_V1_16 },
+      [PlatformType.Vm]: vmDialectMap(dialects, (d) => d.getSourcesV2),
+    }),
+    transformResult: (raw, ctx) =>
+      pickByPlatform(ctx, {
+        K8s: () => raw as GetWorkloadsData,
+        Vm: () => ({ workloads: mapVmSourceV2ToWorkload(raw) }),
+      })?.(),
+  },
+};
+```
+
+For multi-client topologies (e.g. a future `vmagent-api-apollo-client` that ships a constructed client), each `Operation` can carry an optional `client?: ApolloClient<unknown>` override. The runner's `pickClient(op, defaultClient)` honors it on every query, mutation, and multi-fetch fan-out.
+
+---
+
+## Diagnose download — kit-owned 2-step flow
+
+Some flows need a second, non-GraphQL round-trip after the Apollo step succeeds. Today only the **diagnose archive download** uses this — the GraphQL `diagnose` mutation prepares a tarball in a temp directory, then a REST endpoint streams it back to the browser. Both steps live entirely inside the kit; the host adapter doesn't wire anything beyond the standard `apolloConfig`.
+
+`useDescribeApi.downloadDiagnose(formData)` runs as a 2-step async chain:
+
+1. `runQuery(GET_DIAGNOSE, { input: formData, dryRun: false })` — backend builds the bundle and emits SSE progress events to the notification store.
+2. After step 1 resolves with `stats.fileCount > 0` and `dryRun` is false, the kit GETs `<apolloConfig.httpUrl-origin>/diagnose/download`, re-using the host's existing transport configuration:
+   - URL derived via `new URL('/diagnose/download', apolloConfig.httpUrl)` so the GraphQL endpoint can sit at any path (`/graphql`, `/api/graphql`, …) and the diagnose URL still resolves to `<origin>/diagnose/download`.
+   - `apolloConfig.credentials` controls cookies (`'same-origin'` vs `'include'`).
+   - `apolloConfig.authHeader()` and `apolloConfig.csrfHeader()` are awaited and merged into the request headers — same auth as Apollo's auth link, so rotating tokens stay in sync between the prep and download steps.
+3. The returned `Blob` is wrapped in an object URL and triggered as a browser download via a hidden `<a download>` element.
+
+Step 2 is skipped on dry runs and when the bundle is empty. Step 2 errors are logged but not surfaced — step 1 has already succeeded by then, so a step-2 failure shouldn't roll back progress or fire a confusing toast.
+
+Central-ui doesn't map `GET_DIAGNOSE` at all (the SystemDrawer hides the diagnose tab when `describeApi.downloadDiagnose` is `undefined`), so step 2 never fires there. If a future cloud platform needs a different diagnose URL, the kit can grow an `apolloConfig.diagnoseDownloadUrl?: string` override — but until that's a real requirement, the convention "same origin, `/diagnose/download` path" is the contract.
+
+---
+
+## Numbers
+
+|                                           |                        Before |                         After |
+| ----------------------------------------- | ----------------------------: | ----------------------------: |
+| Apollo clients constructed                |              2 (one per host) |                1 (in the kit) |
+| Caching layers for entity lists           | 2 (Apollo + `useEntityStore`) | 1 (Apollo's normalized cache) |
+| Per-host CRUD hooks                       |                      ~16 each |                             0 |
+| `_v2` containers taking API props         |                            37 |                             0 |
+| Webapp pages                              |  4 with 50+ lines of plumbing |             4 one-liner files |
+| Central-ui pages                          |  4 with 50+ lines of plumbing |             4 one-liner files |
+| `any` types in kit's API surface          |                          many |                             0 |
+| Envelope/bare unions in slot types        |                            12 |                             0 |
+| `eslint-disable` in production code paths |                            6+ |                             0 |
+| Mock files in `lib/` (production)         |                           n/a |                             0 |
+| Mock-data location                        |              `src/mock-data/` |       `.storybook/mock-data/` |
+| `useEntityStore` consumers (kit + hosts)  |                     30+ files |                             0 |
+| Lines deleted from host hooks             |                        ~3,000 |                             — |
+
+---
+
+## Open work / follow-ups
+
+- **VM API integration** ([odigos-enterprise/2881](https://github.com/odigos-io/odigos-enterprise/pull/2881), [odigos-enterprise/2836](https://github.com/odigos-io/odigos-enterprise/pull/2836)) — the kit is ready; the central-ui adapter just needs to consume `@odigos/vmagent-api-apollo-client/registry` via `vmDialectMap`.
+- **Workload shape platform-agnosticism** — the kit's `Workload.id.namespace` is required, so VM mappers stuff `'default'` as a placeholder. If/when a third platform lands, this should grow into a discriminated union.
+- **Mixed-version multi-fetch fan-out** — the runner currently groups all proxies under the active `ctx.version`. The legacy `useRemoteFetch.fetchMulti` supported per-proxy-version groups; preserved as a follow-up.
+- **Optimistic instrument-on-form-submit** — `prepareSourcePayloads` no longer patches the cache before the mutation resolves. The user sees the new sources after the post-mutation refetch (~200–500ms instead of instant). If the lag becomes noticeable, reinstate optimism via `client.cache.modify` on `GET_WORKLOADS` — but that requires a per-adapter "modify the canonical list" hook, since central-ui's `REMOTE_FETCH` envelope is opaque to the kit.
+- **Test coverage** — add unit tests for the runner's transform pipeline + the storybook mock link. The current test surface is the two host build pipelines.
+
+---
+
+## Reference
+
+- [`src/contexts/odigos-api/types.ts`](../src/contexts/odigos-api/types.ts) — `Operation`, `OdigosApiOperations`, `OperationContext`, `ApolloConfig`
+- [`src/contexts/odigos-api/runner.ts`](../src/contexts/odigos-api/runner.ts) — imperative `runQuery` / `runMutation` / `runMulti`
+- [`src/contexts/odigos-api/use-api-query.ts`](../src/contexts/odigos-api/use-api-query.ts) — declarative hooks
+- [`src/contexts/odigos-api/use-odigos-api.ts`](../src/contexts/odigos-api/use-odigos-api.ts) — namespaced API surface
+- [`src/contexts/odigos-api/platform-helpers.ts`](../src/contexts/odigos-api/platform-helpers.ts) — `pickByPlatform`, `versionedDocument`, `vmDialectMap`
+- [`.storybook/odigos-api-mock-provider.tsx`](../.storybook/odigos-api-mock-provider.tsx) — Apollo-Link-based mock provider
+- [`odigos/frontend/webapp/lib/odigos-api-adapter.tsx`](https://github.com/odigos-io/odigos/blob/main/frontend/webapp/lib/odigos-api-adapter.tsx) — webapp adapter (canonical pattern)
+- [`odigos-enterprise/central-ui/src/lib/odigos-api-adapter.tsx`](https://github.com/odigos-io/odigos-enterprise/blob/main/central-ui/src/lib/odigos-api-adapter.tsx) — central-ui adapter (REMOTE_FETCH wrapped)
+- [`CHANGELOG.md`](../CHANGELOG.md) — `1.0.0` entry with the breaking-change migration guide