Define and enforce the v1 core versus optional product boundaries

[cssbruno]

Priority

High / architectural

Context

GoWDK currently ships a coordinated language/compiler, generated net/http runtime, static and request-time rendering, endpoint generation, browser runtime, WASM islands, LSP and VS Code tooling, auth and DB helpers, contracts/workers, realtime transports, observability, security audit/SARIF, playground execution, Docker output, and deployment recipes.

A monorepo can contain all of these, but they currently share portions of the same config, compiler IR, CLI namespace, generated-app feature matrix, documentation contract, and release line.

Problem

Without an explicit product boundary, every additional subsystem can expand the compatibility surface of the compiler and generated runtime. Optional tooling can become a de facto core concern because it adds fields to gowdk.Config, gwdkir.Program, application planning, CLI orchestration, generated code, or mandatory CI/release gates.

This increases stabilization cost and makes it difficult to answer:

• what must be stable for GoWDK 1.0;
• what is bundled but optional;
• what is an independently evolving integration/tool;
• which packages and schemas may change together;
• which capabilities are allowed to affect generated applications that do not use them.

Proposed direction

Write an ADR that classifies the repository into explicit product/stability boundaries, for example:

1. Core language/compiler — .gwdk syntax, AST/semantic analysis, diagnostics, validated plans, static/server rendering, endpoint adapter generation.
2. Core generated runtime — minimal net/http serving and the runtime contracts required by generated applications.
3. Bundled optional capabilities — opt-in packages that may integrate with core through narrow typed plans/hooks but are absent from unused output.
4. Dependency-isolated adapters — nested modules for frameworks, brokers, transports, exporters, and external tools.
5. Tooling products — LSP/editor, audit/reporting, playground, deployment recipe generators, and other workflows with their own stability and release expectations.

The ADR should define which boundary owns configuration, semantic IR, application-plan fields, runtime dependencies, versioning, compatibility promises, and release gates.

Acceptance criteria

• A v1 core definition identifies the minimum language, compiler, generated-runtime, and deployment behavior that must stabilize before 1.0.
• Every top-level package family, CLI command family, addon/integration, and generated artifact is mapped to a named boundary and stability level.
• Rules state which capabilities may add fields to public gowdk.Config, shared semantic IR, and the canonical application plan.
• Optional capabilities do not add runtime imports, generated declarations, assets, or startup behavior when unused.
• Dependency and module boundaries match the classification; third-party adapters remain isolated from the root graph.
• Release/version policy says which products version together and which may evolve independently.
• CI distinguishes core merge gates from optional/scheduled/release-specific matrices.
• New cross-cutting feature categories require an ADR explaining ownership and compatibility impact.
• Roadmap, architecture, addon, generated-output, and release documentation use the same classification.
• Existing capabilities that do not fit the boundary receive an explicit migration, extraction, or intentionally-bundled decision.

Related

• Introduce phase-typed validated program and application plan boundaries #667 introduces phase-typed validated program and application-plan boundaries.
• Split gwdkir.Program into semantic IR and target-specific plans #668 separates semantic IR from target-specific plans.
• Separate built-in compiler features from executable addon extensions #670 separates built-in features from executable extensions.
• Extract shared project compilation orchestration from the CLI #671 extracts shared project compilation orchestration from the CLI.