@cat-factory/app 0.256.3 → 0.258.0

package/app/utils/agentPalette.ts

@@ -44,14 +44,19 @@ export interface NarrowedAgentPalette<T> {
  * nothing behaves, and none of them is a reason to drop it from the catalog.
  */
 export function narrowAgentPalette<
-  T extends Pick<AgentArchetype, 'tier' | 'category' | 'purposes'>,
+  T extends Pick<AgentArchetype, 'tier' | 'category' | 'purposes' | 'internal'>,
 >(archetypes: readonly T[], purpose: PipelinePurpose, tier: AgentTier): NarrowedAgentPalette<T> {
+  // INTERNAL kinds are removed BEFORE either dial, and are counted by neither. They are not
+  // hidden, they are not placeable at all: the platform dispatches them for a flow of its own
+  // (the environment analyst hands its draft to the setup wizard), so counting one as
+  // "3 more at the widest tier" would send a reader to a dial that will never reveal it.
+  const placeable = archetypes.filter((a) => !a.internal)
   const relevant = (a: T) => purposeSuggestsAgentKind(purpose, a)
   const inTier = (a: T) => agentTierVisibleAt(a.tier, tier)
   return {
-    offered: archetypes.filter((a) => relevant(a) && inTier(a)),
-    hiddenByPurpose: archetypes.filter((a) => inTier(a) && !relevant(a)).length,
-    hiddenByTier: archetypes.filter((a) => relevant(a) && !inTier(a)).length,
+    offered: placeable.filter((a) => relevant(a) && inTier(a)),
+    hiddenByPurpose: placeable.filter((a) => inTier(a) && !relevant(a)).length,
+    hiddenByTier: placeable.filter((a) => relevant(a) && !inTier(a)).length,
   }
 }
 

package/app/utils/binaryCandidates.spec.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest'
+import type { PipelineStep } from '~/types/execution'
+import { binaryCandidateHasWarnings, binaryCandidateView } from './binaryCandidates'
+
+function step(overrides: Record<string, unknown> = {}): PipelineStep {
+  // The candidate override MERGES into the base state rather than replacing it, so a case that
+  // only cares about one counter does not have to restate the whole candidate list.
+  const { binaryCandidates, ...rest } = overrides
+  return {
+    agentKind: 'imager',
+    state: 'waiting_decision',
+    binaryCandidates: {
+      status: 'awaiting_choice',
+      multiSelect: false,
+      invalidEntries: 0,
+      omitted: 0,
+      unusablePreviews: 0,
+      candidates: [
+        { id: 'c1', service: 's', location: 'a.png', subject: 'anvil', generator: 'flux' },
+        { id: 'c2', service: 's', location: 'b.png', subject: 'anvil', generator: 'retro' },
+        { id: 'c3', service: 's', location: 'c.png', subject: 'hammer' },
+      ],
+      ...(binaryCandidates as Record<string, unknown> | undefined),
+    },
+    ...rest,
+  } as unknown as PipelineStep
+}
+
+describe('binaryCandidateView', () => {
+  // A step that never compared renders nothing at all, exactly as the binary-output section does
+  // for a step that never generated: a row saying "no comparison here" would ride every step.
+  it('is absent for a step with no comparison story', () => {
+    expect(binaryCandidateView({ agentKind: 'coder' } as PipelineStep)).toBeNull()
+    expect(binaryCandidateView(null)).toBeNull()
+  })
+
+  // A person compares one subject at a time; forty subjects is forty comparisons, not one wall of
+  // eighty pictures.
+  it('groups candidates by subject in first-appearance order', () => {
+    const view = binaryCandidateView(step())!
+    expect(view.groups.map((g) => g.subject)).toEqual(['anvil', 'hammer'])
+    expect(view.groups[0]?.rows.map((r) => r.id)).toEqual(['c1', 'c2'])
+  })
+
+  // An unlabelled candidate is not "the same thing" as any labelled one, and filing it under the
+  // first subject would put a picture of something else into a comparison.
+  it('keeps unlabelled candidates in their own group rather than merging them', () => {
+    const view = binaryCandidateView(
+      step({
+        binaryCandidates: {
+          candidates: [
+            { id: 'c1', service: 's', location: 'a.png', subject: 'anvil' },
+            { id: 'c2', service: 's', location: 'b.png' },
+          ],
+        },
+      }),
+    )!
+    expect(view.groups.map((g) => g.subject)).toEqual(['anvil', null])
+  })
+
+  it('marks what was kept and the id it was kept under', () => {
+    const view = binaryCandidateView(
+      step({
+        binaryCandidates: {
+          status: 'chosen',
+          multiSelect: true,
+          choice: {
+            kept: [{ candidateId: 'c2', storeAs: 'anvil-pixel' }],
+            discarded: ['c1', 'c3'],
+            at: 1,
+          },
+        },
+      }),
+    )!
+    const rows = view.groups.flatMap((g) => g.rows)
+    expect(rows.find((r) => r.id === 'c2')).toMatchObject({ kept: true, storeAs: 'anvil-pixel' })
+    expect(rows.find((r) => r.id === 'c1')?.kept).toBe(false)
+    expect(view.awaiting).toBe(false)
+  })
+
+  // An automatic keep is NOT a review. A surface that renders it as a choice tells a reader a
+  // person looked at this and approved it, which is the claim the whole feature exists to make
+  // true.
+  it('reports an automatic keep as its own fact', () => {
+    const view = binaryCandidateView(
+      step({
+        binaryCandidates: {
+          status: 'chosen',
+          choice: { kept: [{ candidateId: 'c1' }], discarded: [], automatic: true, at: 1 },
+        },
+      }),
+    )!
+    expect(view.automatic).toBe(true)
+  })
+
+  it('counts candidates with no renderable preview', () => {
+    expect(binaryCandidateView(step())!.withoutPreview).toBe(3)
+  })
+})
+
+describe('binaryCandidateHasWarnings', () => {
+  // A comparison made over three of five candidates must not read as one made over all five.
+  it('is raised by any counted loss and by nothing else', () => {
+    expect(binaryCandidateHasWarnings(binaryCandidateView(step())!)).toBe(false)
+    for (const field of ['invalidEntries', 'omitted', 'unusablePreviews'] as const) {
+      const view = binaryCandidateView(step({ binaryCandidates: { [field]: 1 } }))!
+      expect(binaryCandidateHasWarnings(view)).toBe(true)
+    }
+  })
+})

package/app/utils/binaryCandidates.ts

@@ -0,0 +1,126 @@
+import type { BinaryCandidate, BinaryCandidateStepState, PipelineStep } from '~/types/execution'
+
+// ---------------------------------------------------------------------------
+// The read model behind the candidate-comparison surface
+// (docs/initiatives/binary-output-foundational-storage.md).
+//
+// A step whose selection declares a `comparison` generates a candidate from each of its selected
+// integrations, stages them, and parks. This module turns that record into what the window
+// renders: the candidates GROUPED BY SUBJECT (which is what a person actually compares), the
+// preview each one does or does not have, and every loss the parse counted.
+//
+// Pure, and reads only the step's own record, which is the rule the sibling binary-output read
+// model follows and for the same reason: the join a human wants is answerable from the step alone, so
+// the surface needs no fetch and reads identically for a finished run.
+// ---------------------------------------------------------------------------
+
+/** One candidate as the window renders it, with the two facts the raw record does not carry. */
+export interface BinaryCandidateRow extends BinaryCandidate {
+  /**
+   * The human kept this one. Meaningful only once a choice exists, which is what lets the window
+   * double as the RECORD of a settled comparison rather than only its control surface.
+   */
+  kept: boolean
+  /** The id it is to be stored under, when the person who kept it assigned one. */
+  storeAs?: string
+}
+
+/** The candidates for one subject, which is the unit a person compares. */
+export interface BinaryCandidateGroup {
+  /**
+   * What these candidates depict, or null when the agent declared no subject. Null is its own
+   * group rather than being merged into another: an unlabelled candidate is not "the same thing"
+   * as any labelled one, and quietly filing it under the first subject would put a picture of
+   * something else into a comparison.
+   */
+  subject: string | null
+  rows: BinaryCandidateRow[]
+}
+
+/** The whole surface's read model. */
+export interface BinaryCandidateView {
+  state: BinaryCandidateStepState
+  /** Candidates grouped by subject, in first-appearance order. */
+  groups: BinaryCandidateGroup[]
+  /** Whether the run is parked on this decision right now (as opposed to showing the record). */
+  awaiting: boolean
+  /** Whether more than one candidate may be kept. */
+  multiSelect: boolean
+  /**
+   * True when the engine kept the only candidate without asking. Its own flag rather than an
+   * absent decider, because a surface that renders it as a choice claims a person looked at this.
+   */
+  automatic: boolean
+  /** How many candidates carry no renderable preview, so the window can say so once. */
+  withoutPreview: number
+}
+
+/**
+ * The step's candidate read model, or null when the step has no comparison story at all.
+ *
+ * A step that never compared renders nothing, exactly as the binary-output section does for a step
+ * that never generated: a row saying "no comparison was configured here" would ride every step of
+ * every run.
+ */
+export function binaryCandidateView(
+  step: PipelineStep | null | undefined,
+): BinaryCandidateView | null {
+  const state = step?.binaryCandidates
+  if (!state) return null
+  const kept = new Map((state.choice?.kept ?? []).map((entry) => [entry.candidateId, entry]))
+  const groups: BinaryCandidateGroup[] = []
+  const bySubject = new Map<string | null, BinaryCandidateGroup>()
+  for (const candidate of state.candidates) {
+    const subject = candidate.subject ?? null
+    let group = bySubject.get(subject)
+    if (!group) {
+      group = { subject, rows: [] }
+      bySubject.set(subject, group)
+      groups.push(group)
+    }
+    const choice = kept.get(candidate.id)
+    group.rows.push({
+      ...candidate,
+      kept: choice !== undefined,
+      ...(choice?.storeAs ? { storeAs: choice.storeAs } : {}),
+    })
+  }
+  return {
+    state,
+    groups,
+    awaiting: state.status === 'awaiting_choice',
+    multiSelect: state.multiSelect === true,
+    automatic: state.choice?.automatic === true,
+    withoutPreview: state.candidates.filter((candidate) => !candidate.previewUrl).length,
+  }
+}
+
+/**
+ * Whether anything about this comparison needs saying beside the candidates: entries the parse
+ * dropped, a truncated list, or preview links it refused.
+ *
+ * Drives the window's warning strip, so a comparison made over three of five candidates cannot
+ * read as one made over all of them. A missing PREVIEW is deliberately not one of these: it is
+ * ordinary (a private asset store issues no public link) and it is stated per candidate, where
+ * the reader can see exactly which one they are judging blind.
+ */
+export function binaryCandidateHasWarnings(view: BinaryCandidateView): boolean {
+  const { invalidEntries = 0, omitted = 0, unusablePreviews = 0 } = view.state
+  return invalidEntries > 0 || omitted > 0 || unusablePreviews > 0
+}
+
+/**
+ * State → the i18n key for the line explaining why no choice was offered.
+ *
+ * An exhaustive `Record` over the reason vocabulary, so a fourth reason fails the typecheck here
+ * rather than rendering a missing key. Every member is a different fault with a different fix,
+ * which is exactly why the engine records the reason instead of leaving the step blank.
+ */
+export const BINARY_CANDIDATE_NO_CHOICE_KEYS: Record<
+  NonNullable<BinaryCandidateStepState['noChoiceReason']>,
+  string
+> = {
+  undeclared: 'binaryCandidates.noChoice.undeclared',
+  parse_failed: 'binaryCandidates.noChoice.parseFailed',
+  no_candidates: 'binaryCandidates.noChoice.noCandidates',
+}

package/app/utils/binaryOutput.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import type { BinaryOutputReport, PipelineStep } from '~/types/execution'
+import type { BinaryOutputArtifact, BinaryOutputReport, PipelineStep } from '~/types/execution'
 import {
   BINARY_OUTPUT_STATE_KEYS,
   binaryOutputHasWarnings,
@@ -371,6 +371,95 @@ describe('the delivered-format check', () => {
   })
 })
 
+// The size axis's delivery-side half. Admission checked what the selected integrations can be
+// ASKED for; only this checks what came back, which is the failure the requirement exists for:
+// an asset stored at the wrong size passes every other check on this panel.
+describe('binaryOutputView, the delivered size', () => {
+  const sized = (
+    outputSize: { width: number; height: number } | undefined,
+    stored: {
+      location: string
+      dimensions?: { width: number; height: number }
+      modality?: BinaryOutputArtifact['modality']
+    }[],
+  ) =>
+    binaryOutputView(
+      step({
+        stepOptions: {
+          binaryOutput: {
+            storageServiceId: 'files',
+            ...(outputSize ? { generation: { outputSize } } : {}),
+          },
+        },
+        binaryOutputs: report({
+          stored: stored.map((entry) => ({ service: 'files', ...entry })),
+        }),
+      }),
+    )
+
+  it('counts an artifact delivered at another size, and marks its row', () => {
+    const view = sized({ width: 96, height: 96 }, [
+      { location: 'a.png', dimensions: { width: 96, height: 96 } },
+      { location: 'b.png', dimensions: { width: 1024, height: 1024 } },
+    ])
+    expect(view?.requiredSize).toEqual({ width: 96, height: 96 })
+    expect(view?.missized).toBe(1)
+    expect(view?.rows.map((row) => row.missized)).toEqual([false, true])
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  it('counts an UNMEASURED artifact apart, never as a delivered one', () => {
+    // The rule this whole feature runs on: "we were not told" and "it came back wrong" are the
+    // same value and opposite facts. Folded together, a run that reported nothing would read as
+    // one that delivered everything wrong; dropped, it would read as a clean one.
+    const view = sized({ width: 96, height: 96 }, [{ location: 'a.png' }])
+    expect(view?.missized).toBe(0)
+    expect(view?.sizeUnreported).toBe(1)
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  it('judges nothing when the step asked for no size', () => {
+    const view = sized(undefined, [
+      { location: 'a.png', dimensions: { width: 1024, height: 1024 } },
+      { location: 'b.png' },
+    ])
+    expect(view?.requiredSize).toBeNull()
+    expect(view?.missized).toBe(0)
+    expect(view?.sizeUnreported).toBe(0)
+    expect(binaryOutputHasWarnings(view!)).toBe(false)
+  })
+
+  // A size is a statement about what is MEASURED in pixels. A step that generates the icon and
+  // its pickup sound delivered exactly what was asked, and counting the audio as unmeasured
+  // would warn about it forever, on a panel whose whole discipline is that a warning means
+  // something went wrong.
+  it('says nothing about an artifact a size cannot describe', () => {
+    const view = sized({ width: 96, height: 96 }, [
+      { location: 'a.png', modality: 'image', dimensions: { width: 96, height: 96 } },
+      { location: 'a.mp3', modality: 'audio' },
+      { location: 'a.glb', modality: '3d-model' },
+    ])
+    expect(view?.missized).toBe(0)
+    expect(view?.sizeUnreported).toBe(0)
+    expect(binaryOutputHasWarnings(view!)).toBe(false)
+  })
+
+  // The other direction, and the one that must not go quiet: an artifact the platform could not
+  // CLASSIFY may well be an image, so it stays covered. Excluding it would turn an unreadable
+  // content type into a silent pass on the one axis the requirement exists to check, and a
+  // RETIRED modality a stale run carries reads the same way.
+  it('keeps an unclassified artifact under the requirement', () => {
+    const view = sized({ width: 96, height: 96 }, [
+      { location: 'a.bin' },
+      // A modality the union no longer has, which a run saved before the 3D split goes on
+      // carrying. Cast because the TYPE cannot express it and the DATA can, which is the whole
+      // reason the read narrows through `isBinaryModality` before it looks anything up.
+      { location: 'b.bin', modality: '3d' as BinaryOutputArtifact['modality'] },
+    ])
+    expect(view?.sizeUnreported).toBe(2)
+  })
+})
+
 describe('binaryOutputPickIssues, generative half', () => {
   const catalog = [{ id: 'files', capabilities: ['asset-storage'] }]
   const generators = [
@@ -400,6 +489,38 @@ describe('binaryOutputPickIssues, generative half', () => {
     expect(pick.uncoveredModalities).toEqual(['audio'])
   })
 
+  // The builder offers a ratio, an exact size and an upscale together, so the conflict it can
+  // save is one it must state: reported only by the failed round trip, the fix (delete one of two
+  // fields on this form) arrives as backend prose about a step the reader has already left.
+  it('states the save refusal for two statements of one delivered size', () => {
+    const pick = binaryOutputPickIssues(
+      {
+        storageServiceId: 'files',
+        generatorIds: ['retro'],
+        generation: { outputSize: { width: 96, height: 96 }, aspectRatio: '16:9' },
+      },
+      catalog,
+      true,
+      generators,
+    )
+    expect(pick.issues).toContain('output_size_ambiguous')
+    expect(pick.conflictingSizeOptions).toEqual(['aspectRatio'])
+  })
+
+  // A step with no storage pick still gets the whole list: the two halves resolve against
+  // different registries, and reporting them one round at a time is the retry cycle this
+  // function returns every issue together to avoid.
+  it('states it on a step whose storage is not picked either', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: '', generation: { outputSize: { width: 96, height: 96 }, upscale: 2 } },
+      catalog,
+      true,
+      generators,
+    )
+    expect(pick.issues).toEqual(expect.arrayContaining(['not_selected', 'output_size_ambiguous']))
+    expect(pick.conflictingSizeOptions).toEqual(['upscale'])
+  })
+
   it('reports BOTH faults when an unknown id was the one covering a requirement', () => {
     // One edit should clear the step. Naming only the missing id would leave the user to
     // discover the uncovered requirement on the next round trip.