@cat-factory/app 0.241.2 → 0.242.0

package/app/components/outcome/OutcomeSummaryWindow.vue

@@ -12,8 +12,8 @@
 // It composes NOTHING itself: `composeRunOutcome` (`~/utils/runOutcome`) is the pure reduction,
 // so the rules that matter (a regression is an `established` requirement observed to fail; an
 // absent producer never renders as a clean result) are unit-tested without mounting this. What
-// lives here is presentation only, plus the ONE fetch the card owns: the enclosing service's
-// spec, which turns the tester's requirement IDS into the requirement TITLES a reader came for.
+// lives here is presentation only, plus the ONE fetch the card owns: the spec THIS RUN was
+// judged against, which turns the tester's requirement IDS into the TITLES a reader came for.
 import { computed, onUnmounted, ref, watch } from 'vue'
 import type {
   OutcomeCheckKind,
@@ -47,32 +47,43 @@ const { t } = useI18n()
 const blobs = useArtifactBlobs()
 onUnmounted(() => blobs.revokeAll())
 
-// The shared seam contract. The `onOpen` loader fetches the ENCLOSING SERVICE's spec: the
-// requirement verdicts are keyed by the spec's own ids, and without it the coverage section can
-// only show ids (which it then says, rather than letting an id read as a title).
-const { open, blockId, instanceId, close } = useResultView('outcome', {
-  onOpen: (view) => {
-    const block = board.getBlock(view.blockId)
-    const service = block ? board.serviceOf(block) : undefined
-    if (service) void serviceSpec.load(service.id)
-  },
-})
+// The shared seam contract.
+const { open, blockId, instanceId, close } = useResultView('outcome')
 
 const block = computed(() => (blockId.value ? board.getBlock(blockId.value) : undefined))
-const service = computed(() => (block.value ? board.serviceOf(block.value) : undefined))
-const instance = computed(() => {
+const runId = computed(() => {
   // The run carried by the opener, else the block's own live run: a card opened from a
   // notification names the run, one opened from the board does not.
-  const id = instanceId.value ?? block.value?.executionId ?? null
-  return id ? (execution.getInstance(id) ?? null) : null
+  return instanceId.value ?? block.value?.executionId ?? null
 })
+const instance = computed(() => (runId.value ? (execution.getInstance(runId.value) ?? null) : null))
+
+// The ONE fetch this card owns: the spec THIS RUN was judged against. Requirement verdicts are
+// keyed by the spec's own ids, and without the spec the coverage section can only show ids
+// (which it then says, rather than letting an id read as a title).
+//
+// Keyed by the RUN, not by the enclosing service, and that is a correctness matter rather than a
+// cache detail: the service read comes from the repo's default branch, so for as long as the
+// run's pull request is open it is missing exactly the requirements the run added and the tester
+// just ruled on. Every one of those verdicts joined against nothing and rendered as "not
+// checked", and the card's counts contradicted `GET /api/v1/runs/:runId/outcome` for one run.
+//
+// A watch rather than the `onOpen` hook, because the run id can arrive after the block does (a
+// card open on a task that starts a run) and the join must follow it.
+watch(
+  runId,
+  (id) => {
+    if (id) void serviceSpec.loadForRun(id)
+  },
+  { immediate: true },
+)
 
 const outcome = computed(() =>
   block.value
     ? composeRunOutcome({
         block: block.value,
         instance: instance.value,
-        spec: service.value ? serviceSpec.viewFor(service.value.id) : null,
+        spec: runId.value ? serviceSpec.viewForRun(runId.value) : null,
       })
     : null,
 )
@@ -110,6 +121,7 @@ const REQUIREMENTS_GAP_KEYS: Record<RequirementsGap, string> = {
   no_tester_step: 'outcome.requirements.gap.no_tester_step',
   tester_not_reported: 'outcome.requirements.gap.tester_not_reported',
   no_verdicts: 'outcome.requirements.gap.no_verdicts',
+  no_requirements: 'outcome.requirements.gap.no_requirements',
 }
 const TESTS_GAP_KEYS: Record<TestsGap, string> = {
   run_unavailable: RUN_UNAVAILABLE_KEY,
@@ -128,7 +140,6 @@ const VISUALS_GAP_KEYS: Record<VisualsGap, string> = {
  */
 const SPEC_JOIN_KEYS: Record<Exclude<OutcomeSpecJoin, 'joined'>, string> = {
   not_read: 'outcome.requirements.spec.not_read',
-  unmatched: 'outcome.requirements.spec.unmatched',
 }
 
 const VERDICT_META: Record<RequirementVerdictStatus, { color: string; key: string }> = {
@@ -186,9 +197,11 @@ const headerTitle = computed(() => outcome.value?.title ?? t('outcome.title'))
 const disposition = computed(() => outcome.value?.disposition ?? 'not_run')
 
 /**
- * The note under the requirement counts when the rows carry no spec titles, null when they do.
- * Resolved here so the `joined` exclusion is checked by the compiler once, rather than by a
- * template condition that would silently render nothing if the union grew.
+ * The note under the requirement counts when the section was NOT counted against the service's
+ * `spec/`, null when it was. It is a statement about the DENOMINATOR, not about missing titles:
+ * an unjoined section counts only what the tester chose to rule on and says nothing about what it
+ * skipped. Resolved here so the `joined` exclusion is checked by the compiler once, rather than by
+ * a template condition that would silently render nothing if the union grew.
  */
 const specNote = computed(() => {
   const requirements = outcome.value?.requirements
@@ -198,19 +211,22 @@ const specNote = computed(() => {
   return t(SPEC_JOIN_KEYS[requirements.spec])
 })
 
+/** The requirement rows, in the composer's severity-first order. */
+const requirementRows = computed(() => {
+  const requirements = outcome.value?.requirements
+  return requirements?.status === 'reported' ? requirements.entries : []
+})
+
 /**
- * The requirement rows, each carrying whether its id is standing in for a title it has no way
- * to show. Marked per row ONLY where the section as a whole joined: an id sitting unmarked
- * between two named requirements reads as a requirement someone named after a slug, while a
- * marker on every row of a section the note above already explains is just noise.
+ * How many verdicts the tester returned against ids this service's `spec/` does not carry, or 0.
+ *
+ * Surfaced because the counts above are the SPEC's and this number is the difference between them
+ * and the tester's own tally. Unstated, a reader comparing the two reads the gap as one of the two
+ * being wrong, when it is really a spec that moved on under the tester.
  */
-const requirementRows = computed(() => {
+const unmatchedVerdicts = computed(() => {
   const requirements = outcome.value?.requirements
-  if (!requirements || requirements.status !== 'reported') return []
-  return requirements.entries.map((entry) => ({
-    ...entry,
-    idOnly: requirements.spec === 'joined' && entry.title === null,
-  }))
+  return requirements?.status === 'reported' ? requirements.unmatchedVerdicts : 0
 })
 
 /** The captured views, resolved to blobs as they arrive (the card shows them inline). */
@@ -373,8 +389,8 @@ function openTestReport() {
               }}
             </UBadge>
           </div>
-          <!-- The ids are all there is: say WHICH reason, rather than letting a slug read as
-               the name of a requirement (never read, versus read and naming none of these). -->
+          <!-- The coverage was not counted against the spec, so say what the numbers above do
+               and do not cover rather than letting them read as the whole picture. -->
           <p
             v-if="specNote"
             class="mb-2 text-[11px] leading-relaxed text-amber-300/90"
@@ -382,6 +398,16 @@ function openTestReport() {
           >
             {{ specNote }}
           </p>
+          <!-- The tester ruled on ids the spec does not carry, so its own tally and the counts
+               above legitimately differ. Said out loud, because the alternative is a reader
+               deciding which of the two numbers to distrust. -->
+          <p
+            v-if="unmatchedVerdicts > 0"
+            class="mb-2 text-[11px] leading-relaxed text-amber-300/90"
+            data-testid="outcome-unmatched-verdicts"
+          >
+            {{ t('outcome.requirements.unmatchedVerdicts', { count: unmatchedVerdicts }) }}
+          </p>
           <ul class="space-y-1.5">
             <li
               v-for="req in requirementRows"
@@ -396,18 +422,6 @@ function openTestReport() {
               <div class="min-w-0">
                 <div class="flex flex-wrap items-center gap-1.5">
                   <span class="text-[13px] text-slate-200">{{ req.title ?? req.id }}</span>
-                  <!-- This row's id is standing in for a title the spec does not have for it,
-                       beside rows that DO carry one. -->
-                  <UBadge
-                    v-if="req.idOnly"
-                    color="neutral"
-                    variant="subtle"
-                    size="sm"
-                    :title="t('outcome.requirements.idOnlyHint')"
-                    data-testid="outcome-requirement-id-only"
-                  >
-                    {{ t('outcome.requirements.idOnly') }}
-                  </UBadge>
                   <UBadge
                     v-if="req.regression"
                     color="error"

package/app/composables/api/spec.ts

@@ -1,14 +1,24 @@
-import { getServiceSpecContract } from '@cat-factory/contracts'
+import { getRunSpecContract, getServiceSpecContract } from '@cat-factory/contracts'
 import type { ApiContext } from './context'
 
 /**
- * The service-spec read (the inspector's "View Requirements" window). Reassembles the
- * sharded `spec/` artifact from the service repo's default branch. Always 200: a service
- * with no spec on main (or no GitHub connected) returns `{ present: false }`.
+ * The two spec reads, which answer different questions and are paired here so a caller has to
+ * pick one deliberately.
+ *
+ * `getServiceSpec` reassembles the sharded `spec/` artifact from the service repo's DEFAULT
+ * branch: what the service requires today, for the inspector's "View Requirements" window.
+ * `getRunSpec` reads it from the branch ONE RUN pushed to: what that run's tester actually ruled
+ * against, for the outcome card's requirement join. While a pull request is open the two are
+ * different trees, and joining a run's verdicts against the first shows every requirement the
+ * run itself added as "not checked".
+ *
+ * Both are always 200: no spec, no repo or no VCS connected returns `{ present: false }`.
  */
 export function specApi({ send, ws }: ApiContext) {
   return {
     getServiceSpec: (workspaceId: string, blockId: string) =>
       send(getServiceSpecContract, { pathPrefix: ws(workspaceId), pathParams: { blockId } }),
+    getRunSpec: (workspaceId: string, executionId: string) =>
+      send(getRunSpecContract, { pathPrefix: ws(workspaceId), pathParams: { executionId } }),
   }
 }

package/app/docs/consumer-extensions.md

@@ -229,6 +229,14 @@ Both links are absolute on purpose: this page ships inside the `@cat-factory/app
 relative path out of it resolves only from a checkout, which is the one place its reader is not.
 (`scripts/check-shipped-doc-links.mjs` fails CI on a shipped doc that grows one.)
 
+The BACKEND half of an operation is registered with one dependency: the runtime facade you boot
+through (`@cat-factory/node-server`, `@cat-factory/local-server` or `@cat-factory/worker`) exports
+every registry constructor and every type a registration literal names. Do not reach below it for
+`@cat-factory/kernel`, `@cat-factory/contracts` or `@cat-factory/prompt-fragments`: those publish at
+EXACT versions, so floating one past what your facade pins resolves a second physical copy and your
+registrations land where nothing reads them
+([ADR 0044](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/adr/0044-facade-extension-surface.md)).
+
 The **same type can be delivered from the backend** instead of code-shipped: register it on the
 deployment's app-owned `TaskTypeRegistry` and it arrives in the workspace snapshot's
 `customTaskTypes`, folded into the SAME merged catalog (data over the wire, never components). The

package/app/stores/serviceSpec.spec.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useServiceSpecStore } from '~/stores/serviceSpec'
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { ServiceSpecView } from '~/types/spec'
+
+// The store holds TWO spec reads, and which one a caller takes is a correctness matter rather
+// than a caching detail. The service read is the repo's DEFAULT branch ("what does this service
+// require", the inspector's requirements window); the run read is the branch ONE RUN pushed to
+// ("what did this run rule on", the outcome card's requirement join). While a pull request is
+// open they are different trees, and the card joining against the first showed every requirement
+// the run itself added as "not checked" while `/api/v1/runs/:runId/outcome` said otherwise.
+//
+// So what is pinned here is that the two never answer for each other: one key space cannot serve
+// the other's question even when a block id and an execution id happen to collide.
+
+function view(service: string): ServiceSpecView {
+  return {
+    present: true,
+    spec: { service, summary: '', modules: [] },
+    features: [],
+  } as unknown as ServiceSpecView
+}
+
+function stubApi(over: Record<string, unknown> = {}) {
+  vi.stubGlobal('useApi', () => ({
+    getServiceSpec: () => Promise.resolve(view('from-default-branch')),
+    getRunSpec: () => Promise.resolve(view('from-run-branch')),
+    ...over,
+  }))
+}
+
+beforeEach(() => {
+  useWorkspaceStore().workspaceId = 'ws1'
+  stubApi()
+})
+
+describe('serviceSpec store', () => {
+  it('reads a run’s spec from the run endpoint, not the service one', async () => {
+    const store = useServiceSpecStore()
+    await store.loadForRun('exec_1')
+    expect(store.viewForRun('exec_1')?.spec?.service).toBe('from-run-branch')
+  })
+
+  it('keeps the two reads in separate key spaces', async () => {
+    // Same id, two questions. Without the prefixes one load would satisfy the other's accessor
+    // and the card would silently join against the default branch again.
+    const store = useServiceSpecStore()
+    await store.load('id_1')
+    await store.loadForRun('id_1')
+    expect(store.viewFor('id_1')?.spec?.service).toBe('from-default-branch')
+    expect(store.viewForRun('id_1')?.spec?.service).toBe('from-run-branch')
+  })
+
+  it('does not answer a run read out of the service cache', async () => {
+    const store = useServiceSpecStore()
+    await store.load('id_1')
+    expect(store.viewForRun('id_1')).toBeUndefined()
+  })
+
+  it('coalesces overlapping loads of one run onto a single request', async () => {
+    let calls = 0
+    stubApi({
+      getRunSpec: () => {
+        calls += 1
+        return Promise.resolve(view('from-run-branch'))
+      },
+    })
+    const store = useServiceSpecStore()
+    await Promise.all([store.loadForRun('exec_1'), store.loadForRun('exec_1')])
+    expect(calls).toBe(1)
+  })
+
+  it('records a failed run read without poisoning the cached view', async () => {
+    stubApi({ getRunSpec: () => Promise.reject(new Error('offline')) })
+    const store = useServiceSpecStore()
+    await store.loadForRun('exec_1')
+    // The card composes `spec: 'not_read'` off an absent view and says so; a fabricated empty
+    // view would have read as a service that declares nothing.
+    expect(store.viewForRun('exec_1')).toBeUndefined()
+  })
+})

package/app/stores/serviceSpec.ts

@@ -4,69 +4,99 @@ import type { ServiceSpecView } from '~/types/spec'
 import { useWorkspaceStore } from '~/stores/workspace'
 
 /**
- * Service-spec read state for the inspector's "View Requirements" window. The spec lives
- * sharded in the service repo under `spec/`; the backend reassembles it from the repo's
- * default branch and serves a {@link ServiceSpecView}. Read-only and fetched on demand
- * (per service frame block), cached per block. Nothing is persisted client-side.
+ * Service-spec read state. The spec lives sharded in the service repo under `spec/`; the backend
+ * reassembles it and serves a {@link ServiceSpecView}. Read-only, fetched on demand, cached.
+ * Nothing is persisted client-side.
+ *
+ * TWO reads, because there are two questions and they have different answers while a pull
+ * request is open:
+ *
+ *  - {@link load} / {@link viewFor}: what the SERVICE requires, from the repo's default branch,
+ *    for the inspector's "View Requirements" window.
+ *  - {@link loadForRun} / {@link viewForRun}: what ONE RUN was judged against, from the branch
+ *    that run pushed to, for the outcome card's requirement join. The card used to read the
+ *    first, so every verdict naming a requirement the run itself added joined against a spec
+ *    that does not carry it yet and rendered as "not checked" — and the card's counts then
+ *    disagreed with `GET /api/v1/runs/:runId/outcome`, which reads the run's branch.
+ *
+ * One cache, two key spaces: the entries are keyed by a PREFIXED id so a block id and an
+ * execution id can never collide, and every accessor mints its key through the same helper.
  */
 export const useServiceSpecStore = defineStore('serviceSpec', () => {
   const api = useApi()
   const workspace = useWorkspaceStore()
 
-  /** The fetched view per block id (undefined = not yet fetched). */
+  const serviceKey = (blockId: string) => `service:${blockId}`
+  const runKey = (executionId: string) => `run:${executionId}`
+
+  /** The fetched view per cache key (undefined = not yet fetched). */
   const views = ref<Record<string, ServiceSpecView>>({})
   /**
-   * In-flight loads keyed by block id — the SINGLE source of truth for "is this block
-   * loading". A reactive Map so `isLoading` (derived from `.has`) tracks set/delete, and it
-   * also coalesces overlapping loads onto one request: no separate loading-flag Set to keep
-   * in sync.
+   * In-flight loads keyed by cache key — the SINGLE source of truth for "is this loading". A
+   * reactive Map so `isLoading` (derived from `.has`) tracks set/delete, and it also coalesces
+   * overlapping loads onto one request: no separate loading-flag Set to keep in sync.
    */
   const inFlight = reactive(new Map<string, Promise<void>>())
-  /** Block ids whose last fetch failed (network / unexpected error). */
-  const erroredByBlock = ref<Set<string>>(new Set())
+  /** Cache keys whose last fetch failed (network / unexpected error). */
+  const erroredByKey = ref<Set<string>>(new Set())
 
   function viewFor(blockId: string): ServiceSpecView | undefined {
-    return views.value[blockId]
+    return views.value[serviceKey(blockId)]
+  }
+  function viewForRun(executionId: string): ServiceSpecView | undefined {
+    return views.value[runKey(executionId)]
   }
   function isLoading(blockId: string): boolean {
-    return inFlight.has(blockId)
+    return inFlight.has(serviceKey(blockId))
   }
   function isErrored(blockId: string): boolean {
-    return erroredByBlock.value.has(blockId)
+    return erroredByKey.value.has(serviceKey(blockId))
   }
 
   function setErrored(key: string, on: boolean) {
-    const next = new Set(erroredByBlock.value)
+    const next = new Set(erroredByKey.value)
     if (on) next.add(key)
     else next.delete(key)
-    erroredByBlock.value = next
+    erroredByKey.value = next
   }
 
-  /** Fetch (and cache) the spec view for a service frame block. */
-  async function load(blockId: string) {
+  /** Fetch (and cache) one view, coalescing concurrent loads of the same key. */
+  function loadKeyed(key: string, fetch: (workspaceId: string) => Promise<ServiceSpecView>) {
     if (!workspace.workspaceId) return
-    const pending = inFlight.get(blockId)
+    const pending = inFlight.get(key)
     if (pending) return pending
-    setErrored(blockId, false)
+    setErrored(key, false)
     const promise = (async () => {
       try {
-        const view = await api.getServiceSpec(workspace.requireId(), blockId)
-        views.value = { ...views.value, [blockId]: view }
+        const view = await fetch(workspace.requireId())
+        views.value = { ...views.value, [key]: view }
       } catch {
-        setErrored(blockId, true)
+        setErrored(key, true)
       } finally {
-        inFlight.delete(blockId)
+        inFlight.delete(key)
       }
     })()
-    inFlight.set(blockId, promise)
+    inFlight.set(key, promise)
     return promise
   }
 
+  /** Fetch the DEFAULT-branch spec view for a service frame block. */
+  async function load(blockId: string) {
+    return loadKeyed(serviceKey(blockId), (workspaceId) => api.getServiceSpec(workspaceId, blockId))
+  }
+
+  /** Fetch the spec view ONE RUN was judged against, from that run's own branch. */
+  async function loadForRun(executionId: string) {
+    return loadKeyed(runKey(executionId), (workspaceId) => api.getRunSpec(workspaceId, executionId))
+  }
+
   return {
     views,
     viewFor,
+    viewForRun,
     isLoading,
     isErrored,
     load,
+    loadForRun,
   }
 })

package/app/utils/catalog.ts

@@ -523,13 +523,14 @@ export function isConsensusEligibleKind(kind: string): boolean {
 }
 
 /**
- * Whether an agent kind is one of the Tester gate kinds (API or UI). Mirrors the backend
- * `isTesterKind`; used by the pipeline builder to surface the test quality-control companion
- * toggle only on Tester steps.
+ * Whether an agent kind is one of the Tester gate kinds (API or UI). Used by the pipeline builder
+ * to surface the test quality-control companion toggle only on Tester steps.
+ *
+ * Re-exported from `@cat-factory/contracts` rather than mirrored: it used to be a hand-written
+ * copy of the engine's rule with the two slugs spelled out as literals, which is the shape that
+ * silently stops matching the day a third tester kind ships.
  */
-export function isTesterKind(kind: string): boolean {
-  return kind === 'tester-api' || kind === 'tester-ui'
-}
+export { isTesterKind } from '@cat-factory/contracts'
 
 /**
  * Display metadata for the engine-driven "system" kinds — the gate/automation