@cat-factory/contracts 0.284.0 → 0.286.0

package/dist/binary-capabilities.d.ts

@@ -0,0 +1,393 @@
+import * as v from 'valibot';
+/**
+ * A CAPABILITY a generative binary integration declares, as a closed vocabulary.
+ *
+ * Closed for the same reason {@link binaryModalitySchema} is: it decides things. A capability
+ * gates a per-step generation option (a control the builder shows, a paragraph the brief writes,
+ * a requirement admission refuses), so `referenceImage` and `reference-image` would be two
+ * capabilities that look identical to a reader and silently never match.
+ *
+ * **A member earns its place only when the PLATFORM exposes something because of it.** That is a
+ * higher bar than "the providers differ", and it is what keeps this from becoming the
+ * discriminator field the design record refuses (`style`, `resolutionRange`, `intendedUse`).
+ * Those were refused because they do not PARTITION a deliverable, so no predicate could be
+ * computed from them and a rule built on one would refuse correctly-configured steps by the taste
+ * of whoever wrote the picklist. A capability partitions exactly: an API either accepts an input
+ * image or it does not, either takes a mask or it does not, and the answer is a fact about the
+ * endpoint rather than an opinion about the art. So `covered` / `uncovered` is computable here,
+ * which is the same property that lets `modalities` and `mediaTypes` carry admission rules.
+ *
+ * It also decides nothing about WHICH of two integrations to call. That question stays exactly
+ * where the design record put it (the step's `generatorIds`, its format requirement, and its own
+ * prompt); this only says what may be ASKED of whichever one is called. A capability that told
+ * two producers of one modality apart without unlocking an option would be the refused
+ * discriminator wearing a new name.
+ *
+ * Anything that does not clear the bar stays prose in `description` / `guidance`, which is where
+ * "good at pixel art", "expensive above 2K" and "rate limited to 5/min" belong.
+ */
+export declare const binaryGeneratorCapabilitySchema: v.PicklistSchema<["reference-image", "multi-reference", "instruction-edit", "mask-edit", "negative-prompt", "seed", "aspect-ratio", "exact-size", "candidate-batch", "upscale", "transparent-background", "tileable"], undefined>;
+export type BinaryGeneratorCapability = v.InferOutput<typeof binaryGeneratorCapabilitySchema>;
+/**
+ * Whether a value is still a member of the vocabulary, DERIVED from the picklist.
+ *
+ * Unlike {@link isBinaryModality} this vocabulary is not persisted on a step: capabilities are
+ * declared in a deployment's own code, so a build that retires a member also stops emitting it.
+ * The guard exists for the ONE seam where that is not true: a MOTHERSHIP-MODE node resolves its
+ * integrations from a process that may be a build AHEAD of it, so a capability this build has
+ * never heard of can arrive over `/internal/binary-generators` and reach a `Record` lookup or a
+ * `switch`. Narrow with this first and describe the negative case as the unknown value it is.
+ */
+export declare function isBinaryGeneratorCapability(value: string): value is BinaryGeneratorCapability;
+/**
+ * Where an artifact the step points a generator AT already lives: a reference image, the source
+ * of an edit, a mask.
+ *
+ * The platform deliberately does NOT fetch it. It is named to the agent in the brief, and the
+ * agent reads it exactly as it calls the generation API itself, which is the same division of
+ * labour the rest of this feature runs on: the platform states, the agent acts, and nothing here
+ * touches bytes. `service` names one of the step's own foundational services when the artifact
+ * lives in the org's estate rather than at a URL, so a private object store needs no public link.
+ */
+export declare const binaryAssetRefSchema: v.ObjectSchema<{
+    /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
+    readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
+    /**
+     * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
+     * agent can fetch directly. Not validated against the step's own selection: a reference can
+     * legitimately live in a service the step does not otherwise use, and the brief names whatever
+     * is here so a wrong id is visible rather than silently dropped.
+     */
+    readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    /** What this is, in the step author's words, folded into the brief verbatim. */
+    readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+}, undefined>;
+export type BinaryAssetRef = v.InferOutput<typeof binaryAssetRefSchema>;
+/**
+ * A reference image plus the ROLE it plays, because "here is an image" is not an instruction.
+ * The same file means "match this palette", "this is the character" or "start from this and
+ * change it" depending on the answer, and every one of the four reference-capable APIs takes a
+ * different parameter for each.
+ */
+export declare const binaryReferenceImageSchema: v.ObjectSchema<{
+    readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
+    readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    readonly role: v.PicklistSchema<["style", "subject", "composition", "base"], undefined>;
+}, undefined>;
+export type BinaryReferenceImage = v.InferOutput<typeof binaryReferenceImageSchema>;
+/**
+ * The step REVISES existing artifacts rather than making new ones.
+ *
+ * A named schema rather than an inline object inside the options bag below, for the reason the
+ * reference-image shape is spelled out: this nests two more object levels under an already-deep
+ * chain, and a named const is where `tsc` can stop re-instantiating it.
+ */
+export declare const binaryEditRequestSchema: v.ObjectSchema<{
+    /**
+     * `instruction` rewrites a whole artifact from a sentence; `mask` repaints only the region a
+     * mask names. Two capabilities, because almost no integration has both.
+     */
+    readonly mode: v.PicklistSchema<["instruction", "mask"], undefined>;
+    /** What to change, folded into the brief verbatim. */
+    readonly instruction: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+    /**
+     * The artifact to revise. Absent ⇒ the step's scope services say which existing asset each
+     * generation revises, which is the ordinary case for a step that re-renders an inventory.
+     */
+    readonly source: v.OptionalSchema<v.ObjectSchema<{
+        /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
+        readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
+        /**
+         * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
+         * agent can fetch directly. Not validated against the step's own selection: a reference can
+         * legitimately live in a service the step does not otherwise use, and the brief names whatever
+         * is here so a wrong id is visible rather than silently dropped.
+         */
+        readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        /** What this is, in the step author's words, folded into the brief verbatim. */
+        readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    }, undefined>, undefined>;
+    /** The mask, for `mask` mode. Absent in `mask` mode is a gap the brief STATES. */
+    readonly mask: v.OptionalSchema<v.ObjectSchema<{
+        /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
+        readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
+        /**
+         * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
+         * agent can fetch directly. Not validated against the step's own selection: a reference can
+         * legitimately live in a service the step does not otherwise use, and the brief names whatever
+         * is here so a wrong id is visible rather than silently dropped.
+         */
+        readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        /** What this is, in the step author's words, folded into the brief verbatim. */
+        readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type BinaryEditRequest = v.InferOutput<typeof binaryEditRequestSchema>;
+/**
+ * The largest pixel extent either axis may carry: a SANITY ceiling on the field, never a claim
+ * about what any endpoint supports.
+ *
+ * Nothing here knows Flux's 4 MP cap or Retro Diffusion's per-style range, and by design nothing
+ * will: the platform checks that a step CAN be asked for dimensions (the `exact-size` capability)
+ * and states the number to the agent, which is the party holding the vendor's contract when it
+ * writes the call. Exported so the read-back that re-checks a reported dimension bounds it against
+ * the same number the write boundary does.
+ */
+export declare const MAX_BINARY_PIXEL_EXTENT = 16384;
+/**
+ * Exact output DIMENSIONS in pixels, for the deliverables where the size IS the requirement.
+ *
+ * A named schema rather than an inline object, for the reason {@link binaryEditRequestSchema} is
+ * one: this nests another object level under an already-deep chain and a named const is where
+ * `tsc` stops re-instantiating it.
+ *
+ * Both members are required together: a width with no height describes no deliverable, and half a
+ * pair would let a size comparison downstream read one axis as matching.
+ */
+export declare const binaryOutputSizeSchema: v.ObjectSchema<{
+    readonly width: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 16384, undefined>]>;
+    readonly height: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 16384, undefined>]>;
+}, undefined>;
+export type BinaryOutputSize = v.InferOutput<typeof binaryOutputSizeSchema>;
+/**
+ * The per-step GENERATION OPTIONS: the parameters a step wants every generation to carry, each
+ * gated by the capability that makes it answerable ({@link BINARY_OPTION_CAPABILITIES}).
+ *
+ * They are a statement about the WORK, exactly like `modalities` and `mediaTypes` beside them,
+ * and they are checked the same way: a step asking for something nothing it selected can do is
+ * refused at admission rather than discovering it at the end of a paid run. What they are NOT is
+ * a passthrough of any vendor's request body. Everything here is a fact about the deliverable
+ * that more than one of the registered APIs can express in its own parameters, and the agent
+ * translates it on the call it writes; a knob only one vendor has (`prompt_upsampling`,
+ * `safety_tolerance`, a sampler name) stays in that integration's `guidance`, where it can say
+ * what it means, rather than becoming a field every other integration ignores.
+ */
+/**
+ * The raw object schema. Exported ONLY so the drift guard in `binary-capabilities.test.ts` can
+ * infer its output type and compare it against the hand-written {@link BinaryGenerationOptions};
+ * every other consumer takes {@link binaryGenerationOptionsSchema}, whose whole purpose is to
+ * stop that inference from happening at each use site. See the interface's note for why.
+ */
+export declare const binaryGenerationOptionsObject: v.ObjectSchema<{
+    /**
+     * Images every generation is conditioned on. Needs `reference-image`; more than one also needs
+     * `multi-reference`, since an API that takes a single input image cannot compose two.
+     */
+    readonly referenceImages: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
+        readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
+        readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+        readonly role: v.PicklistSchema<["style", "subject", "composition", "base"], undefined>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        location: string;
+        service?: string | undefined;
+        note?: string | undefined;
+        role: "base" | "composition" | "style" | "subject";
+    }[], 8, undefined>]>, undefined>;
+    /**
+     * The step REVISES existing artifacts rather than making new ones. Needs `instruction-edit` or
+     * `mask-edit` depending on `mode`.
+     */
+    readonly edit: v.OptionalSchema<v.ObjectSchema<{
+        /**
+         * `instruction` rewrites a whole artifact from a sentence; `mask` repaints only the region a
+         * mask names. Two capabilities, because almost no integration has both.
+         */
+        readonly mode: v.PicklistSchema<["instruction", "mask"], undefined>;
+        /** What to change, folded into the brief verbatim. */
+        readonly instruction: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+        /**
+         * The artifact to revise. Absent ⇒ the step's scope services say which existing asset each
+         * generation revises, which is the ordinary case for a step that re-renders an inventory.
+         */
+        readonly source: v.OptionalSchema<v.ObjectSchema<{
+            /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
+            readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
+            /**
+             * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
+             * agent can fetch directly. Not validated against the step's own selection: a reference can
+             * legitimately live in a service the step does not otherwise use, and the brief names whatever
+             * is here so a wrong id is visible rather than silently dropped.
+             */
+            readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            /** What this is, in the step author's words, folded into the brief verbatim. */
+            readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+        }, undefined>, undefined>;
+        /** The mask, for `mask` mode. Absent in `mask` mode is a gap the brief STATES. */
+        readonly mask: v.OptionalSchema<v.ObjectSchema<{
+            /** Where it lives, in `service`'s addressing when one is named, else an absolute URL. */
+            readonly location: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
+            /**
+             * The foundational service the location is addressed in. Absent ⇒ `location` is a URL the
+             * agent can fetch directly. Not validated against the step's own selection: a reference can
+             * legitimately live in a service the step does not otherwise use, and the brief names whatever
+             * is here so a wrong id is visible rather than silently dropped.
+             */
+            readonly service: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            /** What this is, in the step author's words, folded into the brief verbatim. */
+            readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** What to keep out. Needs `negative-prompt`. */
+    readonly negativePrompt: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+    /**
+     * A fixed seed, so the run is reproducible. Needs `seed`.
+     *
+     * A step comparing candidates deliberately does NOT get its seed varied for it: a fixed seed
+     * across integrations is how two renders of one subject are told apart by the integration
+     * rather than by luck, and the brief says so.
+     */
+    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>;
+    /** `16:9`, `1:1`, `3:2`. Needs `aspect-ratio`. */
+    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>;
+    /**
+     * Exact pixel dimensions every artifact must be delivered at. Needs `exact-size`.
+     *
+     * Mutually exclusive with `aspectRatio` and `upscale`, refused structurally at pipeline save
+     * (`assertUnambiguousOutputSize`): each of those states the final dimensions in a second,
+     * possibly disagreeing way, and the party who would reconcile them is the agent writing the
+     * call — the one with the least basis for deciding, which is the same argument that keeps
+     * `mediaTypes` from meaning "any of these".
+     */
+    readonly outputSize: v.OptionalSchema<v.ObjectSchema<{
+        readonly width: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 16384, undefined>]>;
+        readonly height: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 16384, undefined>]>;
+    }, undefined>, undefined>;
+    /** Render at this multiple of the integration's native size. Needs `upscale`. */
+    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>;
+    /** Deliver an alpha channel rather than a background. Needs `transparent-background`. */
+    readonly transparentBackground: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
+    /** Deliver a seamlessly tiling image. Needs `tileable`. */
+    readonly tileable: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
+}, undefined>;
+/**
+ * The generation options as a TYPE, written out rather than inferred.
+ *
+ * The one hand-written shape in this module, and it is not a style choice. This bag sits at the
+ * bottom of the deepest schema chain the product has: `WorkspaceSnapshot` → pipeline → step
+ * options → binary output → here → a reference image → its pipes: and inferring it pushed `tsc`
+ * past its instantiation limit in `@cat-factory/workspaces`, several packages away, with an error
+ * pointing at a line that has nothing to do with any of this. Naming the type stops the recursion
+ * at this node: every consumer resolves `BinaryGenerationOptions` instead of re-deriving it.
+ *
+ * A hand-written type beside a schema is exactly the drift this codebase avoids elsewhere, so it
+ * is pinned: `binary-capabilities.test.ts` asserts the inferred output and this interface are
+ * mutually assignable, which fails the build if either side gains a field the other does not.
+ * That check lives in a TEST rather than here because performing the inference in this file is
+ * what the annotation exists to stop doing at every use site, and doing it once in one place is
+ * affordable.
+ */
+export interface BinaryGenerationOptions {
+    referenceImages?: BinaryReferenceImage[] | undefined;
+    edit?: BinaryEditRequest | undefined;
+    negativePrompt?: string | undefined;
+    seed?: number | undefined;
+    aspectRatio?: string | undefined;
+    outputSize?: BinaryOutputSize | undefined;
+    upscale?: number | undefined;
+    transparentBackground?: true | undefined;
+    tileable?: true | undefined;
+}
+/**
+ * The generation options as a SCHEMA, typed against the interface above so consumers stop
+ * re-inferring it. `unknown` on the input side is what a parser accepts anyway, and nothing in
+ * this repo reads `InferInput` of a step's options.
+ */
+export declare const binaryGenerationOptionsSchema: v.GenericSchema<unknown, BinaryGenerationOptions>;
+/**
+ * Which option needs which capability, as the ONE table both sides read.
+ *
+ * A `Record` over the option keys rather than a chain of `if`s at each reader, so an option added
+ * to the schema without a capability fails the typecheck here instead of shipping as a control
+ * nothing checks. `referenceImages` maps to a LIST because its requirement grows with its length,
+ * and `edit` maps to one of two by its mode, which is why the derivation below is a function and
+ * not a lookup.
+ */
+export declare const BINARY_OPTION_CAPABILITIES: Record<keyof BinaryGenerationOptions, readonly BinaryGeneratorCapability[]>;
+/**
+ * The capabilities a step's generation options actually REQUIRE, in a stable order.
+ *
+ * Derived rather than declared, so a step never carries a requirement it does not exercise: a
+ * `referenceImages` list of one needs `reference-image` and NOT `multi-reference`, and an `edit`
+ * needs exactly the one capability its mode names. Deriving it is also what keeps the refusal
+ * honest in the other direction, since a requirement nobody stated cannot be silently dropped by
+ * an integration that does not declare it.
+ *
+ * Deliberately NOT extended with `candidate-batch` for a comparison step: an integration without
+ * it can still produce several candidates by repeating the call, so a refusal there would reject
+ * a selection that works. The brief states which of the two the agent should do.
+ */
+export declare function requiredBinaryCapabilities(options: BinaryGenerationOptions | undefined): BinaryGeneratorCapability[];
+/**
+ * A generation option that states the DELIVERED DIMENSIONS a second time, beside an exact
+ * `outputSize`. The union is the option keys themselves, so a reader on either side of the wire
+ * names the field the composer has to delete.
+ */
+export type ConflictingOutputSizeOption = 'aspectRatio' | 'upscale';
+/**
+ * The options that restate the delivered dimensions beside an exact {@link BinaryOutputSize}, in a
+ * stable order. Empty when the step asks for no exact size, which stays the ordinary case.
+ *
+ * `aspectRatio` states the shape the size already fixes, and `upscale` states a multiple of
+ * whatever the integration renders natively, so either one held beside a size leaves the
+ * deliverable's actual dimensions undetermined at exactly the point the step went to the trouble of
+ * determining them. The platform refuses that rather than resolving it by precedence: the party a
+ * precedence rule hands the leftover decision to is the AGENT writing the vendor call, which reads
+ * "96x96" and "16:9" in one brief and picks. Two contradicting statements of one fact is a
+ * mis-configured step and the fix (delete one) is unambiguous, which is what makes refusing it the
+ * cheap option.
+ *
+ * Shared rather than restated on each side, like {@link binaryFormatCoverage} one axis over: the
+ * backend REFUSES the save with it and the SPA has to state the same refusal in the builder, where
+ * it is fixable without a round trip. A rule with a home on only one side becomes a hand-kept copy
+ * on the other, and the two then disagree about which selection is legal.
+ */
+export declare function conflictingOutputSizeOptions(options: BinaryGenerationOptions | undefined): ConflictingOutputSizeOption[];
+/** How a step's required capabilities stand against what its selected integrations declare. */
+export interface BinaryCapabilityCoverage {
+    /** Required capabilities no selected integration declares, judged against integrations that
+     *  DECLARED theirs. These refuse the run. */
+    uncovered: BinaryGeneratorCapability[];
+    /** Required capabilities nothing selected claims, where at least one selected integration
+     *  declares NO capabilities at all, so the requirement might be met and nothing may say
+     *  otherwise. */
+    unverifiable: BinaryGeneratorCapability[];
+}
+/**
+ * Judge `required` against what `selected` declares it can do.
+ *
+ * The same THREE outcomes as {@link binaryFormatCoverage}, and deliberately the same rule, because
+ * the two axes are in the same position: a declaration that pins nothing down is an explicit
+ * documented state ("only the coarse facts are known") rather than a denial. That reading is what
+ * lets this ship without breaking a single integration registered before capabilities existed:
+ * they declare none, so every requirement against them is UNVERIFIABLE, the run is admitted, and
+ * the gap is stated to the agent in its brief and to the composer in the picker. Refusing there
+ * would retroactively invalidate every registration in existence; calling it covered would be a
+ * clean bill of health nobody issued on the surface that decides whether the run may start.
+ *
+ * Kept as its own function rather than a generic over the format one: they read different fields
+ * of different shapes, and a shared generic would be a parameterised `some`/`has` that saves four
+ * lines and hides which axis a caller is asking about.
+ */
+export declare function binaryCapabilityCoverage(required: readonly BinaryGeneratorCapability[], selected: readonly {
+    capabilities?: readonly BinaryGeneratorCapability[];
+}[]): BinaryCapabilityCoverage;
+/**
+ * The integrations that declare each required capability, so a surface can say WHICH of a
+ * step's selection will actually honour an option rather than only that something will.
+ *
+ * The question a person asks the moment a step holds two producers of one modality and one
+ * option: an aspect ratio honoured by one of them and ignored by the other is not a covered
+ * requirement in any useful sense, and coverage alone cannot say so. Ids come out in selection
+ * order and a capability with no declarer is absent, never an empty list, so "nobody" and "not
+ * asked" stay different answers.
+ */
+export declare function binaryCapabilityProviders(required: readonly BinaryGeneratorCapability[], selected: readonly {
+    id: string;
+    capabilities?: readonly BinaryGeneratorCapability[];
+}[]): {
+    capability: BinaryGeneratorCapability;
+    generatorIds: string[];
+}[];
+//# sourceMappingURL=binary-capabilities.d.ts.map

package/dist/binary-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-capabilities.d.ts","sourceRoot":"","sources":["../src/binary-capabilities.ts"],"names":[],"mappings":"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"}