Introduce phase-typed validated program and application plan boundaries

[cssbruno]

Priority

High

Context

Several generated-output APIs accept an ordinary gwdkir.Program plus a convention that the caller has already validated it. BuildFromValidatedIR uses the same program type as unvalidated entry points and relies on a Boolean to select full validation or invariant checks. appgen.Options can also carry both endpoint projections and an optional *gwdkir.Program, then performs route defaults, schema extraction, fragment compilation, and endpoint validation.

Problem

Validation state and compiler phase are not represented by types. Callers can accidentally bypass validation, and ownership of normalization and output-specific checks is split between compiler and generators. This also makes it possible for gowdk check and gowdk build to disagree.

Proposed direction

Introduce opaque phase types, for example:

type AnalyzedProgram struct { /* unexported */ }
type ValidatedProgram struct { /* unexported */ }
type ApplicationPlan struct { /* normalized output plan */ }

Only compiler APIs should construct ValidatedProgram. A single planning/lowering pass should convert it into an immutable ApplicationPlan containing all normalized routes, localized variants, compiled views/layouts/fragments, endpoint schemas, resolved bindings, guards, feature decisions, and request-time metadata.

buildgen and appgen should consume the plan and perform emission only.

Acceptance criteria

• Validation state cannot be represented by an ordinary gwdkir.Program plus a Boolean or naming convention.
• Only compiler-owned APIs can construct a validated program value.
• Route defaults, localization, layout composition, fragment compilation, form schemas, taint metadata, guard policy, and binding decisions are finalized before generation.
• buildgen and appgen accept an immutable plan and do not perform source parsing or semantic validation.
• gowdk check, build, dev, LSP, inspect, and audit can share the same validated snapshot.
• Public or package-level APIs clearly distinguish parse, analyze, validate, plan, and emit phases.
• Tests prove an invalid or merely analyzed program cannot reach generated-output emitters.

Related

This is complementary to #664, which removes raw-source semantic fallbacks.