@cat-factory/contracts 0.308.1 → 0.310.0

package/dist/step-decisions.js

@@ -23,6 +23,65 @@ export const decisionSchema = v.object({
     options: v.array(v.string()),
     chosen: v.nullable(v.string()),
 });
+/**
+ * How urgently a review comment must be acted on, worst first. The three levels are the ones a
+ * reviewer already writes as prose group labels ("Must fix" / "Should fix" / "Minor"), promoted to
+ * a field so the ENGINE can act on them rather than a human having to read the summary to find out
+ * what blocks the work.
+ *
+ * `blocker` is the load-bearing member and the only one with mechanical force: while a companion's
+ * latest verdict carries one, the producer is reworked and the run does not advance past the step,
+ * whatever the overall rating says (see {@link hasBlockingReviewComments} and kernel's
+ * `disposeCompanionVerdict`). A rating is one number over a whole deliverable, so a review that
+ * found something genuinely unshippable could still average above the bar and be waved through;
+ * that is the gap this closes. `major` and `minor` differ only in how a reader (and a reworking
+ * producer) should prioritise them.
+ */
+export const reviewCommentSeveritySchema = v.picklist(['blocker', 'major', 'minor']);
+/** Rank of a {@link ReviewCommentSeverity}, for worst-first ordering and "at or above" tests. */
+export const REVIEW_COMMENT_SEVERITY_RANK = {
+    minor: 0,
+    major: 1,
+    blocker: 2,
+};
+const REVIEW_COMMENT_SEVERITY_SET = new Set(reviewCommentSeveritySchema.options);
+/**
+ * Whether a value is still a member of the vocabulary — DERIVED from the picklist, so it cannot
+ * drift from it the way a hand-written second list would.
+ *
+ * The vocabulary is closed but PERSISTED (a verdict's `comments`, a gate's `comments`, a step's
+ * `rework.comments`), and the schema's `severity` fallback does NOT cover those reads: a stored run
+ * row is mapped onto {@link StepReviewComment} by the facade repositories, never re-parsed, so the
+ * fallback runs on the MODEL REPLY and nowhere else. A member retired from the union therefore goes
+ * on existing in saved rows with its type claiming otherwise, and every `Record<ReviewCommentSeverity, …>`
+ * over it is total against the TYPE and partial against the DATA. Narrow with this at the read
+ * boundary and render the negative case as the unrecognised level it is.
+ *
+ * A retired member here is NAMED rather than dropped or mapped onto a current one, for the reason
+ * `isBinaryModality` names its own: nothing knows which surviving level was meant, and the reader
+ * that meets a stale value first is the panel asking a person to act on the finding. What it must
+ * never do is claim an urgency nobody graded. It carries no mechanical force either (a stale value
+ * is not a `blocker`), so retiring a member means restating the stored rows in the same change;
+ * this is what keeps the interim honest instead of invisible.
+ */
+export function isReviewCommentSeverity(value) {
+    return REVIEW_COMMENT_SEVERITY_SET.has(value);
+}
+/** Where an ungraded comment (and an unrecognised level) sorts: below every graded one. */
+export const UNGRADED_REVIEW_COMMENT_RANK = -1;
+/**
+ * The rank a comment's severity sorts and compares at: {@link REVIEW_COMMENT_SEVERITY_RANK} while
+ * the vocabulary holds it, and {@link UNGRADED_REVIEW_COMMENT_RANK} when the comment carries no
+ * severity (a person's) or one this build no longer knows ({@link isReviewCommentSeverity}).
+ *
+ * The ONE place that lookup happens, so an unrecognised value cannot reach the `Record` raw and
+ * come back `undefined` — which sorts by `NaN` and compares false against every floor at once.
+ */
+export function reviewCommentSeverityRank(severity) {
+    return severity !== undefined && isReviewCommentSeverity(severity)
+        ? REVIEW_COMMENT_SEVERITY_RANK[severity]
+        : UNGRADED_REVIEW_COMMENT_RANK;
+}
 /**
  * One GitHub-review-style comment left on a specific block or item of an agent's
  * proposal — either by a human reviewing an approval gate, or by a quality
@@ -56,9 +115,63 @@ export const stepReviewCommentSchema = v.object({
      * items rather than free prose. Absent for prose-range comments.
      */
     anchorId: v.optional(v.string()),
+    /**
+     * How urgently this point must be acted on (see {@link reviewCommentSeveritySchema}).
+     *
+     * Absent on a HUMAN's comment, which carries no such grading: a person requesting changes on an
+     * approval gate is already holding the run, so there is nothing for a severity to decide. Absent
+     * too on a comment recorded before this field existed. An absent severity is therefore read as
+     * "ungraded", NEVER as a blocker and never as a nit — the one reader that acts on the value
+     * ({@link hasBlockingReviewComments}) asks only whether a `blocker` is present.
+     *
+     * An out-of-vocabulary value from a model reads as `major`, the same "unreadable severity reads
+     * as its safe default" rule the judge and PR-review findings use. `major` rather than either
+     * extreme on purpose: a typo must not manufacture a hard stop, and it must not silently retire
+     * one either, so it lands where the point still costs a rework round without holding the run.
+     *
+     * That fallback covers the MODEL REPLY, which is the only input this schema parses. A stored row
+     * is mapped onto the type by the facade repositories rather than re-parsed, so a value this build
+     * has retired reaches a reader with the fallback never having run: narrow those reads with
+     * {@link isReviewCommentSeverity} / {@link reviewCommentSeverityRank}.
+     */
+    severity: v.optional(v.fallback(reviewCommentSeveritySchema, 'major')),
     /** The reviewer's note on this block / item. */
     body: v.string(),
 });
+/**
+ * The comments that MUST be fixed before the work moves on, worst-first-ordered input aside.
+ *
+ * The pure rule, in contracts rather than in the engine, because both sides have to agree about
+ * it: the engine decides whether the run advances, and the SPA states on the parked step WHY it
+ * stopped and which points to look at. Restated on each side, the panel would eventually count
+ * findings the engine did not.
+ */
+export function blockingReviewComments(comments) {
+    return (comments ?? []).filter((comment) => comment.severity === 'blocker');
+}
+/** Whether any of `comments` is a `blocker` (see {@link blockingReviewComments}). */
+export function hasBlockingReviewComments(comments) {
+    return (comments ?? []).some((comment) => comment.severity === 'blocker');
+}
+/**
+ * Whether a review raised anything it did NOT call a nit.
+ *
+ * What separates a batch worth sending back to the producer from one that only had polish to offer:
+ * a `minor` is stated to the reviewer as "never worth holding anything for", so a rule that spent a
+ * producer re-run plus a re-grading call on one would make that instruction false (kernel's
+ * `disposeCompanionVerdict` is the reader).
+ *
+ * Everything that is not the nit level counts, which puts an UNGRADED comment and a level this build
+ * has retired on the acting side. Both are cases where the urgency is unknown rather than known to
+ * be low, and the cheap error is one wasted round against a point silently dropped.
+ */
+export function hasReviewCommentsBeyondNits(comments) {
+    return (comments ?? []).some((comment) => comment.severity !== 'minor');
+}
+/** `comments` ordered worst severity first; an ungraded comment sorts last. Stable within a level. */
+export function bySeverityWorstFirst(comments) {
+    return [...comments].sort((a, b) => reviewCommentSeverityRank(b.severity) - reviewCommentSeverityRank(a.severity));
+}
 /**
  * The standardized, stored verdict a quality companion produced for an output it
  * graded — shared by every companion site (the pipeline companion step and the
@@ -86,6 +199,10 @@ export const companionVerdictSchema = v.object({
      * mirror-image reason — so it cannot regress on a point raised two rounds ago and forgotten.
      *
      * Absent on a round that anchored nothing, and on every verdict written before this existed.
+     *
+     * Their SEVERITIES are what makes the verdict self-describing: `passed: false` on a round whose
+     * rating cleared `threshold` is only readable next to the `blocker` that held it (see
+     * {@link reviewCommentSeveritySchema}).
      */
     comments: v.optional(v.array(stepReviewCommentSchema)),
 });

package/dist/step-decisions.js.map

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

package/dist/visual-pipeline.d.ts

@@ -1,3 +1,4 @@
+import { type RunServiceScope } from './step-conditions.js';
 import type { Block, Pipeline } from './entities.js';
 /**
  * The agent kind that drives a real browser against a running frontend and captures a
@@ -13,8 +14,30 @@ export declare const UI_TESTER_AGENT_KIND = "tester-ui";
 export declare const VISUAL_CONFIRM_AGENT_KIND = "visual-confirmation";
 /** The visual step kinds: a pipeline carrying any of these is a "visual" pipeline. */
 export declare const VISUAL_STEP_KINDS: readonly ["tester-ui", "visual-confirmation"];
-/** Whether a pipeline includes any visual step (`tester-ui` / `visual-confirmation`). */
+/**
+ * Whether a pipeline includes any visual step (`tester-ui` / `visual-confirmation`) AT ALL,
+ * conditional ones included. The question for a caller asking whether the pipeline could ever
+ * drive a browser (run start resolves the frontend bindings off it). A caller deciding whether
+ * a pipeline may run HERE wants {@link pipelineRunsVisualStep} instead.
+ */
 export declare function pipelineHasVisualStep(pipeline: Pick<Pipeline, 'agentKinds'>): boolean;
+/**
+ * Whether a run of `scope` would actually REACH a visual step: the steps that are enabled and
+ * whose run condition (`stepOptions[i].condition`) the scope admits. This is the question the
+ * frame gate below has to ask, and it is NOT the same as "does the pipeline list one".
+ *
+ * Since the build ladder carries the CONDITIONAL tester pair, every build preset lists a
+ * `tester-ui` scoped to `serviceScope: 'frontend'`. On a backend service that step is skipped
+ * before it dispatches, so the pipeline demands no UI and the run starts fine — which is exactly
+ * what run admission concludes, filtering the chain through the same two rules before it reaches
+ * the frame gate. Asking the coarse question there instead hides every build rung from every
+ * picker on every non-frontend service.
+ *
+ * An UNRESOLVABLE scope (neither half set: a block under no service frame) admits every
+ * condition, the fail-safe direction `stepConditionSatisfied` takes throughout: the visual step
+ * would run, so the frame gate gets to refuse it rather than a condition quietly excusing it.
+ */
+export declare function pipelineRunsVisualStep(pipeline: Pick<Pipeline, 'agentKinds' | 'enabled' | 'stepOptions'>, scope: RunServiceScope): boolean;
 /**
  * Whether a visual pipeline may run on a task under `frame`. A visual step needs a UI to
  * exercise, which exists when the enclosing frame is either:

package/dist/visual-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"visual-pipeline.d.ts","sourceRoot":"","sources":["../src/visual-pipeline.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAepD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,wBAAwB,CAAA;AAE9D,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,+CAA6D,CAAA;AAE3F,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,OAAO,CAIrF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,EACpD,MAAM,EAAE,SAAS,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,gBAAgB,CAAC,EAAE,GAClE,OAAO,CAWT;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,SAAS,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,gBAAgB,CAAC,EAAE,GAClE,MAAM,EAAE,CAcV"}
+{"version":3,"file":"visual-pipeline.d.ts","sourceRoot":"","sources":["../src/visual-pipeline.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAA0B,MAAM,sBAAsB,CAAA;AACnF,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAoBpD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,wBAAwB,CAAA;AAE9D,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,+CAA6D,CAAA;AAY3F;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,OAAO,CAErF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,aAAa,CAAC,EAClE,KAAK,EAAE,eAAe,GACrB,OAAO,CAOT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,EACpD,MAAM,EAAE,SAAS,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,gBAAgB,CAAC,EAAE,GAClE,OAAO,CAWT;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,SAAS,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,gBAAgB,CAAC,EAAE,GAClE,MAAM,EAAE,CAcV"}

package/dist/visual-pipeline.js

@@ -1,15 +1,21 @@
 import { resolveFrontendServePort } from './frontend.js';
+import { stepConditionSatisfied } from './step-conditions.js';
 // ---------------------------------------------------------------------------
 // Visual-pipeline gating (shared by the SPA surface + the backend run-start gate).
 //
 // A "visual" pipeline exercises a rendered UI — it either drives a real browser
 // against a running frontend (`tester-ui`) or parks for a human to review the
 // captured screenshots vs the task's reference designs (`visual-confirmation`).
-// Such a pipeline only makes sense where there IS a UI to exercise: a `frontend`
+// Such a step only makes sense where there IS a UI to exercise: a `frontend`
 // frame (it owns the app under test), or a frame a `frontend` frame links to (the
 // linked frontend is the UI a change to that service is validated through). The SPA
 // uses these predicates to surface visual pipelines only where they can run; the
 // backend gates a run start on the SAME rule so the guarantee holds server-side.
+//
+// What a pipeline LISTS and what a run REACHES are two questions, and the gate wants the
+// second: a visual step scoped to a frontend service (`stepOptions[i].condition`) excuses
+// itself from a backend run before it dispatches, which is what lets one build preset carry
+// both testers. See `pipelineRunsVisualStep`.
 // ---------------------------------------------------------------------------
 /**
  * The agent kind that drives a real browser against a running frontend and captures a
@@ -25,9 +31,44 @@ export const UI_TESTER_AGENT_KIND = 'tester-ui';
 export const VISUAL_CONFIRM_AGENT_KIND = 'visual-confirmation';
 /** The visual step kinds: a pipeline carrying any of these is a "visual" pipeline. */
 export const VISUAL_STEP_KINDS = [UI_TESTER_AGENT_KIND, VISUAL_CONFIRM_AGENT_KIND];
-/** Whether a pipeline includes any visual step (`tester-ui` / `visual-confirmation`). */
+/**
+ * Whether an agent kind drives a rendered UI. Reads {@link VISUAL_STEP_KINDS} rather than
+ * re-spelling the disjunction, so a third visual kind added to that list is seen by both
+ * predicates below instead of leaving the frame gate quietly offering a UI-driving pipeline on a
+ * frame with no UI.
+ */
+function isVisualStepKind(kind) {
+    return VISUAL_STEP_KINDS.includes(kind);
+}
+/**
+ * Whether a pipeline includes any visual step (`tester-ui` / `visual-confirmation`) AT ALL,
+ * conditional ones included. The question for a caller asking whether the pipeline could ever
+ * drive a browser (run start resolves the frontend bindings off it). A caller deciding whether
+ * a pipeline may run HERE wants {@link pipelineRunsVisualStep} instead.
+ */
 export function pipelineHasVisualStep(pipeline) {
-    return pipeline.agentKinds.some((kind) => kind === UI_TESTER_AGENT_KIND || kind === VISUAL_CONFIRM_AGENT_KIND);
+    return pipeline.agentKinds.some(isVisualStepKind);
+}
+/**
+ * Whether a run of `scope` would actually REACH a visual step: the steps that are enabled and
+ * whose run condition (`stepOptions[i].condition`) the scope admits. This is the question the
+ * frame gate below has to ask, and it is NOT the same as "does the pipeline list one".
+ *
+ * Since the build ladder carries the CONDITIONAL tester pair, every build preset lists a
+ * `tester-ui` scoped to `serviceScope: 'frontend'`. On a backend service that step is skipped
+ * before it dispatches, so the pipeline demands no UI and the run starts fine — which is exactly
+ * what run admission concludes, filtering the chain through the same two rules before it reaches
+ * the frame gate. Asking the coarse question there instead hides every build rung from every
+ * picker on every non-frontend service.
+ *
+ * An UNRESOLVABLE scope (neither half set: a block under no service frame) admits every
+ * condition, the fail-safe direction `stepConditionSatisfied` takes throughout: the visual step
+ * would run, so the frame gate gets to refuse it rather than a condition quietly excusing it.
+ */
+export function pipelineRunsVisualStep(pipeline, scope) {
+    return pipeline.agentKinds.some((kind, i) => isVisualStepKind(kind) &&
+        pipeline.enabled?.[i] !== false &&
+        stepConditionSatisfied(pipeline.stepOptions?.[i]?.condition, scope));
 }
 /**
  * Whether a visual pipeline may run on a task under `frame`. A visual step needs a UI to

package/dist/visual-pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"visual-pipeline.js","sourceRoot":"","sources":["../src/visual-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAA;AAGxD,8EAA8E;AAC9E,mFAAmF;AACnF,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,gFAAgF;AAChF,iFAAiF;AACjF,kFAAkF;AAClF,oFAAoF;AACpF,iFAAiF;AACjF,iFAAiF;AACjF,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAA;AAE/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAA;AAE9D,sFAAsF;AACtF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,oBAAoB,EAAE,yBAAyB,CAAU,CAAA;AAE3F,yFAAyF;AACzF,MAAM,UAAU,qBAAqB,CAAC,QAAsC;IAC1E,OAAO,QAAQ,CAAC,UAAU,CAAC,IAAI,CAC7B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,oBAAoB,IAAI,IAAI,KAAK,yBAAyB,CAC9E,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAoD,EACpD,MAAmE;IAEnE,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IACxB,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,IAAI,CAAA;IAC1C,OAAO,MAAM,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,KAAK,KAAK,OAAO;QACnB,CAAC,CAAC,IAAI,KAAK,UAAU;QACrB,CAAC,CAAC,CAAC,cAAc,EAAE,eAAe,IAAI,EAAE,CAAC,CAAC,IAAI,CAC5C,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,KAAK,CAAC,EAAE,CACpF,CACJ,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,yBAAyB,CACvC,cAAsB,EACtB,MAAmE;IAEnE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IACjC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,CAAC,cAAc;YAAE,SAAQ;QAC/E,MAAM,YAAY,GAAG,CAAC,CAAC,cAAc,CAAC,eAAe,CAAC,IAAI,CACxD,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS;YAC9B,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,cAAc;YAC7C,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAChC,CAAA;QACD,IAAI,CAAC,YAAY;YAAE,SAAQ;QAC3B,OAAO,CAAC,GAAG,CAAC,oBAAoB,wBAAwB,CAAC,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,CAAA;IACzF,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;AAC5B,CAAC"}
+{"version":3,"file":"visual-pipeline.js","sourceRoot":"","sources":["../src/visual-pipeline.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/contracts",
-  "version": "0.308.1",
+  "version": "0.310.0",
   "description": "Valibot wire contract shared between the Agent Architecture Board frontend and backend.",
   "repository": {
     "type": "git",