@defrex/autobuild 0.8.0

package/packages/core/src/config/schema.ts

@@ -0,0 +1,774 @@
+/**
+ * autobuild.toml schema (SPEC §16.1, D9): the one declarative per-repo config
+ * file. Declarative, not executable — the kernel, dispatcher, CLI, and any
+ * future tooling parse it without evaluating anything; commands are plain
+ * shell strings.
+ *
+ * Strictness policy (§16.1): unknown top-level keys/tables and unknown keys
+ * inside known tables are ERRORS — a typo must not silently disable a
+ * verifier. Open maps ([commands], [roles], [workspace.config], and the named
+ * [verify.<step>] and [finalize.<step>] table sets) are exempt by construction:
+ * their keys are user-chosen names, while every value remains strictly
+ * validated.
+ */
+import { z } from 'zod'
+import { prImageHostSchema } from '../ontology'
+import { SANDBOX_FORBIDDEN_ENV } from '../ports/workspace/operator-sandbox'
+import { defineEntry, openMap, ownEntries, parseEntry } from '../open-map'
+import { forwardIssues } from '../zod-issues'
+import { displayName, effectiveRuntimeReferences, tomlKey } from './roles'
+
+// ── Open maps ────────────────────────────────────────────────────────────────
+
+//
+// Every open map below is parsed through `../open-map`, which keeps a
+// user-chosen key intact instead of losing it to the prototype chain: the
+// perfectly valid TOML table `[roles."__proto__"]` would otherwise vanish while
+// parsing SUCCEEDS — never eagerly resolved, never dispatchable, and invisible
+// to the unconsumed-key warning that exists to catch exactly this class of dead
+// configuration (§9). A silent drop is the one outcome the strictness policy
+// above rules out.
+//
+// The TOML parser already hands us null-prototype tables with the key intact,
+// and `openMap` keeps it that way end to end.
+//
+// `[workspace.config]` is the one open map here whose keys are PLUGIN-owned
+// rather than Autobuild-owned, which makes faithful pass-through more important
+// rather than less. Autobuild cannot validate a key it does not interpret, so a
+// dropped one is undetectable downstream: the plugin sees an absent key and
+// cannot tell an operator who omitted it from one who declared it, then reports
+// its own error against a table that plainly contains it.
+
+/**
+ * A section mixing ONE known key (`steps`) with an open set of named step
+ * tables — the same preservation contract as `openMap`.
+ *
+ * Without it a valid `[verify."__proto__"]` table vanished before
+ * cross-validation, which then reported "is listed in verify.steps but has no
+ * [verify.__proto__] table" about a table sitting right there in the file. Loud
+ * rather than silent, but a diagnostic that contradicts the source is its own
+ * defect: §16.1 errors are feedback to whoever edits the file.
+ */
+function stepSection<T, C>(
+  label: string,
+  stepsSchema: z.ZodType<string[]>,
+  tableSchema: z.ZodType<T>,
+  compose: (steps: string[], stepConfigs: Record<string, T>) => C,
+) {
+  return z
+    .unknown()
+    .transform((input, ctx): C => {
+      const stepConfigs: Record<string, T> = Object.create(null)
+      let steps: string[] = []
+      for (const [key, raw] of ownEntries(input, label, ctx)) {
+        if (key === 'steps') {
+          const parsed = stepsSchema.safeParse(raw)
+          if (parsed.success) steps = parsed.data
+          else forwardIssues(parsed.error.issues, ctx, ['steps'])
+          continue
+        }
+        const table = parseEntry(tableSchema, raw, key, ctx)
+        if (table.ok) defineEntry(stepConfigs, key, table.value)
+      }
+      return compose(steps, stepConfigs)
+    })
+    .prefault({})
+}
+
+// ── [pr] / [pr.imageHost] ────────────────────────────────────────────────────
+
+/** Optional public GitHub release used for review-window image copies.
+ * Omission is intentionally `undefined`: hosting is off by default. */
+export const imageHostSchema = prImageHostSchema
+export type ImageHostConfig = z.infer<typeof imageHostSchema>
+
+export const prSchema = z.strictObject({
+  imageHost: imageHostSchema.optional(),
+})
+export type PrConfig = z.infer<typeof prSchema>
+
+// ── [workspace] ─────────────────────────────────────────────────────────────
+
+const envNameSchema = z
+  .string()
+  .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'must be a nonblank environment variable name')
+
+/** Strict built-in Vercel configuration. Values are operational policy only;
+ * credentials are referenced by variable name and never accepted as literals. */
+const nonblankProvisioningString = (field: string) =>
+  z.string().refine((value) => value.trim().length > 0, `${field} must be nonblank`)
+
+export const vercelProvisioningStepSchema = z.strictObject({
+  name: nonblankProvisioningString('provisioning step name'),
+  command: nonblankProvisioningString('provisioning step command'),
+})
+export type VercelProvisioningStep = z.infer<typeof vercelProvisioningStepSchema>
+
+const vercelUniversalImageSchema = z
+  .string()
+  .refine(
+    (image) =>
+      /^vercel\/sandbox\/universal(?::[A-Za-z0-9_][A-Za-z0-9._-]{0,127}|@sha256:[0-9a-f]{64})?$/.test(
+        image,
+      ),
+    'Autobuild Bun provisioning is validated only on the vercel/sandbox/universal managed image; use its bare name, a tag, or a sha256 digest containing exactly 64 lowercase hexadecimal characters',
+  )
+
+export const runtimeProvisioningEntrySchema = z.strictObject({
+  install: z.string().refine((value) => value.trim().length > 0, 'install must be nonblank'),
+  preflight: z.string().refine((value) => value.trim().length > 0, 'preflight must be nonblank'),
+})
+export type RuntimeProvisioningEntry = z.infer<typeof runtimeProvisioningEntrySchema>
+
+export const runtimeProvisioningSchema = openMap(
+  '[workspace.config.runtimeProvisioning]',
+  runtimeProvisioningEntrySchema,
+  { keys: 'nonblank' },
+)
+
+export const vercelSandboxConfigSchema = z
+  .strictObject({
+    image: vercelUniversalImageSchema.default('vercel/sandbox/universal:latest'),
+    vcpus: z.number().int().min(1).max(32).default(4),
+    timeoutSeconds: z.number().int().min(60).max(86_400),
+    /** Deadline for each provider acknowledgement; distinct from VM lifetime. */
+    operationTimeoutMs: z.number().int().min(1_000).max(300_000).default(30_000),
+    /** Billing safety net: snapshots created for this environment expire after
+     * this duration instead of the provider's 30-day default. Absent means the
+     * provider default. */
+    snapshotExpirationSeconds: z.number().int().min(300).max(2_592_000).optional(),
+    region: z.string().min(1).optional(),
+    failoverRegions: z.array(z.string().min(1)).default([]),
+    environmentVariables: z.array(envNameSchema).default([]),
+    provisioning: z.array(vercelProvisioningStepSchema).default([]),
+    runtimeProvisioning: runtimeProvisioningSchema,
+    gitUsernameEnv: envNameSchema.optional(),
+    gitPasswordEnv: envNameSchema.optional(),
+  })
+  .superRefine((value, ctx) => {
+    const unique = (entries: readonly string[], path: string) => {
+      const seen = new Set<string>()
+      entries.forEach((entry, index) => {
+        if (seen.has(entry))
+          ctx.addIssue({
+            code: 'custom',
+            path: [path, index],
+            message: `duplicate environment variable ${JSON.stringify(entry)}`,
+          })
+        seen.add(entry)
+      })
+    }
+    unique(value.environmentVariables, 'environmentVariables')
+    unique(value.failoverRegions, 'failoverRegions')
+    const provisioningNames = new Map<string, number>()
+    value.provisioning.forEach((step, index) => {
+      const first = provisioningNames.get(step.name)
+      if (first !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['provisioning', index, 'name'],
+          message: `duplicate provisioning step name ${JSON.stringify(step.name)} — first declared at provisioning[${first}].name`,
+        })
+      } else {
+        provisioningNames.set(step.name, index)
+      }
+    })
+    if (value.region !== undefined && value.failoverRegions.includes(value.region)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['failoverRegions'],
+        message: 'failover regions must not include the primary region',
+      })
+    }
+    if ((value.gitUsernameEnv === undefined) !== (value.gitPasswordEnv === undefined)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['gitPasswordEnv'],
+        message: 'gitUsernameEnv and gitPasswordEnv must be configured together',
+      })
+    }
+    for (const [key, name] of [
+      ['gitUsernameEnv', value.gitUsernameEnv],
+      ['gitPasswordEnv', value.gitPasswordEnv],
+    ] as const) {
+      if (name !== undefined && value.environmentVariables.includes(name)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [key],
+          message:
+            'private repository clone credentials must not be exposed as runtime environment variables',
+        })
+      }
+      if (
+        name !== undefined &&
+        /^(?:GITHUB_TOKEN|GH_TOKEN|VERCEL_(?:TOKEN|OIDC_TOKEN|TEAM_ID|PROJECT_ID))$/.test(name)
+      ) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [key],
+          message:
+            'private repository read credentials must be separate from Forge and Vercel credentials',
+        })
+      }
+    }
+  })
+type NormalizedVercelSandboxConfig = z.infer<typeof vercelSandboxConfigSchema>
+/** Direct provider construction remains source-compatible; schema-parsed
+ * production config always materializes operationTimeoutMs. */
+export type VercelSandboxConfig = Omit<
+  NormalizedVercelSandboxConfig,
+  'operationTimeoutMs' | 'provisioning' | 'runtimeProvisioning'
+> & {
+  operationTimeoutMs?: number
+  /** Optional only for source compatibility with direct adapter construction;
+   * schema-loaded repository configuration always materializes this list. */
+  provisioning?: VercelProvisioningStep[]
+  /** Optional only for source compatibility in direct adapter construction;
+   * parsed production configuration always materializes this map. */
+  runtimeProvisioning?: NormalizedVercelSandboxConfig['runtimeProvisioning']
+}
+
+/** Workspace selector. The host validates the selector envelope; plugin nested
+ * config remains open, while built-in config is validated by configSchema. */
+export const workspaceSchema = z.strictObject({
+  provider: z
+    .string()
+    .refine(
+      (value) => value.trim().length > 0,
+      '[workspace].provider must be a nonblank provider name',
+    )
+    .default('git-worktree'),
+  config: openMap('[workspace.config]', z.unknown(), { keys: 'any' }),
+})
+export type WorkspaceConfig = z.infer<typeof workspaceSchema>
+
+// ── [commands] ───────────────────────────────────────────────────────────────
+//
+// Open map of deterministic verbs the kernel may run. `setup`, `lint`,
+// `typecheck`, `test` are conventions, not required keys (§16.1).
+
+export const commandsSchema = openMap('[commands]', z.string().min(1))
+export type Commands = z.infer<typeof commandsSchema>
+
+// ── [verify.<step>] ──────────────────────────────────────────────────────────
+
+/**
+ * The intentionally small path-selector grammar (§16.1): positive,
+ * repository-relative globs with literal characters, `*`, `?`, and `**` only
+ * as a complete path segment. Reject every ambiguous/unsafe form at config
+ * load rather than allowing a typo to become a never-running safety gate.
+ */
+export function verifyPathGlobError(pattern: string): string | undefined {
+  if (pattern.length === 0) return 'path selectors must be nonempty'
+  if (pattern.includes('\0')) return 'path selectors must not contain NUL bytes'
+  if (pattern.startsWith('/') || /^[A-Za-z]:\//.test(pattern)) {
+    return 'path selectors must be repository-relative, not absolute'
+  }
+  if (pattern.includes('\\')) {
+    return 'path selectors use Git-style "/" separators; backslashes and escapes are unsupported'
+  }
+  if (pattern.startsWith('!')) {
+    return 'path selectors are positive globs; negation is unsupported'
+  }
+  if (/[[\]{}]/.test(pattern)) {
+    return 'path selectors support only literal characters, *, ?, and whole-segment **; character classes and brace expansion are unsupported'
+  }
+  if (/[?*+@!]\(/.test(pattern)) {
+    return 'path selectors support only literal characters, *, ?, and whole-segment **; extglobs are unsupported'
+  }
+
+  const segments = pattern.split('/')
+  if (segments.some((segment) => segment.length === 0)) {
+    return 'path selectors must not contain empty path segments'
+  }
+  if (segments.some((segment) => segment === '.' || segment === '..')) {
+    return 'path selectors must not contain "." or ".." traversal segments'
+  }
+  if (segments.some((segment) => segment.includes('**') && segment !== '**')) {
+    return 'the ** wildcard must occupy a complete path segment'
+  }
+  return undefined
+}
+
+export const verifyPathGlobSchema = z.string().superRefine((pattern, ctx) => {
+  const message = verifyPathGlobError(pattern)
+  if (message !== undefined) ctx.addIssue({ code: 'custom', message })
+})
+
+const verifyApplicabilityShape = {
+  /** Any-match positive path selectors; absent means unconditional. */
+  paths: z
+    .array(verifyPathGlobSchema)
+    .min(1, 'paths must contain at least one repository-relative glob')
+    .optional(),
+  /** Explicit mandatory-gate guard: true takes precedence over paths and a
+   * plan may not deselect the step. */
+  always: z.boolean().optional(),
+}
+
+export const verifyCheckStepSchema = z.strictObject({
+  /** Deterministic: command + pass/fail (§16.1). */
+  kind: z.literal('check'),
+  /** Ref into [commands] — cross-validated below. */
+  command: z.string().min(1),
+  ...verifyApplicabilityShape,
+})
+
+export const verifyAgentStepSchema = z.strictObject({
+  /** Agent-verify: skill + verdict schema (§16.1). */
+  kind: z.literal('agent'),
+  skill: z.string().min(1),
+  ...verifyApplicabilityShape,
+})
+
+export const verifyStepConfigSchema = z.discriminatedUnion('kind', [
+  verifyCheckStepSchema,
+  verifyAgentStepSchema,
+])
+export type VerifyStepConfig = z.infer<typeof verifyStepConfigSchema>
+
+export interface VerifyConfig {
+  /** Step order — each entry names a `verify:<step>` phase (§15.2.1). */
+  steps: string[]
+  /** The [verify.<step>] tables, keyed by step name. */
+  stepConfigs: Record<string, VerifyStepConfig>
+}
+
+/**
+ * [verify] mixes one known key (`steps`) with an open set of per-step
+ * subtables, so it cannot be a strictObject; instead every non-`steps` key is
+ * validated as a step table — nothing passes through loosely, and no step name
+ * is lost to the prototype chain (see `stepSection`).
+ */
+export const verifySectionSchema = stepSection(
+  '[verify]',
+  z.array(z.string().min(1)).default([]),
+  verifyStepConfigSchema,
+  (steps, stepConfigs): VerifyConfig => ({ steps, stepConfigs }),
+)
+
+// ── [finalize.<step>] ────────────────────────────────────────────────────────
+
+/** Finalize steps deliberately omit verify-only applicability fields. */
+export const finalizeCheckStepSchema = z.strictObject({
+  kind: z.literal('check'),
+  /** Ref into [commands] — cross-validated below. */
+  command: z.string().min(1),
+})
+
+export const finalizeAgentStepSchema = z.strictObject({
+  kind: z.literal('agent'),
+  /** Exact installed skill name passed to the configured runtime. */
+  skill: z.string().min(1),
+})
+
+export const finalizeStepConfigSchema = z.discriminatedUnion('kind', [
+  finalizeCheckStepSchema,
+  finalizeAgentStepSchema,
+])
+export type FinalizeStepConfig = z.infer<typeof finalizeStepConfigSchema>
+
+export interface FinalizeConfig {
+  /** Ordered, failure-tolerant post-steps (§5). */
+  steps: string[]
+  /** The [finalize.<step>] tables, keyed by logical step name. */
+  stepConfigs: Record<string, FinalizeStepConfig>
+}
+
+/** Like [verify], [finalize] mixes `steps` with a strict named table set. */
+export const finalizeSectionSchema = stepSection(
+  '[finalize]',
+  z.array(z.string().min(1, 'finalize.steps entries must be nonempty step names')).default([]),
+  finalizeStepConfigSchema,
+  (steps, stepConfigs): FinalizeConfig => ({ steps, stepConfigs }),
+)
+
+// ── [roles] ──────────────────────────────────────────────────────────────────
+//
+// Open map: role → fields on the runtime, model, and args axes (SPEC §9,
+// §16.1). The reserved `default` entry is the raw inheritance base and must
+// name a runtime; registry-aware enforcement lives in the eager resolver;
+// every other role overrides it independently per field. Registry-dependent
+// compatibility validation happens in the eager runtime resolver, because the
+// config loader does not know the injected runtime registry.
+
+const roleArgsSchema = z.array(z.string().min(1))
+
+const runtimeAxesSchema = z.strictObject({
+  runtime: z.string().min(1).optional(),
+  model: z.string().min(1).optional(),
+  args: roleArgsSchema.optional(),
+  // Deprecated compatibility field. It remains schema-valid but is a warning-only no-op.
+  extensions: z.array(z.string().min(1)).optional(),
+})
+
+export const roleSchema = runtimeAxesSchema.extend({
+  // Wall-clock budget for each session dispatched through this logical role.
+  // Absent ⇒ inherit [roles.default], then [policy].sessionBudgetSeconds.
+  // Alternates deliberately use runtimeAxesSchema: one logical role owns one
+  // budget regardless of which provider target executes the attempt.
+  sessionBudgetSeconds: z.number().int().positive().optional(),
+  // Extra CLI arguments. Absent ⇒ inherit [roles.default].args; a declared
+  // list, including [], replaces the default wholesale rather than unioning.
+  args: roleArgsSchema.optional(),
+  // Deprecated compatibility field. It is accepted only so dispatch can emit
+  // a migration diagnostic; it has no effect on runtime resolution.
+  extensions: z.array(z.string().min(1)).optional(),
+  // Ordered failure-triggered execution targets. Absent ⇒ inherit the base
+  // list; a declared list (including []) replaces it wholesale. Each strict
+  // entry overlays the concrete role's resolved primary axes.
+  alternates: z.array(runtimeAxesSchema).optional(),
+})
+export type RoleConfig = z.infer<typeof roleSchema>
+
+// ── [policy] ─────────────────────────────────────────────────────────────────
+
+export const policySchema = z.strictObject({
+  /** Wall-clock bound for an agent phase session; roles may override it. */
+  sessionBudgetSeconds: z.number().int().positive().default(3600),
+  /** Same-finding survival threshold before auto-escalate (§10, §15.4). */
+  stallRounds: z.number().int().positive().default(3),
+  maxVerifyAttempts: z.number().int().positive().default(3),
+  /** Consecutive workspace setup failures before human intervention is required. */
+  maxSetupAttempts: z.number().int().positive().default(3),
+  /** Consecutive provider lifecycle failures before recovery requires a human retry. */
+  maxInfrastructureAttempts: z.number().int().positive().default(3),
+  maxReconcileAttempts: z.number().int().positive().default(3),
+  /** converge's `maxRounds` for the review loops (SPEC §10). */
+  maxReviewRounds: z.number().int().positive().default(6),
+  /** Unclaimed observation occurrences required to start one harvest run. */
+  harvestThreshold: z.number().int().positive().default(5),
+  /** Merged builds after the oldest observation that start harvest; zero disables drift. */
+  harvestMaxDrift: z.number().int().nonnegative().default(3),
+})
+export type PolicyConfig = z.infer<typeof policySchema>
+
+// ── [tickets] ────────────────────────────────────────────────────────────────
+//
+// Which TicketSource the dispatcher drives and the source-vocabulary states
+// that govern its lifecycle (§3.2, §3.3, §13). Declarative only: the Linear
+// API key comes from the LINEAR_API_KEY environment variable, never from this
+// file.
+
+export const ticketsSchema = z.strictObject({
+  /** Builtin or plugin-registered TicketSource name. Registry membership is
+   * validated after configured plugins load. */
+  source: z
+    .string()
+    .refine(
+      (value) => value.trim().length > 0,
+      '[tickets].source must be a nonblank builtin or plugin ticket source name',
+    ),
+  /**
+   * Ticket labels that additionally narrow the mandatory readyState gate
+   * (§3.3). A nonempty list is conjunctive: every configured label must be
+   * present. For readyLabels = ["autobuild", "ready"], a ticket carrying only
+   * "autobuild" does not satisfy the label gate. An explicit [] disables the
+   * label gate; absent uses the ticket source's default (linear: ["autobuild"];
+   * file: none). Resolved by readyCriteria in src/processes/dispatcher.ts.
+   */
+  readyLabels: z.array(z.string().min(1)).optional(),
+  /**
+   * The single workflow state a ticket must sit in to be dispatchable — the
+   * mandatory ready gate (§3.3). Required and non-blank: without it every
+   * ticket from the source would be eligible in any state, including completed
+   * ones (the AUT-10 mis-gating). Applied by readyCriteria on top of any label
+   * gate. Linear matches exactly and case-sensitively; the file source
+   * canonicalizes it to a state directory (`ready` → `ready/`).
+   */
+  readyState: z
+    .string({
+      error:
+        '[tickets].readyState is required — name the one workflow state a ticket must sit in to be dispatched (e.g. "ready"). Omitting it would make every ticket from the source eligible, including completed ones.',
+    })
+    .refine(
+      (s) => s.trim().length > 0,
+      '[tickets].readyState must not be blank — name the one workflow state a ticket must sit in to be dispatched (e.g. "ready").',
+    ),
+  /** Backend team key (e.g. "ENG") — required for linear and hosted. */
+  teamKey: z.string().min(1).optional(),
+  /** Workflow state claim() moves an issue to (§12); Linear and hosted. */
+  claimedState: z.string().min(1).optional(),
+  /** State create() files new tickets into. Absent = the provider's default
+   * (Linear: the team's default state, e.g. Backlog; file: Triage). */
+  createState: z.string().min(1).optional(),
+  /** State the dispatcher hands tickets back to for human triage — spec-gate
+   * bounces (§6.3), aborted builds, closed-unmerged PRs. Absent = the
+   * provider's default (Linear: Backlog; file: Triage) — resolved by
+   * defaultTriageState in src/processes/dispatcher.ts. */
+  triageState: z.string().min(1).optional(),
+  /** State harvest files its synthesized proposals into (§12). Absent = the
+   * triage state, which keeps the constitutional grooming gate: a proposal
+   * waits for a human before it can be dispatched. Setting it to readyState
+   * waives that gate for this repository — proposals dispatch unread — and is
+   * the only supported way to do so. Separate from triageState so the waiver
+   * does not also redirect spec-gate bounces, aborts, and closed-unmerged PRs
+   * into the ready state, where a bounce would re-dispatch itself. Resolved by
+   * defaultProposalState in src/processes/dispatcher.ts. */
+  proposalState: z.string().min(1).optional(),
+  /** Directory of state dirs (`triage/ ready/ doing/ done/`) holding `<id>.md`
+   * ticket files; optional — defaults to `.autobuild/tickets`, resolved
+   * relative to the repo. Kept schema-optional (not `.default()`) so the
+   * linear-only cross-validation below stays meaningful and the factory can
+   * still tell a defaulted dir from an explicit one. */
+  dir: z.string().min(1).optional(),
+})
+export type TicketsConfig = z.infer<typeof ticketsSchema>
+
+// ── [orchestrator] ──────────────────────────────────────────────────────────
+//
+// The operator-agent gate (AUT-340). Absent table ≡ disabled: with `enabled =
+// false` (the default) the sandbox registry tools are absent from every
+// binding and no environment is ever provisioned.
+
+export const orchestratorSandboxSchema = z.strictObject({
+  /** Idle minutes without a sandbox tool call before the dispatcher tick's
+   * janitor stops the environment, keeping its snapshot for the next resume. */
+  idleMinutes: z.number().int().positive().default(30),
+  /** Names of non-secret host environment variables forwarded into the
+   * sandbox (during provisioning/setup and tool exec/start alike). These are
+   * the ONLY non-toolchain environment the sandbox ever sees; forwarding any
+   * store, forge, ticket-provider, model, or Vercel credential name is a
+   * config error. Unset means none. */
+  environmentVariables: z.array(z.string().min(1)).default([]),
+})
+export type OrchestratorSandboxConfig = z.infer<typeof orchestratorSandboxSchema>
+
+export const orchestratorSchema = z.strictObject({
+  enabled: z.boolean().default(false),
+  sandbox: orchestratorSandboxSchema.prefault({}),
+})
+export type OrchestratorConfig = z.infer<typeof orchestratorSchema>
+
+// ── Whole file ───────────────────────────────────────────────────────────────
+
+const configRootSchema = z.strictObject({
+  /** Base branch builds cut from and target (§16.1). */
+  baseBranch: z.string().min(1).default('main'),
+  /** Concurrent builds for this repository (§16.1). */
+  capacity: z.number().int().positive().default(1),
+  /** Forge adapter selected from builtins and configured plugins. */
+  forge: z
+    .string()
+    .refine((value) => value.trim().length > 0, 'forge adapter name must be nonblank')
+    .default('github'),
+  /** Trusted in-process plugin modules, loaded in declaration order from the
+   * consuming repository before production adapters are constructed. Exact
+   * specifier strings must be unique (cross-validated below). */
+  plugins: z
+    .array(
+      z
+        .string()
+        .refine((value) => value.trim().length > 0, 'plugin module specifiers must be nonblank'),
+    )
+    .default([]),
+  pr: prSchema.optional(),
+  workspace: workspaceSchema.prefault({}),
+  commands: commandsSchema,
+  verify: verifySectionSchema,
+  finalize: finalizeSectionSchema,
+  // `default` is reserved inside this open map (§9). The schema preserves the
+  // raw map — EVERY declared key, `__proto__` included, or an entry would
+  // disappear ahead of both eager resolution and the unconsumed-key warning;
+  // the registry-aware eager resolver requires default.runtime and can
+  // therefore include the complete materialized runtime list in its diagnostic.
+  roles: openMap('[roles]', roleSchema),
+  policy: policySchema.prefault({}),
+  orchestrator: orchestratorSchema.prefault({}),
+  // An absent [tickets] table must NOT silently default past the mandatory
+  // ready gate. Prefault feeds the file-source identity through ticketsSchema,
+  // which deliberately fails on missing `readyState` at `tickets.readyState`.
+  // The cast only satisfies prefault's input type; `{ source: 'file' }` is
+  // intentionally invalid until the repository names its ready state.
+  tickets: ticketsSchema.prefault({
+    source: 'file',
+  } as z.input<typeof ticketsSchema>),
+})
+
+/** Root metadata keeps strict error prose and documentation coverage honest. */
+export const TOP_LEVEL_SCALARS = ['baseBranch', 'capacity', 'forge', 'plugins'] as const
+export const TOP_LEVEL_TABLES = Object.keys(configRootSchema.shape).filter(
+  (key) => !(TOP_LEVEL_SCALARS as readonly string[]).includes(key),
+)
+export const TOP_LEVEL_KEYS = Object.keys(configRootSchema.shape)
+
+/**
+ * Cross-validation (§16.1): errors carry the path and what would be accepted,
+ * because validation failures are feedback to whoever edits the file (D6
+ * discipline applied to config).
+ */
+export const configSchema = configRootSchema.superRefine((config, ctx) => {
+  const firstPluginIndex = new Map<string, number>()
+  config.plugins.forEach((specifier, index) => {
+    const firstIndex = firstPluginIndex.get(specifier)
+    if (firstIndex === undefined) {
+      firstPluginIndex.set(specifier, index)
+      return
+    }
+    ctx.addIssue({
+      code: 'custom',
+      path: ['plugins', index],
+      message:
+        `duplicate plugin module specifier ${JSON.stringify(specifier)} — first declared at ` +
+        `plugins[${firstIndex}]; remove or deduplicate this entry`,
+    })
+  })
+
+  if (
+    config.workspace.provider === 'git-worktree' &&
+    Object.keys(config.workspace.config).length > 0
+  ) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['workspace', 'config'],
+      message:
+        '[workspace.config] is not supported by the builtin "git-worktree" provider — remove it or select a plugin workspace provider',
+    })
+  } else if (config.workspace.provider === 'vercel-sandbox') {
+    const parsed = vercelSandboxConfigSchema.safeParse(config.workspace.config)
+    if (!parsed.success) {
+      forwardIssues(parsed.error.issues, ctx, ['workspace', 'config'])
+    } else if (
+      config.roles !== undefined &&
+      config.verify !== undefined &&
+      config.finalize !== undefined
+    ) {
+      for (const group of effectiveRuntimeReferences(config)) {
+        if (Object.hasOwn(parsed.data.runtimeProvisioning, group.runtime)) continue
+        ctx.addIssue({
+          code: 'custom',
+          path: ['workspace', 'config', 'runtimeProvisioning', group.runtime],
+          message:
+            `runtime ${displayName(group.runtime)} is selected by ${group.references.join(', ')} but has no sandbox provisioning; add ` +
+            `[workspace.config.runtimeProvisioning.${tomlKey(group.runtime)}] with nonblank install and preflight commands`,
+        })
+      }
+    }
+  }
+
+  const commandNames = Object.keys(config.commands)
+  const knownCommands =
+    commandNames.length > 0
+      ? `known commands: ${commandNames.join(', ')}`
+      : '[commands] has no entries'
+
+  // A failed transformed subsection can be absent from Zod's partial object
+  // while sibling issues are collected. Guard the cross-check so malformed
+  // tables report validation feedback instead of throwing inside validation.
+  if (config.verify?.stepConfigs !== undefined) {
+    config.verify.steps.forEach((step, index) => {
+      if (!Object.hasOwn(config.verify.stepConfigs, step)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['verify', 'steps', index],
+          message:
+            `verify step "${step}" is listed in verify.steps but has no [verify.${step}] table — ` +
+            `add one with kind = "check" (command = <name in [commands]>) or kind = "agent" (skill = <skill name>)`,
+        })
+      }
+    })
+
+    const listed = new Set(config.verify.steps)
+    for (const [step, stepConfig] of Object.entries(config.verify.stepConfigs)) {
+      if (!listed.has(step)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['verify', step],
+          message:
+            `[verify.${step}] is defined but "${step}" is not listed in verify.steps — ` +
+            `add "${step}" to verify.steps or remove the table`,
+        })
+      }
+      if (stepConfig.kind === 'check' && !Object.hasOwn(config.commands, stepConfig.command)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['verify', step, 'command'],
+          message: `[verify.${step}].command = "${stepConfig.command}" does not name a key in [commands] — ${knownCommands}`,
+        })
+      }
+    }
+  }
+
+  if (config.finalize?.stepConfigs !== undefined) {
+    config.finalize.steps.forEach((step, index) => {
+      if (!Object.hasOwn(config.finalize.stepConfigs, step)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['finalize', 'steps', index],
+          message:
+            `finalize step "${step}" is listed in finalize.steps but has no [finalize.${step}] table — ` +
+            `add one with kind = "check" (command = <name in [commands]>) or kind = "agent" (skill = <skill name>)`,
+        })
+      }
+    })
+
+    const listedFinalize = new Set(config.finalize.steps)
+    for (const [step, stepConfig] of Object.entries(config.finalize.stepConfigs)) {
+      if (!listedFinalize.has(step)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['finalize', step],
+          message:
+            `[finalize.${step}] is defined but "${step}" is not listed in finalize.steps — ` +
+            `add "${step}" to finalize.steps or remove the table`,
+        })
+      }
+      if (stepConfig.kind === 'check' && !Object.hasOwn(config.commands, stepConfig.command)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['finalize', step, 'command'],
+          message: `[finalize.${step}].command = "${stepConfig.command}" does not name a key in [commands] — ${knownCommands}`,
+        })
+      }
+    }
+  }
+
+  const tickets = config.tickets
+  if (tickets.source === 'linear' || tickets.source === 'hosted') {
+    if (tickets.teamKey === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['tickets', 'teamKey'],
+        message: `[tickets].source = "${tickets.source}" requires teamKey${
+          tickets.source === 'linear' ? ' — the Linear team key (e.g. "ENG")' : ''
+        }`,
+      })
+    }
+    if (tickets.dir !== undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['tickets', 'dir'],
+        message: '[tickets].dir applies only to source = "file" — remove it or set source = "file"',
+      })
+    }
+  } else if (tickets.source === 'file') {
+    // dir is optional for the file source: absent = .autobuild/tickets.
+    for (const key of ['teamKey', 'claimedState'] as const) {
+      if (tickets[key] !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['tickets', key],
+          message: `[tickets].${key} applies only to source = "linear" or "hosted" — remove it or select one of those sources`,
+        })
+      }
+    }
+  }
+  // Plugin sources receive the existing ticket lifecycle/configuration fields
+  // unchanged; adapter-specific validation belongs to their factory.
+
+  // The credential-free sandbox rule (AUT-340): a forwarded variable name may
+  // never name a store, forge, ticket-provider, model, or Vercel credential.
+  if (config.orchestrator.enabled) {
+    config.orchestrator.sandbox.environmentVariables.forEach((name, index) => {
+      if (SANDBOX_FORBIDDEN_ENV.includes(name)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['orchestrator', 'sandbox', 'environmentVariables', index],
+          message: `environment variable ${JSON.stringify(name)} is a store, forge, ticket-provider, model, or Vercel credential and may never be forwarded into an operator sandbox`,
+        })
+      }
+    })
+  }
+})
+
+export type Config = z.infer<typeof configSchema>