@cat-factory/contracts 0.284.0 → 0.285.0

package/dist/agent-presentation.d.ts

@@ -93,7 +93,7 @@ export declare const agentPresentationSchema: v.ObjectSchema<{
      * to the deployment and paired on the frontend (an unpaired one degrades to the generic
      * panel — the `pairById` `missing` bucket). Omitted ⇒ the generic step-detail panel.
      */
-    readonly resultView: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["outcome", "requirements-review", "clarity-review", "brainstorm", "tester", "human-test", "visual-confirm", "gate", "consensus-session", "generic-structured", "service-spec", "follow-ups", "merger", "initiative-tracker", "initiative-planning", "doc-interview", "fork-decision", "judge", "pr-review", "ralph-loop"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
+    readonly resultView: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["outcome", "requirements-review", "clarity-review", "brainstorm", "tester", "human-test", "visual-confirm", "gate", "consensus-session", "generic-structured", "service-spec", "follow-ups", "merger", "initiative-tracker", "initiative-planning", "doc-interview", "fork-decision", "binary-candidates", "judge", "pr-review", "ralph-loop"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
 }, undefined>;
 export type AgentPresentation = v.InferOutput<typeof agentPresentationSchema>;
 /** A registered agent kind's id + presentation + whether it runs in a container — the
@@ -152,7 +152,7 @@ export declare const customAgentKindSchema: v.ObjectSchema<{
          * to the deployment and paired on the frontend (an unpaired one degrades to the generic
          * panel — the `pairById` `missing` bucket). Omitted ⇒ the generic step-detail panel.
          */
-        readonly resultView: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["outcome", "requirements-review", "clarity-review", "brainstorm", "tester", "human-test", "visual-confirm", "gate", "consensus-session", "generic-structured", "service-spec", "follow-ups", "merger", "initiative-tracker", "initiative-planning", "doc-interview", "fork-decision", "judge", "pr-review", "ralph-loop"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
+        readonly resultView: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["outcome", "requirements-review", "clarity-review", "brainstorm", "tester", "human-test", "visual-confirm", "gate", "consensus-session", "generic-structured", "service-spec", "follow-ups", "merger", "initiative-tracker", "initiative-planning", "doc-interview", "fork-decision", "binary-candidates", "judge", "pr-review", "ralph-loop"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
     }, undefined>;
     /** Whether the kind runs in a container (vs an inline LLM call). */
     readonly container: v.BooleanSchema<undefined>;

package/dist/binary-candidates.d.ts

@@ -0,0 +1,261 @@
+import * as v from 'valibot';
+/**
+ * The per-step comparison declaration: this step generates candidates and PARKS for a human.
+ *
+ * Its presence is the switch. There is no `enabled: false`, because a step that is not comparing
+ * carries nothing, and a disabled bag would be a saved configuration that describes a behaviour
+ * the run does not have.
+ */
+export declare const binaryCandidateComparisonSchema: v.ObjectSchema<{
+    /**
+     * How many candidates EACH selected integration should produce per subject. Defaults to one,
+     * which is the case the whole feature is named for: one render from each of the integrations
+     * that overlap.
+     *
+     * Above one it also covers the single-integration case, where the comparison is between seeds
+     * rather than between vendors. That is not a lesser use: a step holding one pixel-art API and
+     * asking for four candidates is exactly how a sprite gets picked, and refusing it would make
+     * the feature depend on a deployment happening to have bought two vendors.
+     */
+    readonly perGenerator: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 4, undefined>]>, undefined>;
+    /**
+     * Whether MORE THAN ONE candidate may be kept. Off by default: the ordinary case is a choice,
+     * and a picker that silently allowed two would leave a step delivering an artifact count nobody
+     * asked for.
+     *
+     * On, every kept candidate is stored under its own id (`storeAs`), which is what makes keeping
+     * two a real outcome rather than a collision: two files at one location is one file.
+     */
+    readonly multiSelect: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
+}, undefined>;
+export type BinaryCandidateComparison = v.InferOutput<typeof binaryCandidateComparisonSchema>;
+/**
+ * One generated candidate, as the agent declared it in its fenced ```binary-candidates block.
+ *
+ * `id` is engine-minted (`cand_*`) rather than taken from the reply: the id is what a human's
+ * choice names, so a model that repeats one, omits one, or writes a 4 KB one would break the
+ * decision rather than its own bookkeeping. What the agent DOES supply is `label`, which is how
+ * it refers to the candidate in its own prose, kept so the two records can be lined up.
+ */
+export declare const binaryCandidateSchema: v.ObjectSchema<{
+    /** Engine-minted stable id (`cand_*`), assigned when the declaration is recorded. */
+    readonly id: v.StringSchema<undefined>;
+    /** The agent's own name for this candidate, retained so its prose can be matched to the row. */
+    readonly label: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * The integration that produced it. Optional for the same reason the deliverable's own
+     * `generator` is (a model with native image output produces without a registered integration),
+     * and far more load-bearing here: with several producers in play it is the axis the human is
+     * comparing along, so a candidate that omits it is rendered as unattributed rather than
+     * silently attributed to the step's first integration.
+     */
+    readonly generator: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * What this candidate DEPICTS, in the agent's words (`product:tea-kettle`, `sprite:anvil`).
+     * Candidates are grouped by it, so a step that generated forty subjects renders forty
+     * comparisons rather than one wall of eighty images.
+     */
+    readonly subject: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /** The service the candidate was staged through, lowercased on read-back like a deliverable's. */
+    readonly service: v.StringSchema<undefined>;
+    /** Where it lives in that service's addressing, verbatim. */
+    readonly location: v.StringSchema<undefined>;
+    /** The media type the agent reports for it. */
+    readonly contentType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * A URL the SPA can render the candidate from, when the storage service issued one.
+     *
+     * ABSENT is a real and common state, not a failure: an org's asset store may be private, and
+     * the platform will not invent a link into it. The surface then renders the candidate's
+     * metadata and says the preview is unavailable, which is what lets a private estate use this
+     * feature at all. Constrained to `https` (or loopback) at parse time, because it is rendered
+     * in a browser from text a model wrote.
+     */
+    readonly previewUrl: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /** One line on what makes this candidate different, from the agent that made it. */
+    readonly note: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type BinaryCandidate = v.InferOutput<typeof binaryCandidateSchema>;
+/**
+ * Why a comparison step did NOT park, when it did not.
+ *
+ * Its own vocabulary rather than an absent state, because every member is a different fault with
+ * a different fix and all three end with the run advancing. A comparison that wedged a run on a
+ * model that forgot a fenced block would be a worse outcome than the one it exists to improve.
+ */
+export declare const binaryCandidateNoChoiceReasonSchema: v.PicklistSchema<["undeclared", "parse_failed", "no_candidates"], undefined>;
+export type BinaryCandidateNoChoiceReason = v.InferOutput<typeof binaryCandidateNoChoiceReasonSchema>;
+/**
+ * The candidate lifecycle on a comparison step:
+ * - `awaiting_choice`: parked; the human is comparing.
+ * - `chosen`: the human decided; the step re-runs and stores what survived.
+ * - `no_choice`: nothing to choose between, for one of the reasons above. No park.
+ */
+export declare const binaryCandidateStatusSchema: v.PicklistSchema<["awaiting_choice", "chosen", "no_choice"], undefined>;
+export type BinaryCandidateStatus = v.InferOutput<typeof binaryCandidateStatusSchema>;
+/** One candidate the human kept, and the id it is to be stored under. */
+export declare const binaryCandidateKeepSchema: v.ObjectSchema<{
+    readonly candidateId: v.StringSchema<undefined>;
+    /**
+     * The ALTERNATE ID this candidate is stored under, which is the whole mechanism behind keeping
+     * more than one: two survivors of one subject are two deliverables, and two deliverables need
+     * two addresses. Absent ⇒ the step's ordinary naming applies, which is correct for the single
+     * survivor and is why it is optional rather than defaulted to something invented.
+     */
+    readonly storeAs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, "must be a plain id (letters, digits, . _ -)">]>, undefined>;
+}, undefined>;
+export type BinaryCandidateKeep = v.InferOutput<typeof binaryCandidateKeepSchema>;
+/** The human's resolution, recorded on the step. */
+export declare const binaryCandidateChoiceSchema: v.ObjectSchema<{
+    readonly kept: v.ArraySchema<v.ObjectSchema<{
+        readonly candidateId: v.StringSchema<undefined>;
+        /**
+         * The ALTERNATE ID this candidate is stored under, which is the whole mechanism behind keeping
+         * more than one: two survivors of one subject are two deliverables, and two deliverables need
+         * two addresses. Absent ⇒ the step's ordinary naming applies, which is correct for the single
+         * survivor and is why it is optional rather than defaulted to something invented.
+         */
+        readonly storeAs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, "must be a plain id (letters, digits, . _ -)">]>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * The candidate ids that were NOT kept, recorded explicitly rather than derived by subtraction
+     * at read time. The surviving record must still say what was rejected once the step re-runs and
+     * the candidate list is the only thing left describing a generation nobody kept.
+     */
+    readonly discarded: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    /** Why, in the human's words. Folded into the re-run's brief so the agent knows what was wrong. */
+    readonly note: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /**
+     * Set when the engine kept the only candidate rather than parking, so NOBODY reviewed it.
+     *
+     * Its own flag rather than an absent decider, because the two are the same record and opposite
+     * facts: a surface that renders an auto-kept artifact as "chosen" is telling a reader that a
+     * person looked at this and approved it, which is exactly the claim this feature exists to make
+     * true. An auto-keep is a legitimate outcome and a quieter one, and it says so.
+     */
+    readonly automatic: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
+    readonly at: v.NumberSchema<undefined>;
+}, undefined>;
+export type BinaryCandidateChoice = v.InferOutput<typeof binaryCandidateChoiceSchema>;
+/**
+ * Live candidate-comparison state carried on the run's step. All of it rides `PipelineStep`, no
+ * side table, so D1 and Drizzle parity is free exactly as it is for `forkDecision` / `followUps`.
+ *
+ * The bookkeeping fields mirror `binaryOutputReportSchema`'s, and for the same reason: every way
+ * a candidate was lost is COUNTED rather than absorbed, so a comparison over three images that
+ * was meant to be over five does not read as a complete one.
+ */
+export declare const binaryCandidateStepStateSchema: v.ObjectSchema<{
+    readonly status: v.PicklistSchema<["awaiting_choice", "chosen", "no_choice"], undefined>;
+    readonly candidates: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        /** Engine-minted stable id (`cand_*`), assigned when the declaration is recorded. */
+        readonly id: v.StringSchema<undefined>;
+        /** The agent's own name for this candidate, retained so its prose can be matched to the row. */
+        readonly label: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * The integration that produced it. Optional for the same reason the deliverable's own
+         * `generator` is (a model with native image output produces without a registered integration),
+         * and far more load-bearing here: with several producers in play it is the axis the human is
+         * comparing along, so a candidate that omits it is rendered as unattributed rather than
+         * silently attributed to the step's first integration.
+         */
+        readonly generator: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * What this candidate DEPICTS, in the agent's words (`product:tea-kettle`, `sprite:anvil`).
+         * Candidates are grouped by it, so a step that generated forty subjects renders forty
+         * comparisons rather than one wall of eighty images.
+         */
+        readonly subject: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /** The service the candidate was staged through, lowercased on read-back like a deliverable's. */
+        readonly service: v.StringSchema<undefined>;
+        /** Where it lives in that service's addressing, verbatim. */
+        readonly location: v.StringSchema<undefined>;
+        /** The media type the agent reports for it. */
+        readonly contentType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * A URL the SPA can render the candidate from, when the storage service issued one.
+         *
+         * ABSENT is a real and common state, not a failure: an org's asset store may be private, and
+         * the platform will not invent a link into it. The surface then renders the candidate's
+         * metadata and says the preview is unavailable, which is what lets a private estate use this
+         * feature at all. Constrained to `https` (or loopback) at parse time, because it is rendered
+         * in a browser from text a model wrote.
+         */
+        readonly previewUrl: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /** One line on what makes this candidate different, from the agent that made it. */
+        readonly note: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>, readonly []>;
+    /** Set only when `status` is `no_choice`. */
+    readonly noChoiceReason: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["undeclared", "parse_failed", "no_candidates"], undefined>, undefined>, undefined>;
+    /** Set once the human decides. */
+    readonly choice: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
+        readonly kept: v.ArraySchema<v.ObjectSchema<{
+            readonly candidateId: v.StringSchema<undefined>;
+            /**
+             * The ALTERNATE ID this candidate is stored under, which is the whole mechanism behind keeping
+             * more than one: two survivors of one subject are two deliverables, and two deliverables need
+             * two addresses. Absent ⇒ the step's ordinary naming applies, which is correct for the single
+             * survivor and is why it is optional rather than defaulted to something invented.
+             */
+            readonly storeAs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, "must be a plain id (letters, digits, . _ -)">]>, undefined>;
+        }, undefined>, undefined>;
+        /**
+         * The candidate ids that were NOT kept, recorded explicitly rather than derived by subtraction
+         * at read time. The surviving record must still say what was rejected once the step re-runs and
+         * the candidate list is the only thing left describing a generation nobody kept.
+         */
+        readonly discarded: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        /** Why, in the human's words. Folded into the re-run's brief so the agent knows what was wrong. */
+        readonly note: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        /**
+         * Set when the engine kept the only candidate rather than parking, so NOBODY reviewed it.
+         *
+         * Its own flag rather than an absent decider, because the two are the same record and opposite
+         * facts: a surface that renders an auto-kept artifact as "chosen" is telling a reader that a
+         * person looked at this and approved it, which is exactly the claim this feature exists to make
+         * true. An auto-keep is a legitimate outcome and a quieter one, and it says so.
+         */
+        readonly automatic: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
+        readonly at: v.NumberSchema<undefined>;
+    }, undefined>, undefined>, undefined>;
+    /** Whether more than one candidate may be kept, frozen from the step's config at record time
+     *  so the resolver judges the request against the rule the human was actually shown. */
+    readonly multiSelect: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    /** Declared entries dropped because they were not `{ service, location }` objects. */
+    readonly invalidEntries: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+    /** Valid entries dropped past the per-step cap, so `candidates` is a PREFIX. */
+    readonly omitted: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+    /** Preview URLs dropped because they were not an `https`/loopback URL. The candidate is kept
+     *  and rendered without a preview: a refused link is not a refused candidate. */
+    readonly unusablePreviews: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+}, undefined>;
+export type BinaryCandidateStepState = v.InferOutput<typeof binaryCandidateStepStateSchema>;
+/**
+ * Keep one or more candidates and discard the rest.
+ *
+ * At least one must be kept: "discard everything" is a different act (it means the generation was
+ * a failure), and answering it through this verb would re-run the step to store nothing while
+ * reporting a completed choice. A step whose candidates are all bad is retried or reworked
+ * through the surfaces that already exist for that.
+ */
+export declare const keepBinaryCandidatesSchema: v.ObjectSchema<{
+    readonly keep: v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
+        readonly candidateId: v.StringSchema<undefined>;
+        /**
+         * The ALTERNATE ID this candidate is stored under, which is the whole mechanism behind keeping
+         * more than one: two survivors of one subject are two deliverables, and two deliverables need
+         * two addresses. Absent ⇒ the step's ordinary naming applies, which is correct for the single
+         * survivor and is why it is optional rather than defaulted to something invented.
+         */
+        readonly storeAs: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 64, undefined>, v.RegexAction<string, "must be a plain id (letters, digits, . _ -)">]>, undefined>;
+    }, undefined>, undefined>, v.MinLengthAction<{
+        candidateId: string;
+        storeAs?: string | undefined;
+    }[], 1, undefined>, v.MaxLengthAction<{
+        candidateId: string;
+        storeAs?: string | undefined;
+    }[], 16, undefined>]>;
+    readonly note: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 4000, undefined>]>, undefined>;
+}, undefined>;
+export type KeepBinaryCandidatesInput = v.InferOutput<typeof keepBinaryCandidatesSchema>;
+//# sourceMappingURL=binary-candidates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"binary-candidates.d.ts","sourceRoot":"","sources":["../src/binary-candidates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAmC5B;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B;IAC1C;;;;;;;;;OASG;;IAEH;;;;;;;OAOG;;aAEH,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,+BAA+B,CAAC,CAAA;AAE7F;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;IAChC,qFAAqF;;IAErF,gGAAgG;;IAEhG;;;;;;OAMG;;IAEH;;;;OAIG;;IAEH,kGAAkG;;IAElG,6DAA6D;;IAE7D,+CAA+C;;IAE/C;;;;;;;;OAQG;;IAEH,oFAAoF;;aAEpF,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,8EAa9C,CAAA;AACF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,WAAW,CACvD,OAAO,mCAAmC,CAC3C,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,yEAAyD,CAAA;AACjG,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF,yEAAyE;AACzE,eAAO,MAAM,yBAAyB;;IAEpC;;;;;OAKG;;aAEH,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,oDAAoD;AACpD,eAAO,MAAM,2BAA2B;;;QAXtC;;;;;WAKG;;;IAQH;;;;OAIG;;IAEH,mGAAmG;;IAEnG;;;;;;;OAOG;;;aAGH,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B;;;QAtHzC,qFAAqF;;QAErF,gGAAgG;;QAEhG;;;;;;WAMG;;QAEH;;;;WAIG;;QAEH,kGAAkG;;QAElG,6DAA6D;;QAE7D,+CAA+C;;QAE/C;;;;;;;;WAQG;;QAEH,oFAAoF;;;IAuFpF,6CAA6C;;IAE7C,kCAAkC;;;;YA/ClC;;;;;eAKG;;;QAQH;;;;WAIG;;QAEH,mGAAmG;;QAEnG;;;;;;;WAOG;;;;IAqBH;4FACwF;;IAExF,sFAAsF;;IAEtF,gFAAgF;;IAEhF;qFACiF;;aAEjF,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAA;AAI3F;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;QAxErC;;;;;WAKG;;;;;;;;;;aAsEH,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA"}

package/dist/binary-candidates.js

@@ -0,0 +1,202 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// SIDE-BY-SIDE CANDIDATE COMPARISON for a binary-output step.
+//
+// A step may select several generative integrations that produce the same content type. The
+// design record states the overlap to both the agent and the step's author and deliberately ranks
+// nothing, because the platform has no cost model, no quality model and no view of what the step
+// is for. That is the right answer while the choice has to be made BEFORE the pictures exist.
+//
+// It is the wrong answer when it does not. Two image APIs asked for the same sprite return two
+// sprites, and a person looking at them decides in a second what no description could have
+// decided in advance. So a step may instead declare a COMPARISON: generate a candidate from every
+// selected integration, park, and let a human keep one, or keep several under DISTINCT ids.
+//
+// Two properties are load-bearing and both follow from the rest of the feature:
+//
+// - **The platform never holds the bytes.** Candidates are staged through the step's own storage
+//   service exactly as deliverables are, and what the SPA renders is whatever preview URL that
+//   service reported. A service that reports none leaves the candidate legible as metadata and
+//   says the preview is unavailable, which is a different fact from a candidate that failed.
+// - **The decision is DATA, and the agent executes it.** Keeping a candidate does not move a file:
+//   it records which candidates survive and under which id, and the step re-runs with that
+//   folded into its brief. The platform's own artifact store is for run evidence, and a product
+//   asset it never touched is not something it should start touching to implement a picker.
+// ---------------------------------------------------------------------------
+const candidateSlug = v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(64), v.regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'must be a plain id (letters, digits, . _ -)'));
+/**
+ * The per-step comparison declaration: this step generates candidates and PARKS for a human.
+ *
+ * Its presence is the switch. There is no `enabled: false`, because a step that is not comparing
+ * carries nothing, and a disabled bag would be a saved configuration that describes a behaviour
+ * the run does not have.
+ */
+export const binaryCandidateComparisonSchema = v.object({
+    /**
+     * How many candidates EACH selected integration should produce per subject. Defaults to one,
+     * which is the case the whole feature is named for: one render from each of the integrations
+     * that overlap.
+     *
+     * Above one it also covers the single-integration case, where the comparison is between seeds
+     * rather than between vendors. That is not a lesser use: a step holding one pixel-art API and
+     * asking for four candidates is exactly how a sprite gets picked, and refusing it would make
+     * the feature depend on a deployment happening to have bought two vendors.
+     */
+    perGenerator: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(4))),
+    /**
+     * Whether MORE THAN ONE candidate may be kept. Off by default: the ordinary case is a choice,
+     * and a picker that silently allowed two would leave a step delivering an artifact count nobody
+     * asked for.
+     *
+     * On, every kept candidate is stored under its own id (`storeAs`), which is what makes keeping
+     * two a real outcome rather than a collision: two files at one location is one file.
+     */
+    multiSelect: v.optional(v.literal(true)),
+});
+/**
+ * One generated candidate, as the agent declared it in its fenced ```binary-candidates block.
+ *
+ * `id` is engine-minted (`cand_*`) rather than taken from the reply: the id is what a human's
+ * choice names, so a model that repeats one, omits one, or writes a 4 KB one would break the
+ * decision rather than its own bookkeeping. What the agent DOES supply is `label`, which is how
+ * it refers to the candidate in its own prose, kept so the two records can be lined up.
+ */
+export const binaryCandidateSchema = v.object({
+    /** Engine-minted stable id (`cand_*`), assigned when the declaration is recorded. */
+    id: v.string(),
+    /** The agent's own name for this candidate, retained so its prose can be matched to the row. */
+    label: v.optional(v.string()),
+    /**
+     * The integration that produced it. Optional for the same reason the deliverable's own
+     * `generator` is (a model with native image output produces without a registered integration),
+     * and far more load-bearing here: with several producers in play it is the axis the human is
+     * comparing along, so a candidate that omits it is rendered as unattributed rather than
+     * silently attributed to the step's first integration.
+     */
+    generator: v.optional(v.string()),
+    /**
+     * What this candidate DEPICTS, in the agent's words (`product:tea-kettle`, `sprite:anvil`).
+     * Candidates are grouped by it, so a step that generated forty subjects renders forty
+     * comparisons rather than one wall of eighty images.
+     */
+    subject: v.optional(v.string()),
+    /** The service the candidate was staged through, lowercased on read-back like a deliverable's. */
+    service: v.string(),
+    /** Where it lives in that service's addressing, verbatim. */
+    location: v.string(),
+    /** The media type the agent reports for it. */
+    contentType: v.optional(v.string()),
+    /**
+     * A URL the SPA can render the candidate from, when the storage service issued one.
+     *
+     * ABSENT is a real and common state, not a failure: an org's asset store may be private, and
+     * the platform will not invent a link into it. The surface then renders the candidate's
+     * metadata and says the preview is unavailable, which is what lets a private estate use this
+     * feature at all. Constrained to `https` (or loopback) at parse time, because it is rendered
+     * in a browser from text a model wrote.
+     */
+    previewUrl: v.optional(v.string()),
+    /** One line on what makes this candidate different, from the agent that made it. */
+    note: v.optional(v.string()),
+});
+/**
+ * Why a comparison step did NOT park, when it did not.
+ *
+ * Its own vocabulary rather than an absent state, because every member is a different fault with
+ * a different fix and all three end with the run advancing. A comparison that wedged a run on a
+ * model that forgot a fenced block would be a worse outcome than the one it exists to improve.
+ */
+export const binaryCandidateNoChoiceReasonSchema = v.picklist([
+    /** The reply carried no ```binary-candidates block at all. A prompt/model problem. */
+    'undeclared',
+    /** A block was present and its body was not parseable. */
+    'parse_failed',
+    /**
+     * The block was read and NO candidate survived it: the agent staged nothing, or every entry it
+     * declared was malformed. Deliberately not "fewer than two": a single candidate is auto-kept
+     * (see {@link BinaryCandidateChoice.automatic}) rather than treated as a failed comparison,
+     * mirroring the fork decision's single-path escape hatch. Nobody is asked to choose between one
+     * thing, and discarding a real generation because it had no rival would be the worse outcome.
+     */
+    'no_candidates',
+]);
+/**
+ * The candidate lifecycle on a comparison step:
+ * - `awaiting_choice`: parked; the human is comparing.
+ * - `chosen`: the human decided; the step re-runs and stores what survived.
+ * - `no_choice`: nothing to choose between, for one of the reasons above. No park.
+ */
+export const binaryCandidateStatusSchema = v.picklist(['awaiting_choice', 'chosen', 'no_choice']);
+/** One candidate the human kept, and the id it is to be stored under. */
+export const binaryCandidateKeepSchema = v.object({
+    candidateId: v.string(),
+    /**
+     * The ALTERNATE ID this candidate is stored under, which is the whole mechanism behind keeping
+     * more than one: two survivors of one subject are two deliverables, and two deliverables need
+     * two addresses. Absent ⇒ the step's ordinary naming applies, which is correct for the single
+     * survivor and is why it is optional rather than defaulted to something invented.
+     */
+    storeAs: v.optional(candidateSlug),
+});
+/** The human's resolution, recorded on the step. */
+export const binaryCandidateChoiceSchema = v.object({
+    kept: v.array(binaryCandidateKeepSchema),
+    /**
+     * The candidate ids that were NOT kept, recorded explicitly rather than derived by subtraction
+     * at read time. The surviving record must still say what was rejected once the step re-runs and
+     * the candidate list is the only thing left describing a generation nobody kept.
+     */
+    discarded: v.array(v.string()),
+    /** Why, in the human's words. Folded into the re-run's brief so the agent knows what was wrong. */
+    note: v.optional(v.nullable(v.string())),
+    /**
+     * Set when the engine kept the only candidate rather than parking, so NOBODY reviewed it.
+     *
+     * Its own flag rather than an absent decider, because the two are the same record and opposite
+     * facts: a surface that renders an auto-kept artifact as "chosen" is telling a reader that a
+     * person looked at this and approved it, which is exactly the claim this feature exists to make
+     * true. An auto-keep is a legitimate outcome and a quieter one, and it says so.
+     */
+    automatic: v.optional(v.literal(true)),
+    at: v.number(),
+});
+/**
+ * Live candidate-comparison state carried on the run's step. All of it rides `PipelineStep`, no
+ * side table, so D1 and Drizzle parity is free exactly as it is for `forkDecision` / `followUps`.
+ *
+ * The bookkeeping fields mirror `binaryOutputReportSchema`'s, and for the same reason: every way
+ * a candidate was lost is COUNTED rather than absorbed, so a comparison over three images that
+ * was meant to be over five does not read as a complete one.
+ */
+export const binaryCandidateStepStateSchema = v.object({
+    status: binaryCandidateStatusSchema,
+    candidates: v.optional(v.array(binaryCandidateSchema), []),
+    /** Set only when `status` is `no_choice`. */
+    noChoiceReason: v.optional(v.nullable(binaryCandidateNoChoiceReasonSchema)),
+    /** Set once the human decides. */
+    choice: v.optional(v.nullable(binaryCandidateChoiceSchema)),
+    /** Whether more than one candidate may be kept, frozen from the step's config at record time
+     *  so the resolver judges the request against the rule the human was actually shown. */
+    multiSelect: v.optional(v.boolean()),
+    /** Declared entries dropped because they were not `{ service, location }` objects. */
+    invalidEntries: v.optional(v.number(), 0),
+    /** Valid entries dropped past the per-step cap, so `candidates` is a PREFIX. */
+    omitted: v.optional(v.number(), 0),
+    /** Preview URLs dropped because they were not an `https`/loopback URL. The candidate is kept
+     *  and rendered without a preview: a refused link is not a refused candidate. */
+    unusablePreviews: v.optional(v.number(), 0),
+});
+// ---- Request bodies -------------------------------------------------------
+/**
+ * Keep one or more candidates and discard the rest.
+ *
+ * At least one must be kept: "discard everything" is a different act (it means the generation was
+ * a failure), and answering it through this verb would re-run the step to store nothing while
+ * reporting a completed choice. A step whose candidates are all bad is retried or reworked
+ * through the surfaces that already exist for that.
+ */
+export const keepBinaryCandidatesSchema = v.object({
+    keep: v.pipe(v.array(binaryCandidateKeepSchema), v.minLength(1), v.maxLength(16)),
+    note: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(4000))),
+});
+//# sourceMappingURL=binary-candidates.js.map

package/dist/binary-candidates.js.map

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