Section 44: Annotations, Attributes, and Metadata¶

TECHSPEC-44 — Section 44 · 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¶

Annotations attach structured metadata to declarations. They may guide compiler checks, documentation generation, tooling, or runtime behavior when explicitly supported.

Annotations must not create hidden semantics that an agent cannot inspect.

2. Syntax¶

A preliminary syntax is:

@deprecated("Use fetchRecord instead")
FUNCTION loadRecord(id: Integer) -> Result<Record, LoadError>
    ...

The final grammar and placement rules remain to be specified.

3. Annotation Categories¶

Potential categories include: - Compiler directives. - Deprecation notices. - Documentation metadata. - Test and verification metadata. - Serialization metadata. - Runtime inspection metadata. - Security classification metadata.

Each category must define its permitted locations and effects.

4. Declaration and Validation¶

Every recognized annotation must have: - A defined name. - A declared set of parameters. - Parameter types and validation rules. - Defined compiler or runtime meaning. - Version compatibility rules. - Diagnostics for invalid use.

Unknown annotations must not be silently treated as trusted compiler instructions. Depending on module policy, they must be rejected or preserved as inert metadata.

5. No Hidden Guarantees¶

Annotations such as @verified, @safe, or @pure cannot establish the property they name.

The compiler must derive evidence through the relevant analysis, checks, tests, or proof process. Metadata may identify a requirement or request an analysis, but it is not evidence by itself.

6. Third-Party Annotations¶

Third-party annotations must be namespaced and versioned. They must not override core language rules or grant permissions.

Annotation processors, if introduced, must run in a restricted environment with declared inputs, outputs, and resource limits.

7. Runtime Metadata¶

Only annotations explicitly designated for runtime retention are included in runtime metadata.

The specification must define: - Retention policy. - Visibility. - Serialization behavior. - Whether metadata can be modified. - Resource and performance costs.

8. Verification¶

Build reports identify annotations that affected compilation, the checks they requested, and the actual evidence produced.

9. MVP Scope¶

The MVP may support a small set of built-in annotations, such as deprecation and documentation metadata. User-defined processors are deferred.

10. Design Goal¶

Annotations provide inspectable metadata. They must never become a way to bypass the type system, contracts, permissions, or verification rules.

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