Skip to main content

Valenar Docs Codegen Rules

This page explains how Valenar docs should describe Content/, Generated/, and the future compiler without inventing syntax, ownership, or provenance.

Current Source Of Truth Split​

Valenar currently has two parallel surfaces for game definitions:

  • examples/valenar/Content/*.secs is the future designer-facing source of truth.
  • examples/valenar/Generated/*.cs is the current executable source of truth.

Generated/ files are hand-written stand-ins that match the lowering shape the future compiler is expected to emit.

What Docs May Claim​

Docs may say all of the following:

  • Generated/ is hand-written until the compiler exists.
  • Content/ expresses intended source shape for the future compiler.
  • The future compiler must lower to the same broad patterns used in the current Generated/ tree.
  • examples/valenar/Generated/SecsModule.cs is the single registration entry point for current generated stand-ins.

Docs must not say any of the following unless a committed design doc proves it:

  • that a nonexistent keyword or clause is committed source syntax
  • that candidate_builder, with builder, or from collection ... with builder ... are committed or reserved .secs syntax
  • that a stand-in file came from a real compiler run
  • that a fabricated .secs file exists to justify provenance
  • that fabricated provenance, source links, or source relationships are acceptable documentation shortcuts
  • that runtime-only stand-ins are evidence of approved source syntax
  • that runtime helper names such as CandidateBuilderId, CandidateBuilderDelegate, or SelectorSource.FromCollection(...) are live .secs language forms

Live Behavior Vocabulary​

When docs describe behavior surfaces, use the live vocabulary from the current design docs:

  • activity
  • policy
  • on_action

Do not invent alternate behavior keywords or treat older placeholder words as committed syntax.

Generic SECS patterns stay: definition or data references, generic mechanic activities, and typed args. Valenar spell variants remain SpellDefinition data routed through one generic Activity_CastSpell, not one activity per spell.

Node or composed spellcrafting remains deferred proposal-only material unless a committed design doc says otherwise. Do not present it as live source syntax or canon.

Generated Stand-In Headers​

When a Generated/ file cites a source relationship, only these header shapes are valid:

  1. // Source: <relative-path-to-.secs-file>
  2. // auto-generated or // Source: auto-generated ...
  3. // Hand-written stand-in: no .secs source yet - runtime-only surface.

Docs should quote that third header exactly when explaining the bypass. Do not paraphrase it.

Patterns Docs Can Reference​

Generated files are expected to follow stable lowering patterns already present in the tree.

  • templates lower to static classes with contract helpers and registration
  • declarations live in Generated/Declarations.cs
  • ids and hashes live in Generated/Hashes.cs
  • systems, events, activities, and on-actions are registered through Generated/SecsModule.cs
  • reflection is not part of the expected generated shape

Documentation Rules​

  • Prefer committed docs under docs/design/ when describing language or lowering contracts.
  • Treat Generated/ as a current implementation mirror, not as independent language authority.
  • Treat Content/ as intent and design direction unless the runtime already depends on the matching generated stand-in.
  • If a runtime surface has no committed source syntax yet, say that directly. Do not fill the gap with invented .secs forms.