Module annotation_context 

Annotation context and decorator registry

This module provides the infrastructure for Shape’s annotation system.

Design Philosophy

Annotations in Shape are fully defined in Shape stdlib, not hardcoded in Rust. This module provides the generic runtime primitives that annotation lifecycle hooks use.

Annotation Lifecycle Hooks

Annotations can define handlers for different lifecycle events:

• on_define(fn, ctx) - Called when function is first defined
• before(fn, args, ctx) - Called before each function invocation
• after(fn, args, result, ctx) - Called after each function invocation
• metadata() - Static metadata for tooling and optimization

Example (stdlib/finance/annotations/pattern.shape)

annotation pattern() {
    on_define(fn, ctx) {
        ctx.registry("patterns").set(fn.name, fn);
    }
    metadata() { return { is_pattern: true }; }
}

Runtime Primitives

The AnnotationContext provides domain-agnostic primitives:

• cache - Key-value cache for memoization
• state - Per-annotation persistent state
• registry(name) - Named registries (patterns, strategies, features, etc.)
• emit(event, data) - Event emission for alerts, logging
• data - Data range manipulation (extend/restore for warmup)

Structs

AnnotationCache

Key-value cache for annotation memoization

AnnotationContext

Context passed to annotation lifecycle hooks

AnnotationRegistry

Registry for annotation definitions

AnnotationState

Per-annotation persistent state

CacheEntry

DataRangeState

State for data range manipulation (used by @warmup)

EmittedEvent

An emitted event from an annotation handler

NamedRegistry

A named registry for storing values (functions, patterns, etc.)