pub fn class_static_instance(
class_template: ClassTemplateId,
) -> (InstanceId, TemplateKey)Expand description
Classes plan Task 4 (docs/superpowers/plans/2026-10-03-classes.md, LRM
8.9): the (InstanceId, TemplateKey) pair [StateEngine:: allocate_class_static_singletons] uses for one ClassTemplateId’s
static-property singleton segment — a deterministic, pure function of
class_template alone (never re-derived differently by two call sites),
so every caller (that one allocate_instance call, and every later
foreign-slot reference a Class::static_prop/obj.static_prop access
mints) agrees on exactly which synthetic instance a given class
template’s statics live in.
Not defined in netlist:: despite otherwise matching
crate::netlist::ClassTemplateId’s own “frontend-independent, needed
by STATE” placement rationale: netlist_dedup_invariants.rs’s NL-018
guard (codegen_never_needs_a_second_dedup_key_derivation) source-scans
exactly five netlist:: files for any function whose signature returns a
TemplateKey, asserting the only name that ever does is dedup_key —
protecting that module’s own monopoly on a REAL elaborated module
instance’s dedup key. This function mints a key for a wholly different,
synthetic thing (a class-static singleton has no Definition/dedup
identity of its own), the same way sv-sim-bin::run’s own package/bank
synthetic TemplateKeys are minted inline there, outside netlist::
entirely, rather than through a second netlist:: function — this one
lives next to its one real caller for the identical reason.
Reserved id-range convention, matching the one sv-sim-bin::run
already established for its own synthetic instances rather than
inventing a second one: a real elaborated InstanceId is bump-allocated
from 0; a design’s packages each get one counting DOWN from u32::MAX;
the net-resolution “bank” reserves the single id u32::MAX - (1 << 20).
Class-static segments reserve the next block down again, counting from
u32::MAX - (2 << 20) — disjoint from both of those by the same
generous-headroom convention (not a mathematically tight partition: no
real design instantiates anywhere near 2^20 packages, let alone that
many packages and that many distinct class templates with static
properties at once), so a TemplateKey.definition minted here can never
collide with one a real module Definition, a package, or the bank ever
uses.
Panics (rather than silently wrapping into collision) if class_template’s
own dense id would exhaust that reserved block — expect-style, never a
wrapping/saturating fallback, because a wrapped id would silently alias a
different class template’s segment: exactly the “gate that can never
fail” this plan’s own correctness posture forbids. 2^20 class templates
with static properties is not a real design this implementation
supports; it is a defensive bound stated loudly rather than left to wrap.