@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/flows-actors/deliberation.shared.schemas.d.ts

@@ -0,0 +1,642 @@
+import { z } from "zod";
+import { FlowsActors_IO_PartKind } from "./flows-actors.io.shared.schemas";
+/**
+ * The narrow work-product domain an expert persona is specialized on —
+ * the ROUTING AXIS of the narrowness principle. An expert declares a
+ * small closed set of domains; the deliberation orchestrator REFUSES to
+ * invoke an expert outside its declared domains (fail-closed).
+ *
+ * Deliberate design: agent personas are NARROW, unlike human employees
+ * who wear several hats. A review needing three angles convenes three
+ * experts + a coordinator, never one generalist.
+ *
+ * Single-sourced HERE (the spec-tier `expert-personas` family imports
+ * this enum) so the vocabulary cannot drift across tiers. Extend
+ * per-capability as new deliberation domains ship — never speculatively.
+ */
+export declare enum ExpertWorkDomain {
+    /** Visual brand marks: logo symbols, icons, brand imagery. */
+    VISUAL_BRAND_MARK = "visual_brand_mark",
+    /** Marketing / product copy: website sections, email prose, taglines. */
+    MARKETING_COPY = "marketing_copy",
+    /** UI/design-system coherence: tokens, palette, typography discipline. */
+    UI_DESIGN_COHERENCE = "ui_design_coherence",
+    /** Brand strategy: positioning fit, differentiation, ICP resonance. */
+    BRAND_STRATEGY = "brand_strategy",
+    /**
+     * Information architecture: WHERE a destination, operation or view belongs in
+     * the application shell — surface assignment, grouping, ordering, findability.
+     *
+     * Distinct from {@link UI_DESIGN_COHERENCE}, which is tokens, palette and
+     * typography discipline. A settings section can be perfectly on-palette and
+     * still be in the wrong place; "can a user find this, and does it sit with the
+     * things it belongs with" is a different question with a different expert.
+     *
+     * Added 2026-08-29, when placement became a deliberated decision rather than a
+     * framework default — per this enum's rule, per-capability and never
+     * speculatively.
+     */
+    INFORMATION_ARCHITECTURE = "information_architecture"
+}
+/**
+ * A reviewer's headline recommendation for one candidate. Deliberately
+ * the same three-state vocabulary as the interim brand accept judge —
+ * accept as-is / fixable via revision / materially misses the brief.
+ */
+export declare enum DeliberationRecommendation {
+    /** The candidate satisfies the rubric and can win as-is. */
+    ACCEPT = "accept",
+    /** Close, but has fixable concerns — revise before it can win. */
+    REVISE = "revise",
+    /** Materially misses the rubric — should not survive the shortlist. */
+    REJECT = "reject"
+}
+/** How a candidate entered a round's candidate set. */
+export declare enum DeliberationCandidateProvenance {
+    /** Produced in round 1 from the creative brief. */
+    ORIGINAL = "original",
+    /** Produced by a critique-driven revision of a prior candidate. */
+    REVISED = "revised"
+}
+/** Terminal + live states of a deliberation. */
+export declare enum DeliberationStatus {
+    /** Rounds are still executing. */
+    RUNNING = "running",
+    /** The coordinator judged the outcome converged before budget. */
+    CONVERGED = "converged",
+    /** The round budget was exhausted; synthesis used the last round. */
+    BUDGET_EXHAUSTED = "budget_exhausted",
+    /** The deliberation could not complete (provider/validation failure). */
+    FAILED = "failed",
+    /**
+     * Every candidate was REJECTED by the panel. There is no winner, and that is a
+     * RESULT — not a failure.
+     *
+     * Distinct from {@link FAILED}, which means the machinery could not complete;
+     * here it completed and the answer is "none of these". Distinct from
+     * {@link CONVERGED}, which asserts a winner. Collapsing rejection into either
+     * would be the defect this state exists to remove: a coordinator asked to pick a
+     * winner will pick one, so without a terminal rejection the least-bad candidate
+     * of a uniformly rejected field lands carrying the panel's authority.
+     *
+     * A record in this state carries no `synthesis`. The caller decides what to do —
+     * retry with a new brief, widen the candidate set, or surface the critiques —
+     * because only the caller knows whether "none of these" is recoverable.
+     */
+    REJECTED = "rejected"
+}
+/**
+ * The runtime projection of an `ExpertPersonaCharter` — everything the
+ * engine deliberation machinery needs of a persona, WITHOUT importing the
+ * spec tier (same pattern as the runtime brand-asset siblings). The
+ * COMPANION (which imports both tiers) maps charter → profile when
+ * composing a deliberation plan, and builds the expert's agent from it at
+ * startup (fail-closed when the charter is missing/unaccepted).
+ */
+declare const _RuntimeExpertProfileSchema: z.ZodObject<{
+    charterRef: z.ZodString;
+    roleRef: z.ZodString;
+    workDomains: z.ZodArray<z.ZodEnum<typeof ExpertWorkDomain>>;
+    personaProse: z.ZodString;
+    priorities: z.ZodArray<z.ZodString>;
+    taboos: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    qualityBar: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    reviewProtocol: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const RuntimeExpertProfileSchema: typeof _RuntimeExpertProfileSchema;
+export type RuntimeExpertProfile = z.infer<typeof _RuntimeExpertProfileSchema>;
+/**
+ * One derived evaluation criterion. `ref` is the join key verdicts score
+ * against; `weight` feeds the DETERMINISTIC aggregation (never model
+ * arithmetic); `scaleAnchors` pin what the scale ends MEAN so two
+ * reviewers score commensurably.
+ */
+declare const _EvaluationCriterionSchema: z.ZodObject<{
+    ref: z.ZodString;
+    description: z.ZodString;
+    weight: z.ZodNumber;
+    scaleAnchors: z.ZodObject<{
+        low: z.ZodString;
+        high: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const EvaluationCriterionSchema: typeof _EvaluationCriterionSchema;
+export type EvaluationCriterion = z.infer<typeof _EvaluationCriterionSchema>;
+/**
+ * The DERIVED rubric a deliberation evaluates against. Derived ONCE at
+ * deliberation start by the responsible expert persona (per-run — locked
+ * decision), held CONSTANT across that deliberation's rounds (revise
+ * targets must not move mid-discussion), and EMBEDDED in the
+ * `DeliberationRecord` (auditability without a standalone artifact).
+ * Never persisted as its own resource.
+ */
+declare const _EvaluationRubricSchema: z.ZodObject<{
+    workDomain: z.ZodEnum<typeof ExpertWorkDomain>;
+    derivedFromCharterRef: z.ZodString;
+    criteria: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        description: z.ZodString;
+        weight: z.ZodNumber;
+        scaleAnchors: z.ZodObject<{
+            low: z.ZodString;
+            high: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    derivedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const EvaluationRubricSchema: typeof _EvaluationRubricSchema;
+export type EvaluationRubric = z.infer<typeof _EvaluationRubricSchema>;
+/**
+ * One criterion score inside a verdict. `criterionRef` MUST match a
+ * rubric criterion — enforced fail-closed by
+ * `validateVerdictCriterionRefs` (a hallucinated ref rejects the verdict,
+ * one retry with the error surfaced, then the reviewer is dropped from
+ * the round with a quorum note).
+ */
+declare const _RubricScoreSchema: z.ZodObject<{
+    criterionRef: z.ZodString;
+    score: z.ZodNumber;
+    note: z.ZodString;
+}, z.core.$strip>;
+export declare const RubricScoreSchema: typeof _RubricScoreSchema;
+export type RubricScore = z.infer<typeof _RubricScoreSchema>;
+/**
+ * One actionable critique inside a verdict — the REVISION FUEL. The
+ * producer's revise step compiles the shortlist's critiques into the
+ * revision (text: rewrite the draft; image: a regeneration prompt
+ * addendum — the image transport has no edit operation).
+ */
+declare const _RubricCritiqueSchema: z.ZodObject<{
+    targetAspect: z.ZodString;
+    critique: z.ZodString;
+    suggestion: z.ZodString;
+}, z.core.$strip>;
+export declare const RubricCritiqueSchema: typeof _RubricCritiqueSchema;
+export type RubricCritique = z.infer<typeof _RubricCritiqueSchema>;
+/**
+ * One reviewer's verdict on one candidate — the GENERIC,
+ * strict-structured-output-safe judge contract (flat, all-required,
+ * ref-keyed; "nothing to report" is an empty array, never an absent key).
+ * This is the schema handed to the LLM; the rubric it scores against
+ * travels in the PROMPT.
+ */
+declare const _RubricVerdictSchema: z.ZodObject<{
+    reviewerCharterRef: z.ZodString;
+    candidateRef: z.ZodString;
+    scores: z.ZodArray<z.ZodObject<{
+        criterionRef: z.ZodString;
+        score: z.ZodNumber;
+        note: z.ZodString;
+    }, z.core.$strip>>;
+    recommendation: z.ZodEnum<typeof DeliberationRecommendation>;
+    critiques: z.ZodArray<z.ZodObject<{
+        targetAspect: z.ZodString;
+        critique: z.ZodString;
+        suggestion: z.ZodString;
+    }, z.core.$strip>>;
+    overallNote: z.ZodString;
+}, z.core.$strip>;
+export declare const RubricVerdictSchema: typeof _RubricVerdictSchema;
+export type RubricVerdict = z.infer<typeof _RubricVerdictSchema>;
+declare const _DeliberationCandidateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ref: z.ZodString;
+    provenance: z.ZodLiteral<DeliberationCandidateProvenance.ORIGINAL>;
+    storageRef: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    ref: z.ZodString;
+    provenance: z.ZodLiteral<DeliberationCandidateProvenance.REVISED>;
+    revisedFromRef: z.ZodString;
+    revisionPrompt: z.ZodString;
+    storageRef: z.ZodString;
+}, z.core.$strip>], "provenance">;
+export declare const DeliberationCandidateSchema: typeof _DeliberationCandidateSchema;
+export type DeliberationCandidate = z.infer<typeof _DeliberationCandidateSchema>;
+/**
+ * One critique-revise round: the candidate set reviewed, every verdict
+ * collected, and the coordinator's shortlist (the COST SPINE — round 1
+ * reviews the full set, the coordinator shortlists top-K, rounds 2+
+ * operate on the shortlist only; the panel never re-litigates eliminated
+ * options).
+ */
+declare const _DeliberationRoundSchema: z.ZodObject<{
+    roundNumber: z.ZodNumber;
+    candidateSet: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        ref: z.ZodString;
+        provenance: z.ZodLiteral<DeliberationCandidateProvenance.ORIGINAL>;
+        storageRef: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        ref: z.ZodString;
+        provenance: z.ZodLiteral<DeliberationCandidateProvenance.REVISED>;
+        revisedFromRef: z.ZodString;
+        revisionPrompt: z.ZodString;
+        storageRef: z.ZodString;
+    }, z.core.$strip>], "provenance">>;
+    verdicts: z.ZodArray<z.ZodObject<{
+        reviewerCharterRef: z.ZodString;
+        candidateRef: z.ZodString;
+        scores: z.ZodArray<z.ZodObject<{
+            criterionRef: z.ZodString;
+            score: z.ZodNumber;
+            note: z.ZodString;
+        }, z.core.$strip>>;
+        recommendation: z.ZodEnum<typeof DeliberationRecommendation>;
+        critiques: z.ZodArray<z.ZodObject<{
+            targetAspect: z.ZodString;
+            critique: z.ZodString;
+            suggestion: z.ZodString;
+        }, z.core.$strip>>;
+        overallNote: z.ZodString;
+    }, z.core.$strip>>;
+    shortlistRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const DeliberationRoundSchema: typeof _DeliberationRoundSchema;
+export type DeliberationRound = z.infer<typeof _DeliberationRoundSchema>;
+/** A dissenting position preserved in the synthesis (never averaged away). */
+declare const _DeliberationDissentSchema: z.ZodObject<{
+    charterRef: z.ZodString;
+    position: z.ZodString;
+}, z.core.$strip>;
+export declare const DeliberationDissentSchema: typeof _DeliberationDissentSchema;
+export type DeliberationDissent = z.infer<typeof _DeliberationDissentSchema>;
+/**
+ * The coordinator's synthesis — the "manager's" decision over the panel:
+ * a winner, the grounded rationale, and every preserved dissent.
+ * ADVISORY: the human decision seam on the record is the authority.
+ */
+declare const _DeliberationSynthesisSchema: z.ZodObject<{
+    winnerRef: z.ZodString;
+    rationale: z.ZodString;
+    dissent: z.ZodArray<z.ZodObject<{
+        charterRef: z.ZodString;
+        position: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const DeliberationSynthesisSchema: typeof _DeliberationSynthesisSchema;
+export type DeliberationSynthesis = z.infer<typeof _DeliberationSynthesisSchema>;
+/**
+ * DETERMINISTIC lens accounting for the winner — computed by the machinery from the
+ * final round's verdicts, never asked of a model.
+ *
+ * The floor and the coverage rules guarantee the winner was scored by every required
+ * lens. What they cannot show is HOW those lenses split, and that is the difference
+ * between consensus and a bare majority: "two lenses accepted" and "one accepted, one
+ * wanted revision" produce an identical `synthesis`, because the coordinator writes
+ * prose and prose can round a split into agreement.
+ *
+ * Kept OUT of {@link DeliberationSynthesis} on purpose. That object is model-generated;
+ * a count that can be generated is a count that can be wrong, and the whole point here
+ * is a number a reader can trust without re-reading every verdict.
+ */
+declare const _DeliberationConcurrenceSchema: z.ZodObject<{
+    winnerRef: z.ZodString;
+    lensCount: z.ZodNumber;
+    byRecommendation: z.ZodObject<{
+        accept: z.ZodNumber;
+        revise: z.ZodNumber;
+        reject: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const DeliberationConcurrenceSchema: typeof _DeliberationConcurrenceSchema;
+export type DeliberationConcurrence = z.infer<typeof _DeliberationConcurrenceSchema>;
+/** Who sat at the table. */
+declare const _DeliberationParticipantsSchema: z.ZodObject<{
+    producerAgentRef: z.ZodString;
+    reviewerCharterRefs: z.ZodArray<z.ZodString>;
+    coordinatorCharterRef: z.ZodString;
+}, z.core.$strip>;
+export declare const DeliberationParticipantsSchema: typeof _DeliberationParticipantsSchema;
+export type DeliberationParticipants = z.infer<typeof _DeliberationParticipantsSchema>;
+/** The human decision over an advisory synthesis (the actual authority). */
+declare const _DeliberationHumanDecisionSchema: z.ZodObject<{
+    decision: z.ZodString;
+    decidedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const DeliberationHumanDecisionSchema: typeof _DeliberationHumanDecisionSchema;
+export type DeliberationHumanDecision = z.infer<typeof _DeliberationHumanDecisionSchema>;
+/**
+ * The full minutes of one deliberation — rubric (embedded, constant),
+ * participants, every round with every verdict, the synthesis, and the
+ * human decision seam.
+ *
+ * PERSISTENCE: a deliberation is a BUILD-TIME companion artifact. The
+ * engine machinery RETURNS this record and never persists it; the
+ * companion writes it to its staging area
+ * (`.wildo-saas/generated/deliberations/`). It is deliberately NOT hosted
+ * on the flows-actors execution resources (`user`/`organization`/`applicationFlowActorExecutions`)
+ * — those are scope-owned RUNTIME data (conversational history), the wrong tier
+ * for build-time creative decisions.
+ */
+declare const _DeliberationRecordSchema: z.ZodObject<{
+    deliberationRef: z.ZodString;
+    workDomain: z.ZodEnum<typeof ExpertWorkDomain>;
+    subjectKind: z.ZodEnum<typeof FlowsActors_IO_PartKind>;
+    rubric: z.ZodObject<{
+        workDomain: z.ZodEnum<typeof ExpertWorkDomain>;
+        derivedFromCharterRef: z.ZodString;
+        criteria: z.ZodArray<z.ZodObject<{
+            ref: z.ZodString;
+            description: z.ZodString;
+            weight: z.ZodNumber;
+            scaleAnchors: z.ZodObject<{
+                low: z.ZodString;
+                high: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        derivedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    participants: z.ZodObject<{
+        producerAgentRef: z.ZodString;
+        reviewerCharterRefs: z.ZodArray<z.ZodString>;
+        coordinatorCharterRef: z.ZodString;
+    }, z.core.$strip>;
+    rounds: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        roundNumber: z.ZodNumber;
+        candidateSet: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            ref: z.ZodString;
+            provenance: z.ZodLiteral<DeliberationCandidateProvenance.ORIGINAL>;
+            storageRef: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            ref: z.ZodString;
+            provenance: z.ZodLiteral<DeliberationCandidateProvenance.REVISED>;
+            revisedFromRef: z.ZodString;
+            revisionPrompt: z.ZodString;
+            storageRef: z.ZodString;
+        }, z.core.$strip>], "provenance">>;
+        verdicts: z.ZodArray<z.ZodObject<{
+            reviewerCharterRef: z.ZodString;
+            candidateRef: z.ZodString;
+            scores: z.ZodArray<z.ZodObject<{
+                criterionRef: z.ZodString;
+                score: z.ZodNumber;
+                note: z.ZodString;
+            }, z.core.$strip>>;
+            recommendation: z.ZodEnum<typeof DeliberationRecommendation>;
+            critiques: z.ZodArray<z.ZodObject<{
+                targetAspect: z.ZodString;
+                critique: z.ZodString;
+                suggestion: z.ZodString;
+            }, z.core.$strip>>;
+            overallNote: z.ZodString;
+        }, z.core.$strip>>;
+        shortlistRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    concurrence: z.ZodOptional<z.ZodObject<{
+        winnerRef: z.ZodString;
+        lensCount: z.ZodNumber;
+        byRecommendation: z.ZodObject<{
+            accept: z.ZodNumber;
+            revise: z.ZodNumber;
+            reject: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    synthesis: z.ZodOptional<z.ZodObject<{
+        winnerRef: z.ZodString;
+        rationale: z.ZodString;
+        dissent: z.ZodArray<z.ZodObject<{
+            charterRef: z.ZodString;
+            position: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    roundBudget: z.ZodNumber;
+    status: z.ZodEnum<typeof DeliberationStatus>;
+    charterInputsDigests: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    humanDecision: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        decision: z.ZodString;
+        decidedAt: z.ZodISODateTime;
+    }, z.core.$strip>>>;
+    startedAt: z.ZodISODateTime;
+    finishedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>;
+export declare const DeliberationRecordSchema: typeof _DeliberationRecordSchema;
+export type DeliberationRecord = z.infer<typeof _DeliberationRecordSchema>;
+/**
+ * Rubric-derivation pass output: the criteria only. The machinery stamps
+ * `workDomain` / `derivedFromCharterRef` / `derivedAt` and validates the
+ * assembled rubric through `EvaluationRubricSchema` (unique-ref refine).
+ */
+declare const _DeliberationRubricOutputSchema: z.ZodObject<{
+    criteria: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        description: z.ZodString;
+        weight: z.ZodNumber;
+        scaleAnchors: z.ZodObject<{
+            low: z.ZodString;
+            high: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const DeliberationRubricOutputSchema: typeof _DeliberationRubricOutputSchema;
+export type DeliberationRubricOutput = z.infer<typeof _DeliberationRubricOutputSchema>;
+declare const _DeliberationRubricOutputStrictSchema: z.ZodObject<{
+    criteria: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        description: z.ZodString;
+        weight: z.ZodNumber;
+        scaleAnchors: z.ZodObject<{
+            low: z.ZodString;
+            high: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const DeliberationRubricOutputStrictSchema: typeof _DeliberationRubricOutputStrictSchema;
+/** One wire-level score entry inside {@link DeliberationReviewWireOutput}. */
+export interface DeliberationReviewWireScore {
+    /** 0–100 against the criterion's scale anchors. */
+    score: number;
+    /** One crisp sentence grounding the score in what was observed. */
+    note: string;
+}
+/**
+ * Review pass output as it crosses the LLM wire: `RubricVerdict` minus the
+ * stamped identity fields, with `scores` as an OBJECT keyed by criterion ref.
+ */
+export interface DeliberationReviewWireOutput {
+    scores: Record<string, DeliberationReviewWireScore>;
+    recommendation: DeliberationRecommendation;
+    critiques: RubricCritique[];
+    overallNote: string;
+}
+/**
+ * Build the PER-RUN review wire schema for one rubric: `scores` is a strict
+ * object with EXACTLY the rubric's criterion refs as required keys.
+ *
+ * Why per-run instead of a static array-of-scores contract: the rubric is
+ * per-run DATA (derived at deliberation start), and an array `scores` shape
+ * leaves the "one score per criterion" invariant to the model's discipline —
+ * live runs showed a ~25% first-attempt rejection rate from DUPLICATED
+ * criterion entries (the model restating the criterion it cared most about;
+ * 3/12 reviews on 2026-07-17, each burning a full vision-call retry). Keying
+ * the object by the exact refs makes duplicates and omissions STRUCTURALLY
+ * impossible at the decode layer instead of prompt-begged. The machinery
+ * reshapes the record into the array-shaped `RubricVerdict` for storage and
+ * still runs `validateVerdictCriterionRefs` as the belt-and-braces invariant.
+ *
+ * The schema is `.strict()` end-to-end (hallucinated refs fail decode) and
+ * all-required (strict structured-output transports reject optionals).
+ */
+export declare function buildDeliberationReviewWireSchema(rubric: EvaluationRubric): z.ZodType<DeliberationReviewWireOutput>;
+/** The coordinator's per-round directive. */
+export declare enum DeliberationRoundDirective {
+    /** The outcome is settled — proceed to synthesis (converged). */
+    FINALIZE = "finalize",
+    /** Shortlist the strongest candidates and run a revision round. */
+    REVISE_SHORTLIST = "revise_shortlist"
+}
+/**
+ * Coordinator round pass output. On `FINALIZE`, `shortlistRefs` is an
+ * explicit empty array (prompt contract). The machinery validates
+ * `shortlistRefs` ⊆ the round's candidate refs and caps it at the plan's
+ * shortlist size — an invalid echo falls back to the top-K by
+ * deterministic aggregate.
+ */
+declare const _DeliberationCoordinatorRoundOutputSchema: z.ZodObject<{
+    directive: z.ZodEnum<typeof DeliberationRoundDirective>;
+    shortlistRefs: z.ZodArray<z.ZodString>;
+    rationale: z.ZodString;
+}, z.core.$strip>;
+export declare const DeliberationCoordinatorRoundOutputSchema: typeof _DeliberationCoordinatorRoundOutputSchema;
+export type DeliberationCoordinatorRoundOutput = z.infer<typeof _DeliberationCoordinatorRoundOutputSchema>;
+declare const _DeliberationCoordinatorRoundOutputStrictSchema: z.ZodObject<{
+    directive: z.ZodEnum<typeof DeliberationRoundDirective>;
+    shortlistRefs: z.ZodArray<z.ZodString>;
+    rationale: z.ZodString;
+}, z.core.$strict>;
+export declare const DeliberationCoordinatorRoundOutputStrictSchema: typeof _DeliberationCoordinatorRoundOutputStrictSchema;
+declare const _DeliberationSynthesisStrictSchema: z.ZodObject<{
+    winnerRef: z.ZodString;
+    rationale: z.ZodString;
+    dissent: z.ZodArray<z.ZodObject<{
+        charterRef: z.ZodString;
+        position: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const DeliberationSynthesisStrictSchema: typeof _DeliberationSynthesisStrictSchema;
+/**
+ * A candidate's payload as the machinery consumes it (kind-discriminated).
+ *
+ * STRUCTURED exists because some subjects a panel must judge are DATA, not prose
+ * or pixels — a placement plan, a schema proposal, a configuration. Serializing
+ * such a candidate to text and parsing the winner back was the alternative, and
+ * it was rejected: it makes the artifact's shape a prompt-formatting concern and
+ * gives the round-trip somewhere to lose a field.
+ */
+export type DeliberationCandidateContent = {
+    kind: FlowsActors_IO_PartKind.TEXT;
+    text: string;
+} | {
+    kind: FlowsActors_IO_PartKind.IMAGE;
+    imageDataUri: string;
+} | {
+    kind: FlowsActors_IO_PartKind.STRUCTURED;
+    /** The candidate value itself. This is what wins, and it is what reviewers are shown. */
+    value: unknown;
+    /**
+     * OPTIONAL human-readable framing rendered ABOVE the value — never instead of it.
+     *
+     * The caller owns domain knowledge the engine does not (what a `groupRef`
+     * means, why an order matters), so it may help a reviewer read the data. It
+     * may NOT replace the data: a projection can drift from the value it
+     * describes, and then the panel scores the prose while the winner is the
+     * bytes — real evidence about the wrong target, with a green run concealing
+     * it because the conclusion still looks plausible. The engine therefore
+     * always renders `value`, and pins that a contradicting projection loses.
+     */
+    projection?: string;
+};
+/** One candidate handed to (or produced for) the machinery. */
+export interface DeliberationCandidateInput {
+    /** Stable candidate ref (unique within the deliberation). */
+    ref: string;
+    /** Locator the record stores (the caller owns the bytes). */
+    storageRef: string;
+    content: DeliberationCandidateContent;
+}
+/**
+ * The CALLER-owned revision producer (RF-2: the engine never persists; the
+ * companion owns candidate bytes). The machinery compiles the deterministic
+ * `revisionPrompt` from the shortlisted candidate's critiques (RF-4:
+ * TEXT revises the draft, IMAGE regenerates — both reduce to "produce a new
+ * candidate from parent + instruction" at this seam) and the producer
+ * returns the NEW candidate (fresh ref + persisted payload).
+ */
+export interface DeliberationProducer {
+    produceRevision(parent: DeliberationCandidateInput, revisionPrompt: string): Promise<DeliberationCandidateInput>;
+}
+/** One expert seat at the table: the runtime profile + the agent built from its charter. */
+export interface DeliberationExpertBinding {
+    profile: RuntimeExpertProfile;
+    agentRef: string;
+}
+/**
+ * The full input of `executeDeliberation` — composed by the COMPANION
+ * (which owns charters, agents, candidate bytes, and persistence); the
+ * engine machinery owns only the orchestration semantics.
+ */
+export interface DeliberationPlan {
+    deliberationRef: string;
+    workDomain: ExpertWorkDomain;
+    /** TEXT | IMAGE — anything else is fail-closed at execution. */
+    subjectKind: FlowsActors_IO_PartKind;
+    /** The assembled work-product brief every pass is grounded on. */
+    briefContext: string;
+    /** The reviewing panel (min 1). Narrowness is enforced by the COMPOSER. */
+    reviewers: DeliberationExpertBinding[];
+    /** The coordinator (shortlist + convergence + synthesis). */
+    coordinator: DeliberationExpertBinding;
+    /** The expert who derives the rubric (usually the domain owner). */
+    rubricDeriver: DeliberationExpertBinding;
+    /** Recorded as `participants.producerAgentRef` (audit). */
+    producerAgentRef: string;
+    producer: DeliberationProducer;
+    initialCandidates: DeliberationCandidateInput[];
+    /** Max rounds before forced synthesis (locked default 2, max 3). */
+    roundBudget: number;
+    /** Top-K candidates revised per round (RF-5 cost funnel). */
+    shortlistSize: number;
+    /** Participating charters' inputsDigests (staleness audit stamps). */
+    charterInputsDigests: Record<string, string>;
+}
+/**
+ * Result of the fail-closed criterion-ref validation of one verdict
+ * against the rubric it claims to score.
+ */
+export interface VerdictCriterionRefsValidation {
+    /** `true` iff the rubric is well-formed AND the verdict scores EXACTLY its criteria (no more, no less, no dupes). */
+    ok: boolean;
+    /** Refs in the verdict that do not exist in the rubric (hallucinated). Deduplicated. */
+    unknownRefs: string[];
+    /** Rubric criteria the verdict did not score. */
+    missingRefs: string[];
+    /** Refs scored more than once in the verdict. */
+    duplicateRefs: string[];
+    /**
+     * Refs appearing more than once in the RUBRIC itself. The schema's
+     * uniqueness refine rejects these at parse time; this re-check is the
+     * fail-closed defense for in-process-constructed rubrics that skipped
+     * parsing — a duplicated rubric ref would silently DOUBLE-WEIGHT that
+     * criterion in the aggregate.
+     */
+    duplicateRubricRefs: string[];
+}
+/**
+ * Fail-closed validation that a verdict's scores line up 1:1 with a
+ * well-formed rubric's criteria. A verdict with hallucinated, missing, or
+ * duplicated refs must be rejected (the machinery retries once with the
+ * error surfaced, then drops the reviewer from the round with a quorum
+ * note); a malformed rubric (duplicate refs) fails regardless of the
+ * verdict.
+ */
+export declare function validateVerdictCriterionRefs(rubric: EvaluationRubric, verdict: RubricVerdict): VerdictCriterionRefsValidation;
+/**
+ * Deterministic weighted aggregate of one verdict against the rubric:
+ * `sum(weight_i × score_i) / sum(weight_i)` over the rubric's criteria,
+ * on the verdict's 0–100 scale. Model-computed totals are never trusted —
+ * this is the ONLY sanctioned aggregation.
+ *
+ * Throws if the verdict does not validate against the rubric
+ * (`validateVerdictCriterionRefs`) — aggregating a malformed verdict
+ * would silently misweight; callers must validate (and retry/drop) first.
+ */
+export declare function aggregateWeightedScore(rubric: EvaluationRubric, verdict: RubricVerdict): number;
+export {};
+//# sourceMappingURL=deliberation.shared.schemas.d.ts.map

package/dist/esm/flows-actors/deliberation.shared.schemas.d.ts.map

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