Reflection & Metadata

1. Abstract

This RFC defines Aura’s attributes (annotations) and metadata retention model for compile-time tooling, derives, and optional runtime reflection. v1 favors pay-as-you-go metadata (not full Java-style always-on reflection) to keep single binaries lean while enabling serializers, test discovery, and DI-like libraries later—without putting frameworks in core.

2. Motivation

2.1 Problem statement

Derives, tests, and serializers need a uniform attribute system. Full runtime reflection on every type bloats binaries and hurts optimization; zero reflection blocks ecosystem patterns.

2.2 Why now

Macros (RFC-010), testing (RFC-011), and compiler emission depend on attribute grammar and retention.

2.3 Success metrics

3. Goals

• Unified attribute syntax on declarations and parameters.
• Retention policies: source / binary / runtime.
• Opt-in runtime type info (TypeId, members) for annotated types.
• Hooks for derive macros.

4. Non-goals

• Full dynamic invoke on every method of every class by default.
• Java classpath scanning of the world.
• Runtime code generation / JIT of new classes in v1.

5. Prior art & alternatives

6. Design

6.1 Overview

@attr(...)  on decl
    → compiler front records Attribute
    → expand derives ([RFC-010](/rfc/010))
    → emit metadata per retention
    → optional runtime APIs in std.reflect

6.2 Attribute syntax

@test
@derive(Equals, Hash)
@deprecated("use NewApi", since = "0.2")
@json(name = "user_id")
fun foo(@notNull x: String) { }

• Attributes are @Name or @Name(args).
• Args: positional and/or named literals / simple consts.
• Repeatable attributes only if declared repeatable.
• Unknown attributes are a hard compile error (builtins + declared attribute types only).

6.3 Attribute declaration

@Attr(retention = Runtime, targets = [Class, Fun])
class JsonName(val name: String)

Or simpler v1: built-in set + user attributes as classes marked @attribute.

6.4 Retention

Default for user attrs: Binary (available to tools/dependents without runtime bloat). Runtime requires explicit opt-in.

6.5 Built-in attributes (alpha vocabulary)

The current names and implementation status are tracked in docs/api/compiler-alpha.md. Reserved names are accepted only after their parser/sema phase is enabled; until then they must produce an explicit unsupported diagnostic rather than being silently ignored.

6.6 Runtime reflection API (sketch)

package std.reflect

class Type {
  fun name(): String
  fun methods(): Array<Method>
  fun fields(): Array<Field>
  // ...
}

fun typeOf<T>(): Type
fun typeIdOf<T>(): TypeId

Constraints:

• Only types with runtime metadata; others → error or limited info.
• Visibility: public members only by default; non-pub requires same-module or privileged API (if ever).
• Generics: may show raw class + type args if reified/recorded; mono instances may collapse—document honestly.

6.7 Interaction with monomorphization

• Concrete mono functions need not all appear in reflection.
• Class metadata describes the class template; type arguments recorded when retention requests it.

6.8 Examples

@derive(Debug)
@reflect  // opt into runtime metadata
class User(
  @json(name = "id") val id: Long,
  val email: String,
)

6.9 Error model / edge cases

6.10 Compatibility & migration

• Adding @deprecated is non-breaking.
• Changing retention of a public attribute type may be breaking for consumers.
• Metadata format versioned in binary.

7. Open questions

8. Rationale & trade-offs

Pay-as-you-go metadata protects single-binary size and optimization. Attributes unify derives, tests, and future serializers. Limited reflection avoids building a second dynamic language on top of Aura. Cost: less “magic” than Java enterprise stacks—acceptable for core scope.

9. Unresolved / future work

• Runtime invocation of reflected methods remains outside v1; type identity, opt-in type kinds, and public member metadata are compiler-backed
• Annotation processors beyond macros
• Source generators pipeline

10. Security & safety considerations

• Reflection must not silently pierce private across trust boundaries.
• Runtime metadata can leak class structure—document for security-sensitive apps; provide strip flags.
• Untrusted attributes from dependencies run only as compile-time macros under sandbox (RFC-010), not arbitrary runtime code.

11. Implementation plan (optional)

11.1 Implemented compiler boundary

The current compiler implements the normalized attribute metadata boundary. CheckedFile.attribute_metadata carries declaration, target, name, normalized arguments, retention, and source span. Built-in and registered host macro/derive expansion is recorded in CheckedFile.expansions with its phase, invocation span, and generated span.

Generated C exposes Binary/Runtime entries through a versioned read-only table: AURA_METADATA_ABI_VERSION is 1, with accessors aura_generated_attribute_metadata and aura_generated_expansion_metadata. Source-retained attributes remain compiler/tooling metadata and are deliberately not copied into the binary table.

12. References

• RFC-001, RFC-002, RFC-004, RFC-010, RFC-011
• Java retention policies; Rust attribute model

Changelog