Section 45: Macros and Metaprogramming¶

TECHSPEC-45 — Section 45 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Purpose¶

Metaprogramming allows programs to generate or transform code. It can reduce repetition, but unrestricted code generation creates serious risks for correctness, security, diagnostics, and reproducibility.

The initial language should avoid general-purpose macros.

2. MVP Policy¶

No user-defined macros or arbitrary source rewriting are required for the MVP.

Reusable abstractions should first be expressed through functions, generics, interfaces, and compile-time constants.

3. Future Macro Model¶

If macros are introduced, they should: - Operate on structured syntax trees rather than raw text where possible. - Declare the syntax they accept and produce. - Be deterministic. - Run in a restricted compile-time environment. - Have explicit resource limits. - Preserve source-location information. - Produce inspectable expansion output.

4. Hygiene and Name Resolution¶

Generated identifiers must not accidentally capture or overwrite names in the caller's scope.

The specification must define hygienic name handling, explicit capture mechanisms if any, visibility, and collision diagnostics.

5. Effects and Permissions¶

Macro expansion must not have unrestricted filesystem, network, process, database, or environment access.

Any permitted external input must be explicit, permissioned, recorded, and included in reproducibility metadata.

6. Expansion Validation¶

Generated code must pass the same parsing, type, contract, effect, permission, and safety checks as handwritten code.

A macro's successful expansion does not prove the generated program correct.

7. Diagnostics¶

Diagnostics must identify: - The macro invocation. - The macro definition and version. - The generated source location. - The expansion path. - The original source location where available.

Agents must be able to inspect expanded code.

8. Reproducibility and Supply Chain¶

Macro versions and inputs must be locked. Build records must identify the exact macro implementation and expansion output hash.

9. Security¶

Macro execution is code execution during compilation. It must be sandboxed and resource-limited. A macro must not gain permissions merely because the compiler runs it.

10. Design Goal¶

Metaprogramming must not create a hidden language inside the language. Generated code remains subject to the complete ordinary verification pipeline.

Source file: TECHSPEC-45.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.