@cat-factory/contracts 0.6.0

package/dist/clarity.d.ts

@@ -0,0 +1,75 @@
+import * as v from 'valibot';
+/** A single triage finding the clarity reviewer raised — same shape as a requirements item. */
+export declare const clarityReviewItemSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+    readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+    readonly title: v.StringSchema<undefined>;
+    readonly detail: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
+    readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly updatedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type ClarityReviewItem = v.InferOutput<typeof clarityReviewItemSchema>;
+/** Lifecycle of a clarity review as a whole — identical to the requirements review lifecycle. */
+export declare const clarityReviewStatusSchema: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+export type ClarityReviewStatus = v.InferOutput<typeof clarityReviewStatusSchema>;
+/** A clarity (bug-report triage) review for one board block. */
+export declare const clarityReviewSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly blockId: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+    readonly items: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+        readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+        readonly title: v.StringSchema<undefined>;
+        readonly detail: v.StringSchema<undefined>;
+        readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
+        readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly createdAt: v.NumberSchema<undefined>;
+        readonly updatedAt: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+    /** `provider:model` that produced the review, for transparency; null in tests. */
+    readonly model: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * The clarified bug report the incorporation companion last folded the answers into.
+     * Set once a doc has been produced (status `merged`/`incorporated`); null while still
+     * awaiting answers on the first pass. Consumed by every downstream agent step + the
+     * spec-writer once the phase is settled.
+     */
+    readonly clarifiedReport: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** How many reviewer passes have run so far (the initial review is iteration 1). */
+    readonly iteration: v.OptionalSchema<v.NumberSchema<undefined>, 1>;
+    /** The reviewer-pass budget, snapshotted from the task's merge preset when the review started. */
+    readonly maxIterations: v.OptionalSchema<v.NumberSchema<undefined>, 1>;
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly updatedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type ClarityReview = v.InferOutput<typeof clarityReviewSchema>;
+/** Record a human's answer to a single clarity review item. */
+export declare const replyClarityItemSchema: v.ObjectSchema<{
+    readonly reply: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+}, undefined>;
+export type ReplyClarityItemInput = v.InferOutput<typeof replyClarityItemSchema>;
+/** Set a clarity review item's status (resolve / dismiss / reopen). */
+export declare const updateClarityItemStatusSchema: v.ObjectSchema<{
+    readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
+}, undefined>;
+export type UpdateClarityItemStatusInput = v.InferOutput<typeof updateClarityItemStatusSchema>;
+/**
+ * Incorporate the settled answers into a standardized, clear bug report. An optional
+ * `feedback` comment is the human's "do it differently" lever when redoing a merge.
+ */
+export declare const incorporateClaritySchema: v.ObjectSchema<{
+    readonly feedback: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 4000, undefined>]>, undefined>;
+}, undefined>;
+export type IncorporateClarityInput = v.InferOutput<typeof incorporateClaritySchema>;
+/** How a human resolves a clarity review that hit its iteration cap with findings open. */
+export declare const resolveClarityExceededSchema: v.ObjectSchema<{
+    readonly choice: v.PicklistSchema<["extra-round", "proceed", "stop-reset"], undefined>;
+}, undefined>;
+export type ResolveClarityExceededInput = v.InferOutput<typeof resolveClarityExceededSchema>;
+export type ResolveClarityExceededChoice = ResolveClarityExceededInput['choice'];
+//# sourceMappingURL=clarity.d.ts.map

package/dist/clarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarity.d.ts","sourceRoot":"","sources":["../src/clarity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAqB5B,+FAA+F;AAC/F,eAAO,MAAM,uBAAuB;;;;;;;;;;aAA8B,CAAA;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E,iGAAiG;AACjG,eAAO,MAAM,yBAAyB,4GAAgC,CAAA;AACtE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,gEAAgE;AAChE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;IAK9B,kFAAkF;;IAElF;;;;;OAKG;;IAEH,oFAAoF;;IAEpF,kGAAkG;;;;aAIlG,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAIrE,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB;;aAEjC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAEhF,uEAAuE;AACvE,eAAO,MAAM,6BAA6B;;aAExC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAE9F;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;aAEnC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEpF,2FAA2F;AAC3F,eAAO,MAAM,4BAA4B;;aAEvC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAC5F,MAAM,MAAM,4BAA4B,GAAG,2BAA2B,CAAC,QAAQ,CAAC,CAAA"}

package/dist/clarity.js

@@ -0,0 +1,66 @@
+import * as v from 'valibot';
+import { iterationCapChoiceSchema } from './iteration-cap.js';
+import { requirementReviewItemSchema, requirementReviewStatusSchema } from './requirements.js';
+// ---------------------------------------------------------------------------
+// Clarity-review wire contracts. A clarity reviewer triages a board block's BUG
+// REPORT — its description plus any context an upstream `bug-investigator` step
+// enriched it with — for *fixability*: are the repro steps, expected-vs-actual
+// behaviour, environment, affected area and scope clear enough to act on? It
+// raises review items (the same shape as the requirements reviewer's) each with a
+// severity. A human answers or dismisses each; an incorporation companion folds the
+// answers into ONE standardized, clear bug report, then the reviewer re-reviews it.
+// The cycle repeats until the reviewer is clean (or every remaining finding is
+// dismissed / tolerated by the task's severity threshold), or the task's iteration
+// cap is hit and a human picks how to proceed.
+//
+// This is the requirements-review flow applied to a different subject, so it REUSES
+// the requirements review item + status shapes (one source of truth) and differs
+// only in subject and in the persisted document field name (`clarifiedReport`).
+// ---------------------------------------------------------------------------
+/** A single triage finding the clarity reviewer raised — same shape as a requirements item. */
+export const clarityReviewItemSchema = requirementReviewItemSchema;
+/** Lifecycle of a clarity review as a whole — identical to the requirements review lifecycle. */
+export const clarityReviewStatusSchema = requirementReviewStatusSchema;
+/** A clarity (bug-report triage) review for one board block. */
+export const clarityReviewSchema = v.object({
+    id: v.string(),
+    blockId: v.string(),
+    status: clarityReviewStatusSchema,
+    items: v.array(clarityReviewItemSchema),
+    /** `provider:model` that produced the review, for transparency; null in tests. */
+    model: v.nullable(v.string()),
+    /**
+     * The clarified bug report the incorporation companion last folded the answers into.
+     * Set once a doc has been produced (status `merged`/`incorporated`); null while still
+     * awaiting answers on the first pass. Consumed by every downstream agent step + the
+     * spec-writer once the phase is settled.
+     */
+    clarifiedReport: v.nullable(v.string()),
+    /** How many reviewer passes have run so far (the initial review is iteration 1). */
+    iteration: v.optional(v.number(), 1),
+    /** The reviewer-pass budget, snapshotted from the task's merge preset when the review started. */
+    maxIterations: v.optional(v.number(), 1),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+// ---- Request bodies -------------------------------------------------------
+/** Record a human's answer to a single clarity review item. */
+export const replyClarityItemSchema = v.object({
+    reply: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(4000)),
+});
+/** Set a clarity review item's status (resolve / dismiss / reopen). */
+export const updateClarityItemStatusSchema = v.object({
+    status: v.picklist(['open', 'answered', 'resolved', 'dismissed']),
+});
+/**
+ * Incorporate the settled answers into a standardized, clear bug report. An optional
+ * `feedback` comment is the human's "do it differently" lever when redoing a merge.
+ */
+export const incorporateClaritySchema = v.object({
+    feedback: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(4000))),
+});
+/** How a human resolves a clarity review that hit its iteration cap with findings open. */
+export const resolveClarityExceededSchema = v.object({
+    choice: iterationCapChoiceSchema,
+});
+//# sourceMappingURL=clarity.js.map

package/dist/clarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarity.js","sourceRoot":"","sources":["../src/clarity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EAAE,2BAA2B,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAA;AAE9F,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,6EAA6E;AAC7E,kFAAkF;AAClF,oFAAoF;AACpF,oFAAoF;AACpF,+EAA+E;AAC/E,mFAAmF;AACnF,+CAA+C;AAC/C,EAAE;AACF,oFAAoF;AACpF,iFAAiF;AACjF,gFAAgF;AAChF,8EAA8E;AAE9E,+FAA+F;AAC/F,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAA;AAGlE,iGAAiG;AACjG,MAAM,CAAC,MAAM,yBAAyB,GAAG,6BAA6B,CAAA;AAGtE,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,yBAAyB;IACjC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;IACvC,kFAAkF;IAClF,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACvC,oFAAoF;IACpF,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpC,kGAAkG;IAClG,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAGF,8EAA8E;AAE9E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;CACvE,CAAC,CAAA;AAGF,uEAAuE;AACvE,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;CAClE,CAAC,CAAA;AAGF;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;CACtE,CAAC,CAAA;AAGF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,MAAM,EAAE,wBAAwB;CACjC,CAAC,CAAA"}

package/dist/companion.d.ts

@@ -0,0 +1,32 @@
+import * as v from 'valibot';
+/** The default quality bar a companion's rating must reach for the run to proceed. */
+export declare const DEFAULT_COMPANION_THRESHOLD = 0.8;
+/** The default number of automatic rework attempts before a companion parks for a human. */
+export declare const DEFAULT_COMPANION_MAX_ATTEMPTS = 3;
+/**
+ * A companion agent's structured assessment of the producer step's output. `rating`
+ * is the single overall quality score (0..1, higher = better); `summary` is the
+ * prose justification surfaced to the human and folded into a rework; `comments`
+ * optionally anchor specific challenges to individual items (by `anchorId`) or prose
+ * ranges, reusing the shared step-review comment shape.
+ */
+export declare const companionAssessmentSchema: v.ObjectSchema<{
+    /** Overall quality of the reviewed outcome (0..1, higher = better). */
+    readonly rating: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>;
+    /** Plain-prose justification of the rating + the changes the producer should make. */
+    readonly summary: v.StringSchema<undefined>;
+    /** Optional per-item / per-block challenges (shared shape with human reviews). */
+    readonly comments: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly quotedSource: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly srcStart: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        readonly srcEnd: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        readonly anchorId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly body: v.StringSchema<undefined>;
+    }, undefined>, undefined>, undefined>;
+}, undefined>;
+export type CompanionAssessment = v.InferOutput<typeof companionAssessmentSchema>;
+/** Parse-or-throw a companion assessment payload the model returned (the engine validates it). */
+export declare function parseCompanionAssessment(value: unknown): CompanionAssessment;
+/** Non-throwing variant: returns the parsed assessment or `undefined` when invalid. */
+export declare function safeParseCompanionAssessment(value: unknown): CompanionAssessment | undefined;
+//# sourceMappingURL=companion.d.ts.map

package/dist/companion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion.d.ts","sourceRoot":"","sources":["../src/companion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAgB5B,sFAAsF;AACtF,eAAO,MAAM,2BAA2B,MAAM,CAAA;AAE9C,4FAA4F;AAC5F,eAAO,MAAM,8BAA8B,IAAI,CAAA;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;IACpC,uEAAuE;;IAEvE,sFAAsF;;IAEtF,kFAAkF;;;;;;;;aAElF,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,kGAAkG;AAClG,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAE5E;AAED,uFAAuF;AACvF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAG5F"}

package/dist/companion.js

@@ -0,0 +1,43 @@
+import * as v from 'valibot';
+import { stepReviewCommentSchema } from './entities.js';
+// ---------------------------------------------------------------------------
+// Companion-agent wire contracts. A companion agent reviews the outcome of an
+// immediately-preceding producer step (e.g. an architect design, a spec's
+// acceptance scenarios, or a coder's change), challenges its quality and
+// completeness, and returns a single overall quality rating in 0..1 plus
+// actionable feedback. The execution engine compares the rating against the
+// step's configured threshold (default 0.8): at or above it the run proceeds to
+// the human gate / next step; below it the producer step is re-run with the
+// companion's feedback folded in, and once the rework budget is exhausted the step
+// parks on a human iteration-cap gate (one more round / proceed anyway / stop & reset)
+// instead of failing.
+// ---------------------------------------------------------------------------
+/** The default quality bar a companion's rating must reach for the run to proceed. */
+export const DEFAULT_COMPANION_THRESHOLD = 0.8;
+/** The default number of automatic rework attempts before a companion parks for a human. */
+export const DEFAULT_COMPANION_MAX_ATTEMPTS = 3;
+/**
+ * A companion agent's structured assessment of the producer step's output. `rating`
+ * is the single overall quality score (0..1, higher = better); `summary` is the
+ * prose justification surfaced to the human and folded into a rework; `comments`
+ * optionally anchor specific challenges to individual items (by `anchorId`) or prose
+ * ranges, reusing the shared step-review comment shape.
+ */
+export const companionAssessmentSchema = v.object({
+    /** Overall quality of the reviewed outcome (0..1, higher = better). */
+    rating: v.pipe(v.number(), v.minValue(0), v.maxValue(1)),
+    /** Plain-prose justification of the rating + the changes the producer should make. */
+    summary: v.string(),
+    /** Optional per-item / per-block challenges (shared shape with human reviews). */
+    comments: v.optional(v.array(stepReviewCommentSchema)),
+});
+/** Parse-or-throw a companion assessment payload the model returned (the engine validates it). */
+export function parseCompanionAssessment(value) {
+    return v.parse(companionAssessmentSchema, value);
+}
+/** Non-throwing variant: returns the parsed assessment or `undefined` when invalid. */
+export function safeParseCompanionAssessment(value) {
+    const result = v.safeParse(companionAssessmentSchema, value);
+    return result.success ? result.output : undefined;
+}
+//# sourceMappingURL=companion.js.map

package/dist/companion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion.js","sourceRoot":"","sources":["../src/companion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AAEvD,8EAA8E;AAC9E,8EAA8E;AAC9E,0EAA0E;AAC1E,yEAAyE;AACzE,yEAAyE;AACzE,4EAA4E;AAC5E,gFAAgF;AAChF,4EAA4E;AAC5E,mFAAmF;AACnF,uFAAuF;AACvF,sBAAsB;AACtB,8EAA8E;AAE9E,sFAAsF;AACtF,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAA;AAE9C,4FAA4F;AAC5F,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,uEAAuE;IACvE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACxD,sFAAsF;IACtF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,kFAAkF;IAClF,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;CACvD,CAAC,CAAA;AAGF,kGAAkG;AAClG,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,CAAC,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAA;AAClD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAA;IAC5D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;AACnD,CAAC"}

package/dist/consensus.d.ts

@@ -0,0 +1,195 @@
+import * as v from 'valibot';
+/** The consensus strategy a step uses. Mirrors the consensus capability traits. */
+export declare const consensusStrategySchema: v.PicklistSchema<["specialist-panel", "debate", "ranked-voting"], undefined>;
+export type ConsensusStrategy = v.InferOutput<typeof consensusStrategySchema>;
+/**
+ * A single participant in a consensus session: a named role, an optional extra
+ * system framing that biases its perspective (e.g. "argue for the simplest
+ * viable design"), and the model it runs on. `modelId` absent ⇒ the step/block
+ * default model. Diversity of role + model is what makes consensus useful, so a
+ * session should carry ≥2 participants with distinct framings/models.
+ */
+export declare const consensusParticipantSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    /** Human-facing role label, e.g. "Pragmatist", "Security reviewer". */
+    readonly role: v.StringSchema<undefined>;
+    /** Extra perspective framing folded into this participant's system prompt. */
+    readonly systemFraming: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /** Model catalog id this participant runs on; absent ⇒ step/block default. */
+    readonly modelId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type ConsensusParticipant = v.InferOutput<typeof consensusParticipantSchema>;
+/**
+ * Optional gating of the (expensive) consensus process on the task's estimate.
+ * When `enabled`, consensus runs only if ANY supplied axis is met or exceeded
+ * (risk ≥ minRisk OR impact ≥ minImpact OR complexity ≥ minComplexity);
+ * otherwise the standard single-actor agent runs. `onMissingEstimate` decides
+ * what to do when no estimate is available (default `consensus`, i.e. fail-safe
+ * to thoroughness).
+ */
+export declare const consensusGatingSchema: v.ObjectSchema<{
+    readonly enabled: v.BooleanSchema<undefined>;
+    readonly minComplexity: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    readonly minRisk: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    readonly minImpact: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    readonly onMissingEstimate: v.OptionalSchema<v.PicklistSchema<["consensus", "standard"], undefined>, "consensus">;
+}, undefined>;
+export type ConsensusGating = v.InferOutput<typeof consensusGatingSchema>;
+/**
+ * Optional gating of whether a pipeline STEP runs at all, on the task's estimate
+ * (the same three axes as {@link consensusGatingSchema}, produced by the core
+ * `task-estimator` agent). When `enabled`, the step runs only if ANY supplied axis
+ * is met or exceeded (risk ≥ minRisk OR impact ≥ minImpact OR complexity ≥
+ * minComplexity); otherwise it is transparently SKIPPED at runtime. `onMissingEstimate`
+ * decides what to do when no estimate is available (default `run`, i.e. fail-safe to
+ * thoroughness). A step carrying enabled gating requires a `task-estimator` earlier in
+ * the pipeline — the builder/engine reject a pipeline that gates without one. Used today
+ * to make a companion (reviewer / architect-companion / spec-companion) conditional on
+ * how heavy the task is.
+ */
+export declare const stepGatingSchema: v.ObjectSchema<{
+    readonly enabled: v.BooleanSchema<undefined>;
+    readonly minComplexity: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    readonly minRisk: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    readonly minImpact: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+    readonly onMissingEstimate: v.OptionalSchema<v.PicklistSchema<["run", "skip"], undefined>, "run">;
+}, undefined>;
+export type StepGating = v.InferOutput<typeof stepGatingSchema>;
+/**
+ * The consensus configuration stored on a pipeline step (set in the builder for
+ * a step whose agent kind carries a consensus trait). When `enabled` is false
+ * the step runs as the standard agent.
+ */
+export declare const consensusStepConfigSchema: v.ObjectSchema<{
+    readonly enabled: v.BooleanSchema<undefined>;
+    readonly strategy: v.PicklistSchema<["specialist-panel", "debate", "ranked-voting"], undefined>;
+    readonly participants: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        /** Human-facing role label, e.g. "Pragmatist", "Security reviewer". */
+        readonly role: v.StringSchema<undefined>;
+        /** Extra perspective framing folded into this participant's system prompt. */
+        readonly systemFraming: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /** Model catalog id this participant runs on; absent ⇒ step/block default. */
+        readonly modelId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** Model that runs the neutral synthesis / judging pass; absent ⇒ step default. */
+    readonly synthesizerModelId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /** Debate rounds (1..5); ignored by non-debate strategies. Default applied by the engine. */
+    readonly rounds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 5, undefined>]>, undefined>;
+    /** Optional gating of the process on the task estimate; absent ⇒ always run when enabled. */
+    readonly gating: v.OptionalSchema<v.ObjectSchema<{
+        readonly enabled: v.BooleanSchema<undefined>;
+        readonly minComplexity: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+        readonly minRisk: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+        readonly minImpact: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, undefined>;
+        readonly onMissingEstimate: v.OptionalSchema<v.PicklistSchema<["consensus", "standard"], undefined>, "consensus">;
+    }, undefined>, undefined>;
+}, undefined>;
+export type ConsensusStepConfig = v.InferOutput<typeof consensusStepConfigSchema>;
+/**
+ * A `task-estimator` agent's structured triage of a task along three axes
+ * (each 0..1; higher = more complex / riskier / higher blast-radius). Produced
+ * after requirements are clarified and the spec is structured, persisted on the
+ * block, surfaced in the UI, and used to gate consensus steps. This is CORE —
+ * it ships independent of the consensus package.
+ */
+export declare const taskEstimateSchema: v.ObjectSchema<{
+    readonly complexity: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>;
+    readonly risk: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>;
+    readonly impact: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>;
+    /** The estimator's plain-prose justification for the scores. */
+    readonly rationale: v.StringSchema<undefined>;
+    /** Identifier of the model that produced the estimate, for transparency. */
+    readonly model: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly createdAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type TaskEstimate = v.InferOutput<typeof taskEstimateSchema>;
+/** One scored dimension a ranked-voting participant assigned (0..1). */
+export declare const consensusScoreSchema: v.ObjectSchema<{
+    readonly dimension: v.StringSchema<undefined>;
+    readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>;
+    readonly rationale: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type ConsensusScore = v.InferOutput<typeof consensusScoreSchema>;
+/** One participant's contribution within a round (an argument, critique, or scoring). */
+export declare const consensusContributionSchema: v.ObjectSchema<{
+    readonly participantId: v.StringSchema<undefined>;
+    readonly text: v.StringSchema<undefined>;
+    readonly scores: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly dimension: v.StringSchema<undefined>;
+        readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>;
+        readonly rationale: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
+}, undefined>;
+export type ConsensusContribution = v.InferOutput<typeof consensusContributionSchema>;
+/** A single round of the process. `kind` distinguishes the dialectic phases. */
+export declare const consensusRoundSchema: v.ObjectSchema<{
+    readonly index: v.NumberSchema<undefined>;
+    readonly kind: v.OptionalSchema<v.PicklistSchema<["draft", "critique", "score"], undefined>, undefined>;
+    readonly contributions: v.ArraySchema<v.ObjectSchema<{
+        readonly participantId: v.StringSchema<undefined>;
+        readonly text: v.StringSchema<undefined>;
+        readonly scores: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly dimension: v.StringSchema<undefined>;
+            readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>;
+            readonly rationale: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type ConsensusRound = v.InferOutput<typeof consensusRoundSchema>;
+export declare const consensusSessionStatusSchema: v.PicklistSchema<["running", "synthesizing", "done", "failed"], undefined>;
+export type ConsensusSessionStatus = v.InferOutput<typeof consensusSessionStatusSchema>;
+/**
+ * The full transcript of a consensus session: who participated, the round-by-round
+ * contributions, the synthesized result, and confidence/dissent. Persisted
+ * (`consensus_sessions`) and streamed live so the dedicated window can visualize
+ * the process. One per (executionId, stepIndex).
+ */
+export declare const consensusSessionSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly blockId: v.StringSchema<undefined>;
+    readonly executionId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly stepIndex: v.NumberSchema<undefined>;
+    /** The underlying agent kind this session ran for (e.g. `architect`). */
+    readonly agentKind: v.StringSchema<undefined>;
+    readonly strategy: v.PicklistSchema<["specialist-panel", "debate", "ranked-voting"], undefined>;
+    readonly status: v.PicklistSchema<["running", "synthesizing", "done", "failed"], undefined>;
+    readonly participants: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        /** Human-facing role label, e.g. "Pragmatist", "Security reviewer". */
+        readonly role: v.StringSchema<undefined>;
+        /** Extra perspective framing folded into this participant's system prompt. */
+        readonly systemFraming: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /** Model catalog id this participant runs on; absent ⇒ step/block default. */
+        readonly modelId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly rounds: v.ArraySchema<v.ObjectSchema<{
+        readonly index: v.NumberSchema<undefined>;
+        readonly kind: v.OptionalSchema<v.PicklistSchema<["draft", "critique", "score"], undefined>, undefined>;
+        readonly contributions: v.ArraySchema<v.ObjectSchema<{
+            readonly participantId: v.StringSchema<undefined>;
+            readonly text: v.StringSchema<undefined>;
+            readonly scores: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+                readonly dimension: v.StringSchema<undefined>;
+                readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>;
+                readonly rationale: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** The neutral synthesis / winning result; null until the synthesis pass completes. */
+    readonly synthesis: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Aggregate confidence in the result (0..1), when the strategy yields one. */
+    readonly confidence: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+    /** Notable unresolved disagreements surfaced by the synthesizer. */
+    readonly dissent: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /** Failure detail when `status` is `failed`. */
+    readonly error: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly updatedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type ConsensusSession = v.InferOutput<typeof consensusSessionSchema>;
+/** Parse-or-throw a task estimate payload an agent returned (the engine validates it). */
+export declare function parseTaskEstimate(value: unknown): TaskEstimate;
+/** Parse-or-throw a consensus step config (used when persisting builder edits). */
+export declare function parseConsensusStepConfig(value: unknown): ConsensusStepConfig;
+//# sourceMappingURL=consensus.d.ts.map

package/dist/consensus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consensus.d.ts","sourceRoot":"","sources":["../src/consensus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAoB5B,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,8EAA8D,CAAA;AAClG,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;IAErC,uEAAuE;;IAEvE,8EAA8E;;IAE9E,8EAA8E;;aAE9E,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;aAMhC,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB;;;;;;aAM3B,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;QApDpC,uEAAuE;;QAEvE,8EAA8E;;QAE9E,8EAA8E;;;IAoD9E,mFAAmF;;IAEnF,6FAA6F;;IAE7F,6FAA6F;;;;;;;;aAE7F,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;IAI7B,gEAAgE;;IAEhE,4EAA4E;;;aAG5E,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAInE,wEAAwE;AACxE,eAAO,MAAM,oBAAoB;;;;aAI/B,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,yFAAyF;AACzF,eAAO,MAAM,2BAA2B;;;;;;;;aAItC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF,gFAAgF;AAChF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;aAI/B,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,eAAO,MAAM,4BAA4B,4EAKvC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;IAKjC,yEAAyE;;;;;;QAjIzE,uEAAuE;;QAEvE,8EAA8E;;QAE9E,8EAA8E;;;;;;;;;;;;;;;;IAmI9E,uFAAuF;;IAEvF,+EAA+E;;IAE/E,oEAAoE;;IAEpE,gDAAgD;;;;aAIhD,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAE9D;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAE5E"}

package/dist/consensus.js

@@ -0,0 +1,164 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// Consensus-orchestration wire contracts.
+//
+// Consensus is a general MECHANISM (not one specific step): an eligible agent
+// step can be run through a multi-model process — a specialist panel, a debate,
+// or ranked voting/scoring — to produce a higher-quality result of the SAME
+// shape that single-actor agent would have produced (a polished document, an
+// aggregate of observations, occasionally structured scores). It is opt-in per
+// step in the pipeline builder and lives behind a separate optional package
+// (`@cat-factory/consensus`); these are the shared wire shapes.
+//
+// Because the process is expensive it can be GATED on a task's estimate (see
+// {@link taskEstimateSchema}, produced by the core `task-estimator` agent): a
+// sub-threshold task transparently runs the standard single-actor agent instead.
+// ---------------------------------------------------------------------------
+const scoreSchema = v.pipe(v.number(), v.minValue(0), v.maxValue(1));
+/** The consensus strategy a step uses. Mirrors the consensus capability traits. */
+export const consensusStrategySchema = v.picklist(['specialist-panel', 'debate', 'ranked-voting']);
+/**
+ * A single participant in a consensus session: a named role, an optional extra
+ * system framing that biases its perspective (e.g. "argue for the simplest
+ * viable design"), and the model it runs on. `modelId` absent ⇒ the step/block
+ * default model. Diversity of role + model is what makes consensus useful, so a
+ * session should carry ≥2 participants with distinct framings/models.
+ */
+export const consensusParticipantSchema = v.object({
+    id: v.string(),
+    /** Human-facing role label, e.g. "Pragmatist", "Security reviewer". */
+    role: v.string(),
+    /** Extra perspective framing folded into this participant's system prompt. */
+    systemFraming: v.optional(v.string()),
+    /** Model catalog id this participant runs on; absent ⇒ step/block default. */
+    modelId: v.optional(v.string()),
+});
+/**
+ * Optional gating of the (expensive) consensus process on the task's estimate.
+ * When `enabled`, consensus runs only if ANY supplied axis is met or exceeded
+ * (risk ≥ minRisk OR impact ≥ minImpact OR complexity ≥ minComplexity);
+ * otherwise the standard single-actor agent runs. `onMissingEstimate` decides
+ * what to do when no estimate is available (default `consensus`, i.e. fail-safe
+ * to thoroughness).
+ */
+export const consensusGatingSchema = v.object({
+    enabled: v.boolean(),
+    minComplexity: v.optional(scoreSchema),
+    minRisk: v.optional(scoreSchema),
+    minImpact: v.optional(scoreSchema),
+    onMissingEstimate: v.optional(v.picklist(['consensus', 'standard']), 'consensus'),
+});
+/**
+ * Optional gating of whether a pipeline STEP runs at all, on the task's estimate
+ * (the same three axes as {@link consensusGatingSchema}, produced by the core
+ * `task-estimator` agent). When `enabled`, the step runs only if ANY supplied axis
+ * is met or exceeded (risk ≥ minRisk OR impact ≥ minImpact OR complexity ≥
+ * minComplexity); otherwise it is transparently SKIPPED at runtime. `onMissingEstimate`
+ * decides what to do when no estimate is available (default `run`, i.e. fail-safe to
+ * thoroughness). A step carrying enabled gating requires a `task-estimator` earlier in
+ * the pipeline — the builder/engine reject a pipeline that gates without one. Used today
+ * to make a companion (reviewer / architect-companion / spec-companion) conditional on
+ * how heavy the task is.
+ */
+export const stepGatingSchema = v.object({
+    enabled: v.boolean(),
+    minComplexity: v.optional(scoreSchema),
+    minRisk: v.optional(scoreSchema),
+    minImpact: v.optional(scoreSchema),
+    onMissingEstimate: v.optional(v.picklist(['run', 'skip']), 'run'),
+});
+/**
+ * The consensus configuration stored on a pipeline step (set in the builder for
+ * a step whose agent kind carries a consensus trait). When `enabled` is false
+ * the step runs as the standard agent.
+ */
+export const consensusStepConfigSchema = v.object({
+    enabled: v.boolean(),
+    strategy: consensusStrategySchema,
+    participants: v.array(consensusParticipantSchema),
+    /** Model that runs the neutral synthesis / judging pass; absent ⇒ step default. */
+    synthesizerModelId: v.optional(v.string()),
+    /** Debate rounds (1..5); ignored by non-debate strategies. Default applied by the engine. */
+    rounds: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(5))),
+    /** Optional gating of the process on the task estimate; absent ⇒ always run when enabled. */
+    gating: v.optional(consensusGatingSchema),
+});
+/**
+ * A `task-estimator` agent's structured triage of a task along three axes
+ * (each 0..1; higher = more complex / riskier / higher blast-radius). Produced
+ * after requirements are clarified and the spec is structured, persisted on the
+ * block, surfaced in the UI, and used to gate consensus steps. This is CORE —
+ * it ships independent of the consensus package.
+ */
+export const taskEstimateSchema = v.object({
+    complexity: scoreSchema,
+    risk: scoreSchema,
+    impact: scoreSchema,
+    /** The estimator's plain-prose justification for the scores. */
+    rationale: v.string(),
+    /** Identifier of the model that produced the estimate, for transparency. */
+    model: v.optional(v.nullable(v.string())),
+    createdAt: v.number(),
+});
+// ---- Session transcript (the persisted + streamed observability surface) ----
+/** One scored dimension a ranked-voting participant assigned (0..1). */
+export const consensusScoreSchema = v.object({
+    dimension: v.string(),
+    value: scoreSchema,
+    rationale: v.optional(v.string()),
+});
+/** One participant's contribution within a round (an argument, critique, or scoring). */
+export const consensusContributionSchema = v.object({
+    participantId: v.string(),
+    text: v.string(),
+    scores: v.optional(v.array(consensusScoreSchema)),
+});
+/** A single round of the process. `kind` distinguishes the dialectic phases. */
+export const consensusRoundSchema = v.object({
+    index: v.number(),
+    kind: v.optional(v.picklist(['draft', 'critique', 'score'])),
+    contributions: v.array(consensusContributionSchema),
+});
+export const consensusSessionStatusSchema = v.picklist([
+    'running',
+    'synthesizing',
+    'done',
+    'failed',
+]);
+/**
+ * The full transcript of a consensus session: who participated, the round-by-round
+ * contributions, the synthesized result, and confidence/dissent. Persisted
+ * (`consensus_sessions`) and streamed live so the dedicated window can visualize
+ * the process. One per (executionId, stepIndex).
+ */
+export const consensusSessionSchema = v.object({
+    id: v.string(),
+    blockId: v.string(),
+    executionId: v.nullable(v.string()),
+    stepIndex: v.number(),
+    /** The underlying agent kind this session ran for (e.g. `architect`). */
+    agentKind: v.string(),
+    strategy: consensusStrategySchema,
+    status: consensusSessionStatusSchema,
+    participants: v.array(consensusParticipantSchema),
+    rounds: v.array(consensusRoundSchema),
+    /** The neutral synthesis / winning result; null until the synthesis pass completes. */
+    synthesis: v.nullable(v.string()),
+    /** Aggregate confidence in the result (0..1), when the strategy yields one. */
+    confidence: v.optional(v.nullable(v.number())),
+    /** Notable unresolved disagreements surfaced by the synthesizer. */
+    dissent: v.optional(v.array(v.string())),
+    /** Failure detail when `status` is `failed`. */
+    error: v.optional(v.nullable(v.string())),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+/** Parse-or-throw a task estimate payload an agent returned (the engine validates it). */
+export function parseTaskEstimate(value) {
+    return v.parse(taskEstimateSchema, value);
+}
+/** Parse-or-throw a consensus step config (used when persisting builder edits). */
+export function parseConsensusStepConfig(value) {
+    return v.parse(consensusStepConfigSchema, value);
+}
+//# sourceMappingURL=consensus.js.map

package/dist/consensus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consensus.js","sourceRoot":"","sources":["../src/consensus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,0CAA0C;AAC1C,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,4EAA4E;AAC5E,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAC5E,gEAAgE;AAChE,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,iFAAiF;AACjF,8EAA8E;AAE9E,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;AAEpE,mFAAmF;AACnF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,kBAAkB,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAA;AAGlG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,uEAAuE;IACvE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,8EAA8E;IAC9E,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACrC,8EAA8E;IAC9E,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAChC,CAAC,CAAA;AAGF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IACtC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IAChC,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IAClC,iBAAiB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,EAAE,WAAW,CAAC;CAClF,CAAC,CAAA;AAGF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IACtC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IAChC,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IAClC,iBAAiB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC;CAClE,CAAC,CAAA;AAGF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,QAAQ,EAAE,uBAAuB;IACjC,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IACjD,mFAAmF;IACnF,kBAAkB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1C,6FAA6F;IAC7F,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,6FAA6F;IAC7F,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;CAC1C,CAAC,CAAA;AAGF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,UAAU,EAAE,WAAW;IACvB,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,WAAW;IACnB,gEAAgE;IAChE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,4EAA4E;IAC5E,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAGF,gFAAgF;AAEhF,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,KAAK,EAAE,WAAW;IAClB,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAClC,CAAC,CAAA;AAGF,yFAAyF;AACzF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;CAClD,CAAC,CAAA;AAGF,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5D,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,2BAA2B,CAAC;CACpD,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,QAAQ,CAAC;IACrD,SAAS;IACT,cAAc;IACd,MAAM;IACN,QAAQ;CACT,CAAC,CAAA;AAGF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,yEAAyE;IACzE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,uBAAuB;IACjC,MAAM,EAAE,4BAA4B;IACpC,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IACjD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC;IACrC,uFAAuF;IACvF,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACjC,+EAA+E;IAC/E,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,oEAAoE;IACpE,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,gDAAgD;IAChD,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAGF,0FAA0F;AAC1F,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,CAAC,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAA;AAC3C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,CAAC,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAA;AAClD,CAAC"}