Skip to content

Section 37: Reflection, Introspection, and Dynamic Behavior

TECHSPEC-37 — Section 37 · 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. Reflection Philosophy

Reflection allows programs to inspect information about their own structure and behavior at runtime.

The language should support useful introspection without allowing dynamic behavior to bypass its type system, contracts, permissions, or verification rules.

Dynamic flexibility must not silently weaken established guarantees.

2. Supported Introspection

The standard library should provide controlled access to:

  • Module information.
  • Type definitions.
  • Function signatures.
  • Parameter types.
  • Return types.
  • Declared contracts.
  • Declared effects.
  • Permissions.
  • Runtime type information.
  • Verification metadata.

Rules: - Introspection must expose only information permitted by the applicable visibility and security rules. - Reflected information must accurately represent the compiled program. - Missing metadata must be reported explicitly. - Runtime information must not be presented as compile-time proof.

3. Type Introspection

Programs may inspect the type of a value.

Example:

LET valueType: TypeInfo = Reflection.typeOf(value)

Rules: - Type information must correspond to the actual runtime value. - Type inspection must not silently convert values. - Generic type information must follow documented preservation rules. - Runtime type inspection must not bypass static type restrictions. - Unknown or unavailable type information must be represented explicitly.

4. Function Introspection

Programs may inspect function metadata.

Available information may include: - Function name. - Parameter names and types. - Return type. - Preconditions. - Postconditions. - Declared effects. - Required permissions. - Failure types.

Rules: - Function metadata must reflect the compiled declaration. - Introspection must not expose private implementation details without permission. - A declared contract must not be represented as a proven contract. - Verification evidence must retain its actual verification status.

5. Dynamic Invocation

The language may support controlled dynamic function invocation.

Example:

LET result = Reflection.invoke(
    functionReference,
    arguments
)

Rules: - Dynamic invocation must validate argument types. - Return types must remain explicit. - Contract checks must still apply. - Required permissions must still be enforced. - Side effects must remain visible. - Invocation failures must be represented explicitly. - Dynamic invocation must not bypass access restrictions.

6. Dynamic Loading

Dynamic module loading may be supported through a controlled runtime API.

Rules: - Loaded modules must have identifiable origins. - Module integrity must be checked where applicable. - Dependencies must be resolved explicitly. - Permissions must be reviewed before execution. - Loaded code must not automatically inherit unrestricted capabilities. - Compatibility must be checked against the active language and runtime versions. - Loading a module must not imply that its behavior has been verified.

7. Dynamic Values and Type Safety

The language may provide a restricted dynamic value type for interoperability.

Proposed type:

DynamicValue

Rules: - Dynamic values must not silently become statically typed values. - Conversion must require explicit validation. - Invalid conversions must produce structured errors. - Dynamic operations must retain observable failure behavior. - Use of dynamic values should be visible in verification reports. - Dynamic behavior must not silently bypass contracts or ownership rules.

8. Reflection Permissions

Reflection may expose information that is sensitive or security-relevant.

Rules: - Access to private metadata must require appropriate permission. - Dynamic loading requires explicit authorization. - Dynamic invocation must respect function visibility and permissions. - Reflection must not expose secret values through metadata. - Dependencies must not gain reflection privileges automatically.

9. Compiler and Runtime Responsibilities

The compiler and runtime must: - Generate accurate runtime metadata. - Preserve declared types and function signatures. - Enforce visibility restrictions. - Validate dynamic invocation. - Preserve contracts and effects during reflection. - Identify dynamic operations in verification reports. - Prevent reflection from bypassing language safety guarantees.

10. Verification Limitations

Dynamic behavior can make static analysis more difficult.

Verification reports must distinguish: - Structure known at compile time. - Structure inspected at runtime. - Dynamic behavior validated. - Dynamic behavior executed. - Properties that remain unknown or unverified.

Successful introspection does not prove that inspected code is correct or safe.

11. Design Goal

An AI agent must be able to inspect program structure and perform controlled dynamic operations without losing the guarantees established by the language's type, contract, ownership, and permission systems.

Reflection must provide visibility into a program, not an escape hatch from its rules.

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