[Language] Define a v1 language budget before adding more embedded mini-language features

[cssbruno]

Priority

Medium-high — stabilization, tooling completeness, and long-term language maintainability.

Context

.gwdk sources now combine or reference several mini-languages and host languages:

• metadata declarations;
• route syntax;
• build records and build expressions;
• paths records;
• view markup;
• client expressions/statements;
• server declarations;
• inline CSS;
• JavaScript/TypeScript asset declarations;
• inline and targeted Go blocks;
• addon-defined Go-block targets.

The build-expression surface already includes arithmetic, boolean logic, comparisons, lists, objects, comprehensions, reductions, field/index access, and deterministic transform rules.

Problem

Every new source-language feature multiplies the amount of parser, formatter, diagnostics, IR, LSP, conformance, documentation, and generated-output behavior that must stay consistent.

The current language direction risks creating several partial languages inside one file instead of keeping computation and integration in ordinary Go packages.

Specific risks:

1. Build expressions duplicate parts of Go while having separate semantics.
2. TypeScript transform-only behavior can look like TypeScript support without providing normal type-checking guarantees.
3. Inline Go blocks reduce ordinary editor/toolchain ergonomics compared with normal .go files.
4. Feature growth makes v1 compatibility harder because syntax and semantics stabilize before boundaries are clear.

Proposed direction

Define a v1 language budget and feature gate anything outside it.

A conservative v1 budget could be:

• declarative package/page/component/layout structure;
• routes, guards, metadata, and explicit bindings;
• markup with safe interpolation;
• minimal display expressions;
• computation in ordinary Go functions and packages;
• addon integrations through explicit versioned contracts rather than arbitrary source-language growth.

Any new expression or block feature should require a full contract covering grammar, parser, formatter, diagnostics, IR, LSP, docs, conformance corpus, and generated-output behavior.

Acceptance criteria

• A v1 language budget document separates core syntax, experimental syntax, and planned syntax.
• New syntax proposals require a checklist covering parser/formatter/diagnostics/IR/LSP/docs/tests.
• Existing build-expression features are classified as core, experimental, or migration-only.
• Computation that should live in Go is explicitly documented and diagnosed where possible.
• TypeScript support is documented as transform-only unless full type-checking is added.
• CI enforces that docs and conformance corpus identify experimental syntax.

Related

• Define and enforce the v1 core versus optional product boundaries #677 — Define and enforce the v1 core versus optional product boundaries
• Move semantic validation and asset identity planning out of internal/parser #673 — Move semantic validation and asset identity planning out of internal/parser