Vernac specification and contracts

This is the normative documentation for the 0.5.0 language revision. It is organized into language rules and feature contracts; both parts define the language. MUST/MUST NOT express requirements, SHOULD a recommendation, and MAY a permission. Examples illustrate rules; explicitly incomplete fragments require their surrounding model. Planned features are not guarantees.

The language reference is the usage-oriented overview. The grammar describes parsing, not the complete supported language: semantic resolution and feature contracts also constrain accepted programs.

Language foundations

• Namespaces and imports: source layout, identities and resolution.
• Domain field types and nullness: allowed types and optional values.

• Names and Unicode: identifiers, defaults and collisions.

• Ubiquitous language: term documentation and exact-name model associations.

Domain and application contracts

• Value objects
• Enum values
• Named collections
• Behavior
• Entities and aggregates
• Usecases
• Domain services
• Versioned modules: exports, compiled reuse, activation and independent histories.
• Events and listeners

Persistence and integration contracts

• PostgreSQL mapping
• Scalar representation limits
• Repository queries
• Pagination runtime foundation: offset/cursor queries and completed HTTP results.
• HTTP inbound adapters
• Server-rendered MVC adapters (0.5.0 development)
• Ports and adapters
• Adapter configuration
• Adapter DTOs and JSON
• Mappings
• REST declarations

• HTTP runtime and failures

• Domain diagram tooling: source/model projection and its limits.

Authority and maintenance

Each rule has one authoritative home. Tutorials explain it and references summarize it; they MUST NOT introduce contradictory defaults. contracts specifies observable APIs and runtime semantics; specification specifies cross-cutting language semantics. These are two sections of the same specification, not competing sources of truth.

Implementation notes and test results are evidence, not normative promises. When a contract and implementation disagree, investigate and correct the defect or explicitly revise the contract. Do not silently treat an old document, a parser production or a generated excerpt as a new supported feature.

See documentation maintenance and the release plan for remaining verification work.

Subsequent design work

SaaS policies and deeper cross-language IDE integration remain separately planned. The module completion record defines the delivered 0.4.0 scope.

The 0.5.0 shared Java implementation contract defines parameter nullability, external target resolution and overload identity across behavior, usecases, services, listeners and adapters.