@cat-factory/app 0.256.2 → 0.257.0

package/app/components/settings/KubernetesEngineForm.vue

@@ -14,6 +14,7 @@ import type {
   InfraEngine,
   InfraHandlerConfig,
 } from '@cat-factory/contracts'
+import { isKubernetesUrlSource } from '@cat-factory/contracts'
 import type { K3sSetupPrefill } from '~/stores/ui'
 
 // The kube branch of the discriminated handler config this form produces (the `local-k3s` /
@@ -22,6 +23,10 @@ import type { K3sSetupPrefill } from '~/stores/ui'
 // `as never` cast, so a wrong config shape is caught at the call site instead of server-side.
 type KubeHandlerConfig = Extract<InfraHandlerConfig, { engine: 'local-k3s' | 'remote-kubernetes' }>
 type KubeHandlerPayload = { config: KubeHandlerConfig; secrets: Record<string, string> }
+/** The engine connection block itself, read off the variant so it cannot drift from it. */
+type KubeEngineConfig = KubeHandlerConfig['kubernetes']
+/** How the environment URL is derived: its own discriminated union, keyed by `source`. */
+type KubeUrlSource = KubeEngineConfig['url']
 
 const props = defineProps<{
   /** `local-k3s` or `remote-kubernetes` — the engine this handler is registered under. */
@@ -46,12 +51,9 @@ const emit = defineEmits<{
 
 const { t } = useI18n()
 
-type UrlSource =
-  | 'ingressTemplate'
-  | 'ingressStatus'
-  | 'serviceStatus'
-  | 'gatewayStatus'
-  | 'httpRouteStatus'
+/** The `source` discriminants, read off the contract union: a source added there makes
+ *  `buildUrl`'s switch non-exhaustive rather than leaving this list quietly short. */
+type UrlSource = KubeUrlSource['source']
 
 const form = reactive({
   label: '',
@@ -101,23 +103,34 @@ watch(
   (h) => {
     const cfg = h?.config
     if (!cfg || (cfg.engine !== 'local-k3s' && cfg.engine !== 'remote-kubernetes')) return
-    const k = cfg.kubernetes as Record<string, unknown>
-    form.label = typeof k.label === 'string' ? k.label : ''
-    form.apiServerUrl = typeof k.apiServerUrl === 'string' ? k.apiServerUrl : ''
-    form.caCertPem = typeof k.caCertPem === 'string' ? k.caCertPem : ''
+    // Narrowing `cfg.engine` above types `kubernetes` as the engine config, so these read the
+    // contract directly. They used to widen it to a `Record` and `typeof`-guard every field,
+    // which re-derived at runtime what the discriminated union already states.
+    const k = cfg.kubernetes
+    form.label = k.label
+    form.apiServerUrl = k.apiServerUrl
+    form.caCertPem = k.caCertPem ?? ''
     form.insecureSkipTlsVerify = k.insecureSkipTlsVerify === true
-    form.namespaceTemplate = typeof k.namespaceTemplate === 'string' ? k.namespaceTemplate : ''
-    form.imageTemplate = typeof k.imageTemplate === 'string' ? k.imageTemplate : ''
-    const url = k.url as Record<string, unknown> | undefined
-    const src = typeof url?.source === 'string' ? (url.source as UrlSource) : 'ingressTemplate'
-    form.urlSource = src
-    form.hostTemplate = typeof url?.hostTemplate === 'string' ? url.hostTemplate : ''
-    form.ingressName = typeof url?.ingressName === 'string' ? url.ingressName : ''
-    form.serviceName = typeof url?.serviceName === 'string' ? url.serviceName : ''
-    form.servicePort = typeof url?.port === 'number' ? String(url.port) : ''
-    form.gatewayName = typeof url?.gatewayName === 'string' ? url.gatewayName : ''
-    form.httpRouteName = typeof url?.httpRouteName === 'string' ? url.httpRouteName : ''
-    form.urlScheme = url?.scheme === 'http' || url?.scheme === 'https' ? url.scheme : 'default'
+    form.namespaceTemplate = k.namespaceTemplate ?? ''
+    form.imageTemplate = k.imageTemplate ?? ''
+    // Each url field is read off the ONE variant that carries it, so a field belonging to a
+    // different `source` cannot silently populate the form.
+    //
+    // Typed as present with an on-union `source`, read as neither: both were true when the
+    // connect form admitted this config, and the value has been through storage since — which is
+    // exactly why the backend re-parses a stored `providerConfig` rather than asserting it, and
+    // this form is where an operator REPAIRS one that drifted. An unrecognised source falls back
+    // to the form's default, because `buildUrl` has no branch to build a config out of one.
+    const url: KubeUrlSource | undefined = k.url
+    const source = url?.source
+    form.urlSource = isKubernetesUrlSource(source) ? source : 'ingressTemplate'
+    form.hostTemplate = url?.source === 'ingressTemplate' ? url.hostTemplate : ''
+    form.ingressName = url?.source === 'ingressStatus' ? (url.ingressName ?? '') : ''
+    form.serviceName = url?.source === 'serviceStatus' ? url.serviceName : ''
+    form.servicePort = url?.source === 'serviceStatus' && url.port != null ? String(url.port) : ''
+    form.gatewayName = url?.source === 'gatewayStatus' ? (url.gatewayName ?? '') : ''
+    form.httpRouteName = url?.source === 'httpRouteStatus' ? (url.httpRouteName ?? '') : ''
+    form.urlScheme = url?.scheme ?? 'default'
   },
   { immediate: true },
 )
@@ -222,42 +235,81 @@ const connectBlockedReason = computed(() => {
   return t('settings.infrastructure.kubernetesEngine.invalidPort')
 })
 
-function buildUrl(): Record<string, unknown> {
-  const url: Record<string, unknown> = { source: form.urlSource }
-  if (form.urlSource === 'ingressTemplate') {
-    url.hostTemplate = form.hostTemplate.trim()
-  } else if (form.urlSource === 'ingressStatus') {
-    if (form.ingressName.trim()) url.ingressName = form.ingressName.trim()
-  } else if (form.urlSource === 'serviceStatus') {
-    url.serviceName = form.serviceName.trim()
-    const port = Number(form.servicePort)
-    if (form.servicePort.trim() && Number.isInteger(port)) url.port = port
-  } else if (form.urlSource === 'gatewayStatus') {
-    if (form.gatewayName.trim()) url.gatewayName = form.gatewayName.trim()
-  } else {
-    if (form.httpRouteName.trim()) url.httpRouteName = form.httpRouteName.trim()
+/**
+ * The URL-derivation block, built as the contract's discriminated union rather than a `Record`.
+ * Each branch returns its OWN variant, so the fields a source carries are checked against that
+ * source: setting `hostTemplate` on a `serviceStatus` url stops compiling instead of shipping a
+ * config the backend rejects. `urlScheme` is the one field every variant shares, and the
+ * 'default' sentinel means "omit it and let the derivation decide".
+ */
+function buildUrl(): KubeUrlSource {
+  const scheme = form.urlScheme === 'default' ? {} : { scheme: form.urlScheme }
+  switch (form.urlSource) {
+    case 'ingressTemplate':
+      return { source: 'ingressTemplate', hostTemplate: form.hostTemplate.trim(), ...scheme }
+    case 'ingressStatus': {
+      const ingressName = form.ingressName.trim()
+      return { source: 'ingressStatus', ...(ingressName ? { ingressName } : {}), ...scheme }
+    }
+    case 'serviceStatus': {
+      const port = Number(form.servicePort)
+      return {
+        source: 'serviceStatus',
+        serviceName: form.serviceName.trim(),
+        ...(form.servicePort.trim() && Number.isInteger(port) ? { port } : {}),
+        ...scheme,
+      }
+    }
+    case 'gatewayStatus': {
+      const gatewayName = form.gatewayName.trim()
+      return { source: 'gatewayStatus', ...(gatewayName ? { gatewayName } : {}), ...scheme }
+    }
+    case 'httpRouteStatus': {
+      const httpRouteName = form.httpRouteName.trim()
+      return { source: 'httpRouteStatus', ...(httpRouteName ? { httpRouteName } : {}), ...scheme }
+    }
+    default:
+      return refuseUnknownUrlSource(form.urlSource)
   }
-  if (form.urlScheme !== 'default') url.scheme = form.urlScheme
-  return url
+}
+
+/**
+ * A `source` outside the contract union, which the switch above therefore cannot build.
+ *
+ * The parameter is `never`, so this keeps BOTH properties at once: a source added to the contract
+ * without a case above still fails the typecheck (the argument stops being `never`), while a value
+ * the union never had is refused at runtime instead of falling off the end of the switch. That end
+ * is what the `default` exists to close: it returned `undefined`, which `buildPayload` then sent as
+ * the config's `url` for the backend to reject as a missing block.
+ *
+ * Deliberately NOT mapped onto a current source. Nothing here knows which one was meant, and a
+ * guess would silently rewrite the operator's URL derivation to something they never picked.
+ */
+function refuseUnknownUrlSource(source: never): never {
+  throw new Error(`Unsupported Kubernetes URL source '${String(source)}'`)
 }
 
 function buildPayload(): KubeHandlerPayload {
-  const kubernetes: Record<string, unknown> = {
+  // Built as the contract type rather than assembled into a `Record` and asserted: an optional
+  // field is a conditional SPREAD, so a key the config does not declare (or a value of the
+  // wrong type) fails the build here instead of surfacing as a server-side validation refusal.
+  const caCertPem = form.caCertPem.trim()
+  const namespaceTemplate = form.namespaceTemplate.trim()
+  const imageTemplate = form.imageTemplate.trim()
+  const kubernetes: KubeEngineConfig = {
     label: form.label.trim(),
     apiServerUrl: form.apiServerUrl.trim(),
     url: buildUrl(),
+    ...(caCertPem ? { caCertPem } : {}),
+    ...(form.insecureSkipTlsVerify ? { insecureSkipTlsVerify: true } : {}),
+    ...(namespaceTemplate ? { namespaceTemplate } : {}),
+    ...(imageTemplate ? { imageTemplate } : {}),
   }
-  if (form.caCertPem.trim()) kubernetes.caCertPem = form.caCertPem.trim()
-  if (form.insecureSkipTlsVerify) kubernetes.insecureSkipTlsVerify = true
-  if (form.namespaceTemplate.trim()) kubernetes.namespaceTemplate = form.namespaceTemplate.trim()
-  if (form.imageTemplate.trim()) kubernetes.imageTemplate = form.imageTemplate.trim()
-  // One honest assertion at the boundary that actually builds the shape (the reactive form is
-  // dynamically assembled, then validated server-side); the emitted config flows typed onward.
   // OMIT the token when the field is blank so the backend preserves the saved one (a blank
   // secret means "keep it") — only a typed value is sent, and it replaces the stored token.
   const token = apiToken.value.trim()
   return {
-    config: { engine: props.engine, kubernetes } as unknown as KubeHandlerConfig,
+    config: { engine: props.engine, kubernetes },
     secrets: token ? { [KUBERNETES_ENV_TOKEN_SECRET_KEY]: token } : {},
   }
 }

package/app/components/spec/ServiceSpecWindow.vue

@@ -21,6 +21,7 @@ import {
   summarizeSpecStates,
   type RequirementStateFilter,
 } from './ServiceSpecWindow.logic'
+import type { BadgeColor } from '~/utils/badge'
 
 const { t } = useI18n()
 const board = useBoardStore()
@@ -115,7 +116,7 @@ function retry() {
 
 // Exhaustive priority → label/chip map. Literal `t()` keys keep the typed-key drift
 // guard live, vs a runtime-built `spec.priority.${value}`.
-const PRIORITY_META: Record<RequirementPriority, { label: string; chip: string }> = {
+const PRIORITY_META: Record<RequirementPriority, { label: string; chip: BadgeColor }> = {
   must: { label: t('spec.priority.must'), chip: 'error' },
   should: { label: t('spec.priority.should'), chip: 'warning' },
   could: { label: t('spec.priority.could'), chip: 'neutral' },
@@ -131,7 +132,7 @@ const KIND_LABELS: Record<RequirementKind, string> = {
 // Exhaustive implementation-state → presentation map. `established` is the only state that
 // means "the service is observed to do this"; everything else is a behaviour that has been
 // agreed and not yet seen to hold, which must never read as standing behaviour.
-const STATE_META: Record<RequirementState, { label: string; chip: string; icon: string }> = {
+const STATE_META: Record<RequirementState, { label: string; chip: BadgeColor; icon: string }> = {
   established: {
     label: t('spec.state.established'),
     chip: 'success',
@@ -448,7 +449,7 @@ function kindLabel(item: RequirementItem): string {
                     <!-- implementation state: agreed vs observed to hold. The distinction the
                          build prompt and the tester act on, so a reader must see it too. -->
                     <UBadge
-                      :color="stateMeta(req).chip as any"
+                      :color="stateMeta(req).chip"
                       variant="subtle"
                       size="sm"
                       :icon="stateMeta(req).icon"
@@ -456,7 +457,7 @@ function kindLabel(item: RequirementItem): string {
                     >
                       {{ stateMeta(req).label }}
                     </UBadge>
-                    <UBadge :color="priorityMeta(req).chip as any" variant="subtle" size="sm">
+                    <UBadge :color="priorityMeta(req).chip" variant="subtle" size="sm">
                       {{ priorityMeta(req).label }}
                     </UBadge>
                     <UBadge color="neutral" variant="subtle" size="sm">{{ kindLabel(req) }}</UBadge>

package/app/composables/api/binaryCandidates.ts

@@ -0,0 +1,36 @@
+import {
+  getBinaryCandidatesContract,
+  keepBinaryCandidatesContract,
+  type KeepBinaryCandidatesInput,
+} from '@cat-factory/contracts'
+import type { ApiContext } from './context'
+
+/**
+ * Generated-candidate comparison. A binary-output step configured to COMPARE generates a
+ * candidate from each of its selected integrations, stages them through the step's storage
+ * service, and parks. These endpoints read the staged candidates and record which of them
+ * survive (and under which alternate ids); keeping re-runs the step to deliver exactly those.
+ * The read returns null when no step carries candidate state.
+ */
+export function binaryCandidatesApi({ send, ws }: ApiContext) {
+  return {
+    // The live candidate state for a run (null when no step carries one).
+    getBinaryCandidates: (workspaceId: string, executionId: string) =>
+      send(getBinaryCandidatesContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+      }),
+
+    // Keep the chosen candidates and discard the rest.
+    keepBinaryCandidates: (
+      workspaceId: string,
+      executionId: string,
+      body: KeepBinaryCandidatesInput,
+    ) =>
+      send(keepBinaryCandidatesContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+        body,
+      }),
+  }
+}

package/app/composables/useApi.ts

@@ -13,6 +13,7 @@ import { boardApi } from './api/board'
 import { documentsApi } from './api/documents'
 import { executionApi } from './api/execution'
 import { followUpsApi } from './api/followUps'
+import { binaryCandidatesApi } from './api/binaryCandidates'
 import { forkDecisionApi } from './api/forkDecision'
 import { inputGateApi } from './api/inputGate'
 import { judgeApi } from './api/judge'
@@ -131,6 +132,7 @@ export function useApi() {
     ...bugHuntApi(ctx),
     ...reviewsApi(ctx),
     ...followUpsApi(ctx),
+    ...binaryCandidatesApi(ctx),
     ...forkDecisionApi(ctx),
     ...inputGateApi(ctx),
     ...judgeApi(ctx),

package/app/docs/architecture.md

@@ -3,7 +3,7 @@
 How the SPA stays in sync with the backend. The app is a **thin client**: it holds
 no business logic, calls the Worker for every mutation, and hydrates its stores
 from server snapshots plus pushed events. For the high-level tour see
-[`../README.md`](../README.md).
+[`frontend/app/README.md`](../../README.md).
 
 ## The three paths
 

package/app/modular/panels/inspector.ts

@@ -4,8 +4,8 @@ import type { PanelEntry } from '@modular-vue/core'
 import type { Block } from '~/types/domain'
 
 /** The engine's opaque component type on a `PanelEntry` (the neutral `UiComponent`,
- *  which isn't exported by name). A Vue component is a valid one; the outlet renders
- *  it as a Vue component. We reference it structurally so no cast reaches for `any`. */
+ *  which isn't exported by name). Referenced structurally off `PanelEntry` so a
+ *  `defineComponent` result is checked against it rather than asserted into it. */
 type PanelComponent = PanelEntry<Block>['component']
 import {
   INSPECTOR_PANELS_SLOT,
@@ -61,7 +61,7 @@ function blockPanel(component: Component, id: InspectorPanelId): PanelComponent
       const block = usePanelSubject<Block>()
       return () => h(component, { block: block.value })
     },
-  }) as unknown as PanelComponent
+  })
 }
 
 /** Exhaustive id → sub-panel map. Typed `Record<InspectorPanelId, …>` so adding a

package/app/modular/result-views.ts

@@ -13,6 +13,7 @@ import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindo
 import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
 import ServiceSpecWindow from '~/components/spec/ServiceSpecWindow.vue'
 import FollowUpWindow from '~/components/followUp/FollowUpWindow.vue'
+import BinaryCandidatesWindow from '~/components/binaryCandidates/BinaryCandidatesWindow.vue'
 import ForkDecisionWindow from '~/components/forkDecision/ForkDecisionWindow.vue'
 import PrReviewWindow from '~/components/prReview/PrReviewWindow.vue'
 import MergerResultView from '~/components/panels/MergerResultView.vue'
@@ -77,6 +78,9 @@ const BUILT_IN_RESULT_VIEWS: Record<ResultViewId, Component> = {
   'follow-ups': FollowUpWindow,
   // The implementation-fork decision: the proposer's approaches + the human's pick / custom.
   'fork-decision': ForkDecisionWindow,
+  // The generated-candidate comparison: the candidates a generating step staged, side by side,
+  // and the human's keep/discard decision (with the alternate ids they assigned).
+  'binary-candidates': BinaryCandidatesWindow,
   // The PR deep-review: the reviewer's sliced, prioritized findings + the human's multi-select.
   'pr-review': PrReviewWindow,
   // The merger's verdict: PR complexity/risk/impact scores + the engine's decision (and why).

package/app/stores/binaryCandidates.ts

@@ -0,0 +1,89 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { KeepBinaryCandidatesInput } from '@cat-factory/contracts'
+import type { BinaryCandidateStepState } from '~/types/execution'
+import { useApi } from '~/composables/useApi'
+import { useWorkspaceStore } from '~/stores/workspace'
+import { useExecutionStore } from '~/stores/execution'
+
+/**
+ * The generated-candidate action surface. The live state lives on the run's step
+ * (`step.binaryCandidates`) and the execution stream keeps it fresh, so the window reads it
+ * straight off the execution store; this store only wraps the `keep` action (plus a warm-up
+ * `load`), tracks the in-flight state so the window can disable its controls, and echoes the
+ * returned state back so the UI settles without waiting for the stream. Shaped exactly like the
+ * fork-decision store, which is the same park one subject over.
+ */
+export const useBinaryCandidatesStore = defineStore('binaryCandidates', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  /** True while a keep call is in flight (drives the button spinner / disabled state). */
+  const keeping = ref(false)
+  /** The last error message from an action, surfaced inline; cleared on the next action. */
+  const error = ref<string | null>(null)
+
+  /**
+   * Apply an authoritative candidate state to the run's step.
+   *
+   * A pipeline may carry more than one generating step, so target the step this decision is
+   * ABOUT rather than the first that happens to hold candidate state: prefer the one still
+   * awaiting a choice, then the current step, and only then any step carrying state. Without
+   * that order a run whose earlier generator already settled would have its finished record
+   * overwritten by the live one.
+   *
+   * Only ever called through {@link ExecutionStore.echoAfter}, which drops the echo when the
+   * event stream already delivered a newer revision.
+   */
+  function assign(
+    instance: ReturnType<typeof execution.getInstance> & object,
+    state: BinaryCandidateStepState,
+  ): void {
+    const current = instance.steps[instance.currentStep]
+    const step =
+      instance.steps.find((s) => s.binaryCandidates?.status === 'awaiting_choice') ??
+      (current?.binaryCandidates ? current : undefined) ??
+      instance.steps.find((s) => s.binaryCandidates)
+    if (step) step.binaryCandidates = state
+  }
+
+  /** Warm the live state from the GET (the stream also keeps it fresh). Best-effort. */
+  async function load(executionId: string): Promise<void> {
+    error.value = null
+    try {
+      await execution.echoAfter(
+        executionId,
+        () => api.getBinaryCandidates(workspace.requireId(), executionId),
+        (state, instance) => {
+          if (state) assign(instance, state as BinaryCandidateStepState)
+        },
+      )
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to load'
+    }
+  }
+
+  /**
+   * Keep the chosen candidates (each with the id it is to be stored under) and discard the rest.
+   * The step then re-runs to deliver exactly what survived.
+   */
+  async function keep(executionId: string, input: KeepBinaryCandidatesInput): Promise<void> {
+    error.value = null
+    keeping.value = true
+    try {
+      await execution.echoAfter(
+        executionId,
+        () => api.keepBinaryCandidates(workspace.requireId(), executionId, input),
+        (state, instance) => assign(instance, state as BinaryCandidateStepState),
+      )
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to keep candidates'
+      throw e
+    } finally {
+      keeping.value = false
+    }
+  }
+
+  return { keeping, error, load, keep }
+})

package/app/stores/board/placement.ts

@@ -3,9 +3,29 @@ import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { createBoardDependencies } from './dependencies'
 import { moveRefusalKey } from './moveRefusal'
+import type { Block } from '~/types/domain'
 import type { BoardWriteContext } from './context'
 import { UNDO_WINDOW_MS } from './context'
 
+/** A field `updateBlock` may patch: the contract's key set, nothing wider. */
+type PatchKey = keyof UpdateBlockInput
+/** The pre-patch values of the fields one call touches, for the rollback. */
+type PatchSnapshot = Partial<Record<PatchKey, unknown>>
+
+/**
+ * View a block through the patch key set, for the optimistic write's snapshot + rollback.
+ *
+ * A plain widening, not an assertion: the rollback is inherently keyed by whatever the caller
+ * put in the patch, so it has to index the block dynamically, and this bounds that indexing to
+ * the contract instead of the `Record<string, unknown>` it used to widen to. Two patch keys
+ * (`customTaskTypeFields` / `builtinTaskTypeFields`) are request-only, since the server folds
+ * them into the block's `taskTypeFields`, so the view is `Partial`: they read as absent going in
+ * and are cleared again by a rollback, which is what the untyped version did.
+ */
+function blockAsPatchable(block: Block): PatchSnapshot {
+  return block
+}
+
 /**
  * The board's placement (drag/drop/reparent) and per-block edit operations — the writes that
  * move a block or patch its fields, including the dependency edges. Extracted from
@@ -194,10 +214,13 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     // Snapshot ONLY the fields this patch touches so a rejected write restores them exactly
     // (a patch may set several at once) rather than leaving a stale optimistic value stuck on
     // screen with no feedback — the same rollback contract the other mutations here follow.
-    const prev: Record<string, unknown> = {}
-    const patchRecord = patch as Record<string, unknown>
-    const record = b as unknown as Record<string, unknown>
-    for (const key of Object.keys(patch)) prev[key] = record[key]
+    // `Object.keys` is typed `string[]`, so the key set is narrowed to the patch contract once
+    // here; every read and write below then goes through `PatchKey`, and a key outside the
+    // contract cannot reach the block.
+    const keys = Object.keys(patch) as PatchKey[]
+    const prev: PatchSnapshot = {}
+    const before = blockAsPatchable(b)
+    for (const key of keys) prev[key] = before[key]
     Object.assign(b, patch) // optimistic
     try {
       upsert(await api.updateBlock(useWorkspaceStore().requireId(), id, patch))
@@ -206,10 +229,11 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
       // swaps in a fresh one) while the write was in flight, so `b` can be stale. Only revert
       // fields that still hold OUR optimistic value, so a newer server value that landed
       // mid-flight isn't clobbered by the rollback.
-      const cur = getBlock(id) as unknown as Record<string, unknown> | undefined
-      if (cur) {
-        for (const key of Object.keys(patch)) {
-          if (cur[key] === patchRecord[key]) cur[key] = prev[key]
+      const live = getBlock(id)
+      if (live) {
+        const cur = blockAsPatchable(live)
+        for (const key of keys) {
+          if (cur[key] === patch[key]) cur[key] = prev[key]
         }
       }
       toast.add({

package/app/stores/ui/resultViews.ts

@@ -164,12 +164,13 @@ export function createUiResultViews() {
   // The run-scoped openers (a caller that knows only the RUN, so the step index has to be
   // resolved) live in a sibling module: they share one shape and one hazard, and lifting them out
   // keeps this factory inside its per-function line budget. Their two seams are bound here.
-  const { openFollowUps, openForkDecision, openPrReview, openTestEvidence } = createRunStepOpeners({
-    dispatchStepView: (instanceId, stepIndex) => dispatchStepView(instanceId, stepIndex),
-    setResultView: (view, instance, stepIndex) => {
-      resultView.value = { view, blockId: instance.blockId, instanceId: instance.id, stepIndex }
-    },
-  })
+  const { openFollowUps, openForkDecision, openBinaryCandidates, openPrReview, openTestEvidence } =
+    createRunStepOpeners({
+      dispatchStepView: (instanceId, stepIndex) => dispatchStepView(instanceId, stepIndex),
+      setResultView: (view, instance, stepIndex) => {
+        resultView.value = { view, blockId: instance.blockId, instanceId: instance.id, stepIndex }
+      },
+    })
 
   function closeResultView() {
     resultView.value = null
@@ -209,6 +210,7 @@ export function createUiResultViews() {
     openInitiativePlanning,
     openFollowUps,
     openForkDecision,
+    openBinaryCandidates,
     openPrReview,
     openTestEvidence,
     openOutcome,

package/app/stores/ui/runStepOpeners.ts

@@ -93,6 +93,28 @@ export function createRunStepOpeners(deps: RunStepOpenerDeps) {
     )
   }
 
+  // Open the generated-candidate comparison window for a run's binary-output step (from the
+  // pipeline chip / inspector rail / step overlay). Resolves the step index from the run when not
+  // given, preferring the step parked awaiting a choice.
+  //
+  // Resolved by the CANDIDATE STATE rather than by an agent kind, unlike its neighbours: any kind
+  // carrying the `binary-output` trait can run a comparison, and a deployment's own kinds are
+  // exactly the ones a hard-coded kind list here would never name.
+  function openBinaryCandidates(instanceId: string, stepIndex: number | null = null) {
+    withStep(
+      instanceId,
+      stepIndex,
+      (instance) => {
+        const awaiting = indexOf(instance, (s) => s.binaryCandidates?.status === 'awaiting_choice')
+        if (awaiting >= 0) return awaiting
+        const current = instance.steps[instance.currentStep]
+        if (current?.binaryCandidates) return instance.currentStep
+        return indexOf(instance, (s) => !!s.binaryCandidates)
+      },
+      (instance, idx) => deps.setResultView('binary-candidates', instance, idx),
+    )
+  }
+
   // Open the PR deep-review window for a run's `pr-reviewer` step (from the `pr_review_ready`
   // notification / the step). Resolves the step index from the run when not given, preferring
   // the step parked awaiting a finding selection.
@@ -139,5 +161,5 @@ export function createRunStepOpeners(deps: RunStepOpenerDeps) {
     )
   }
 
-  return { openFollowUps, openForkDecision, openPrReview, openTestEvidence }
+  return { openFollowUps, openForkDecision, openBinaryCandidates, openPrReview, openTestEvidence }
 }

package/app/types/execution.ts

@@ -95,6 +95,11 @@ export type {
   BinaryOutputArtifact,
   BinaryOutputConfig,
   BinaryOutputReport,
+  // The candidate-comparison set on a step whose selection declares a `comparison`: the staged
+  // candidates, the live park state, and the human's keep/discard decision.
+  BinaryCandidate,
+  BinaryCandidateChoice,
+  BinaryCandidateStepState,
   TesterStepState,
   HumanTestEnvironment,
   RunEnvironment,

package/app/utils/badge.ts

@@ -0,0 +1,14 @@
+import type { BadgeProps } from '@nuxt/ui'
+
+/**
+ * The colour names a `UBadge` accepts, derived from the component's own prop type rather
+ * than restated as a literal union. Nuxt UI resolves the prop from the app config's badge
+ * theme, so deriving keeps a chip map honest if the deployment's palette gains or loses a
+ * colour, where a hand-written copy would just drift.
+ *
+ * A status → chip map types its values against this, which is what lets a `:color="…"`
+ * binding pass the value straight through. The maps used to be typed `string`, so every
+ * binding needed an `as any` to get past the prop's union; that cast also silently accepted
+ * a typo'd colour, which renders as an unstyled badge rather than failing the build.
+ */
+export type BadgeColor = NonNullable<BadgeProps['color']>