repo-contract 0.2.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-contract",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Enforce your repository's own quality bar before CI even spins up. Configure arbitrary checks, capture what happened as evidence, and let repository-owned policies determine what passes. repo-contract provides the execution and evidence layer without becoming another CI system or imposing its own definition of code quality.",
   "keywords": [
     "contract",

package/schemas/evidence.schema.json

@@ -111,7 +111,7 @@
         },
         "output": {
           "$ref": "#/definitions/ParsedOutput%3Cunknown%3E",
-          "description": "The parsed interpretation of `stdout`, present only if this check's config requested a `format`."
+          "description": "The parsed interpretation of `stdout`, present only if this check's config requested a `format`. If that config also supplied `output.schema`, a successful parse is additionally validated (and possibly transformed) by that schema before landing here -- see this interface's own doc comment above and `CheckDefinitionConfig.output.schema`."
         }
       },
       "required": [
@@ -126,7 +126,7 @@
         "stderr",
         "status"
       ],
-      "description": "What actually happened when one configured check ran. `output` is present only if that check's config requested a format, and is otherwise `undefined` -- a policy narrows with `ctx.result.output?.success` (or an `if (ctx.result.output) { ... }` guard) before reading `.value`/`.error`.\n\n`output.value` is typed `unknown` for every format, including `\"text\"` (even though `parseText` always produces a `string` at runtime) -- neither repo-contract nor TypeScript's generic inference can reliably carry a specific check's own literal `output.format` through to that same check's `policy` parameter once several checks with heterogeneous formats live together in one `checks` record (a real TypeScript inference limitation hit and confirmed during implementation, not a hypothetical -- see specs/decisions/ for the isolated repro). A policy author narrows or casts `.value` themselves, exactly as they already must for `\"json\"`/`\"yaml\"` where no schema knowledge exists either way."
+      "description": "What actually happened when one configured check ran. `output` is present only if that check's config requested a format, and is otherwise `undefined` -- a policy narrows with `ctx.result.output?.success` (or an `if (ctx.result.output) { ... }` guard) before reading `.value`/`.error`.\n\n`output.value` is the value produced by the configured `format` parser, optionally validated and (if a schema transforms/coerces it) replaced by `output.schema` (see `CheckDefinitionConfig.output.schema`) -- so it is not necessarily the raw parser result once a check's config supplies a schema. It is typed `unknown` for every format regardless, including `\"text\"` (even though `parseText` always produces a `string` at runtime) and regardless of whether a schema was supplied -- neither repo-contract nor TypeScript's generic inference can reliably carry a specific check's own literal `output.format` (or a specific `schema`'s own inferred output type) through to that same check's `policy` parameter once several checks with heterogeneous formats live together in one `checks` record (a real TypeScript inference limitation hit and confirmed during implementation, not a hypothetical -- see specs/decisions/ for the isolated repro). This is a deliberate, acknowledged tradeoff, not a gap this package is attempting to close: a schema still gives its own author real compile-time input/output typing via `StandardSchemaV1<Input, Output>` for their own code, just not threaded through this shared `CheckEvidence` shape. A policy author narrows or casts `.value` themselves, exactly as they already must for `\"json\"`/`\"yaml\"` with no schema supplied."
     },
     "global.NodeJS.Signals": {
       "type": "string",

package/src/config/validate-config.ts

@@ -321,7 +321,7 @@ function validateOutput(checkId: string, output: unknown): void {
   if (output === null || typeof output !== "object") {
     throw new InvalidCheckConfigError(checkId, "output must be an object when provided.")
   }
-  const { format } = output as Record<string, unknown>
+  const { format, schema } = output as Record<string, unknown>
   // `typeof format !== "string"` is behaviorally redundant with the clause
   // after it: `Array#includes` uses strict equality, so a non-string
   // `format` can never match an entry of `OUTPUT_FORMATS` (all strings),
@@ -334,6 +334,60 @@ function validateOutput(checkId: string, output: unknown): void {
       `output.format must be one of ${OUTPUT_FORMATS.map((f) => `"${f}"`).join(", ")}.`,
     )
   }
+  validateOutputSchema(checkId, schema)
+}
+
+/**
+ * Validates that `schema`, when provided, is at least *plausibly* a `StandardSchemaV1`-compliant
+ * object (https://standardschema.dev) -- checks only the three fields every
+ * `StandardSchemaV1.Props` object must have (`version`, `vendor`, `validate`), since `schema` is
+ * an opaque, consumer-supplied object and anything else in its shape (e.g. the optional `types`
+ * field) is not part of the contract this function can or should enforce. Never calls `validate`
+ * itself -- that only happens once a check's stdout actually parses (see `parseOutput`); this
+ * function's whole job is structural, not behavioral.
+ *
+ * Accepts a callable `schema` (`typeof schema === "function"`), not just a plain object -- ArkType's
+ * `Type` values are themselves callable functions with `"~standard"` attached as a property, exactly
+ * as valid a Standard Schema-compliant value as a plain object one (e.g. Zod's), since `["~standard"]`
+ * property access works identically on either. Rejecting callable schemas outright would incorrectly
+ * reject a real, popular Standard Schema implementation.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param schema - the check's raw `output.schema` field to validate.
+ */
+function validateOutputSchema(checkId: string, schema: unknown): void {
+  if (schema === undefined) return
+  // eslint-disable-next-line secure-coding/no-improper-type-validation -- `null` is already excluded by the preceding `schema === null` short-circuit, and an array slipping past this check (typeof [] === "object") is still correctly rejected by the "~standard" property check just below, since no array has one -- the class of bug this rule guards against (silently treating null/an array as a valid object) can't actually happen here.
+  if (schema === null || (typeof schema !== "object" && typeof schema !== "function")) {
+    throw new InvalidCheckConfigError(
+      checkId,
+      "output.schema must be a Standard Schema-compliant object or function when provided (see https://standardschema.dev).",
+    )
+  }
+
+  const standard = (schema as Record<PropertyKey, unknown>)["~standard"]
+  if (standard === null || typeof standard !== "object") {
+    throw new InvalidCheckConfigError(
+      checkId,
+      'output.schema must have a "~standard" property (see https://standardschema.dev).',
+    )
+  }
+
+  const { version, vendor, validate } = standard as Record<string, unknown>
+  if (version !== 1) {
+    throw new InvalidCheckConfigError(checkId, 'output.schema["~standard"].version must be 1.')
+  }
+  if (typeof vendor !== "string") {
+    throw new InvalidCheckConfigError(
+      checkId,
+      'output.schema["~standard"].vendor must be a string.',
+    )
+  }
+  if (typeof validate !== "function") {
+    throw new InvalidCheckConfigError(
+      checkId,
+      'output.schema["~standard"].validate must be a function.',
+    )
+  }
 }
 
 /**

package/src/errors.ts

@@ -121,6 +121,32 @@ export class ParserDependencyMissingError extends RepoContractError {
 // case a future optional format needs the same treatment.
 type OutputFormatForError = "yaml"
 
+/**
+ * A check's `output.schema["~standard"].validate()` threw synchronously, or returned a `Promise`
+ * that rejected, instead of returning a `Result`. This is a bug in the consumer-supplied schema
+ * object, not malformed check output -- the same distinction `PolicyThrewError` below draws for a
+ * throwing policy: a schema *returning* failure `issues` becomes an ordinary
+ * `ParsedOutputFailure` (reported as data, exactly like a malformed-JSON/YAML parse failure), but
+ * a schema *throwing* means the validator itself is broken, so it propagates as a rejected
+ * `runRepoContract()` promise instead. The original thrown/rejected value is preserved verbatim
+ * via the native `Error` `cause` chain.
+ */
+export class StandardSchemaValidateThrewError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_STANDARD_SCHEMA_VALIDATE_THREW"`. */
+  readonly code = "REPO_CONTRACT_STANDARD_SCHEMA_VALIDATE_THREW"
+  /** The id of the check whose `output.schema` threw during validation. */
+  readonly checkId: string
+
+  constructor(checkId: string, cause: unknown) {
+    super(
+      `Check "${checkId}"'s output.schema["~standard"].validate() threw instead of returning a Result`,
+      { cause },
+    )
+    this.name = "StandardSchemaValidateThrewError"
+    this.checkId = checkId
+  }
+}
+
 /**
  * A check's `policy` function threw synchronously, or returned a `Promise`
  * that later rejected. Both failure modes are wrapped identically. The

package/src/evidence/build-evidence.ts

@@ -45,7 +45,12 @@ export async function buildEvidence(
     results.map(async ([checkId, check, raw]): Promise<ParsedCheckEntry> => {
       if (check.output === undefined) return [checkId, check, raw]
       try {
-        const output = await parseOutput(check.output.format, raw.stdout, checkId)
+        const output = await parseOutput(
+          check.output.format,
+          raw.stdout,
+          checkId,
+          check.output.schema,
+        )
         return [checkId, check, { ...raw, output }]
       } catch (error) {
         thrown.push(error)

package/src/index.ts

@@ -19,9 +19,12 @@ export {
   PolicyReadUnrequestedOutputError,
   PolicyThrewError,
   RepoContractError,
+  StandardSchemaValidateThrewError,
   UnknownCheckIdError,
 } from "./errors.js"
 
+export type { StandardSchemaV1 } from "./standard-schema/types.js"
+
 export type {
   CheckDefinition,
   CheckDefinitionConfig,

package/src/parsing/format-schema-issues.ts

@@ -0,0 +1,56 @@
+import type { StandardSchemaV1 } from "../standard-schema/types.js"
+
+/**
+ * Renders a failed `output.schema` validation's issues as a single, human-readable string for
+ * `ParsedOutputFailure.error` -- e.g. `Schema validation failed: foo.bar: Expected string;
+ * items[2].name: Required`. Kept as its own small module, independent of `parseOutput`, so its
+ * path-rendering logic (the only non-trivial part) can be unit-tested directly.
+ * @param issues - the failed `StandardSchemaV1.Result`'s `issues`.
+ * @returns the formatted error string.
+ */
+export function formatSchemaIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  return `Schema validation failed: ${issues.map(formatIssue).join("; ")}`
+}
+
+/**
+ * Renders one issue as `path: message`, or just `message` when it has no path.
+ * @param issue - the issue to render.
+ * @returns the rendered issue.
+ */
+function formatIssue(issue: StandardSchemaV1.Issue): string {
+  const path = formatPath(issue.path)
+  return path === "" ? issue.message : `${path}: ${issue.message}`
+}
+
+/**
+ * Renders an issue's `path` as a dotted/bracketed accessor string, e.g. `foo.bar` or
+ * `items[2].name`. Each segment is either a bare `PropertyKey` (`string | number | symbol` -- a
+ * `symbol` must never be interpolated directly into a template literal, which throws `TypeError:
+ * Cannot convert a Symbol value to a string`; always going through `String(key)` avoids that for
+ * every segment type uniformly) or a `{ key: PropertyKey }` object per the spec.
+ * @param path - the issue's raw `path`, if any.
+ * @returns the rendered path, or `""` for a pathless issue.
+ */
+function formatPath(
+  path: readonly (PropertyKey | StandardSchemaV1.PathSegment)[] | undefined,
+): string {
+  // Equivalent mutant: mutating `path.length === 0` to `false` makes an empty (but defined) `path`
+  // fall through to `path.map(...).join("")` below instead of returning `""` here directly -- but
+  // mapping and joining an empty array always produces `""` regardless of the mapping function, so
+  // both branches are observably identical for every possible input; no test could ever distinguish
+  // them by `formatPath`'s return value.
+  // Stryker disable next-line ConditionalExpression -- equivalent mutant: `path.length === 0` falling through to `path.map(...).join("")` on an empty array also produces `""`, identical to this early return, for every possible input -- no test could ever distinguish them.
+  if (path === undefined || path.length === 0) return ""
+
+  return path
+    .map((segment) =>
+      // eslint-disable-next-line secure-coding/no-improper-type-validation -- `segment` is declared `PropertyKey | StandardSchemaV1.PathSegment` (never `null` or an array), so `typeof segment === "object"` can only match the `PathSegment` object form here; the null/array-safe rewrite this rule suggests is flagged as an unreachable condition by @typescript-eslint/no-unnecessary-condition given that exact type, so satisfying both rules at once is impossible -- the type itself is the guarantee this check would otherwise add at runtime.
+      typeof segment === "object" ? segment.key : segment,
+    )
+    .map((key, index) => {
+      if (typeof key === "number") return `[${String(key)}]`
+      const rendered = String(key)
+      return index === 0 ? rendered : `.${rendered}`
+    })
+    .join("")
+}

package/src/parsing/parse-output.ts

@@ -1,19 +1,66 @@
+import { StandardSchemaValidateThrewError } from "../errors.js"
+import type { StandardSchemaV1 } from "../standard-schema/types.js"
 import type { OutputFormat, ParsedOutput } from "../types.js"
+import { formatSchemaIssues } from "./format-schema-issues.js"
 import { parseJson } from "./parse-json.js"
 import { parseText } from "./parse-text.js"
 import { parseYaml } from "./parse-yaml.js"
 
 /**
- * Dispatches to the parser for `format`. Never throws for a malformed-output parse failure -- see each parser's own documentation. May throw `ParserDependencyMissingError` for `format: "yaml"` if the optional `yaml` peer dependency is unavailable.
+ * Dispatches to the parser for `format`, then -- only on a successful parse, and only if `schema`
+ * is supplied -- runs `schema["~standard"].validate()` against the parsed value
+ * (https://standardschema.dev). `parse-json.ts`/`parse-yaml.ts`/`parse-text.ts` stay entirely
+ * unaware of `schema`; this is the sole orchestration point. `validate()` may return its `Result`
+ * synchronously or as a `Promise` -- `await`ing either uniformly is a no-op for the synchronous
+ * case, so this doesn't need its own reason to be async on top of the one this function already
+ * has (the dynamic `import("yaml")` for `format: "yaml"`). A successful `Result` (`issues ===
+ * undefined`) *replaces* `value` with the schema's own (possibly transformed) output; a failing
+ * `Result` becomes a `ParsedOutputFailure` whose `error` is built by `formatSchemaIssues`.
+ * `schema.validate()` itself throwing or rejecting is a bug in the consumer-supplied schema, not
+ * malformed output -- it throws `StandardSchemaValidateThrewError` rather than becoming a
+ * `ParsedOutputFailure`. Never throws for a malformed-output parse failure -- see each parser's
+ * own documentation. May throw `ParserDependencyMissingError` for `format: "yaml"` if the
+ * optional `yaml` peer dependency is unavailable.
  * @param format - which parser to dispatch to.
  * @param stdout - the check's raw stdout to parse.
- * @param checkId - identifies which check's output is being parsed, used in the `ParserDependencyMissingError` thrown for a missing `yaml` dependency.
- * @returns the parsed output produced by the selected parser.
+ * @param checkId - identifies which check's output is being parsed, used in a thrown `ParserDependencyMissingError`/`StandardSchemaValidateThrewError`.
+ * @param schema - an optional Standard Schema-compliant validator to run against a successful parse's value.
+ * @returns the parsed (and, if `schema` was supplied and validation succeeded, schema-transformed) output.
  */
 export async function parseOutput(
   format: OutputFormat,
   stdout: string,
   checkId: string,
+  schema?: StandardSchemaV1,
+): Promise<ParsedOutput<unknown>> {
+  const parsed = await dispatch(format, stdout, checkId)
+  if (!parsed.success || schema === undefined) return parsed
+
+  let result: StandardSchemaV1.Result<unknown>
+  try {
+    result = await schema["~standard"].validate(parsed.value)
+  } catch (error) {
+    throw new StandardSchemaValidateThrewError(checkId, error)
+  }
+
+  if (result.issues === undefined) {
+    return { format, success: true, value: result.value }
+  }
+  return { format, success: false, error: formatSchemaIssues(result.issues) }
+}
+
+/**
+ * Dispatches to the parser for `format` -- the pre-existing behavior of `parseOutput`, extracted
+ * so `parseOutput` itself reads as: parse, then optionally validate.
+ * @param format - which parser to dispatch to.
+ * @param stdout - the check's raw stdout to parse.
+ * @param checkId - identifies which check's output is being parsed, used in a thrown `ParserDependencyMissingError`.
+ * @returns the parsed output produced by the selected parser.
+ */
+async function dispatch(
+  format: OutputFormat,
+  stdout: string,
+  checkId: string,
 ): Promise<ParsedOutput<unknown>> {
   switch (format) {
     case "json":

package/src/standard-schema/types.ts

@@ -0,0 +1,93 @@
+/**
+ * Hand-vendored from `@standard-schema/spec@1.1.0` (https://standardschema.dev), pinned
+ * 2026-09-04 -- see specs/decisions/0012-hand-vendored-standard-schema-support-for-optional-output-validation.md for why this is
+ * vendored rather than an installed dependency, and for the version-pin/re-diff process. Pure type
+ * declarations, zero runtime code -- assigning any real Zod/Valibot/ArkType (etc.) schema to this
+ * type costs nothing at runtime. Only `StandardSchemaV1` (validation) is vendored here -- the
+ * separate, optional `StandardJSONSchemaV1` (JSON Schema conversion) extension
+ * (https://standardschema.dev/json-schema) is out of scope; see the ADR.
+ *
+ * Upstream's `StandardSchemaV1.Props` actually extends a shared `StandardTypedV1.Props` base
+ * (`version`/`vendor`/`types`); this vendored copy inlines those fields directly into one flat
+ * interface, since repo-contract has no use for the shared base on its own -- structurally
+ * identical for any real schema object assigned to it. Re-diff against
+ * `@standard-schema/spec`'s published `dist/index.d.ts` if this file is ever touched.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>
+}
+
+/** Namespaced members of {@link StandardSchemaV1}: `Props`, `Result`, `SuccessResult`, `FailureResult`, `Issue`, `PathSegment`, `Types`, `InferInput`, `InferOutput`. */
+// eslint-disable-next-line @typescript-eslint/no-namespace -- the interface+namespace declaration-merging pattern is required here to mirror @standard-schema/spec's own published shape (StandardSchemaV1.Props/.Result/.Issue/... nested under the interface's own name) -- an ES2015 module can't merge with an interface of the same name the way a namespace does, and diverging from upstream's exact shape would defeat this file's whole purpose of being a faithful, re-diffable vendor copy (see this file's own top comment).
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1
+    /** The vendor name of the schema library. */
+    readonly vendor: string
+    /** Validates unknown input values. */
+    readonly validate: (
+      value: unknown,
+      options?: Options,
+    ) => Result<Output> | Promise<Result<Output>>
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined
+  }
+
+  /** Options passable to `validate`. */
+  export interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: readonly Issue[]
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string
+    /** The path of the issue, if any. */
+    readonly path?: readonly (PropertyKey | PathSegment)[] | undefined
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input
+    /** The output type of the schema. */
+    readonly output: Output
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["input"]
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["output"]
+}

package/src/types.ts

@@ -12,6 +12,8 @@ import type {
   SpawnSyncReturns,
 } from "node:child_process"
 
+import type { StandardSchemaV1 } from "./standard-schema/types.js"
+
 /** Output interpretation a check can explicitly request. No format requested means no parsing -- the consumer gets raw stdout/stderr only. */
 export type OutputFormat = "json" | "yaml" | "text"
 
@@ -66,16 +68,21 @@ export type ParsedOutput<T> = ParsedOutputSuccess<T> | ParsedOutputFailure
  * `undefined` -- a policy narrows with `ctx.result.output?.success` (or an
  * `if (ctx.result.output) { ... }` guard) before reading `.value`/`.error`.
  *
- * `output.value` is typed `unknown` for every format, including `"text"`
- * (even though `parseText` always produces a `string` at runtime) --
- * neither repo-contract nor TypeScript's generic inference can reliably
- * carry a specific check's own literal `output.format` through to that
- * same check's `policy` parameter once several checks with heterogeneous
- * formats live together in one `checks` record (a real TypeScript
- * inference limitation hit and confirmed during implementation, not a
- * hypothetical -- see specs/decisions/ for the isolated repro). A policy
- * author narrows or casts `.value` themselves, exactly as they already must
- * for `"json"`/`"yaml"` where no schema knowledge exists either way.
+ * `output.value` is the value produced by the configured `format` parser, optionally validated
+ * and (if a schema transforms/coerces it) replaced by `output.schema` (see
+ * `CheckDefinitionConfig.output.schema`) -- so it is not necessarily the raw parser result once a
+ * check's config supplies a schema. It is typed `unknown` for every format regardless, including
+ * `"text"` (even though `parseText` always produces a `string` at runtime) and regardless of
+ * whether a schema was supplied -- neither repo-contract nor TypeScript's generic inference can
+ * reliably carry a specific check's own literal `output.format` (or a specific `schema`'s own
+ * inferred output type) through to that same check's `policy` parameter once several checks with
+ * heterogeneous formats live together in one `checks` record (a real TypeScript inference
+ * limitation hit and confirmed during implementation, not a hypothetical -- see specs/decisions/
+ * for the isolated repro). This is a deliberate, acknowledged tradeoff, not a gap this package
+ * is attempting to close: a schema still gives its own author real compile-time input/output
+ * typing via `StandardSchemaV1<Input, Output>` for their own code, just not threaded through this
+ * shared `CheckEvidence` shape. A policy author narrows or casts `.value` themselves, exactly as
+ * they already must for `"json"`/`"yaml"` with no schema supplied.
  */
 export interface CheckEvidence {
   /** The executable that was actually spawned (after tokenization, if `run` was a string). */
@@ -102,7 +109,12 @@ export interface CheckEvidence {
   readonly spawnError?: string
   /** Populated only for `status === "spawn_error"` -- the underlying Node `ErrnoException`'s structured `.code` (e.g. `"ENOENT"`, `"EACCES"`), when Node provides one. Never populated for any other status. Distinguishes "the executable does not exist" from other spawn failures (permission denied, invalid executable format, etc.) without parsing `spawnError`'s free-text message. */
   readonly spawnErrorCode?: string
-  /** The parsed interpretation of `stdout`, present only if this check's config requested a `format`. */
+  /**
+   * The parsed interpretation of `stdout`, present only if this check's config requested a
+   * `format`. If that config also supplied `output.schema`, a successful parse is additionally
+   * validated (and possibly transformed) by that schema before landing here -- see this
+   * interface's own doc comment above and `CheckDefinitionConfig.output.schema`.
+   */
   readonly output?: ParsedOutput<unknown>
 }
 
@@ -238,7 +250,31 @@ export interface CheckDefinitionConfig {
   /** Maximum time to let this check's process run before it is terminated and recorded with `status: "timed_out"`. No timeout by default. */
   readonly timeoutMs?: number
   /** Request that stdout be parsed as this format. Omit for no parsing -- the consumer gets raw stdout/stderr only. */
-  readonly output?: { readonly format: OutputFormat }
+  readonly output?: {
+    readonly format: OutputFormat
+    /**
+     * An optional Standard Schema-compliant validator (Zod, Valibot, ArkType, or any other
+     * implementation of https://standardschema.dev), run once the requested `format` parse
+     * itself succeeds. repo-contract never imports a schema library itself --
+     * `StandardSchemaV1` is hand-vendored (see `src/standard-schema/types.ts`) purely as a
+     * type-level contract, so accepting any consumer's own schema object costs zero new
+     * runtime or dev dependencies (see
+     * specs/decisions/0012-hand-vendored-standard-schema-support-for-optional-output-validation.md). A successful
+     * `~standard.validate()` result *replaces* the parsed value on `CheckEvidence.output.value`
+     * (letting a schema transform, not just check, its input); a failing result becomes an
+     * ordinary `ParsedOutputFailure`, indistinguishable in shape from a malformed-JSON/YAML
+     * parse failure -- both are "this check's output isn't what was expected," reported as
+     * data, never a throw (see `parseOutput`). `validate()` itself throwing or rejecting is a
+     * different case -- a bug in the supplied schema, not malformed output -- and surfaces as
+     * `StandardSchemaValidateThrewError` instead (see that error's own doc comment). Like every
+     * other format's `value`, `schema`'s inferred output type is *not* threaded to
+     * `CheckEvidence.output.value`'s declared type -- it stays `unknown`, for the same
+     * heterogeneous-checks-in-one-record TypeScript inference limitation already documented on
+     * `CheckEvidence` above; a policy still narrows or casts `.value` itself, now
+     * shaped/transformed by `schema` at runtime even though the type alone doesn't say so.
+     */
+    readonly schema?: StandardSchemaV1
+  }
   /**
    * A full scheduling barrier at this check's own position in the `checks` object: it does not
    * spawn until every check declared *earlier* has reached a terminal status (nothing "currently in