Consolidate generated endpoint metadata into one canonical endpoint plan

[cssbruno]

Priority

Medium

Context

Endpoint information is currently projected through several overlapping models:

gwdkir.Endpoint and page block declarations
  -> appgen ActionEndpoint / APIEndpoint / FragmentEndpoint
  -> BackendEndpointRegistration
  -> BackendActionAdapter / BackendAPIAdapter / BackendFragmentAdapter

Method, route, page ID, guards, source span, binding, and related policy fields are repeatedly copied. appgen.Options can also carry both endpoint projections and the original IR.

Problem

Every new endpoint concern—authorization, cache policy, CSRF, rate limits, observability, body limits, error behavior, localization, or source metadata—must be threaded through multiple structs and conversions. Omitting a field can silently make generated registrations, adapters, proxy matching, reports, and runtime behavior disagree.

Proposed direction

Create one normalized EndpointPlan collection during application planning. Supporting records such as decoders, calls, responses, and fallbacks should reference a stable EndpointID rather than repeat endpoint identity and policy fields.

Example shape:

type EndpointPlan struct {
    ID      EndpointID
    Kind    EndpointKind
    Method  string
    Path    RoutePattern
    Owner   OwnerRef
    Policy  EndpointPolicy
    Binding HandlerBinding
    Source  SourceRef
}

type DecoderPlan struct {
    Endpoint EndpointID
    Schema   InputSchema
}

Acceptance criteria

• All generated request-time routes derive from one canonical endpoint-plan collection.
• Route registration, backend adapter calls, split proxy matching, reports, and security posture reference the same endpoint IDs.
• Method/path normalization, defaulting, localization, dynamic params, guards, CSRF, rate limits, cache/error policy, and binding status are computed once.
• Decoder, call, response, and fallback plans reference endpoint IDs instead of duplicating endpoint identity.
• appgen.Options no longer accepts competing endpoint projections plus raw IR.
• Adding a new endpoint policy field requires changing the canonical plan and its explicit consumers, not a conversion chain.
• Invariant tests detect dangling endpoint references and duplicate endpoint IDs.
• Golden tests prove route manifests, backend registration, proxy matching, and generated handlers remain aligned.

Related

#667 should provide the application-planning phase that owns this canonical model.