refactor(compiler): split semantic IR source maps and target plans (#755)

* add semantic IR identities

* refactor(compiler): move endpoint source fidelity to source map

* fix(compiler): address semantic id review feedback

Author: cssbruno

docs/compiler/pipeline.md

@@ -61,6 +61,12 @@ The IR models packages, source files, page routes, backend endpoints from
 source-selected assets, asset scope/hash metadata, parsed view nodes, typed
 literal records, and imported build-data call metadata.
 
+Standalone Go endpoint comments lower into normalized `Program.Endpoints`
+records with stable `EndpointID` values. Exact source spelling and route-param
+spans for those comments live in `Program.SourceMap`; validators can use that
+source map for diagnostics, but generated-output planners consume the normalized
+endpoint record and carry the semantic ID into target-specific plans.
+
 `gwdkir.Blocks` retains source bodies for spans, formatting, inspection, and
 compatibility only. Parser/analyzer lowering must populate parsed `view {}`
 nodes, ordered literal `paths {}`/`build {}` records, and imported build-data

docs/engineering/architecture.md

@@ -35,6 +35,13 @@ request-time lane selected with `server {}` or `go server {}`.
 `internal/gwdkir.Program` is the compiler handoff. New generated-output work
 should consume that IR or add fields there first.
 
+Semantic records carry stable typed IDs for pages, routes, components, layouts,
+and endpoints. Exact source spelling and spans that are only needed for
+diagnostics or inspection belong in source-map records instead of duplicate raw
+semantic entities. Build output and generated app code use explicit target plans
+(`buildgen.BuildPlan`, `appgen.ApplicationPlan`) so target-only decisions do not
+expand the shared semantic program.
+
 Current handoff path:
 
 ```text

internal/appgen/adapter_ir.go

@@ -32,6 +32,7 @@ const (
 )
 
 type BackendEndpointRegistration struct {
+	ID      gwdkir.EndpointID
 	Kind    BackendEndpointKind
 	Method  string
 	Path    string
@@ -149,6 +150,7 @@ func backendAdapterIR(options Options) BackendAdapterIR {
 	var ir BackendAdapterIR
 	for _, action := range sortedActionEndpoints(options.Actions) {
 		endpoint := BackendEndpointRegistration{
+			ID:      action.EndpointID,
 			Kind:    BackendEndpointAction,
 			Method:  actionMethod(action),
 			Path:    action.Route,
@@ -223,6 +225,7 @@ func backendAdapterIR(options Options) BackendAdapterIR {
 	}
 	for _, api := range sortedAPIEndpoints(options.APIs) {
 		endpoint := BackendEndpointRegistration{
+			ID:      api.EndpointID,
 			Kind:    BackendEndpointAPI,
 			Method:  api.Method,
 			Path:    api.Route,
@@ -268,6 +271,7 @@ func backendAdapterIR(options Options) BackendAdapterIR {
 	}
 	for _, fragment := range sortedFragmentEndpoints(options.Fragments) {
 		endpoint := BackendEndpointRegistration{
+			ID:      fragment.EndpointID,
 			Kind:    BackendEndpointFragment,
 			Method:  fragment.Method,
 			Path:    fragment.Route,

internal/appgen/adapter_ir_test.go

@@ -11,6 +11,7 @@ import (
 func TestBackendAdapterIRCapturesRouteAndHandlerMetadata(t *testing.T) {
 	ir := backendAdapterIR(Options{
 		Actions: []ActionEndpoint{{
+			EndpointID:  gwdkir.EndpointID("action-id"),
 			PageID:      "newsletter",
 			ActionName:  "Subscribe",
 			Method:      "POST",
@@ -32,11 +33,12 @@ func TestBackendAdapterIRCapturesRouteAndHandlerMetadata(t *testing.T) {
 			BackendAlias: "newsletter",
 		}},
 		APIs: []APIEndpoint{{
-			PageID:  "status",
-			APIName: "Health",
-			Method:  "GET",
-			Route:   "/api/health",
-			Guards:  []string{"public"},
+			EndpointID: gwdkir.EndpointID("api-id"),
+			PageID:     "status",
+			APIName:    "Health",
+			Method:     "GET",
+			Route:      "/api/health",
+			Guards:     []string{"public"},
 			Binding: source.BackendBinding{
 				Status:       source.BackendBindingBound,
 				ImportPath:   "example.com/app/status",
@@ -46,6 +48,7 @@ func TestBackendAdapterIRCapturesRouteAndHandlerMetadata(t *testing.T) {
 			BackendAlias: "status",
 		}},
 		Fragments: []FragmentEndpoint{{
+			EndpointID:   gwdkir.EndpointID("fragment-id"),
 			PageID:       "patients",
 			FragmentName: "List",
 			Method:       "GET",
@@ -78,6 +81,9 @@ func TestBackendAdapterIRCapturesRouteAndHandlerMetadata(t *testing.T) {
 	if ir.Registrations[0].Kind != BackendEndpointAction || ir.Registrations[0].Path != "/newsletter" || ir.Registrations[0].Handler != "action" {
 		t.Fatalf("unexpected action registration: %#v", ir.Registrations[0])
 	}
+	if ir.Registrations[0].ID != gwdkir.EndpointID("action-id") || ir.Registrations[1].ID != gwdkir.EndpointID("api-id") || ir.Registrations[2].ID != gwdkir.EndpointID("fragment-id") {
+		t.Fatalf("expected semantic endpoint IDs in registrations, got %#v", ir.Registrations)
+	}
 	if ir.Registrations[1].Kind != BackendEndpointAPI || ir.Registrations[1].Path != "/api/health" || ir.Registrations[1].Handler != "api" {
 		t.Fatalf("unexpected API registration: %#v", ir.Registrations[1])
 	}

internal/appgen/ir.go

@@ -28,13 +28,14 @@ func actionEndpointsFromIR(config gowdk.Config, ir gwdkir.Program) ([]ActionEndp
 			if route == "" {
 				route = page.Route
 			}
-			bindingRoute := route
 			fragments, err := actionFragmentsFromIR(action)
 			if err != nil {
 				return nil, fmt.Errorf("%s.%s: %w", page.ID, action.Name, err)
 			}
+			semanticEndpoint := irEndpointForBlock(ir.Endpoints, gwdkir.EndpointAction, page.ID, action.Name, method, route)
 			for _, localized := range actionEndpointRoutes(config.I18N, page.Route, route, action.Route == "") {
 				endpoints = append(endpoints, ActionEndpoint{
+					EndpointID:       semanticEndpoint.SemanticID(),
 					PageID:           page.ID,
 					ActionName:       action.Name,
 					Method:           method,
@@ -51,7 +52,7 @@ func actionEndpointsFromIR(config gowdk.Config, ir gwdkir.Program) ([]ActionEndp
 					Redirect:         action.Redirect,
 					Fragments:        fragments,
 					ErrorPage:        action.ErrorPage,
-					Binding:          bindings[irEndpointKey(gwdkir.EndpointAction, page.ID, action.Name, method, bindingRoute)],
+					Binding:          bindings[semanticEndpoint.SemanticID()],
 					Source:           page.Source,
 					SourceSpan:       action.Span,
 				})
@@ -62,8 +63,9 @@ func actionEndpointsFromIR(config gowdk.Config, ir gwdkir.Program) ([]ActionEndp
 		if endpoint.Kind != gwdkir.EndpointAction || endpoint.Source != gwdkir.EndpointSourceGo {
 			continue
 		}
-		binding := bindings[irEndpointKey(endpoint.Kind, endpoint.PageID, endpoint.Symbol, endpoint.Method, endpoint.Path)]
+		binding := bindings[endpoint.SemanticID()]
 		endpoints = append(endpoints, ActionEndpoint{
+			EndpointID:  endpoint.SemanticID(),
 			PageID:      endpoint.PageID,
 			ActionName:  endpoint.Symbol,
 			Method:      endpoint.Method,
@@ -116,15 +118,17 @@ func apiEndpointsFromIR(ir gwdkir.Program) ([]APIEndpoint, error) {
 			if route == "" {
 				route = page.Route
 			}
+			semanticEndpoint := irEndpointForBlock(ir.Endpoints, gwdkir.EndpointAPI, page.ID, api.Name, method, route)
 			endpoints = append(endpoints, APIEndpoint{
+				EndpointID: semanticEndpoint.SemanticID(),
 				PageID:     page.ID,
 				APIName:    api.Name,
 				Method:     method,
 				Route:      route,
 				Guards:     append([]string(nil), page.Guards...),
 				ErrorPage:  api.ErrorPage,
 				CORS:       cloneEndpointCORS(api.CORS),
-				Binding:    bindings[irEndpointKey(gwdkir.EndpointAPI, page.ID, api.Name, method, route)],
+				Binding:    bindings[semanticEndpoint.SemanticID()],
 				Source:     page.Source,
 				SourceSpan: api.Span,
 			})
@@ -135,13 +139,14 @@ func apiEndpointsFromIR(ir gwdkir.Program) ([]APIEndpoint, error) {
 			continue
 		}
 		endpoints = append(endpoints, APIEndpoint{
+			EndpointID: endpoint.SemanticID(),
 			PageID:     endpoint.PageID,
 			APIName:    endpoint.Symbol,
 			Method:     endpoint.Method,
 			Route:      endpoint.Path,
 			ErrorPage:  endpoint.ErrorPage,
 			CORS:       cloneEndpointCORS(endpoint.CORS),
-			Binding:    bindings[irEndpointKey(endpoint.Kind, endpoint.PageID, endpoint.Symbol, endpoint.Method, endpoint.Path)],
+			Binding:    bindings[endpoint.SemanticID()],
 			Source:     endpoint.SourceFile,
 			SourceSpan: endpoint.Span,
 		})
@@ -175,18 +180,21 @@ func fragmentEndpointsFromIR(ir gwdkir.Program) ([]FragmentEndpoint, error) {
 			if method == "" {
 				method = "GET"
 			}
+			route := strings.TrimSpace(fragment.Route)
+			semanticEndpoint := irEndpointForBlock(ir.Endpoints, gwdkir.EndpointFragment, page.ID, fragment.Name, method, route)
 			endpoints = append(endpoints, FragmentEndpoint{
+				EndpointID:   semanticEndpoint.SemanticID(),
 				PageID:       page.ID,
 				FragmentName: fragment.Name,
 				Method:       method,
-				Route:        strings.TrimSpace(fragment.Route),
-				RouteParams:  gwdkir.RouteParamsFromPath(strings.TrimSpace(fragment.Route)),
+				Route:        route,
+				RouteParams:  gwdkir.RouteParamsFromPath(route),
 				Target:       fragment.Target,
 				HTML:         html,
 				Package:      page.Package,
 				Uses:         uses,
 				Guards:       append([]string(nil), page.Guards...),
-				Binding:      bindings[irEndpointKey(gwdkir.EndpointFragment, page.ID, fragment.Name, method, strings.TrimSpace(fragment.Route))],
+				Binding:      bindings[semanticEndpoint.SemanticID()],
 				Source:       page.Source,
 				SourceSpan:   fragment.Span,
 			})
@@ -316,8 +324,8 @@ func irExportTypes(exports []gwdkir.Export) map[string]clientlang.ValueType {
 	return out
 }
 
-func irBindingsByEndpoint(endpoints []gwdkir.Endpoint) map[string]source.BackendBinding {
-	out := map[string]source.BackendBinding{}
+func irBindingsByEndpoint(endpoints []gwdkir.Endpoint) map[gwdkir.EndpointID]source.BackendBinding {
+	out := map[gwdkir.EndpointID]source.BackendBinding{}
 	for _, endpoint := range endpoints {
 		if endpoint.Binding.Status == "" && endpoint.Binding.ImportPath == "" && endpoint.Binding.FunctionName == "" {
 			continue
@@ -326,7 +334,7 @@ func irBindingsByEndpoint(endpoints []gwdkir.Endpoint) map[string]source.Backend
 		if endpoint.Kind == gwdkir.EndpointAPI {
 			kind = "api"
 		}
-		out[irEndpointKey(endpoint.Kind, endpoint.PageID, endpoint.Symbol, endpoint.Method, endpoint.Path)] = source.BackendBinding{
+		out[endpoint.SemanticID()] = source.BackendBinding{
 			Kind:          kind,
 			PageID:        endpoint.PageID,
 			Source:        endpoint.SourceFile,
@@ -350,8 +358,23 @@ func irBindingsByEndpoint(endpoints []gwdkir.Endpoint) map[string]source.Backend
 	return out
 }
 
-func irEndpointKey(kind gwdkir.EndpointKind, pageID, symbol, method, route string) string {
-	return strings.Join([]string{string(kind), pageID, symbol, method, route}, "\x00")
+func irEndpointForBlock(endpoints []gwdkir.Endpoint, kind gwdkir.EndpointKind, pageID, symbol, method, route string) gwdkir.Endpoint {
+	for _, endpoint := range endpoints {
+		if endpoint.Kind == kind &&
+			endpoint.PageID == pageID &&
+			endpoint.Symbol == symbol &&
+			endpoint.Method == method &&
+			endpoint.Path == route {
+			return endpoint
+		}
+	}
+	return gwdkir.Endpoint{
+		Kind:   kind,
+		PageID: pageID,
+		Symbol: symbol,
+		Method: method,
+		Path:   route,
+	}
 }
 
 func actionFragmentsFromIR(action gwdkir.Action) ([]ActionFragment, error) {

internal/appgen/types.go

@@ -71,6 +71,7 @@ func OptionsFromIR(config gowdk.Config, ir *gwdkir.Program) Options {
 
 // ActionEndpoint describes a generated action handler.
 type ActionEndpoint struct {
+	EndpointID       gwdkir.EndpointID
 	PageID           string
 	ActionName       string
 	Method           string
@@ -114,6 +115,7 @@ type ActionValidationRule struct {
 
 // APIEndpoint describes a generated API handler.
 type APIEndpoint struct {
+	EndpointID   gwdkir.EndpointID
 	PageID       string
 	APIName      string
 	Method       string
@@ -129,6 +131,7 @@ type APIEndpoint struct {
 
 // FragmentEndpoint describes a generated server fragment handler.
 type FragmentEndpoint struct {
+	EndpointID   gwdkir.EndpointID
 	PageID       string
 	FragmentName string
 	Method       string

internal/compiler/backend_bindings.go

@@ -74,17 +74,20 @@ func computeBackendBindings(ir gwdkir.Program) []source.BackendBinding {
 			}
 		}
 	}
-	for _, endpoint := range ir.GoEndpoints {
-		dir := sourceDir(endpoint.Source)
+	for _, endpoint := range ir.Endpoints {
+		if endpoint.Source != gwdkir.EndpointSourceGo {
+			continue
+		}
+		dir := sourceDir(endpoint.SourceFile)
 		pkg, ok := cache[dir]
 		if !ok {
 			pkg = inspectFeaturePackage(dir)
 			cache[dir] = pkg
 		}
 		switch endpoint.Kind {
-		case "act", "action":
+		case gwdkir.EndpointAction:
 			bindings = append(bindings, bindStandaloneAction(endpoint, pkg))
-		case "api":
+		case gwdkir.EndpointAPI:
 			bindings = append(bindings, bindStandaloneAPI(endpoint, pkg))
 		}
 	}
@@ -156,12 +159,8 @@ func bindLoadFromPackage(page gwdkir.Page, functionName string, pkg featurePacka
 	return binding
 }
 
-func bindStandaloneAction(endpoint gwdkir.GoEndpoint, pkg featurePackage) source.BackendBinding {
-	method := endpoint.Method
-	if method == "" {
-		method = "POST"
-	}
-	return bindActionEndpoint(baseStandaloneBackendBinding(endpoint, actionHandlerKind, method, pkg), pkg)
+func bindStandaloneAction(endpoint gwdkir.Endpoint, pkg featurePackage) source.BackendBinding {
+	return bindActionEndpoint(baseStandaloneBackendBinding(endpoint, actionHandlerKind, endpoint.Method, pkg), pkg)
 }
 
 func bindActionEndpoint(binding source.BackendBinding, pkg featurePackage) source.BackendBinding {
@@ -193,12 +192,8 @@ func bindActionEndpoint(binding source.BackendBinding, pkg featurePackage) sourc
 	return binding
 }
 
-func bindStandaloneAPI(endpoint gwdkir.GoEndpoint, pkg featurePackage) source.BackendBinding {
-	method := endpoint.Method
-	if method == "" {
-		method = "GET"
-	}
-	return bindAPIEndpoint(baseStandaloneBackendBinding(endpoint, apiHandlerKind, method, pkg), pkg)
+func bindStandaloneAPI(endpoint gwdkir.Endpoint, pkg featurePackage) source.BackendBinding {
+	return bindAPIEndpoint(baseStandaloneBackendBinding(endpoint, apiHandlerKind, endpoint.Method, pkg), pkg)
 }
 
 func bindAPIEndpoint(binding source.BackendBinding, pkg featurePackage) source.BackendBinding {
@@ -315,18 +310,18 @@ func baseBackendBinding(page gwdkir.Page, kind, blockName, method, route string,
 	}
 }
 
-func baseStandaloneBackendBinding(endpoint gwdkir.GoEndpoint, kind, method string, pkg featurePackage) source.BackendBinding {
+func baseStandaloneBackendBinding(endpoint gwdkir.Endpoint, kind, method string, pkg featurePackage) source.BackendBinding {
 	return source.BackendBinding{
 		Kind:         kind,
-		PageID:       standaloneEndpointPageID(endpoint.Package, endpoint.Name),
-		Source:       endpoint.Source,
+		PageID:       endpoint.PageID,
+		Source:       endpoint.SourceFile,
 		Span:         endpoint.Span,
-		BlockName:    endpoint.Name,
+		BlockName:    endpoint.Symbol,
 		Method:       method,
-		Route:        endpoint.Route,
+		Route:        endpoint.Path,
 		ImportPath:   pkg.ImportPath,
 		PackageName:  bindingPackageName(pkg.Name, endpoint.Package),
-		FunctionName: endpoint.Name,
+		FunctionName: endpoint.Symbol,
 		Status:       source.BackendBindingMissing,
 	}
 }