@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/flows-actors/deliberation.shared.schemas.js

@@ -0,0 +1,604 @@
+import { z } from "zod";
+import { FlowsActors_IO_PartKind } from "./flows-actors.io.shared.schemas.js";
+//===============================================================
+//  Expert-Persona Deliberation — shared contracts
+// ------------------------------------------------------------
+// The GENERIC vocabulary of the agentic deliberation system: narrow
+// expert personas (derived per-app from the specification tier) review
+// candidate work products against a DERIVED evaluation rubric across
+// bounded critique-revise rounds, a coordinator synthesizes, a human
+// decides.
+//
+// TIER SPLIT (dependency direction — do not blur):
+// - The DERIVED artifacts (`ExpertRoleTemplate`, `ExpertPersonaCharter`)
+//   live in `@wildo-ai/saas-specifications` `_core/expert-personas/`
+//   (spec tier — committed, human-reviewable). `saas-backend-lib` can
+//   NEVER import them (specifications sits BELOW backend-lib in the
+//   graph).
+// - THIS file is the runtime-visible half: the enums the spec family
+//   imports (single-sourced here — `ExpertWorkDomain`), the
+//   `RuntimeExpertProfile` projection the COMPANION maps a charter into
+//   before handing it to engine machinery, and the rubric / verdict /
+//   deliberation-record contracts the engine round loop operates on.
+//
+// KEY DESIGN DECISION (the anti-"taste-as-code" contract): evaluation
+// CRITERIA ARE DATA, not schema fields. The rubric is derived per
+// deliberation run by an expert persona and travels in the judge PROMPT;
+// the verdict schema below stays FIXED and GENERIC (criterion-ref-keyed
+// score array), so one schema serves every work domain and every derived
+// rubric while remaining strict-structured-output compatible (flat,
+// all-required, no dynamic keys). Weighted aggregation is DETERMINISTIC
+// CODE (`aggregateWeightedScore`) — never model arithmetic — and
+// hallucinated criterion refs are rejected fail-closed
+// (`validateVerdictCriterionRefs`).
+//===============================================================
+/**
+ * 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 var ExpertWorkDomain;
+(function (ExpertWorkDomain) {
+    /** Visual brand marks: logo symbols, icons, brand imagery. */
+    ExpertWorkDomain["VISUAL_BRAND_MARK"] = "visual_brand_mark";
+    /** Marketing / product copy: website sections, email prose, taglines. */
+    ExpertWorkDomain["MARKETING_COPY"] = "marketing_copy";
+    /** UI/design-system coherence: tokens, palette, typography discipline. */
+    ExpertWorkDomain["UI_DESIGN_COHERENCE"] = "ui_design_coherence";
+    /** Brand strategy: positioning fit, differentiation, ICP resonance. */
+    ExpertWorkDomain["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.
+     */
+    ExpertWorkDomain["INFORMATION_ARCHITECTURE"] = "information_architecture";
+})(ExpertWorkDomain || (ExpertWorkDomain = {}));
+/**
+ * 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 var DeliberationRecommendation;
+(function (DeliberationRecommendation) {
+    /** The candidate satisfies the rubric and can win as-is. */
+    DeliberationRecommendation["ACCEPT"] = "accept";
+    /** Close, but has fixable concerns — revise before it can win. */
+    DeliberationRecommendation["REVISE"] = "revise";
+    /** Materially misses the rubric — should not survive the shortlist. */
+    DeliberationRecommendation["REJECT"] = "reject";
+})(DeliberationRecommendation || (DeliberationRecommendation = {}));
+/** How a candidate entered a round's candidate set. */
+export var DeliberationCandidateProvenance;
+(function (DeliberationCandidateProvenance) {
+    /** Produced in round 1 from the creative brief. */
+    DeliberationCandidateProvenance["ORIGINAL"] = "original";
+    /** Produced by a critique-driven revision of a prior candidate. */
+    DeliberationCandidateProvenance["REVISED"] = "revised";
+})(DeliberationCandidateProvenance || (DeliberationCandidateProvenance = {}));
+/** Terminal + live states of a deliberation. */
+export var DeliberationStatus;
+(function (DeliberationStatus) {
+    /** Rounds are still executing. */
+    DeliberationStatus["RUNNING"] = "running";
+    /** The coordinator judged the outcome converged before budget. */
+    DeliberationStatus["CONVERGED"] = "converged";
+    /** The round budget was exhausted; synthesis used the last round. */
+    DeliberationStatus["BUDGET_EXHAUSTED"] = "budget_exhausted";
+    /** The deliberation could not complete (provider/validation failure). */
+    DeliberationStatus["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.
+     */
+    DeliberationStatus["REJECTED"] = "rejected";
+})(DeliberationStatus || (DeliberationStatus = {}));
+/**
+ * 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).
+ */
+const _RuntimeExpertProfileSchema = z.object({
+    /** The committed charter this profile projects (audit back-pointer). */
+    charterRef: z.string().min(1),
+    /** The framework role template the charter was derived from. */
+    roleRef: z.string().min(1),
+    /** The narrow domains this expert may produce briefs / reviews for. */
+    workDomains: z.array(z.enum(ExpertWorkDomain)).min(1),
+    /** The compiled app-specific persona prose ("who I am for THIS app"). */
+    personaProse: z.string().min(1),
+    /** Ordered priorities the persona judges by (highest first). */
+    priorities: z.array(z.string().min(1)).min(1),
+    /** Hard taboos — things this persona must never reward or produce. */
+    taboos: z.array(z.string().min(1)).default([]),
+    /**
+     * What a top-tier candidate looks like for this app (rubric scale-anchor
+     * seeds). Mirrors the charter's optional Lever-2 extension.
+     */
+    qualityBar: z.array(z.string().min(1)).optional(),
+    /** The persona's ordered review checks (systematic judging method). */
+    reviewProtocol: z.array(z.string().min(1)).optional(),
+});
+export const RuntimeExpertProfileSchema = _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.
+ */
+const _EvaluationCriterionSchema = z.object({
+    /** Stable kebab-case key verdict scores reference (e.g. `favicon-legibility`). */
+    ref: z.string().min(1),
+    /** What is being evaluated, in one or two sentences. */
+    description: z.string().min(1),
+    /**
+     * Relative importance, > 0 and FINITE. Normalization happens in
+     * `aggregateWeightedScore` (weights need not sum to anything);
+     * `.finite()` closes the Infinity/Infinity → NaN aggregate hole.
+     */
+    weight: z.number().positive().finite(),
+    /** What the scale extremes mean — pins reviewer calibration. */
+    scaleAnchors: z.object({
+        /** What a 0 looks like for this criterion. */
+        low: z.string().min(1),
+        /** What a 100 looks like for this criterion. */
+        high: z.string().min(1),
+    }),
+});
+export const EvaluationCriterionSchema = _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.
+ */
+const _EvaluationRubricSchema = z.object({
+    /** The work domain this rubric evaluates. */
+    workDomain: z.enum(ExpertWorkDomain),
+    /** The charter of the expert who derived the rubric. */
+    derivedFromCharterRef: z.string().min(1),
+    /** The derived criteria (the DATA that replaces hardcoded score fields). */
+    criteria: z.array(_EvaluationCriterionSchema).min(1),
+    /** ISO-8601 derivation moment. */
+    derivedAt: z.iso.datetime(),
+}).refine((rubric) => new Set(rubric.criteria.map((criterion) => criterion.ref)).size === rubric.criteria.length, {
+    // The rubric is LLM-DERIVED data — a model emitting the same ref twice
+    // (with different weights) is a plausible output, and a duplicated ref
+    // would silently DOUBLE-WEIGHT that criterion in the aggregate. Reject
+    // at parse; `validateVerdictCriterionRefs` re-checks as defense for
+    // in-process-constructed rubrics that skipped parsing.
+    message: 'criteria[].ref must be unique — a duplicated ref would silently double-weight it in the aggregate.',
+    path: ['criteria'],
+});
+export const EvaluationRubricSchema = _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).
+ */
+const _RubricScoreSchema = z.object({
+    /** The rubric criterion this score answers. */
+    criterionRef: z.string().min(1),
+    /** 0–100 against the criterion's scale anchors. */
+    score: z.number().min(0).max(100),
+    /** One crisp sentence grounding the score in what was observed. */
+    note: z.string().min(1),
+});
+export const RubricScoreSchema = _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).
+ */
+const _RubricCritiqueSchema = z.object({
+    /** Which aspect of the candidate the critique targets. */
+    targetAspect: z.string().min(1),
+    /** What is wrong, grounded in the rubric/persona view. */
+    critique: z.string().min(1),
+    /** The concrete change that would address it. */
+    suggestion: z.string().min(1),
+});
+export const RubricCritiqueSchema = _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.
+ */
+const _RubricVerdictSchema = z.object({
+    /** The reviewing expert's charter ref. */
+    reviewerCharterRef: z.string().min(1),
+    /** The candidate under review. */
+    candidateRef: z.string().min(1),
+    /** One score per rubric criterion (validated fail-closed, both ways). */
+    scores: z.array(_RubricScoreSchema).min(1),
+    /** Headline recommendation. */
+    recommendation: z.enum(DeliberationRecommendation),
+    /**
+     * Actionable critiques (revision fuel). REQUIRED — "no critiques" is an
+     * explicit empty array, never an absent key: this schema is handed to the
+     * LLM, and the strict structured-output transport rejects any non-required
+     * property (a `.default()` would emit one). The prompt contract mandates
+     * `[]`, not the schema.
+     */
+    critiques: z.array(_RubricCritiqueSchema),
+    /** The reviewer's overall reading of the candidate, one short paragraph. */
+    overallNote: z.string().min(1),
+});
+export const RubricVerdictSchema = _RubricVerdictSchema;
+/**
+ * One candidate as it exists inside a round's candidate set — a
+ * DISCRIMINATED UNION on `provenance` so the audit invariant is enforced by
+ * the schema, not by convention: a `REVISED` candidate MUST carry both
+ * `revisedFromRef` and `revisionPrompt` ("every revision is reproducible
+ * from the record"), while an `ORIGINAL` candidate carries neither.
+ */
+const _DeliberationCandidateOriginalSchema = z.object({
+    /** Stable candidate ref (unique within the deliberation). */
+    ref: z.string().min(1),
+    /** Produced in round 1 from the creative brief. */
+    provenance: z.literal(DeliberationCandidateProvenance.ORIGINAL),
+    /**
+     * Where the candidate's payload lives (staging-relative path or
+     * artifact locator). The record stores locators, never payload bytes.
+     */
+    storageRef: z.string().min(1),
+});
+const _DeliberationCandidateRevisedSchema = z.object({
+    /** Stable candidate ref (unique within the deliberation). */
+    ref: z.string().min(1),
+    /** Produced by a critique-driven revision of a prior candidate. */
+    provenance: z.literal(DeliberationCandidateProvenance.REVISED),
+    /** The candidate this one revises. REQUIRED for revisions. */
+    revisedFromRef: z.string().min(1),
+    /**
+     * The compiled revision instruction (text) or regeneration prompt
+     * (image) — REQUIRED so every revision is reproducible from the record.
+     */
+    revisionPrompt: z.string().min(1),
+    /** Where the candidate's payload lives (locator, never bytes). */
+    storageRef: z.string().min(1),
+});
+const _DeliberationCandidateSchema = z.discriminatedUnion('provenance', [
+    _DeliberationCandidateOriginalSchema,
+    _DeliberationCandidateRevisedSchema,
+]);
+export const DeliberationCandidateSchema = _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).
+ */
+const _DeliberationRoundSchema = z.object({
+    /** 1-based round number. */
+    roundNumber: z.number().int().min(1),
+    /** The candidates reviewed this round. */
+    candidateSet: z.array(_DeliberationCandidateSchema).min(1),
+    /** Every reviewer verdict collected this round (dissent preserved). */
+    verdicts: z.array(_RubricVerdictSchema),
+    /** The coordinator's shortlist feeding the next round (absent on the final round). */
+    shortlistRefs: z.array(z.string().min(1)).optional(),
+});
+export const DeliberationRoundSchema = _DeliberationRoundSchema;
+/** A dissenting position preserved in the synthesis (never averaged away). */
+const _DeliberationDissentSchema = z.object({
+    /** The dissenting expert's charter ref. */
+    charterRef: z.string().min(1),
+    /** The dissenting position, in the expert's own terms. */
+    position: z.string().min(1),
+});
+export const DeliberationDissentSchema = _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.
+ */
+const _DeliberationSynthesisSchema = z.object({
+    /** The winning candidate ref. */
+    winnerRef: z.string().min(1),
+    /** Why the winner beats the field, grounded in verdicts + rubric. */
+    rationale: z.string().min(1),
+    /**
+     * Dissenting positions, preserved verbatim. REQUIRED — unanimity is an
+     * explicit empty array (the coordinator's synthesis is LLM-generated;
+     * same strict structured-output discipline as the verdict's `critiques`).
+     */
+    dissent: z.array(_DeliberationDissentSchema),
+});
+export const DeliberationSynthesisSchema = _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.
+ */
+const _DeliberationConcurrenceSchema = z.object({
+    /** The candidate these counts describe. */
+    winnerRef: z.string().min(1),
+    /** Distinct reviewer lenses that scored the winner. */
+    lensCount: z.number().int().min(0),
+    /** How those lenses split. Unanimity is `accept === lensCount`. */
+    byRecommendation: z.object({
+        accept: z.number().int().min(0),
+        revise: z.number().int().min(0),
+        reject: z.number().int().min(0),
+    }),
+});
+export const DeliberationConcurrenceSchema = _DeliberationConcurrenceSchema;
+/** Who sat at the table. */
+const _DeliberationParticipantsSchema = z.object({
+    /** The producing agent (image/text generator) — an agent ref, not a charter. */
+    producerAgentRef: z.string().min(1),
+    /** The reviewing experts' charter refs (the panel). */
+    reviewerCharterRefs: z.array(z.string().min(1)).min(1),
+    /** The coordinating expert's charter ref (synthesis + shortlist + convergence). */
+    coordinatorCharterRef: z.string().min(1),
+});
+export const DeliberationParticipantsSchema = _DeliberationParticipantsSchema;
+/** The human decision over an advisory synthesis (the actual authority). */
+const _DeliberationHumanDecisionSchema = z.object({
+    /** What the human decided (accepted ref, override, or rejection note). */
+    decision: z.string().min(1),
+    /** ISO-8601 decision moment. */
+    decidedAt: z.iso.datetime(),
+});
+export const DeliberationHumanDecisionSchema = _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.
+ */
+const _DeliberationRecordSchema = z.object({
+    /** Unique deliberation id (companion-minted). */
+    deliberationRef: z.string().min(1),
+    /** The work domain deliberated. */
+    workDomain: z.enum(ExpertWorkDomain),
+    /**
+     * The candidate payload modality. Drives the revision path: TEXT
+     * revises the draft; IMAGE regenerates with a critique addendum (the
+     * image transport has no edit operation). Other kinds are fail-closed
+     * at execution until they have honest transports.
+     */
+    subjectKind: z.enum(FlowsActors_IO_PartKind),
+    /** The derived rubric (embedded; constant across this record's rounds). */
+    rubric: _EvaluationRubricSchema,
+    participants: _DeliberationParticipantsSchema,
+    /** The rounds, in order. Appended as the deliberation progresses. */
+    rounds: z.array(_DeliberationRoundSchema).default([]),
+    /**
+     * Deterministic lens accounting for the winner, beside the synthesis it describes.
+     * Absent exactly when `synthesis` is.
+     */
+    concurrence: _DeliberationConcurrenceSchema.optional(),
+    /** The coordinator's synthesis (absent while RUNNING, on FAILED, and on REJECTED — a rejected field has no winner to synthesise). */
+    synthesis: _DeliberationSynthesisSchema.optional(),
+    /** Max rounds before the coordinator must synthesize (cost bound). */
+    roundBudget: z.number().int().min(1),
+    status: z.enum(DeliberationStatus),
+    /**
+     * The charters' `inputsDigest`s at deliberation time — lets an audit
+     * see a decision was made under a stale persona (keyed by charterRef).
+     */
+    charterInputsDigests: z.record(z.string(), z.string()).default({}),
+    /** The human authority's decision; null until the human acts. */
+    humanDecision: _DeliberationHumanDecisionSchema.nullable().default(null),
+    /** ISO-8601 timestamps. */
+    startedAt: z.iso.datetime(),
+    finishedAt: z.iso.datetime().optional(),
+});
+export const DeliberationRecordSchema = _DeliberationRecordSchema;
+//===============================================================
+//  LLM-facing pass contracts (deliberation orchestration)
+// ------------------------------------------------------------
+// The schemas HANDED TO THE MODEL by each orchestration pass. They are
+// the stamped-fields-free projections of the record contracts above:
+// identity/provenance fields (charter refs, candidate refs, timestamps,
+// work domain) are stamped DETERMINISTICALLY by the machinery — a model
+// never authors its own audit trail. Flat, all-required (strict
+// structured-output discipline; "empty" is []/'' by prompt contract).
+//===============================================================
+/**
+ * Rubric-derivation pass output: the criteria only. The machinery stamps
+ * `workDomain` / `derivedFromCharterRef` / `derivedAt` and validates the
+ * assembled rubric through `EvaluationRubricSchema` (unique-ref refine).
+ */
+const _DeliberationRubricOutputSchema = z.object({
+    criteria: z.array(_EvaluationCriterionSchema).min(1),
+});
+export const DeliberationRubricOutputSchema = _DeliberationRubricOutputSchema;
+const _DeliberationRubricOutputStrictSchema = z.object({
+    criteria: z.array(_EvaluationCriterionSchema.strict()).min(1),
+}).strict();
+export const DeliberationRubricOutputStrictSchema = _DeliberationRubricOutputStrictSchema;
+/**
+ * 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 function buildDeliberationReviewWireSchema(rubric) {
+    const scoreValue = z.object({
+        score: z.number().min(0).max(100),
+        note: z.string().min(1),
+    }).strict();
+    const scoresShape = Object.fromEntries(rubric.criteria.map((criterion) => [criterion.ref, scoreValue]));
+    return z.object({
+        scores: z.object(scoresShape).strict(),
+        recommendation: z.enum(DeliberationRecommendation),
+        critiques: z.array(_RubricCritiqueSchema.strict()),
+        overallNote: z.string().min(1),
+    }).strict();
+}
+/** The coordinator's per-round directive. */
+export var DeliberationRoundDirective;
+(function (DeliberationRoundDirective) {
+    /** The outcome is settled — proceed to synthesis (converged). */
+    DeliberationRoundDirective["FINALIZE"] = "finalize";
+    /** Shortlist the strongest candidates and run a revision round. */
+    DeliberationRoundDirective["REVISE_SHORTLIST"] = "revise_shortlist";
+})(DeliberationRoundDirective || (DeliberationRoundDirective = {}));
+/**
+ * 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.
+ */
+const _DeliberationCoordinatorRoundOutputSchema = z.object({
+    directive: z.enum(DeliberationRoundDirective),
+    /** The candidates to revise next round (empty on FINALIZE). */
+    shortlistRefs: z.array(z.string().min(1)),
+    /** Why this directive, grounded in the verdicts. */
+    rationale: z.string().min(1),
+});
+export const DeliberationCoordinatorRoundOutputSchema = _DeliberationCoordinatorRoundOutputSchema;
+const _DeliberationCoordinatorRoundOutputStrictSchema = _DeliberationCoordinatorRoundOutputSchema.strict();
+export const DeliberationCoordinatorRoundOutputStrictSchema = _DeliberationCoordinatorRoundOutputStrictSchema;
+// The synthesis pass hands `DeliberationSynthesisSchema` itself to the model
+// (it is already flat + all-required); the machinery validates `winnerRef`
+// against the final candidate set (fallback: top deterministic aggregate)
+// and filters dissent entries to known reviewer charter refs.
+const _DeliberationSynthesisStrictSchema = z.object({
+    winnerRef: z.string().min(1),
+    rationale: z.string().min(1),
+    dissent: z.array(_DeliberationDissentSchema.strict()),
+}).strict();
+export const DeliberationSynthesisStrictSchema = _DeliberationSynthesisStrictSchema;
+/**
+ * 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 function validateVerdictCriterionRefs(rubric, verdict) {
+    const rubricRefs = new Set();
+    const duplicateRubricRefs = [];
+    for (const criterion of rubric.criteria) {
+        if (rubricRefs.has(criterion.ref) && !duplicateRubricRefs.includes(criterion.ref)) {
+            duplicateRubricRefs.push(criterion.ref);
+        }
+        rubricRefs.add(criterion.ref);
+    }
+    const seen = new Set();
+    const unknownRefs = [];
+    const duplicateRefs = [];
+    for (const score of verdict.scores) {
+        if (!rubricRefs.has(score.criterionRef) && !unknownRefs.includes(score.criterionRef)) {
+            unknownRefs.push(score.criterionRef);
+        }
+        if (seen.has(score.criterionRef) && !duplicateRefs.includes(score.criterionRef)) {
+            duplicateRefs.push(score.criterionRef);
+        }
+        seen.add(score.criterionRef);
+    }
+    const missingRefs = [...rubricRefs].filter((ref) => !seen.has(ref));
+    return {
+        ok: unknownRefs.length === 0
+            && missingRefs.length === 0
+            && duplicateRefs.length === 0
+            && duplicateRubricRefs.length === 0,
+        unknownRefs,
+        missingRefs,
+        duplicateRefs,
+        duplicateRubricRefs,
+    };
+}
+/**
+ * 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 function aggregateWeightedScore(rubric, verdict) {
+    const validation = validateVerdictCriterionRefs(rubric, verdict);
+    if (!validation.ok) {
+        throw new Error(`Cannot aggregate a verdict that does not match its rubric ` +
+            `(unknown: [${validation.unknownRefs.join(", ")}], ` +
+            `missing: [${validation.missingRefs.join(", ")}], ` +
+            `duplicate: [${validation.duplicateRefs.join(", ")}], ` +
+            `duplicate rubric refs: [${validation.duplicateRubricRefs.join(", ")}]).`);
+    }
+    const scoreByRef = new Map(verdict.scores.map((score) => [score.criterionRef, score.score]));
+    let weightedSum = 0;
+    let weightSum = 0;
+    for (const criterion of rubric.criteria) {
+        // Ref alignment is guaranteed by the validation above.
+        weightedSum += criterion.weight * scoreByRef.get(criterion.ref);
+        weightSum += criterion.weight;
+    }
+    return weightedSum / weightSum;
+}
+//# sourceMappingURL=deliberation.shared.schemas.js.map