@kirrosh/zond 0.22.0 → 0.23.0

package/src/core/lint/walker.ts

@@ -0,0 +1,248 @@
+import type { OpenAPIV3 } from "openapi-types";
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"] as const;
+
+export type SchemaContextKind =
+  | "param-schema"
+  | "request-body"
+  | "response-body"
+  | "property";
+
+export interface ParamContext {
+  kind: "parameter";
+  jsonpointer: string;
+  path: string;
+  method: string;
+  param: OpenAPIV3.ParameterObject;
+}
+
+export interface ResponseContext {
+  kind: "response";
+  jsonpointer: string;
+  path: string;
+  method: string;
+  status: string;
+  response: OpenAPIV3.ResponseObject;
+}
+
+export interface RequestBodyContext {
+  kind: "requestBody";
+  jsonpointer: string;
+  path: string;
+  method: string;
+  requestBody: OpenAPIV3.RequestBodyObject;
+}
+
+export interface SchemaContext {
+  kind: "schema";
+  jsonpointer: string;
+  path?: string;
+  method?: string;
+  origin: SchemaContextKind;
+  /** Property name if this schema is a value of `properties.<name>`. */
+  propertyName?: string;
+  schema: OpenAPIV3.SchemaObject;
+}
+
+export type WalkContext = ParamContext | ResponseContext | RequestBodyContext | SchemaContext;
+
+export type Visitor = (ctx: WalkContext) => void;
+
+/**
+ * RFC6901 segment encoder: `~` → `~0`, `/` → `~1`.
+ */
+function escapePointerSegment(s: string | number): string {
+  return String(s).replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+/**
+ * Walk an OpenAPI 3.x document, invoking `visit` for parameters, request bodies,
+ * responses, and every nested schema (recursively through properties / items /
+ * combinators). Each call carries a stable RFC6901 jsonpointer so issues can
+ * point precisely to the source.
+ *
+ * Cycles (already-visited schema objects by reference) are short-circuited so
+ * `@readme/openapi-parser`-resolved $ref-cycles don't loop.
+ */
+export function walk(doc: OpenAPIV3.Document, visit: Visitor): void {
+  if (!doc.paths) return;
+  for (const [path, pathItem] of Object.entries(doc.paths)) {
+    if (!pathItem) continue;
+    const pathPtr = `/paths/${escapePointerSegment(path)}`;
+
+    // Path-level parameters
+    if (pathItem.parameters) {
+      pathItem.parameters.forEach((p, idx) => {
+        const param = p as OpenAPIV3.ParameterObject;
+        const ptr = `${pathPtr}/parameters/${idx}`;
+        visit({ kind: "parameter", jsonpointer: ptr, path, method: "*", param });
+        if (param.schema) {
+          walkSchema(
+            param.schema as OpenAPIV3.SchemaObject,
+            `${ptr}/schema`,
+            { origin: "param-schema", path, method: "*" },
+            visit,
+            new Set(),
+          );
+        }
+      });
+    }
+
+    for (const m of HTTP_METHODS) {
+      const op = (pathItem as Record<string, unknown>)[m] as OpenAPIV3.OperationObject | undefined;
+      if (!op) continue;
+      const opPtr = `${pathPtr}/${m}`;
+      const method = m.toUpperCase();
+
+      // Operation-level parameters
+      if (op.parameters) {
+        op.parameters.forEach((p, idx) => {
+          const param = p as OpenAPIV3.ParameterObject;
+          const ptr = `${opPtr}/parameters/${idx}`;
+          visit({ kind: "parameter", jsonpointer: ptr, path, method, param });
+          if (param.schema) {
+            walkSchema(
+              param.schema as OpenAPIV3.SchemaObject,
+              `${ptr}/schema`,
+              { origin: "param-schema", path, method },
+              visit,
+              new Set(),
+            );
+          }
+        });
+      }
+
+      // Request body
+      if (op.requestBody) {
+        const rb = op.requestBody as OpenAPIV3.RequestBodyObject;
+        const rbPtr = `${opPtr}/requestBody`;
+        visit({ kind: "requestBody", jsonpointer: rbPtr, path, method, requestBody: rb });
+        if (rb.content) {
+          for (const [ct, mt] of Object.entries(rb.content)) {
+            if (mt.schema) {
+              walkSchema(
+                mt.schema as OpenAPIV3.SchemaObject,
+                `${rbPtr}/content/${escapePointerSegment(ct)}/schema`,
+                { origin: "request-body", path, method },
+                visit,
+                new Set(),
+              );
+            }
+          }
+        }
+      }
+
+      // Responses
+      if (op.responses) {
+        for (const [status, respObj] of Object.entries(op.responses)) {
+          const resp = respObj as OpenAPIV3.ResponseObject;
+          const respPtr = `${opPtr}/responses/${escapePointerSegment(status)}`;
+          visit({ kind: "response", jsonpointer: respPtr, path, method, status, response: resp });
+          if (resp.content) {
+            for (const [ct, mt] of Object.entries(resp.content)) {
+              if (mt.schema) {
+                walkSchema(
+                  mt.schema as OpenAPIV3.SchemaObject,
+                  `${respPtr}/content/${escapePointerSegment(ct)}/schema`,
+                  { origin: "response-body", path, method },
+                  visit,
+                  new Set(),
+                );
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+interface WalkSchemaCtx {
+  origin: SchemaContextKind;
+  path?: string;
+  method?: string;
+  propertyName?: string;
+}
+
+function walkSchema(
+  schema: OpenAPIV3.SchemaObject,
+  pointer: string,
+  ctx: WalkSchemaCtx,
+  visit: Visitor,
+  visited: Set<unknown>,
+): void {
+  if (!schema || typeof schema !== "object") return;
+  if (visited.has(schema)) return;
+  visited.add(schema);
+
+  visit({
+    kind: "schema",
+    jsonpointer: pointer,
+    path: ctx.path,
+    method: ctx.method,
+    origin: ctx.origin,
+    propertyName: ctx.propertyName,
+    schema,
+  });
+
+  if (schema.properties) {
+    for (const [name, sub] of Object.entries(schema.properties)) {
+      walkSchema(
+        sub as OpenAPIV3.SchemaObject,
+        `${pointer}/properties/${escapePointerSegment(name)}`,
+        { origin: "property", path: ctx.path, method: ctx.method, propertyName: name },
+        visit,
+        visited,
+      );
+    }
+  }
+
+  const arraySchema = schema as OpenAPIV3.ArraySchemaObject;
+  if (arraySchema.items) {
+    walkSchema(
+      arraySchema.items as OpenAPIV3.SchemaObject,
+      `${pointer}/items`,
+      { ...ctx, propertyName: undefined },
+      visit,
+      visited,
+    );
+  }
+
+  for (const combinator of ["allOf", "anyOf", "oneOf"] as const) {
+    const arr = (schema as Record<string, unknown>)[combinator] as OpenAPIV3.SchemaObject[] | undefined;
+    if (Array.isArray(arr)) {
+      arr.forEach((sub, idx) => {
+        walkSchema(
+          sub,
+          `${pointer}/${combinator}/${idx}`,
+          { ...ctx, propertyName: undefined },
+          visit,
+          visited,
+        );
+      });
+    }
+  }
+
+  if (typeof schema.additionalProperties === "object" && schema.additionalProperties !== null) {
+    walkSchema(
+      schema.additionalProperties as OpenAPIV3.SchemaObject,
+      `${pointer}/additionalProperties`,
+      { ...ctx, propertyName: undefined },
+      visit,
+      visited,
+    );
+  }
+}
+
+/**
+ * Normalise OpenAPI 3.0 `nullable: true` so callers can reason about a single
+ * type list. Returns the (possibly array) type without mutating the schema.
+ */
+export function normalisedTypes(schema: OpenAPIV3.SchemaObject): string[] {
+  const t = (schema as { type?: string | string[] }).type;
+  const list: string[] = Array.isArray(t) ? [...t] : t ? [t] : [];
+  if ((schema as { nullable?: boolean }).nullable === true && !list.includes("null")) {
+    list.push("null");
+  }
+  return list;
+}

package/src/core/meta/meta-store.ts

@@ -1,78 +1,11 @@
-import { join } from "path";
 import { createHash } from "crypto";
-import type { ZondMeta, FileMeta } from "./types.ts";
-import type { RawSuite } from "../generator/serializer.ts";
-import { normalizePath } from "../generator/coverage-scanner.ts";
-
-const META_FILENAME = ".zond-meta.json";
-
-export async function readMeta(testsDir: string): Promise<ZondMeta | null> {
-  const metaPath = join(testsDir, META_FILENAME);
-  const file = Bun.file(metaPath);
-  if (!(await file.exists())) return null;
-  try {
-    return JSON.parse(await file.text()) as ZondMeta;
-  } catch {
-    return null;
-  }
-}
-
-export async function writeMeta(testsDir: string, meta: ZondMeta): Promise<void> {
-  const metaPath = join(testsDir, META_FILENAME);
-  await Bun.write(metaPath, JSON.stringify(meta, null, 2) + "\n");
-}
-
-export function hashSpec(specContent: string): string {
-  return createHash("sha256").update(specContent).digest("hex");
-}
 
 /**
- * Derive suite type from tags array or filename.
+ * SHA-256 of the canonical (decycled) JSON form of an OpenAPI document.
+ * Used as the freshness hash recorded in `.api-catalog.yaml`,
+ * `.api-resources.yaml`, and `.api-fixtures.yaml` so `zond doctor` can
+ * detect drift between the local snapshot and its derived artifacts.
  */
-function detectSuiteType(suite: RawSuite): FileMeta["suiteType"] {
-  const tags = suite.tags ?? [];
-  if (tags.includes("auth")) return "auth";
-  if (tags.includes("sanity")) return "sanity";
-  if (tags.includes("crud")) return "crud";
-  if (tags.includes("unsafe")) return "unsafe";
-  return "smoke";
-}
-
-/**
- * Extract first tag from fileStem or suite folder for grouping.
- * e.g. fileStem "smoke-users" → tag "users"
- */
-function detectTag(suite: RawSuite): string | undefined {
-  const stem = suite.fileStem ?? suite.name;
-  const match = stem.match(/^(?:smoke|crud|auth|sanity|unsafe)-(.+?)(?:-unsafe)?$/);
-  return match?.[1];
-}
-
-/**
- * Build normalized endpoint keys from a raw suite's test steps.
- * e.g. "GET /users/{*}", "POST /users"
- */
-function extractEndpointKeys(suite: RawSuite): string[] {
-  const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
-  const keys: string[] = [];
-  for (const step of suite.tests) {
-    for (const method of HTTP_METHODS) {
-      const path = step[method] as string | undefined;
-      if (path) {
-        keys.push(`${method} ${normalizePath(path)}`);
-        break;
-      }
-    }
-  }
-  return [...new Set(keys)];
-}
-
-export function buildFileMeta(suite: RawSuite, zondVersion: string): FileMeta {
-  return {
-    generatedAt: new Date().toISOString(),
-    zondVersion,
-    suiteType: detectSuiteType(suite),
-    tag: detectTag(suite),
-    endpoints: extractEndpointKeys(suite),
-  };
+export function hashSpec(specContent: string): string {
+  return createHash("sha256").update(specContent).digest("hex");
 }

package/src/core/output/README.md

@@ -0,0 +1,91 @@
+# core/output — typed `--report` / `--output` / `--json` policy
+
+`OutputSpec<Payload>` is the single source-of-truth for how a command
+produces output. Per-command parsers (`checks run`, `probe security`,
+`run`, …) are migrated in ARV-117/118/119 — this directory only ships
+the infrastructure.
+
+Closes the seven divergent-output bugs collected in
+`strategy/lessons.md` §E (ARV-50, ARV-82, ARV-97, …) by replacing N
+ad-hoc parsers with one resolver.
+
+## Policy matrix
+
+The runner (`runCommandWithOutput`) reads `--report`, `--output`, and
+`--json` from the CLI layer and resolves them to a `ResolvedOutput`
+decision according to this matrix:
+
+| Input                                | Format         | Channel             | Notes |
+| ------------------------------------ | -------------- | ------------------- | ----- |
+| _(nothing)_                          | `defaultFormat`| from format policy  | bare invocation |
+| `--report <fmt>`                     | `<fmt>` (or alias) | from format policy | unknown → error |
+| `--json`                             | first format with `envelopeWrap: true` | from format policy | falls back to `defaultFormat` when no envelope-wrap format exists |
+| `--output <path>`                    | unchanged      | `file` (path = resolved absolute) | `--output` always wins over `defaultChannel` |
+| `--report sarif` (defaults to file)  | `sarif`        | `file` (`defaultFilename` if no `--output`) | ARV-5 default `zond-checks.sarif` |
+| `--report ndjson` (defaults to stdout) | `ndjson`     | `stdout` | event stream — see ARV-10 |
+| `--report ndjson --output <path>`    | `ndjson`       | `file`     | ARV-97 — explicit `--output` redirects the stream |
+| `--json` + `--report <fmt>`          | —              | —          | mutually exclusive (throws `OutputSpecError`) |
+
+Aliases (`spec.aliases`) let a single CLI flag value resolve to
+another format — used by `checks run` so `--report ndjson` continues to
+mean "the `--ndjson` streaming flag", matching skill-prompt
+expectations (ARV-63).
+
+## Building a spec
+
+```ts
+import type { OutputSpec } from "@/core/output";
+
+interface ChecksPayload { findings: Finding[]; summary: Summary }
+
+export const CHECKS_RUN_OUTPUT: OutputSpec<ChecksPayload> = {
+  command: "checks run",
+  defaultFormat: "json",
+  formats: {
+    json:   { defaultChannel: "stdout", envelopeWrap: true,  description: "JSON envelope" },
+    sarif:  { defaultChannel: "file",   defaultFilename: "zond-checks.sarif" },
+    ndjson: { defaultChannel: "stdout", description: "event stream — one JSON per line" },
+  },
+  aliases: {
+    // `--report ndjson` is a friendly alias retained from skill prompts.
+    ndjson: "ndjson",
+  },
+  render: (format, payload) => {
+    if (format === "sarif")  return generateSarifReport(payload);
+    if (format === "ndjson") return payload.findings.map(f => JSON.stringify(f)).join("\n");
+    return JSON.stringify(payload, null, 2);
+  },
+};
+```
+
+The CLI handler then does:
+
+```ts
+const { resolved, exitCode } = await runCommandWithOutput(
+  CHECKS_RUN_OUTPUT,
+  cmd.opts<OutputOptions>(),
+  async () => runChecks({ /* ... */ }),
+);
+process.exit(exitCode);
+```
+
+`resolveOutput()` can be called standalone (without rendering) when a
+command wants to plug the resolution into its own streaming pipeline —
+e.g. `checks run` opens an fd ahead of time and feeds events into it
+incrementally; in that case the command consumes `resolved.path` and
+`resolved.channel` and handles I/O itself.
+
+## Why the format set is open
+
+Each command owns its own format vocabulary. `run` ships
+`json`/`junit`; `checks run` ships `json`/`sarif`/`ndjson`; `probe *`
+ships `json` only. Declaring formats per-spec instead of in a global
+union avoids a leaky enum and keeps `--help` accurate per command.
+
+## Errors
+
+`resolveOutput` throws `OutputSpecError` for policy violations
+(`--json + --report`, unknown format, file-default without filename).
+The CLI handler catches it and produces either `jsonError` or a human
+`printError`, matching the rest of the codebase's input-error
+behaviour (exit code 2).

package/src/core/output/index.ts

@@ -0,0 +1,13 @@
+/**
+ * ARV-116 (m-19): public surface of the output-spec module.
+ */
+export type {
+  OutputChannel,
+  OutputFormat,
+  OutputOptions,
+  OutputSpec,
+  FormatPolicy,
+  ResolvedOutput,
+} from "./types.ts";
+export { OutputSpecError } from "./types.ts";
+export { resolveOutput, runCommandWithOutput, type RunOutputResult } from "./run.ts";

package/src/core/output/run.ts

@@ -0,0 +1,126 @@
+/**
+ * ARV-116 (m-19): runner that turns an `OutputSpec` + CLI flags into
+ * a `ResolvedOutput`, then renders and writes the payload.
+ *
+ * Resolution order:
+ *   1. `--json` and `--report` are mutually exclusive — error.
+ *   2. If `--report` is set, look it up in `aliases` first, then in
+ *      `formats`. Unknown → error (consistent with ARV-97; never
+ *      silently swallow a typo).
+ *   3. If `--json` is set, pick the first envelope-wrapping format
+ *      from the spec. Specs without one fall back to the
+ *      `defaultFormat` (acceptable for commands like `run` whose
+ *      `--json` is special-cased — see ARV-117).
+ *   4. Otherwise use `defaultFormat`.
+ *   5. Channel: `--output` forces file. Without it, take the format's
+ *      `defaultChannel`. File channel without an explicit `--output`
+ *      uses `defaultFilename` (relative paths resolved against cwd).
+ */
+import { resolve as resolvePath } from "path";
+import {
+  OutputSpecError,
+  type OutputOptions,
+  type OutputSpec,
+  type ResolvedOutput,
+} from "./types.ts";
+
+export function resolveOutput<P>(
+  spec: OutputSpec<P>,
+  opts: OutputOptions,
+): ResolvedOutput {
+  if (opts.json && typeof opts.report === "string" && opts.report.length > 0) {
+    throw new OutputSpecError(
+      "--json and --report are mutually exclusive — pick one output channel",
+    );
+  }
+
+  // Step 1: resolve the format.
+  let format: string;
+  if (typeof opts.report === "string" && opts.report.length > 0) {
+    const alias = spec.aliases?.[opts.report];
+    format = alias ?? opts.report;
+  } else if (opts.json) {
+    format = pickEnvelopeFormat(spec) ?? spec.defaultFormat;
+  } else {
+    format = spec.defaultFormat;
+  }
+
+  const policy = spec.formats[format];
+  if (!policy) {
+    const known = Object.keys(spec.formats).sort().join(", ");
+    throw new OutputSpecError(
+      `Unknown --report format: "${format}". Available for ${spec.command}: ${known}`,
+    );
+  }
+
+  // Step 2: resolve channel + path.
+  const explicitOutput = typeof opts.output === "string" && opts.output.length > 0
+    ? opts.output
+    : undefined;
+  let channel: "stdout" | "file";
+  let path: string | undefined;
+  if (explicitOutput) {
+    channel = "file";
+    path = resolvePath(explicitOutput);
+  } else if (policy.defaultChannel === "file") {
+    channel = "file";
+    path = policy.defaultFilename ? resolvePath(policy.defaultFilename) : undefined;
+    if (!path) {
+      throw new OutputSpecError(
+        `Format "${format}" defaults to file but has no defaultFilename and --output was not set`,
+      );
+    }
+  } else {
+    channel = "stdout";
+  }
+
+  return {
+    format,
+    channel,
+    path,
+    envelopeWrap: policy.envelopeWrap === true,
+  };
+}
+
+function pickEnvelopeFormat<P>(spec: OutputSpec<P>): string | undefined {
+  for (const [name, policy] of Object.entries(spec.formats)) {
+    if (policy.envelopeWrap) return name;
+  }
+  return undefined;
+}
+
+export interface RunOutputResult<P> {
+  resolved: ResolvedOutput;
+  payload: P;
+  exitCode: number;
+}
+
+/** Render and write the payload according to the resolved decision.
+ *  Returns the resolved decision plus the exit code from the spec's
+ *  `exitCodePolicy` (0 by default). The CLI handler typically passes
+ *  the exit code straight to `process.exit`. */
+export async function runCommandWithOutput<P>(
+  spec: OutputSpec<P>,
+  opts: OutputOptions,
+  produce: () => Promise<P>,
+): Promise<RunOutputResult<P>> {
+  const resolved = resolveOutput(spec, opts);
+  const payload = await produce();
+
+  if (!spec.render) {
+    throw new OutputSpecError(
+      `OutputSpec for "${spec.command}" has no render() hook — cannot serialise payload`,
+    );
+  }
+  const body = spec.render(resolved.format, payload);
+
+  if (resolved.channel === "file") {
+    await Bun.write(resolved.path!, body);
+  } else {
+    process.stdout.write(body);
+    if (!body.endsWith("\n")) process.stdout.write("\n");
+  }
+
+  const exitCode = spec.exitCodePolicy ? spec.exitCodePolicy(payload) : 0;
+  return { resolved, payload, exitCode };
+}

package/src/core/output/types.ts

@@ -0,0 +1,129 @@
+/**
+ * ARV-116 (m-19): typed declaration of every `--report` / `--output` /
+ * `--json` combination a command supports.
+ *
+ * Background. Lesson §E of strategy/lessons.md collects seven separate
+ * bug reports about output-flag plumbing:
+ *   - ARV-97 — `--report ndjson --output <path>` silently dropped events;
+ *   - ARV-50 — probe `--dry-run` JSON shape diverged from `--report json`;
+ *   - ARV-82 — `db runs --json` envelope `data` field shape disagreed
+ *     with sibling commands;
+ *   - …and four more along the same lines.
+ *
+ * Root cause: each command has its own ad-hoc flag parser. Some treat
+ * "ndjson" as an alias for `--ndjson`, some don't. Some honour
+ * `--output` for SARIF only, some for every format. Some wrap in a JSON
+ * envelope, some emit a raw stream. There is no single place to read
+ * "what does `command X` produce when I pass `--report Y --output Z`".
+ *
+ * This module gives that single place. A command declares an
+ * `OutputSpec<Payload>` once — listing the formats it supports, each
+ * format's default channel (stdout vs file), each format's default
+ * filename, and whether the format wraps in the standard `--json`
+ * envelope. A runner helper (`runCommandWithOutput`) consumes the spec
+ * plus the CLI flags and resolves them to a single `ResolvedOutput`
+ * decision, with consistent mutual-exclusion enforcement.
+ *
+ * The spec is the source-of-truth for ARV-120's build-time check:
+ * every `--json` command must declare an `OutputSpec` with an
+ * `envelopeWrap: true` entry, so the published schema and the runtime
+ * output cannot drift.
+ *
+ * This task only ships the infrastructure. Per-command migration
+ * (`run`, `checks`, `probe*`) lands in ARV-117/118/119.
+ */
+
+/** Where a rendered payload lands. */
+export type OutputChannel = "stdout" | "file";
+
+/** A format name — `sarif` / `ndjson` / `json` / `junit` etc. The set is
+ *  open: each command declares its own. */
+export type OutputFormat = string;
+
+/** Per-format policy: where the format writes by default, what filename
+ *  to use when it writes to a file, and whether the payload is wrapped
+ *  in the standard `{ ok, command, data, ... }` envelope. */
+export interface FormatPolicy {
+  /** Default destination when neither `--output` nor channel-overriding
+   *  flags are present. SARIF defaults to file (`zond-checks.sarif`);
+   *  NDJSON defaults to stdout (one event per line for piping); JSON
+   *  envelopes default to stdout. */
+  defaultChannel: OutputChannel;
+  /** Default filename when `defaultChannel === "file"`. Relative paths
+   *  are resolved against cwd by the runner. Ignored when
+   *  `defaultChannel === "stdout"` — the user has to opt in to a file
+   *  via `--output`. */
+  defaultFilename?: string;
+  /** True for formats that should be wrapped in the shared envelope
+   *  (`jsonOk` / `jsonError` from `cli/json-envelope.ts`). Streaming
+   *  formats (NDJSON) and bespoke serialisations (SARIF, JUnit) are
+   *  not envelope-wrapped — they have their own contracts. */
+  envelopeWrap?: boolean;
+  /** ARV-120: for `envelopeWrap` formats — basename of the JSON schema
+   *  under `docs/json-schema/` that describes the envelope's `data`
+   *  field. The build-time coverage test asserts the file exists, so
+   *  a renamed/deleted schema fails CI together with the spec. */
+  envelopeSchemaFile?: string;
+  /** Optional human description, surfaced by `--help` generators and
+   *  the README table. */
+  description?: string;
+}
+
+export interface OutputSpec<Payload = unknown> {
+  /** Command name — propagated into the JSON envelope's `command` field
+   *  and used by error messages. */
+  command: string;
+  /** Supported formats keyed by name. Unknown formats fall through to
+   *  an error (no silent acceptance, see ARV-97). */
+  formats: Record<OutputFormat, FormatPolicy>;
+  /** Default format when neither `--report` nor `--json` is set. */
+  defaultFormat: OutputFormat;
+  /** Optional alias map: `{ ndjson: 'ndjson' }` lets `--report ndjson`
+   *  fold into the `--ndjson` flag (ARV-63 alias, retained because
+   *  skill prompts ship it). Keys are flag values seen on the CLI;
+   *  values are the resolved format name. */
+  aliases?: Record<string, OutputFormat>;
+  /** Optional pre-validated render hook. Called by the runner once
+   *  the format is resolved. Receives the payload plus the resolved
+   *  format and returns the serialized output. */
+  render?: (format: OutputFormat, payload: Payload) => string;
+  /** Optional exit-code policy. Receives the payload after a
+   *  successful run; returns the process exit code (0 by default). */
+  exitCodePolicy?: (payload: Payload) => number;
+}
+
+/** Decision the runner makes after applying the spec to CLI flags. */
+export interface ResolvedOutput {
+  /** Resolved format name (always one of `spec.formats`). */
+  format: OutputFormat;
+  /** Resolved destination. */
+  channel: OutputChannel;
+  /** Filesystem path when `channel === "file"`. Absolute path expected
+   *  by callers — the runner resolves it against cwd. */
+  path?: string;
+  /** Whether the runner should wrap the payload in the standard
+   *  envelope before writing. Mirrors `FormatPolicy.envelopeWrap`. */
+  envelopeWrap: boolean;
+}
+
+/** Inputs the runner reads from the CLI layer. Names mirror commander
+ *  options so a command can pass `cmd.opts<OutputOptions>()` directly. */
+export interface OutputOptions {
+  /** `--report <format>`. */
+  report?: string;
+  /** `--output <path>`. */
+  output?: string;
+  /** `--json`. */
+  json?: boolean;
+}
+
+/** Thrown by `resolveOutput` when the user-supplied flags violate the
+ *  spec's policy (unknown format, mutually exclusive flags, …). The
+ *  CLI layer catches this and emits the standard `jsonError` or
+ *  human `printError`. */
+export class OutputSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OutputSpecError";
+  }
+}