@cat-factory/contracts 0.284.0 → 0.285.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/dist/agent-presentation.d.ts +2 -2
  2. package/dist/binary-candidates.d.ts +261 -0
  3. package/dist/binary-candidates.d.ts.map +1 -0
  4. package/dist/binary-candidates.js +202 -0
  5. package/dist/binary-candidates.js.map +1 -0
  6. package/dist/binary-capabilities.d.ts +328 -0
  7. package/dist/binary-capabilities.d.ts.map +1 -0
  8. package/dist/binary-capabilities.js +361 -0
  9. package/dist/binary-capabilities.js.map +1 -0
  10. package/dist/binary-generators.d.ts +27 -0
  11. package/dist/binary-generators.d.ts.map +1 -1
  12. package/dist/binary-generators.js +28 -0
  13. package/dist/binary-generators.js.map +1 -1
  14. package/dist/binary-outputs.d.ts +31 -0
  15. package/dist/binary-outputs.d.ts.map +1 -1
  16. package/dist/binary-outputs.js +30 -0
  17. package/dist/binary-outputs.js.map +1 -1
  18. package/dist/entities.d.ts +10 -0
  19. package/dist/entities.d.ts.map +1 -1
  20. package/dist/execution.d.ts +90 -0
  21. package/dist/execution.d.ts.map +1 -1
  22. package/dist/execution.js +13 -0
  23. package/dist/execution.js.map +1 -1
  24. package/dist/index.d.ts +2 -0
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +2 -0
  27. package/dist/index.js.map +1 -1
  28. package/dist/requests.d.ts +10 -0
  29. package/dist/requests.d.ts.map +1 -1
  30. package/dist/result-views.d.ts +1 -1
  31. package/dist/result-views.d.ts.map +1 -1
  32. package/dist/result-views.js +1 -0
  33. package/dist/result-views.js.map +1 -1
  34. package/dist/routes/agent-runs.d.ts +68 -0
  35. package/dist/routes/agent-runs.d.ts.map +1 -1
  36. package/dist/routes/binaryCandidates.d.ts +139 -0
  37. package/dist/routes/binaryCandidates.d.ts.map +1 -0
  38. package/dist/routes/binaryCandidates.js +31 -0
  39. package/dist/routes/binaryCandidates.js.map +1 -0
  40. package/dist/routes/bug-hunt.d.ts +68 -0
  41. package/dist/routes/bug-hunt.d.ts.map +1 -1
  42. package/dist/routes/execution.d.ts +272 -0
  43. package/dist/routes/execution.d.ts.map +1 -1
  44. package/dist/routes/human-review.d.ts +34 -0
  45. package/dist/routes/human-review.d.ts.map +1 -1
  46. package/dist/routes/human-test.d.ts +170 -0
  47. package/dist/routes/human-test.d.ts.map +1 -1
  48. package/dist/routes/index.d.ts +1 -0
  49. package/dist/routes/index.d.ts.map +1 -1
  50. package/dist/routes/index.js +1 -0
  51. package/dist/routes/index.js.map +1 -1
  52. package/dist/routes/pipelines.d.ts +40 -0
  53. package/dist/routes/pipelines.d.ts.map +1 -1
  54. package/dist/routes/visual-confirm.d.ts +102 -0
  55. package/dist/routes/visual-confirm.d.ts.map +1 -1
  56. package/dist/routes/workspaces.d.ts +82 -2
  57. package/dist/routes/workspaces.d.ts.map +1 -1
  58. package/dist/snapshot.d.ts +41 -1
  59. package/dist/snapshot.d.ts.map +1 -1
  60. package/package.json +1 -1
@@ -0,0 +1,328 @@
1
+ import * as v from 'valibot';
2
+ /**
3
+ * A CAPABILITY a generative binary integration declares, as a closed vocabulary.
4
+ *
5
+ * Closed for the same reason {@link binaryModalitySchema} is: it decides things. A capability
6
+ * gates a per-step generation option (a control the builder shows, a paragraph the brief writes,
7
+ * a requirement admission refuses), so `referenceImage` and `reference-image` would be two
8
+ * capabilities that look identical to a reader and silently never match.
9
+ *
10
+ * **A member earns its place only when the PLATFORM exposes something because of it.** That is a
11
+ * higher bar than "the providers differ", and it is what keeps this from becoming the
12
+ * discriminator field the design record refuses (`style`, `resolutionRange`, `intendedUse`).
13
+ * Those were refused because they do not PARTITION a deliverable, so no predicate could be
14
+ * computed from them and a rule built on one would refuse correctly-configured steps by the taste
15
+ * of whoever wrote the picklist. A capability partitions exactly: an API either accepts an input
16
+ * image or it does not, either takes a mask or it does not, and the answer is a fact about the
17
+ * endpoint rather than an opinion about the art. So `covered` / `uncovered` is computable here,
18
+ * which is the same property that lets `modalities` and `mediaTypes` carry admission rules.
19
+ *
20
+ * It also decides nothing about WHICH of two integrations to call. That question stays exactly
21
+ * where the design record put it (the step's `generatorIds`, its format requirement, and its own
22
+ * prompt); this only says what may be ASKED of whichever one is called. A capability that told
23
+ * two producers of one modality apart without unlocking an option would be the refused
24
+ * discriminator wearing a new name.
25
+ *
26
+ * Anything that does not clear the bar stays prose in `description` / `guidance`, which is where
27
+ * "good at pixel art", "expensive above 2K" and "rate limited to 5/min" belong.
28
+ */
29
+ export declare const binaryGeneratorCapabilitySchema: v.PicklistSchema<["reference-image", "multi-reference", "instruction-edit", "mask-edit", "negative-prompt", "seed", "aspect-ratio", "candidate-batch", "upscale", "transparent-background", "tileable"], undefined>;
30
+ export type BinaryGeneratorCapability = v.InferOutput<typeof binaryGeneratorCapabilitySchema>;
31
+ /**
32
+ * Whether a value is still a member of the vocabulary, DERIVED from the picklist.
33
+ *
34
+ * Unlike {@link isBinaryModality} this vocabulary is not persisted on a step: capabilities are
35
+ * declared in a deployment's own code, so a build that retires a member also stops emitting it.
36
+ * The guard exists for the ONE seam where that is not true: a MOTHERSHIP-MODE node resolves its
37
+ * integrations from a process that may be a build AHEAD of it, so a capability this build has
38
+ * never heard of can arrive over `/internal/binary-generators` and reach a `Record` lookup or a
39
+ * `switch`. Narrow with this first and describe the negative case as the unknown value it is.
40
+ */
41
+ export declare function isBinaryGeneratorCapability(value: string): value is BinaryGeneratorCapability;
42
+ /**
43
+ * Where an artifact the step points a generator AT already lives: a reference image, the source
44
+ * of an edit, a mask.
45
+ *
46
+ * The platform deliberately does NOT fetch it. It is named to the agent in the brief, and the
47
+ * agent reads it exactly as it calls the generation API itself, which is the same division of
48
+ * labour the rest of this feature runs on: the platform states, the agent acts, and nothing here
49
+ * touches bytes. `service` names one of the step's own foundational services when the artifact
50
+ * lives in the org's estate rather than at a URL, so a private object store needs no public link.
51
+ */
52
+ export declare const binaryAssetRefSchema: v.ObjectSchema<{
53
+ /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
54
+ readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
55
+ /**
56
+ * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
57
+ * agent can fetch directly. Not validated against the step's own selection: a reference can
58
+ * legitimately live in a service the step does not otherwise use, and the brief names whatever
59
+ * is here so a wrong id is visible rather than silently dropped.
60
+ */
61
+ readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
62
+ /** What this is, in the step author's words, folded into the brief verbatim. */
63
+ readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
64
+ }, undefined>;
65
+ export type BinaryAssetRef = v.InferOutput<typeof binaryAssetRefSchema>;
66
+ /**
67
+ * A reference image plus the ROLE it plays, because "here is an image" is not an instruction.
68
+ * The same file means "match this palette", "this is the character" or "start from this and
69
+ * change it" depending on the answer, and every one of the four reference-capable APIs takes a
70
+ * different parameter for each.
71
+ */
72
+ export declare const binaryReferenceImageSchema: v.ObjectSchema<{
73
+ readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
74
+ readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
75
+ readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
76
+ readonly role: v.PicklistSchema<["style", "subject", "composition", "base"], undefined>;
77
+ }, undefined>;
78
+ export type BinaryReferenceImage = v.InferOutput<typeof binaryReferenceImageSchema>;
79
+ /**
80
+ * The step REVISES existing artifacts rather than making new ones.
81
+ *
82
+ * A named schema rather than an inline object inside the options bag below, for the reason the
83
+ * reference-image shape is spelled out: this nests two more object levels under an already-deep
84
+ * chain, and a named const is where `tsc` can stop re-instantiating it.
85
+ */
86
+ export declare const binaryEditRequestSchema: v.ObjectSchema<{
87
+ /**
88
+ * `instruction` rewrites a whole artifact from a sentence; `mask` repaints only the region a
89
+ * mask names. Two capabilities, because almost no integration has both.
90
+ */
91
+ readonly mode: v.PicklistSchema<["instruction", "mask"], undefined>;
92
+ /** What to change, folded into the brief verbatim. */
93
+ readonly instruction: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
94
+ /**
95
+ * The artifact to revise. Absent ⇒ the step's scope services say which existing asset each
96
+ * generation revises, which is the ordinary case for a step that re-renders an inventory.
97
+ */
98
+ readonly source: v.OptionalSchema<v.ObjectSchema<{
99
+ /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
100
+ readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
101
+ /**
102
+ * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
103
+ * agent can fetch directly. Not validated against the step's own selection: a reference can
104
+ * legitimately live in a service the step does not otherwise use, and the brief names whatever
105
+ * is here so a wrong id is visible rather than silently dropped.
106
+ */
107
+ readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
108
+ /** What this is, in the step author's words, folded into the brief verbatim. */
109
+ readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
110
+ }, undefined>, undefined>;
111
+ /** The mask, for `mask` mode. Absent in `mask` mode is a gap the brief STATES. */
112
+ readonly mask: v.OptionalSchema<v.ObjectSchema<{
113
+ /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
114
+ readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
115
+ /**
116
+ * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
117
+ * agent can fetch directly. Not validated against the step's own selection: a reference can
118
+ * legitimately live in a service the step does not otherwise use, and the brief names whatever
119
+ * is here so a wrong id is visible rather than silently dropped.
120
+ */
121
+ readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
122
+ /** What this is, in the step author's words, folded into the brief verbatim. */
123
+ readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
124
+ }, undefined>, undefined>;
125
+ }, undefined>;
126
+ export type BinaryEditRequest = v.InferOutput<typeof binaryEditRequestSchema>;
127
+ /**
128
+ * The per-step GENERATION OPTIONS: the parameters a step wants every generation to carry, each
129
+ * gated by the capability that makes it answerable ({@link BINARY_OPTION_CAPABILITIES}).
130
+ *
131
+ * They are a statement about the WORK, exactly like `modalities` and `mediaTypes` beside them,
132
+ * and they are checked the same way: a step asking for something nothing it selected can do is
133
+ * refused at admission rather than discovering it at the end of a paid run. What they are NOT is
134
+ * a passthrough of any vendor's request body. Everything here is a fact about the deliverable
135
+ * that more than one of the registered APIs can express in its own parameters, and the agent
136
+ * translates it on the call it writes; a knob only one vendor has (`prompt_upsampling`,
137
+ * `safety_tolerance`, a sampler name) stays in that integration's `guidance`, where it can say
138
+ * what it means, rather than becoming a field every other integration ignores.
139
+ */
140
+ /**
141
+ * The raw object schema. Exported ONLY so the drift guard in `binary-capabilities.test.ts` can
142
+ * infer its output type and compare it against the hand-written {@link BinaryGenerationOptions};
143
+ * every other consumer takes {@link binaryGenerationOptionsSchema}, whose whole purpose is to
144
+ * stop that inference from happening at each use site. See the interface's note for why.
145
+ */
146
+ export declare const binaryGenerationOptionsObject: v.ObjectSchema<{
147
+ /**
148
+ * Images every generation is conditioned on. Needs `reference-image`; more than one also needs
149
+ * `multi-reference`, since an API that takes a single input image cannot compose two.
150
+ */
151
+ readonly referenceImages: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
152
+ readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
153
+ readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
154
+ readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
155
+ readonly role: v.PicklistSchema<["style", "subject", "composition", "base"], undefined>;
156
+ }, undefined>, undefined>, v.MaxLengthAction<{
157
+ location: string;
158
+ service?: string | undefined;
159
+ note?: string | undefined;
160
+ role: "base" | "composition" | "style" | "subject";
161
+ }[], 8, undefined>]>, undefined>;
162
+ /**
163
+ * The step REVISES existing artifacts rather than making new ones. Needs `instruction-edit` or
164
+ * `mask-edit` depending on `mode`.
165
+ */
166
+ readonly edit: v.OptionalSchema<v.ObjectSchema<{
167
+ /**
168
+ * `instruction` rewrites a whole artifact from a sentence; `mask` repaints only the region a
169
+ * mask names. Two capabilities, because almost no integration has both.
170
+ */
171
+ readonly mode: v.PicklistSchema<["instruction", "mask"], undefined>;
172
+ /** What to change, folded into the brief verbatim. */
173
+ readonly instruction: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
174
+ /**
175
+ * The artifact to revise. Absent ⇒ the step's scope services say which existing asset each
176
+ * generation revises, which is the ordinary case for a step that re-renders an inventory.
177
+ */
178
+ readonly source: v.OptionalSchema<v.ObjectSchema<{
179
+ /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
180
+ readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
181
+ /**
182
+ * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
183
+ * agent can fetch directly. Not validated against the step's own selection: a reference can
184
+ * legitimately live in a service the step does not otherwise use, and the brief names whatever
185
+ * is here so a wrong id is visible rather than silently dropped.
186
+ */
187
+ readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
188
+ /** What this is, in the step author's words, folded into the brief verbatim. */
189
+ readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
190
+ }, undefined>, undefined>;
191
+ /** The mask, for `mask` mode. Absent in `mask` mode is a gap the brief STATES. */
192
+ readonly mask: v.OptionalSchema<v.ObjectSchema<{
193
+ /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
194
+ readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
195
+ /**
196
+ * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
197
+ * agent can fetch directly. Not validated against the step's own selection: a reference can
198
+ * legitimately live in a service the step does not otherwise use, and the brief names whatever
199
+ * is here so a wrong id is visible rather than silently dropped.
200
+ */
201
+ readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
202
+ /** What this is, in the step author's words, folded into the brief verbatim. */
203
+ readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
204
+ }, undefined>, undefined>;
205
+ }, undefined>, undefined>;
206
+ /** What to keep out. Needs `negative-prompt`. */
207
+ readonly negativePrompt: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
208
+ /**
209
+ * A fixed seed, so the run is reproducible. Needs `seed`.
210
+ *
211
+ * A step comparing candidates deliberately does NOT get its seed varied for it: a fixed seed
212
+ * across integrations is how two renders of one subject are told apart by the integration
213
+ * rather than by luck, and the brief says so.
214
+ */
215
+ readonly seed: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 4294967295, undefined>]>, undefined>;
216
+ /** `16:9`, `1:1`, `3:2`. Needs `aspect-ratio`. */
217
+ readonly aspectRatio: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 16, undefined>, v.RegexAction<string, "must be an aspect ratio of the form W:H">]>, undefined>;
218
+ /** Render at this multiple of the integration's native size. Needs `upscale`. */
219
+ readonly upscale: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 2, undefined>, v.MaxValueAction<number, 8, undefined>]>, undefined>;
220
+ /** Deliver an alpha channel rather than a background. Needs `transparent-background`. */
221
+ readonly transparentBackground: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
222
+ /** Deliver a seamlessly tiling image. Needs `tileable`. */
223
+ readonly tileable: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
224
+ }, undefined>;
225
+ /**
226
+ * The generation options as a TYPE, written out rather than inferred.
227
+ *
228
+ * The one hand-written shape in this module, and it is not a style choice. This bag sits at the
229
+ * bottom of the deepest schema chain the product has: `WorkspaceSnapshot` → pipeline → step
230
+ * options → binary output → here → a reference image → its pipes: and inferring it pushed `tsc`
231
+ * past its instantiation limit in `@cat-factory/workspaces`, several packages away, with an error
232
+ * pointing at a line that has nothing to do with any of this. Naming the type stops the recursion
233
+ * at this node: every consumer resolves `BinaryGenerationOptions` instead of re-deriving it.
234
+ *
235
+ * A hand-written type beside a schema is exactly the drift this codebase avoids elsewhere, so it
236
+ * is pinned: `binary-capabilities.test.ts` asserts the inferred output and this interface are
237
+ * mutually assignable, which fails the build if either side gains a field the other does not.
238
+ * That check lives in a TEST rather than here because performing the inference in this file is
239
+ * what the annotation exists to stop doing at every use site, and doing it once in one place is
240
+ * affordable.
241
+ */
242
+ export interface BinaryGenerationOptions {
243
+ referenceImages?: BinaryReferenceImage[] | undefined;
244
+ edit?: BinaryEditRequest | undefined;
245
+ negativePrompt?: string | undefined;
246
+ seed?: number | undefined;
247
+ aspectRatio?: string | undefined;
248
+ upscale?: number | undefined;
249
+ transparentBackground?: true | undefined;
250
+ tileable?: true | undefined;
251
+ }
252
+ /**
253
+ * The generation options as a SCHEMA, typed against the interface above so consumers stop
254
+ * re-inferring it. `unknown` on the input side is what a parser accepts anyway, and nothing in
255
+ * this repo reads `InferInput` of a step's options.
256
+ */
257
+ export declare const binaryGenerationOptionsSchema: v.GenericSchema<unknown, BinaryGenerationOptions>;
258
+ /**
259
+ * Which option needs which capability, as the ONE table both sides read.
260
+ *
261
+ * A `Record` over the option keys rather than a chain of `if`s at each reader, so an option added
262
+ * to the schema without a capability fails the typecheck here instead of shipping as a control
263
+ * nothing checks. `referenceImages` maps to a LIST because its requirement grows with its length,
264
+ * and `edit` maps to one of two by its mode, which is why the derivation below is a function and
265
+ * not a lookup.
266
+ */
267
+ export declare const BINARY_OPTION_CAPABILITIES: Record<keyof BinaryGenerationOptions, readonly BinaryGeneratorCapability[]>;
268
+ /**
269
+ * The capabilities a step's generation options actually REQUIRE, in a stable order.
270
+ *
271
+ * Derived rather than declared, so a step never carries a requirement it does not exercise: a
272
+ * `referenceImages` list of one needs `reference-image` and NOT `multi-reference`, and an `edit`
273
+ * needs exactly the one capability its mode names. Deriving it is also what keeps the refusal
274
+ * honest in the other direction, since a requirement nobody stated cannot be silently dropped by
275
+ * an integration that does not declare it.
276
+ *
277
+ * Deliberately NOT extended with `candidate-batch` for a comparison step: an integration without
278
+ * it can still produce several candidates by repeating the call, so a refusal there would reject
279
+ * a selection that works. The brief states which of the two the agent should do.
280
+ */
281
+ export declare function requiredBinaryCapabilities(options: BinaryGenerationOptions | undefined): BinaryGeneratorCapability[];
282
+ /** How a step's required capabilities stand against what its selected integrations declare. */
283
+ export interface BinaryCapabilityCoverage {
284
+ /** Required capabilities no selected integration declares, judged against integrations that
285
+ * DECLARED theirs. These refuse the run. */
286
+ uncovered: BinaryGeneratorCapability[];
287
+ /** Required capabilities nothing selected claims, where at least one selected integration
288
+ * declares NO capabilities at all, so the requirement might be met and nothing may say
289
+ * otherwise. */
290
+ unverifiable: BinaryGeneratorCapability[];
291
+ }
292
+ /**
293
+ * Judge `required` against what `selected` declares it can do.
294
+ *
295
+ * The same THREE outcomes as {@link binaryFormatCoverage}, and deliberately the same rule, because
296
+ * the two axes are in the same position: a declaration that pins nothing down is an explicit
297
+ * documented state ("only the coarse facts are known") rather than a denial. That reading is what
298
+ * lets this ship without breaking a single integration registered before capabilities existed:
299
+ * they declare none, so every requirement against them is UNVERIFIABLE, the run is admitted, and
300
+ * the gap is stated to the agent in its brief and to the composer in the picker. Refusing there
301
+ * would retroactively invalidate every registration in existence; calling it covered would be a
302
+ * clean bill of health nobody issued on the surface that decides whether the run may start.
303
+ *
304
+ * Kept as its own function rather than a generic over the format one: they read different fields
305
+ * of different shapes, and a shared generic would be a parameterised `some`/`has` that saves four
306
+ * lines and hides which axis a caller is asking about.
307
+ */
308
+ export declare function binaryCapabilityCoverage(required: readonly BinaryGeneratorCapability[], selected: readonly {
309
+ capabilities?: readonly BinaryGeneratorCapability[];
310
+ }[]): BinaryCapabilityCoverage;
311
+ /**
312
+ * The integrations that declare each required capability, so a surface can say WHICH of a
313
+ * step's selection will actually honour an option rather than only that something will.
314
+ *
315
+ * The question a person asks the moment a step holds two producers of one modality and one
316
+ * option: an aspect ratio honoured by one of them and ignored by the other is not a covered
317
+ * requirement in any useful sense, and coverage alone cannot say so. Ids come out in selection
318
+ * order and a capability with no declarer is absent, never an empty list, so "nobody" and "not
319
+ * asked" stay different answers.
320
+ */
321
+ export declare function binaryCapabilityProviders(required: readonly BinaryGeneratorCapability[], selected: readonly {
322
+ id: string;
323
+ capabilities?: readonly BinaryGeneratorCapability[];
324
+ }[]): {
325
+ capability: BinaryGeneratorCapability;
326
+ generatorIds: string[];
327
+ }[];
328
+ //# sourceMappingURL=binary-capabilities.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"binary-capabilities.d.ts","sourceRoot":"","sources":["../src/binary-capabilities.ts"],"names":[],"mappings":"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"}