Code Generation Vocabulary

This appendix defines the vocabulary used throughout sigil-stitch. The architecture overview describes how these concepts flow through the implementation, while Declaration Specs and Language Lowering records their ownership boundaries. Versioned exceptions are catalogued in 0.6.8 Legacy Compatibility and Migration.

Declaration Intent

Declaration spec

A structured, language-independent request for a declaration such as a type, function, field, property, or variant. It records semantic intent, not target-language token placement or spelling.

Capability

A semantic feature that a target language may support, require, or reject for a particular declaration kind and context. A capability describes what can be represented; it is not a switch for target grammar.

Language adapter

The target-specific boundary that decides whether declaration intent is representable and converts accepted intent into target-language structure. It owns detailed declaration grammar such as keyword order, punctuation, and metadata placement.

Target grammar

The language-specific keyword order, punctuation, precedence, escaping, and metadata placement used to express accepted declaration intent. Target grammar belongs to the language adapter; it is not a general format abstraction or a capability.

Function intent

A complete function declaration classified by its role and context before target-language validation. It remains semantic and does not contain a partially rendered signature.

Type intent

One complete type declaration before target-language validation. TypeIntent exposes its kind, semantic modifiers, documentation, annotations, type parameters and constraints, type relationships, primary-constructor parameters, variants, and member families without choosing their source order or spelling.

Closed sum

A type declaration whose complete ordered set of named cases is part of its semantic intent. Each case is unit-shaped or carries positional or named record data. A closed sum may contain no cases: the empty sum is uninhabited. The declaration does not prescribe whether a target uses an enum, algebraic data type, sealed root with generated case declarations, nested declarations, or sibling declarations.

The zero-case form declares a named uninhabited type. A particular target may have a Never or bottom type with the same absence of values, but that is a type-expression or subtype concept rather than this caller-named declaration. The shared model does not equate them; a target may reuse such a type only if it preserves the declaration’s name and every valid use position.

Closed-sum intent is not a sealed modifier or an enum-formatting option. A case carrying a TypeName owns that payload relationship; it does not assert that an already-declared type is a nominal subtype of the sum root.

Validated type

A crate-constructed view whose type-level intent and every child declaration have passed intrinsic, capability, and target-local validation against the same adapter. ValidatedType exposes child declarations only through their validated wrappers. The adapter lowers the complete declaration and chooses whether it produces one block or several; every returned block must be non-empty.

Type name

A semantic type reference. It remains structured until one selected language adapter lowers the complete value before import collection. A TypeName may contain other type names, but it never contains a language-neutral choice of punctuation, precedence, or layout. Primitive and Raw are explicit target-aware leaves rather than a general type grammar.

Structured source block

A CodeBlock is the shared Rust container for source nodes associated with one selected target. Its Rust type is language-agnostic so declaration lowerers, rewrite, import collection, and rendering can compose it, but its literal content and structure are not a portable cross-language program.

Generic binding and kind expression

A declaration-owned name with a single, pack, or lifetime domain, optional kind intent, and supplied bounds. GenericParamSpec records the binding; GenericParamView borrows the owner’s complete ordered sequence. Uses refer to names without a shared scope resolver. The target compiler owns inference and instantiation.

KindExpr records Type, a named kind, or a constructor’s parameter and result kinds. Declaration lowering owns representation or rejection. Named kinds are not inferred; legacy raw binder suffixes are not modern kind expressions.

Type application and expansion pattern

Application of a supplied type-level base to ordered arguments. An expansion retains its complete pattern, including every referenced pack. The library does not evaluate the pattern, solve its arity, or reinterpret a tuple as an argument list.

Callable parameter sequence

Ordered scalar slots, repeated-element segments, and complete expansion patterns. Optional presence belongs to a scalar slot and differs from an optional value. Labels and ordering restrictions belong to the selected language, not to a shared rest-parameter grammar.

String literal type

A type inhabited by exactly one decoded string value. TypeName::StringLiteral stores the value without target quotes or escapes. The language adapter either lowers it exactly or rejects it; several string literal types compose through TypeName::Union, not a string-enum or literal-set abstraction.

Field sequence

The ordered fields owned by one type declaration or one record payload, considered together in their semantic context. A language adapter handles the complete sequence so it can validate collisions and own sequence-level grammar.

Field context

The semantic role in which a field sequence appears: direct emission, ordinary type members, an ordinary variant record payload, or a closed-sum case record payload. Keeping the payload contexts distinct prevents support for generated closed-sum cases from widening ordinary enum behavior. A field context identifies representability; it does not prescribe placement, punctuation, or separators. The Direct(DeclarationContext) payload retains only the pre-0.6.8 direct-emission placement input. It is a narrow compatibility exception, not a reusable placement or target-grammar model.

Property intent

One computed property with a value type, read and/or write behavior, semantic modifiers, documentation, and attributes before target-language validation. It does not choose accessor syntax or a field-style representation.

Property context

The semantic role in which one computed property appears: direct emission or a member of an owning TypeKind. The Direct(DeclarationContext) payload exists only to retain the pre-0.6.8 public emission facade; it is not a general accessor-placement model.

Type members intent

A validation-only view of one owning type’s semantic fields, computed properties, and explicit methods. TypeMembersIntent exists for relationships that cannot be checked within one member family, such as target-derived name collisions. It contains no target grammar, has no validated wrapper, and does not participate in lowering. It is not a sequence-level replacement for PropertyIntent. Each adapter defines its own emitted namespaces: a field/property pair collides in TypeScript, Kotlin, Swift, and Scala only when both declarations occupy the same target-local namespace, while PHP properties instead derive case-insensitive accessor-method names.

Read accessor and write accessor

Semantic read and write behavior supplied by a property’s getter and setter bodies. A language adapter may express that behavior as accessor declarations, a computed-property body, or target-local methods. The capability names do not prescribe getter keywords, setter placement, or surrounding grammar.

Optional presence

A field semantic in which the containing value may omit the field entirely. FieldSpec::is_optional() requests this meaning. It is distinct from an optional value.

Optional value

A value semantic in which a present field can carry the target language’s absence or null representation. TypeName::Optional expresses this meaning; it does not make the field itself omissible.

Variant sequence

The ordered variants owned by one type declaration, together with the semantic presence of non-variant members. A variant lowerer handles the sequence as a whole; the owning type lowerer chooses where that sequence appears relative to other member families. Non-variant members include fields, properties, methods, embedded types, and opaque members.

For a closed sum, an empty sequence is meaningful rather than missing input: it declares an empty sum. Ordinary value-enum validation remains independent and may continue to require at least one member for a particular target.

Variant Data

Discriminant

An explicit value that identifies an enum member in a representation where members map to values. It is distinct from an expression passed to an enum constructor.

Constructor arguments

Expressions passed when an enum entry constructs an instance of its declaring enum type. They are values evaluated at the declaration site, not types carried by a sum-type case.

Positional payload

Types carried in order by a sum-type constructor or enum case. The payload has positions but no field names.

Record payload

Named, typed fields carried by a sum-type constructor or enum case. These are case-local payload fields, not ordinary members of the enclosing type.

Transformation Boundaries

Source-tree rewrite

One language-local structural correction is applied exactly once to each source CodeBlock after declaration lowering and before type-name lowering. It is for target source fixups that require a tree-level view, such as joining a Go IIFE close to its invocation. It does not own declaration grammar, type grammar, validation, or final layout. Raw content, raw import metadata, and blocks returned by type-name lowering are not source-rewrite inputs.

Type-name lowering

The fallible conversion of one complete TypeName into a non-empty CodeBlock before import collection. The selected language adapter owns representability, precedence, punctuation, string escaping, and any target-derived type imports. A successful lowering block may retain only terminal import-aware type references; unresolved compound type names fail closed.

Import conflict set

The complete peer set of semantic imports that request the same local binding within one file. Exact explicit bindings are hard constraints; preferred aliases and natural names are soft requests. The resolver assigns every peer atomically and does not receive an incoming import, current owner, winner/loser pair, or mutable claim table.

sigil-stitch