@smileid/usesmileid 12.0.0-beta01

package/src/presentation/flow/validation/job_type_validator.ts

@@ -0,0 +1,645 @@
+import type { MLConfig } from "../../../core/models/ml_config";
+import type { NetworkConfig } from "../../../core/models/network_config";
+import type {
+  BiometricKYCParams,
+  ConsentInformation,
+  DocumentVerificationParams,
+  EnhancedDocumentVerificationParams,
+  EnhancedKYCParams,
+  UserDetails,
+} from "../../../core/models/params";
+import { JobType } from "../../../core/models/job_type";
+import type { ScreenSpec } from "../dsl/builder/screens_builder";
+import { CaptureType } from "../dsl/builder/screens_builder";
+import { InvalidJobTypeScreenConfigException } from "../../../core/exception/job_validation_exceptions";
+import {
+  DuplicateScreenTypeException,
+  InvalidScreenOrderException,
+  MissingCaptureForPreviewException,
+} from "../../../core/exception/screen_config_validation_exceptions";
+import { IssueSeverity } from "../../../core/exception/issue_severity";
+import type { ValidationIssue } from "./validation_state";
+
+/**
+ * Job-type-specific flow validation rules.
+ *
+ * Every rule that decides whether a flow's screen composition is valid
+ * for the configured job lives in this module — duplicate screen types,
+ * screen ordering, preview placement, ML analyzer dependencies, consent
+ * presence, capture counts, processing, and per-job field requirements.
+ * `FlowValidator` only owns the builder / job-agnostic concerns (empty
+ * screens, per-screen config, ML / Network block presence, missing job
+ * type) before dispatching to the matching validator.
+ *
+ * Adding a new job type requires only a new entry in
+ * `FlowValidator`'s `jobTypeValidators` registry — `FlowValidator`
+ * itself never changes.
+ *
+ * Each rule appends typed `InvalidJobTypeScreenConfigException` /
+ * `DuplicateScreenTypeException` / `InvalidScreenOrderException` /
+ * `MissingCaptureForPreviewException` instances so partner tooling can
+ * pivot on `errorCode` or regex-match on the message text.
+ */
+
+/**
+ * A `JobTypeValidator` runs every composition rule for one job type and
+ * appends any findings to `issues`. Implemented as a class per job-type
+ * family so the registry can map a `JobType` to a single instance.
+ */
+export interface JobTypeValidator {
+  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void;
+}
+
+/**
+ * Inputs the job-type rules read. A subset of the `FlowValidator`
+ * input — only the fields the per-`JobType` rules actually consume.
+ */
+export type JobTypeValidatorInput = {
+  readonly steps: readonly ScreenSpec[];
+  readonly network?: NetworkConfig | undefined;
+  readonly ml?: MLConfig | undefined;
+  readonly consentInformation?: ConsentInformation | undefined;
+  readonly enhancedKYCParams?: EnhancedKYCParams | undefined;
+  readonly biometricKYCParams?: BiometricKYCParams | undefined;
+  readonly documentVerificationParams?: DocumentVerificationParams | undefined;
+  readonly enhancedDocumentVerificationParams?:
+    | EnhancedDocumentVerificationParams
+    | undefined;
+  readonly userDetails?: UserDetails | undefined;
+};
+
+/**
+ * Stable display label for a `JobType` enum value, matching the
+ * canonical name carried in the `Invalid configuration for {name}:`
+ * message string. The DSL-facing `JobType` keys are camelCase; this map
+ * supplies the PascalCase label used in partner-visible copy.
+ */
+const JOB_TYPE_NAMES: ReadonlyMap<JobType, string> = new Map<JobType, string>([
+  [JobType.biometricKyc, "BiometricKyc"],
+  [JobType.smartSelfieAuthentication, "SmartSelfieAuthentication"],
+  [JobType.smartSelfieEnrollment, "SmartSelfieEnrollment"],
+  [JobType.enhancedKyc, "EnhancedKyc"],
+  [JobType.documentVerification, "DocumentVerification"],
+  [JobType.bvn, "BVN"],
+  [JobType.enhancedDocumentVerification, "EnhancedDocumentVerification"],
+  [JobType.unknown, "Unknown"],
+]);
+
+/**
+ * Resolve the partner-visible label for a `JobType` value.
+ */
+function jobTypeName(jobType: JobType): string {
+  return JOB_TYPE_NAMES.get(jobType) ?? "Unknown";
+}
+
+/**
+ * Consent rule: exactly one form of consent is required — either a
+ * Consent screen or pre-supplied `consentInformation`, never both and
+ * never neither.
+ */
+function appendConsentRule(
+  jobType: JobType,
+  input: JobTypeValidatorInput,
+  issues: ValidationIssue[],
+): void {
+  const hasConsentScreen = input.steps.some((s) => s.kind === "consent");
+  const hasConsentInformation = input.consentInformation !== undefined;
+  if (!hasConsentScreen && !hasConsentInformation) {
+    issues.push(
+      InvalidJobTypeScreenConfigException.forJob({
+        jobType,
+        reason:
+          "must include either a Consent screen or a pre-supplied consentInformation",
+        suggestedFix:
+          "Add a consent { } screen to your flow, or supply consentInformation via the builder",
+      }),
+    );
+  } else if (hasConsentScreen && hasConsentInformation) {
+    issues.push(
+      InvalidJobTypeScreenConfigException.forJob({
+        jobType,
+        reason:
+          "must not include both a Consent screen and a pre-supplied consentInformation — use one or the other",
+        suggestedFix:
+          "Remove the consent { } screen if supplying consentInformation, or clear consentInformation if using the consent screen",
+      }),
+    );
+  }
+}
+
+/**
+ * Reject more than one screen of any non-Capture, non-Preview type.
+ * Capture screens may repeat (selfie + document) and Preview screens are
+ * governed by the per-job preview rule instead, so both are excluded.
+ */
+function appendDuplicateScreenRule(
+  steps: readonly ScreenSpec[],
+  issues: ValidationIssue[],
+): void {
+  const indicesByKind = new Map<string, number[]>();
+  steps.forEach((step, index) => {
+    if (step.kind === "capture" || step.kind === "preview") return;
+    const list = indicesByKind.get(step.kind) ?? [];
+    list.push(index);
+    indicesByKind.set(step.kind, list);
+  });
+  for (const [kind, indices] of indicesByKind) {
+    if (indices.length > 1) {
+      issues.push(
+        new DuplicateScreenTypeException({ screenType: kind, indices }),
+      );
+    }
+  }
+}
+
+/**
+ * Enforce consent-first, processing-last, and instructions-before-capture
+ * ordering. Preview ordering is handled by `appendPreviewRule`.
+ */
+function appendScreenOrderRule(
+  steps: readonly ScreenSpec[],
+  issues: ValidationIssue[],
+): void {
+  const consentIndex = steps.findIndex((s) => s.kind === "consent");
+  if (consentIndex > 0) {
+    issues.push(
+      new InvalidScreenOrderException({
+        description: "Consent screen must be the first screen in the flow",
+        severity: IssueSeverity.error,
+      }),
+    );
+  }
+  const processingIndex = steps.findIndex((s) => s.kind === "processing");
+  if (processingIndex !== -1 && processingIndex !== steps.length - 1) {
+    issues.push(
+      new InvalidScreenOrderException({
+        description: "Processing screen must be the last screen in the flow",
+        severity: IssueSeverity.error,
+      }),
+    );
+  }
+  let hasCaptureBeforeThisPoint = false;
+  steps.forEach((step, index) => {
+    if (step.kind === "capture") {
+      hasCaptureBeforeThisPoint = true;
+    } else if (step.kind === "instructions" && hasCaptureBeforeThisPoint) {
+      issues.push(
+        new InvalidScreenOrderException({
+          description: `Instructions screen at index ${index} must appear before the Capture screen`,
+          severity: IssueSeverity.error,
+        }),
+      );
+    }
+  });
+}
+
+/**
+ * Preview rule for flows that allow at most `maxPreviews` preview
+ * screens, each of which must follow a Capture screen. A preview with
+ * no preceding capture emits `MissingCaptureForPreviewException`; an
+ * extra preview beyond `maxPreviews` emits `InvalidScreenOrderException`.
+ */
+function appendPreviewRule(
+  steps: readonly ScreenSpec[],
+  maxPreviews: number,
+  issues: ValidationIssue[],
+): void {
+  let hasCaptureBeforeThisPoint = false;
+  let previewCount = 0;
+  steps.forEach((step, index) => {
+    if (step.kind === "capture") {
+      hasCaptureBeforeThisPoint = true;
+    } else if (step.kind === "preview") {
+      previewCount += 1;
+      if (!hasCaptureBeforeThisPoint) {
+        issues.push(
+          new MissingCaptureForPreviewException({ previewIndex: index }),
+        );
+      } else if (previewCount > maxPreviews) {
+        issues.push(
+          new InvalidScreenOrderException({
+            description: `Preview screen at index ${index} exceeds the maximum of ${maxPreviews} preview screen(s) allowed for this flow`,
+            severity: IssueSeverity.error,
+          }),
+        );
+      }
+    }
+  });
+}
+
+/**
+ * Processing screen is required for every job type. The companion
+ * `network { }` block requirement is surfaced by `FlowValidator`
+ * (job-agnostic) to keep a single emission point.
+ */
+function appendProcessingRule(
+  jobType: JobType,
+  input: JobTypeValidatorInput,
+  issues: ValidationIssue[],
+): void {
+  const hasProcessingScreen = input.steps.some((s) => s.kind === "processing");
+  if (!hasProcessingScreen) {
+    issues.push(
+      InvalidJobTypeScreenConfigException.forJob({
+        jobType,
+        reason: "must include a Processing screen",
+        suggestedFix:
+          "Add a processing { } screen as the last screen in the flow",
+      }),
+    );
+  }
+}
+
+/**
+ * Enforce exactly one selfie Capture screen.
+ */
+function appendSelfieCaptureRule(
+  jobType: JobType,
+  input: JobTypeValidatorInput,
+  issues: ValidationIssue[],
+): void {
+  const selfieCaptures = input.steps.filter(
+    (s) => s.kind === "capture" && s.config.captureType === CaptureType.selfie,
+  );
+  if (selfieCaptures.length === 0) {
+    issues.push(
+      InvalidJobTypeScreenConfigException.forJob({
+        jobType,
+        reason:
+          "must include exactly one Capture screen with captureType = SELFIE",
+        suggestedFix:
+          "Add a capture { captureType = CaptureType.SELFIE } screen to your flow",
+      }),
+    );
+  } else if (selfieCaptures.length > 1) {
+    issues.push(
+      InvalidJobTypeScreenConfigException.forJob({
+        jobType,
+        reason: `must include exactly one Capture screen with captureType = SELFIE, but found ${selfieCaptures.length}`,
+        suggestedFix:
+          "Remove the extra selfie capture screens — only one is allowed",
+      }),
+    );
+  }
+}
+
+/**
+ * Validate the selfie ML analyzer dependency. A Capture screen requires
+ * an `ml { }` block, and that block must register analyzers for
+ * `CaptureType.SELFIE`. The missing-block warning is owned by
+ * `FlowValidator`; this rule emits only the error-severity
+ * `InvalidJobTypeScreenConfigException`.
+ */
+function appendSelfieMlRule(
+  jobType: JobType,
+  input: JobTypeValidatorInput,
+  missingMlSuggestedFix: string,
+  issues: ValidationIssue[],
+): void {
+  if (!input.ml) {
+    issues.push(
+      InvalidJobTypeScreenConfigException.forJob({
+        jobType,
+        reason:
+          "ml { } block is required and must register analyzers for CaptureType.SELFIE",
+        suggestedFix: missingMlSuggestedFix,
+      }),
+    );
+  } else if (!input.ml.analyzers.selfie) {
+    issues.push(
+      InvalidJobTypeScreenConfigException.forJob({
+        jobType,
+        reason: "ml { } block must register analyzers for CaptureType.SELFIE",
+        suggestedFix:
+          "Add forCaptureType(CaptureType.SELFIE) { } inside the ml { } block",
+      }),
+    );
+  }
+}
+
+/**
+ * Validates selfie-only flows: BiometricKyc, SmartSelfieAuthentication,
+ * SmartSelfieEnrollment.
+ *
+ * Allows at most one Preview screen, which must follow a Capture screen.
+ */
+export class SelfieJobTypeValidator implements JobTypeValidator {
+  constructor(private readonly jobType: JobType) {}
+
+  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void {
+    appendDuplicateScreenRule(input.steps, issues);
+    appendScreenOrderRule(input.steps, issues);
+    appendPreviewRule(input.steps, 1, issues);
+    appendConsentRule(this.jobType, input, issues);
+
+    appendSelfieCaptureRule(this.jobType, input, issues);
+
+    const hasDocumentCapture = input.steps.some(
+      (s) =>
+        s.kind === "capture" && s.config.captureType === CaptureType.document,
+    );
+    if (hasDocumentCapture) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason: "must not include a Document capture screen",
+          suggestedFix: `Remove the Document capture screen — ${jobTypeName(this.jobType)} requires selfie capture only`,
+        }),
+      );
+    }
+
+    appendProcessingRule(this.jobType, input, issues);
+
+    appendSelfieMlRule(
+      this.jobType,
+      input,
+      "Add the ml { } block with forCaptureType(CaptureType.SELFIE) { } inside",
+      issues,
+    );
+    if (input.ml?.analyzers.document) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason:
+            "ml { } block must not register analyzers for CaptureType.DOCUMENT",
+          suggestedFix: `Remove forCaptureType(CaptureType.DOCUMENT) { } from the ml { } block — ${jobTypeName(this.jobType)} does not use document capture`,
+        }),
+      );
+    }
+
+    if (
+      this.jobType === JobType.biometricKyc &&
+      input.biometricKYCParams === undefined
+    ) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason: "biometricKYCParams is required for BiometricKyc jobs",
+          suggestedFix:
+            "Set builder.biometricKYCParams with the identity fields before building",
+        }),
+      );
+    }
+
+    if (input.userDetails === undefined) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason: `userDetails is required for ${jobTypeName(this.jobType)} jobs`,
+          suggestedFix:
+            "Set builder.userDetails with the end user PII before building",
+        }),
+      );
+    }
+  }
+}
+
+/**
+ * Validates document flows: DocumentVerification,
+ * EnhancedDocumentVerification.
+ *
+ * Allows up to two Preview screens (a selfie-step preview and a
+ * document-step preview); each must follow a Capture screen. The
+ * document analyzer is optional — the native pipeline falls back to a
+ * noop document detector — but a selfie analyzer is required for the
+ * biometric match against the document portrait.
+ */
+export class DocumentJobTypeValidator implements JobTypeValidator {
+  constructor(private readonly jobType: JobType) {}
+
+  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void {
+    appendDuplicateScreenRule(input.steps, issues);
+    appendScreenOrderRule(input.steps, issues);
+    appendPreviewRule(input.steps, 2, issues);
+    appendConsentRule(this.jobType, input, issues);
+
+    appendSelfieCaptureRule(this.jobType, input, issues);
+
+    const documentCaptures = input.steps.filter(
+      (s) =>
+        s.kind === "capture" && s.config.captureType === CaptureType.document,
+    );
+    if (documentCaptures.length === 0) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason:
+            "must include exactly one Capture screen with captureType = DOCUMENT",
+          suggestedFix:
+            "Add a capture { captureType = CaptureType.DOCUMENT } screen to your flow",
+        }),
+      );
+    } else if (documentCaptures.length > 1) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason: `must include exactly one Capture screen with captureType = DOCUMENT, but found ${documentCaptures.length}`,
+          suggestedFix:
+            "Remove the extra document capture screens — only one is allowed",
+        }),
+      );
+    }
+
+    appendProcessingRule(this.jobType, input, issues);
+
+    // CaptureType.DOCUMENT uses a noop document detector by default — no
+    // explicit registration required.
+    appendSelfieMlRule(
+      this.jobType,
+      input,
+      "Add the ml { } block with forCaptureType(CaptureType.SELFIE) { } inside — document capture uses NoopDocumentDetectorAnalyzer by default",
+      issues,
+    );
+
+    this.appendParamsRule(input, issues);
+
+    if (input.userDetails === undefined) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason: `userDetails is required for ${jobTypeName(this.jobType)} jobs`,
+          suggestedFix:
+            "Set builder.userDetails with the end user PII before building",
+        }),
+      );
+    }
+  }
+
+  /**
+   * Require the params object for each document job. Per-field blank
+   * checks live in the standalone validators in `flow_validator.ts`.
+   */
+  private appendParamsRule(
+    input: JobTypeValidatorInput,
+    issues: ValidationIssue[],
+  ): void {
+    if (
+      this.jobType === JobType.documentVerification &&
+      input.documentVerificationParams === undefined
+    ) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason:
+            "documentVerificationParams is required for DocumentVerification jobs",
+          suggestedFix:
+            "Set builder.documentVerificationParams with the country (and optional idType) before building",
+        }),
+      );
+    }
+    if (
+      this.jobType === JobType.enhancedDocumentVerification &&
+      input.enhancedDocumentVerificationParams === undefined
+    ) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason:
+            "enhancedDocumentVerificationParams is required for EnhancedDocumentVerification jobs",
+          suggestedFix:
+            "Set builder.enhancedDocumentVerificationParams with the country and idType before building",
+        }),
+      );
+    }
+  }
+}
+
+/**
+ * Validates non-capture flows: EnhancedKyc, BVN.
+ *
+ * No capture happens, so no Preview screen is permitted. The flow must
+ * consist of consent (in-flow or pre-supplied) followed by processing.
+ * Enhanced KYC additionally requires `enhancedKYCParams` and
+ * `userDetails`.
+ */
+export class NonCaptureJobTypeValidator implements JobTypeValidator {
+  constructor(private readonly jobType: JobType) {}
+
+  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void {
+    appendDuplicateScreenRule(input.steps, issues);
+    appendScreenOrderRule(input.steps, issues);
+    appendPreviewRule(input.steps, 0, issues);
+    appendConsentRule(this.jobType, input, issues);
+
+    appendProcessingRule(this.jobType, input, issues);
+
+    const disallowedScreens = input.steps.filter(
+      (s) => s.kind !== "consent" && s.kind !== "processing",
+    );
+    if (disallowedScreens.length > 0) {
+      const types = [...new Set(disallowedScreens.map((s) => s.kind))].join(
+        ", ",
+      );
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason: `must only contain consent and processing screens, but found: ${types}`,
+          suggestedFix:
+            "Remove all screens except consent { } and processing { } from your flow",
+        }),
+      );
+    }
+
+    if (
+      this.jobType === JobType.enhancedKyc &&
+      input.enhancedKYCParams === undefined
+    ) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason: "enhancedKYCParams is required for EnhancedKyc jobs",
+          suggestedFix:
+            "Set builder.enhancedKYCParams with the identity fields before building",
+        }),
+      );
+    }
+
+    if (
+      this.jobType === JobType.enhancedKyc &&
+      input.userDetails === undefined
+    ) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason: "userDetails is required for EnhancedKyc jobs",
+          suggestedFix:
+            "Set builder.userDetails with the end user PII before building",
+        }),
+      );
+    }
+  }
+}
+
+/**
+ * Generic structural validator used when no concrete `JobType` is
+ * resolved yet (e.g. a UI-only flow without a `network { }` block). It
+ * applies only the job-agnostic structural rules so partners still get
+ * screen-order / duplicate / preview feedback while prototyping. A
+ * single Preview following a Capture is permitted by default.
+ */
+export class DefaultStructuralValidator implements JobTypeValidator {
+  validate(input: JobTypeValidatorInput, issues: ValidationIssue[]): void {
+    appendDuplicateScreenRule(input.steps, issues);
+    appendScreenOrderRule(input.steps, issues);
+    appendPreviewRule(input.steps, 1, issues);
+  }
+}
+
+/**
+ * Registry mapping each `JobType` to its validator instance. Adding a new job
+ * type is a one-line registry change here; the validator runs the union of
+ * the per-type rules (consent + selfie / document / etc.) declared above.
+ */
+export const jobTypeValidators: ReadonlyMap<JobType, JobTypeValidator> =
+  new Map<JobType, JobTypeValidator>([
+    [JobType.biometricKyc, new SelfieJobTypeValidator(JobType.biometricKyc)],
+    [
+      JobType.smartSelfieAuthentication,
+      new SelfieJobTypeValidator(JobType.smartSelfieAuthentication),
+    ],
+    [
+      JobType.smartSelfieEnrollment,
+      new SelfieJobTypeValidator(JobType.smartSelfieEnrollment),
+    ],
+    [
+      JobType.documentVerification,
+      new DocumentJobTypeValidator(JobType.documentVerification),
+    ],
+    [
+      JobType.enhancedDocumentVerification,
+      new DocumentJobTypeValidator(JobType.enhancedDocumentVerification),
+    ],
+    [JobType.enhancedKyc, new NonCaptureJobTypeValidator(JobType.enhancedKyc)],
+    [JobType.bvn, new NonCaptureJobTypeValidator(JobType.bvn)],
+  ]);
+
+const defaultStructuralValidator = new DefaultStructuralValidator();
+
+/**
+ * Resolve the validator for the configured job type, falling back to the
+ * generic structural validator when the job type is unknown or
+ * unregistered. Always returns a validator so the generic structural
+ * rules run regardless of dispatch.
+ */
+export function resolveJobTypeValidator(
+  jobType: JobType | undefined,
+): JobTypeValidator {
+  if (jobType === undefined || jobType === JobType.unknown) {
+    return defaultStructuralValidator;
+  }
+  return jobTypeValidators.get(jobType) ?? defaultStructuralValidator;
+}
+
+/**
+ * Run the job-type-specific rules against the flow and append any issues
+ * found. Called by `FlowValidator` after its generic builder pass. The
+ * matching validator is resolved from the configured `jobType`, with the
+ * generic structural validator as the fallback for unknown job types.
+ */
+export function collectJobTypeIssues(
+  input: JobTypeValidatorInput,
+  issues: ValidationIssue[],
+): void {
+  const jobType = input.network?.config?.jobType;
+  resolveJobTypeValidator(jobType).validate(input, issues);
+}

package/src/presentation/flow/validation/validation_state.ts

@@ -0,0 +1,65 @@
+import { IssueSeverity } from "../../../core/exception/issue_severity";
+import type { UseSmileIDValidationException } from "../../../core/exception/use_smile_id_validation_exception";
+
+export { IssueSeverity };
+
+/**
+ * Validation state types.
+ *
+ * The shape is a discriminated union: narrow on `valid` to access
+ * `issues`. Compile-time exhaustiveness via `switch (state.valid)`.
+ */
+
+/**
+ * One validation finding. Each issue is a typed exception subclass —
+ * partners can `instanceof EmptyScreensBlockException` /
+ * `instanceof InvalidScreenOrderException` etc. to narrow on the
+ * specific rule, or pivot on `errorCode` for an exhaustive switch.
+ *
+ * Type alias rather than a separate plain-object record so the
+ * validator output and the thrown exception are the same value —
+ * partner tooling that forwards issues across platforms reads the
+ * same fields everywhere.
+ */
+export type ValidationIssue = UseSmileIDValidationException;
+
+/**
+ * Result of running the flow validator.
+ *
+ * - `valid: true` — every rule passed (no errors and no warnings).
+ * - `valid: false` — at least one error issue. `issues` is non-empty
+ *   and may contain a mix of `error` and `warning` entries.
+ */
+export type ValidationState = { readonly valid: true } | ValidationStateInvalid;
+
+/**
+ * The invalid branch of [ValidationState] — carries one or more typed
+ * validation issues. `FlowBuildResult.invalid` payloads,
+ * `BuilderValidationException.validationState`, and the `b.validate()`
+ * invalid result all use this exact shape.
+ */
+export type ValidationStateInvalid = {
+  readonly valid: false;
+  readonly issues: readonly ValidationIssue[];
+};
+
+const VALID_STATE: ValidationState = Object.freeze({ valid: true });
+
+/**
+ * Construct a `ValidationState`.
+ *
+ * `ValidationState.valid` returns the canonical "no issues" sentinel
+ * (frozen) — partners can compare via `state.valid === true` without
+ * worrying about reference identity.
+ *
+ * `ValidationState.invalid(issues)` returns a frozen invalid state.
+ * If `issues` is empty, returns the valid sentinel — `validate()`
+ * implementations don't need to special-case the empty path.
+ */
+export const ValidationState = {
+  valid: VALID_STATE,
+  invalid(issues: readonly ValidationIssue[]): ValidationState {
+    if (issues.length === 0) return VALID_STATE;
+    return Object.freeze({ valid: false, issues: Object.freeze([...issues]) });
+  },
+} as const;