capabilities

A capability is an explicit, machine-checkable contract an operator opts into. The compiler reads an operator’s capabilities to decide whether optimization passes (init elision, kernel-body interning, static scheduling, and — later — fusion) may be applied to it. The default is :attr:OpCapability.NONE, meaning an operator is treated as fully opaque: emitted inline, never interned, never statically reordered. This keeps brand-new operators correct with zero declarations; optimizations are strictly opt-in (“buy-in”) per operator.

See docs-maintainers/rfcs/0003-operator-capabilities-interning.md for the full design.

Stage 1 (this module) introduces the vocabulary and a derivation that maps the pre-existing ad-hoc seams (has_init and the shared_*_helpers methods) onto capability flags. It deliberately does not change any emitted code.

OpCapability()

Optimization contracts an operator may declare.

Flags compose with |. The base operator declares :attr:NONE; subclasses widen the set as they satisfy each contract.

NONE = 0

No declared contract. The operator is emitted inline, retains its per-instance _init, is never interned, and is never statically reordered. Always correct; the safe default.

STATELESS = enum.auto()

The operator emits no per-instance _init and no mutable file-scope (non-const) storage. Generalizes has_init is False.

DESCRIPTOR_DRIVEN = enum.auto()

The operator’s _run body is a pure function of a single const per-node descriptor plus ctx->tensor_ptrs. It bakes no absolute addresses and holds no mutable state. Eligible for kernel-body interning and direct static scheduling.

SHARED_KERNEL = enum.auto()

The operator routes its _run body through a single signature-keyed shared runtime helper (emitted once) rather than an inlined per-node body. Generalizes a non-empty shared_kernel_helpers / shared_activation_helpers.

STATIC_SCHEDULABLE = enum.auto()

The operator is safe to invoke via a direct static call site (no requirement for the runtime function-pointer table).

PURE = enum.auto()

The operator has no side effects beyond writing its output tensors. Reserved for future fusion/scheduling passes.

REORDERABLE = enum.auto()

The operator’s schedule position is flexible within its data dependencies. Reserved for future scheduling passes.