alloc_phase.capacity

1/// Bindings gathers compile-time type coordinates and lifecycle phase bindings2/// separate from the source envelope. Fields include owner, default_limits,3/// seal, teardown, and source, which all default to null. Validation requires4/// owner to match the Owner type supplied to validateDeclaration. The5/// default_limits binding is required for application_default limit sources and6/// forbidden for caller limit sources, while seal and teardown bindings are7/// required for phase_static declarations. The optional source type is retained8/// as metadata but is not inspected by the validator. Envelope digests exclude9/// all bindings and premises, and the struct owns no heap memory or reference10/// counts.11pub const Bindings = struct {12    owner: ?type = null,13    default_limits: ?type = null,14    seal: ?PhaseBinding = null,15    teardown: ?PhaseBinding = null,16    source: ?type = null,17};

1/// ClaimSelector designates an external claim supporting a certified summary2/// premise through its id field. Validation confirms that the id string3/// satisfies the syntax of a canonical dotted identifier containing at least4/// two segments. The check verifies identifier syntax only and does not look up5/// or confirm the existence of the referenced claim.6pub const ClaimSelector = struct {7    id: []const u8,8};

1/// CoveredStorage describes a discrete memory region covered by an owner claim2/// through its id, lifetime, and detail fields. The id string must contain 1 to3/// 64 bytes, starting with a lowercase ASCII letter and followed only by4/// lowercase ASCII letters, digits, or underscores. Each id must be unique5/// within the containing covered list. The lifetime field holds a6/// StorageLifetime tag, and the detail string must contain 1 to 512 single-line7/// bytes without null bytes, carriage returns, or line feeds. The struct8/// borrows these slices without owning allocations or enforcing lifetimes at9/// runtime.10pub const CoveredStorage = struct {11    id: []const u8,12    lifetime: StorageLifetime,13    detail: []const u8,14};

1/// Declaration couples a SourceEnvelope specification with its corresponding2/// compile-time Bindings. The struct acts as a typed metadata container rather3/// than a runtime resource allocation. Calling validateDeclaration checks the4/// declaration against a specified Owner type, expected OwnerShape, and source5/// constraints, but validating a declaration does not verify the whole owner6/// shape by itself. Constructing or validating a declaration installs no7/// automatic runtime enforcement.8pub const Declaration = struct {9    source: SourceEnvelope,10    bindings: Bindings,11};

1/// EnvelopeView provides a structurally uniform representation of a2/// SourceEnvelope where the typed capacity specification is replaced by a3/// SpecView. The remaining borrowed metadata fields, including id, kind,4/// limit_source, storage, overload, risks, work, dependencies, and obligations,5/// remain identical. This view enables structural serialization and digest6/// computation without depending on semantic type coordinates. Slices7/// referenced by the view remain borrowed and are not owned by the view struct.8pub const EnvelopeView = struct {9    id: []const u8,10    kind: Kind,11    limit_source: LimitSource,12    storage: Storage,13    capacity: spec.View,14    overload: Overload,15    risks: Risks,16    work: ?Work = null,17    dependencies: []const []const u8 = &.{},18    obligations: []const Obligation,19};

1/// `Kind` specifies source classification as either `startup_static` or2/// `phase_static`. Validation of `phase_static` requires valid seal and3/// teardown bindings. In contrast, `startup_static` does not require or inspect4/// optional phase bindings in `validateBindings`. The tag describes a claim and5/// does not govern actual allocation behavior or enforce an operational6/// lifetime.7pub const Kind = enum {8    startup_static,9    phase_static,10};

1/// LimitSource indicates whether memory capacity limits originate from the2/// caller or from application defaults. Selecting caller forbids supplying a3/// default_limits selector binding. Selecting application_default requires4/// supplying a selector struct containing a public declaration member. The5/// declaration validator verifies that this selector struct exists, but it6/// checks no signature or value compatibility between that declaration and the7/// owner limits.8pub const LimitSource = enum {9    caller,10    application_default,11};

1/// Obligation pairs a claim-local identifier key with an ObligationRole tag.2/// The key string must contain 1 to 64 bytes, beginning with a lowercase ASCII3/// letter and containing only lowercase letters, digits, or underscores. The4/// source envelope accepts a list of 1 to 24 obligations, and every key must be5/// unique within that list. Validation mandates the capacity_model role in6/// every claim, the overload role unless overload is not applicable,7/// appropriate risk roles for witnessed risks, and the work_bound role when a8/// work equation is declared. Keys remain local to the enclosing claim rather9/// than resolving globally.10pub const Obligation = struct {11    key: []const u8,12    role: ObligationRole,13};

1/// ObligationRole classifies the evidentiary purpose of a named obligation2/// within a claim. Roles identify evidence requirements including3/// capacity_model, overload, work_bound, transitive_risk, foreign_risk, seal,4/// and teardown. Declaration validation enforces role presence rules for5/// selected source fields, requiring capacity_model for every claim, overload6/// unless overload handling is not applicable, work_bound when a work equation7/// is present, and matching risk roles when transitive or foreign risks are8/// witnessed. Assigning a role classifies the requirement within the9/// declaration but does not establish that evidence exists or that any test10/// passed.11pub const ObligationRole = enum {12    capacity_model,13    acquisition,14    initialization_failure,15    overload,16    seal,17    teardown,18    work_bound,19    transitive_risk,20    foreign_risk,21    integration,22    custom,23};

1/// ObligationSelector identifies a claim-local obligation that grounds a2/// theorem premise through its key field. Validation checks that the key is a3/// valid local identifier and that it matches an obligation declared in the4/// current source envelope. The check enforces no role restriction on the5/// targeted obligation and performs no evaluation of the theorem.6pub const ObligationSelector = struct {7    key: []const u8,8};

1/// `Overload` describes declared overload behavior through its `kind` and2/// `detail` fields, where `detail` identifies protected state. Full declaration3/// validation checks that `kind` is compatible with `OwnerShape` and verifies4/// that `detail` contains 1 to 512 bytes excluding NUL, LF, and CR characters.5/// Merely constructing the record validates nothing and installs no dynamic6/// policy.7pub const Overload = struct {8    kind: OverloadKind,9    detail: []const u8,10};

1/// OverloadKind defines the policy an owner follows when an operation exceeds2/// capacity. Compatibility depends on the storage source and shape of the3/// owner. Exact shapes accept reject_before_seal or not_applicable. For4/// rejecting shapes, allocator-backed owners accept reject_before_mutation,5/// replace, drop, or terminal, while caller-provisioned owners accept only6/// reject_before_mutation. The accompanying detail string describes which7/// internal state is protected, such as allowing submitted and rejected8/// counters to increment in a full fixture. Validation checks compatibility9/// between the enum tag and the owner shape without inspecting operation10/// bodies.11pub const OverloadKind = enum {12    reject_before_seal,13    reject_before_mutation,14    replace,15    drop,16    terminal,17    not_applicable,18};

1/// PhaseBinding associates a lifecycle transition with an implementation seam2/// and an evidentiary premise through its family and premise fields. Both3/// fields default to null, but validating a phase_static declaration requires4/// both to be present. The family field must be a selector struct containing a5/// public declaration member that resolves to a function. Validation does not6/// inspect the function signature or body, nor does it require the function to7/// match Owner.activate or Owner.deinit. The struct stores compile-time type8/// and premise descriptors rather than a runtime callable closure.9pub const PhaseBinding = struct {10    family: ?type = null,11    premise: ?Premise = null,12};

1/// Premise pairs a PremiseClass category with a PremiseAuthority variant to2/// justify a phase lifecycle binding. The validatePremise function checks that3/// the class and authority are mutually compatible, that selector identifiers4/// follow required canonical or local syntax, and that local theorem keys exist5/// within the source obligations. Validation confirms structural and syntactic6/// compatibility but produces no proof of the underlying fact.7pub const Premise = struct {8    class: PremiseClass,9    authority: PremiseAuthority,10};

1/// PremiseAuthority specifies the justifying source for a premise as a tagged2/// union over checker, theorem, certified_claim, and trusted variants. Each3/// variant carries its respective selector, except checker, which carries no4/// payload. The authority must pair with a compatible PremiseClass during5/// validation: checker requires checked_semantic_fact or checked_path_fact,6/// theorem requires theorem_domain, certified_claim requires certified_summary,7/// and trusted requires trusted_user, trusted_extern, or trusted_environment.8pub const PremiseAuthority = union(enum) {9    checker,10    theorem: ObligationSelector,11    certified_claim: ClaimSelector,12    trusted: TrustDeclarationSelector,13};

1/// PremiseClass names the form of basis that supports a phase binding. Its tags2/// distinguish between mathematical theorem domains, checked semantic or path3/// facts, certified claim summaries, and trusted user, external, or environment4/// assertions. Selecting a tag identifies the expected authority category5/// during premise validation, but the enum itself does not establish or6/// evaluate the underlying evidence.7pub const PremiseClass = enum {8    theorem_domain,9    checked_semantic_fact,10    checked_path_fact,11    certified_summary,12    trusted_user,13    trusted_extern,14    trusted_environment,15};

1/// Risk pairs a RiskStatus tag with a descriptive detail string explaining an2/// operational boundary hazard. The detail string must contain 1 to 5123/// single-line bytes without null characters, carriage returns, or line feeds.4/// Declaration validation inspects the detail text grammar and verifies that5/// any risk marked witnessed has a corresponding obligation role declared in6/// the source envelope. The struct retains these values as source metadata7/// without executing checks at runtime.8pub const Risk = struct {9    status: RiskStatus,10    detail: []const u8,11};

1/// RiskStatus describes whether an identified hazard has evidentiary coverage2/// through the witnessed, excluded, or open tags. Setting status to witnessed3/// requires declaring a matching risk role obligation in the source envelope,4/// but it does not establish that a test passed. Setting status to excluded5/// documents that the hazard falls outside the operational scope of the claim.6/// Setting status to open documents an unresolved claim status without7/// satisfying an obligation requirement.8pub const RiskStatus = enum {9    witnessed,10    excluded,11    open,12};

1/// Risks groups the operational hazards of an owner into transitive and foreign2/// Risk records. The transitive field documents risks originating within3/// callees or subsidiary components, while the foreign field documents risks4/// arising from external resources. The descriptive details define the actual5/// scope of each hazard. Declaration validation enforces grammar and witnessed6/// obligations for both fields, but it does not compute or audit a transitive7/// closure across components.8pub const Risks = struct {9    transitive: Risk,10    foreign: Risk,11};

1/// SourceEnvelope contains the primary specification metadata of a claim,2/// gathering its id, kind, limit_source, storage, capacity, overload, risks,3/// optional work, dependencies, and obligations. The `id` must be a canonical4/// identifier of 1 to 64 bytes consisting of at least two non-empty dot5/// segments composed of lowercase letters, digits, or underscores, where6/// leading digits and underscores are permitted. The `capacity` field is a7/// typed `Spec` with semantic type fields requiring a compile-time8/// representation rather than expression evaluation. The `dependencies` slice9/// accepts up to 8 canonical identifiers, rejects duplicates or10/// self-references, and performs no registry lookup or cycle analysis. The11/// envelope borrows its referenced slices rather than deep-copying runtime12/// strings.13pub const SourceEnvelope = struct {14    id: []const u8,15    kind: Kind,16    limit_source: LimitSource,17    storage: Storage,18    capacity: spec.Spec,19    overload: Overload,20    risks: Risks,21    work: ?Work = null,22    dependencies: []const []const u8 = &.{},23    obligations: []const Obligation,24};

1/// Storage specifies the memory coverage boundaries of a claim using covered2/// and excluded slices, rather than holding the backing storage buffer of an3/// owner. The covered list accepts 1 to 16 CoveredStorage records with unique4/// local identifiers. The excluded list accepts 1 to 16 descriptive strings,5/// each bounded to 1 to 512 single-line bytes excluding null bytes, carriage6/// returns, and line feeds. Excluded entries are not checked for uniqueness,7/// and their presence makes no claim that other process memory is absent. The8/// struct holds borrowed slices rather than copying text or managing memory.9pub const Storage = struct {10    covered: []const CoveredStorage,11    excluded: []const []const u8,12};

1/// StorageLifetime labels the operational stage of a covered storage region2/// using the initialization, steady, or transferred tags. These values provide3/// descriptive metadata about when an owner uses a memory region. The enum4/// performs no runtime lifetime tracking, memory management, or ownership5/// operations.6pub const StorageLifetime = enum {7    initialization,8    steady,9    transferred,10};

1/// TrustDeclarationSelector identifies a trust declaration supporting a trusted2/// user, external component, or environment premise through its id field.3/// Validation checks that the id string conforms to canonical dotted identifier4/// syntax. The validator performs no resolution of the external identifier and5/// does not validate the underlying trust declaration.6pub const TrustDeclarationSelector = struct {7    id: []const u8,8};

1/// Violation enumerates the failure categories returned by the source2/// declaration validator. When validation fails, the validator returns the3/// first detected violation category rather than reporting a runtime allocation4/// error. Malformed user types supplied in bindings may trigger Zig compile5/// errors before validation completes. In root.zig, this type is exported under6/// the public alias DeclarationViolation.7pub const Violation = enum {8    id_format,9    storage_covered_missing,10    storage_covered_overflow,11    storage_region_id_invalid,12    storage_region_duplicate,13    storage_detail_invalid,14    storage_excluded_missing,15    storage_excluded_overflow,16    storage_excluded_invalid,17    capacity_limits_mismatch,18    capacity_field_path_invalid,19    capacity_type_selector_invalid,20    capacity_node_outside_fragment,21    capacity_assertion_invalid,22    overload_detail_invalid,23    overload_shape_incompatible,24    risk_detail_invalid,25    risk_obligation_missing,26    work_missing,27    work_equation_invalid,28    work_obligation_missing,29    dependencies_overflow,30    dependency_format,31    dependency_duplicate,32    dependency_self,33    obligations_missing,34    obligations_overflow,35    obligation_key_invalid,36    obligation_key_duplicate,37    capacity_model_obligation_missing,38    overload_obligation_missing,39    owner_binding_missing,40    owner_binding_mismatch,41    default_limits_binding_missing,42    default_limits_binding_unexpected,43    default_limits_binding_invalid,44    seal_binding_missing,45    teardown_binding_missing,46    seam_family_missing,47    seam_family_invalid,48    premise_missing,49    premise_authority_mismatch,50    premise_selector_invalid,51    premise_obligation_unknown,52};

1/// `WitnessAnnotation` holds `claim_id` and `obligation_key` slices alongside a2/// `role` value. The `witness` operation requires `Owner.claim` to have the3/// exact type `Declaration` and verifies that the obligation key exists, but it4/// does not validate the whole claim. Passing the returned annotation to5/// `record` associates it with the enclosing test. Constructing the annotation6/// alone does not record an association with a test or prove that a test7/// passed, and it performs no test execution or assertion inspection.8pub const WitnessAnnotation = struct {9    claim_id: []const u8,10    obligation_key: []const u8,11    role: ObligationRole,12};

1/// `Work` defines an `equation` field consisting of descriptive work bound text2/// between 1 and 512 bytes long, excluding NUL, LF, and CR characters. It is3/// required whenever an owner uses a caller-provisioned shape, and its presence4/// requires declaring an obligation with the work_bound role. The equation text5/// provides descriptive documentation that is neither parsed nor evaluated6/// during validation. This record differs from the WorkLimits structure, which7/// supplies concrete numeric limits.8pub const Work = struct {9    equation: []const u8,10};

1/// Demonstrates an implementation of the caller-provisioned exact owner2/// protocol, re-exported from the package root as `ProvisionedExactFixture`.3/// The owner accepts requested capacities from 1 to 64 bytes and requires4/// caller-provided storage at least as long as the requested count. It retains5/// the entire caller slice across its active lifecycle and returns that exact6/// slice upon deinitialization, even when the provided buffer exceeds the7/// requested capacity. Lifecycle transitions are guarded by debug assertions8/// across `initialization`, `steady`, and `teardown` phases without allocating9/// memory or holding an internal allocator. The instance remains caller-backed10/// throughout its existence. It represents a concrete demonstration fixture, so11/// its specific buffer retention and assertion choices should not be taken as12/// universal requirements for all provisioned owners.13pub const ExactOwner = struct {14    /// This constant defines the 16-byte storage alignment required by15    /// `ExactOwner.Storage`, which the caller must satisfy by supplying an16    /// aligned slice.17    pub const storage_alignment: usize = 16;18    /// This type is a mutable caller-provided slice of []align(16)u8 borrowed19    /// until owner deinit. It may be backed by a caller heap allocation or20    /// another suitable buffer. The fixture does not own or free the underlying21    /// allocation.22    pub const Storage = []align(storage_alignment) u8;23    /// Specifies the input limit configuration for `ExactOwner`, containing a24    /// single `bytes: usize` field. For this demonstration fixture, valid25    /// values are restricted to the range from 1 through 64 bytes.26    pub const Limits = struct {27        bytes: usize,28    };29    /// Represents the derived capacity of `ExactOwner`, storing the required30    /// byte count in `storage_bytes: usize`. This value reflects the storage31    /// quantity computed from the input limits, rather than the total length of32    /// the backing slice supplied by the caller.33    pub const Capacity = struct {34        storage_bytes: usize,3536        /// This derivation error reports `EmptyStorage` for 0 requested bytes37        /// and `CapacityExceeded` when requested bytes exceed 64. The error set38        /// represents capacity derivation limits and does not include39        /// allocation failure.40        pub const DeriveError = error{41            EmptyStorage,42            CapacityExceeded,43        };4445        /// Calculates the required `Capacity` from the provided `Limits`46        /// without performing memory allocation. Returns `error.EmptyStorage`47        /// when `limits.bytes` is zero, and `error.CapacityExceeded` when48        /// `limits.bytes` exceeds 64. For valid inputs between 1 and 64, it49        /// returns a `Capacity` instance whose `storage_bytes` equals50        /// `limits.bytes`.51        pub fn derive(limits: Limits) DeriveError!Capacity {52            if (limits.bytes == 0) return error.EmptyStorage;53            if (limits.bytes > storage_bytes_max) return error.CapacityExceeded;54            return .{ .storage_bytes = limits.bytes };55        }56    };57    /// Defines the error set returned by `init`, formed as the union of58    /// `Capacity.DeriveError` (`error{EmptyStorage, CapacityExceeded}`) and59    /// `error{StorageTooShort}`. Because initialization relies entirely on60    /// caller-provided memory without invoking dynamic allocators, the error61    /// set excludes `error.OutOfMemory`.62    pub const InitError = Capacity.DeriveError || error{StorageTooShort};63    /// This declaration specifies literal declared work bounds with64    /// transition_steps_max set to 1, cleanup_steps_per_call_max set to 0, and65    /// cleanup_calls_at_capacity_max set to 0. These values represent66    /// structural bounds whose numeric shape passes validation rather than67    /// measured CPU counts or independently established semantic unit proofs.68    pub const work_limits: capacity.WorkLimits = .{69        .transition_steps_max = 1,70        .cleanup_steps_per_call_max = 0,71        .cleanup_calls_at_capacity_max = 0,72    };73    /// Declares the compile-time `Declaration` capturing formal specification74    /// metadata for `ExactOwner`. It records the source envelope and typed75    /// bindings, specifying the capacity model, the overload policy76    /// `reject_before_seal`, open risk statuses for transitive and foreign77    /// risks, the transition work equation, and obligation keys. This78    /// declaration documents formal properties and links verification79    /// obligations for external analysis tools. The presence of the declaration80    /// does not itself prove that the implementation satisfies the stated81    /// invariants.82    pub const claim: capacity.Declaration = .{83        .source = .{84            .id = "alloc.provisioned_exact_fixture",85            .kind = .phase_static,86            .limit_source = .caller,87            .storage = .{88                .covered = &.{89                    .{90                        .id = "caller_byte_storage",91                        .lifetime = .transferred,92                        .detail = "caller byte storage",93                    },94                },95                .excluded = &.{96                    "caller-owned payloads",97                },98            },99            .capacity = .{100                .inputs = &.{101                    capacity.bindInput(Limits, "bytes", "bytes"),102                },103                .type_selectors = &.{},104                .nodes = &.{105                    .{ .input = 0 },106                },107                .assertions = &.{.{108                    .scope = .closure_total,109                    .measure = .retained,110                    .relation = .exact,111                    .expression = 0,112                }},113            },114            .overload = .{115                .kind = .reject_before_seal,116                .detail = "short storage rejects before owner construction",117            },118            .risks = .{119                .transitive = .{120                    .status = .open,121                    .detail = "fixture has no callees",122                },123                .foreign = .{124                    .status = .open,125                    .detail = "fixture has no foreign resources",126                },127            },128            .work = .{ .equation = "transition_steps <= transition_steps_max" },129            .obligations = &.{130                .{ .key = "alloc_provisioned_exact_capacity_capacity_model", .role = .capacity_model },131                .{ .key = "alloc_provisioned_exact_capacity_overload", .role = .overload },132                .{ .key = "alloc_provisioned_exact_capacity_work_bound", .role = .work_bound },133            },134        },135        .bindings = .{136            .owner = @This(),137            .seal = .{138                .family = capacity.selector(@This().activate),139                .premise = .{140                    .class = .checked_semantic_fact,141                    .authority = .checker,142                },143            },144            .teardown = .{145                .family = capacity.selector(@This().deinit),146                .premise = .{147                    .class = .checked_semantic_fact,148                    .authority = .checker,149                },150            },151        },152    };153154    phase: capacity.Phase,155    capacity: Capacity,156    storage: Storage,157158    const storage_bytes_max: usize = 64;159160    /// Initializes an `ExactOwner` instance using caller-supplied storage and161    /// configuration limits. It executes `Capacity.derive` first, returning162    /// `error.StorageTooShort` without constructing an owner instance if163    /// `storage.len` is less than `derived.storage_bytes`. On success, it164    /// retains the entire caller slice, sets the internal phase to165    /// `initialization`, and records the derived capacity. The function166    /// performs no heap allocations.167    pub fn init(storage: Storage, limits: Limits) InitError!ExactOwner {168        const derived = try Capacity.derive(limits);169        if (storage.len < derived.storage_bytes) return error.StorageTooShort;170        return .{171            .phase = .initialization,172            .capacity = derived,173            .storage = storage,174        };175    }176177    /// Transitions the owner from `initialization` to `steady` phase. It178    /// verifies that the current phase is `initialization` using a debug179    /// assertion, which may be disabled in non-debug compilation modes and180    /// therefore does not guarantee a panic in all release configurations.181    /// Activation acquires no system resources and performs no memory182    /// allocations.183    pub fn activate(self: *ExactOwner) void {184        std.debug.assert(self.phase == .initialization);185        self.phase = .steady;186    }187188    /// Returns the active byte capacity of the owner, guarded by a debug189    /// assertion that the owner is in the `steady` phase. The returned value is190    /// `capacity.storage_bytes`, representing the required count derived from191    /// initialization limits, rather than the length of the underlying storage192    /// slice.193    pub fn bytes(self: *const ExactOwner) usize {194        std.debug.assert(self.phase == .steady);195        return self.capacity.storage_bytes;196    }197198    /// Deinitializes the owner, transitioning the internal phase from `steady`199    /// to `teardown`, invalidating the owner instance by setting it to200    /// `undefined`, and returning the original caller-supplied slice in its201    /// entirety. The function relies on a debug assertion to check the `steady`202    /// phase prerequisite. It performs no implicit cleanup or byte zeroing and203    /// does not free memory, leaving full ownership and custody of the returned204    /// buffer with the caller.205    pub fn deinit(self: *ExactOwner) Storage {206        std.debug.assert(self.phase == .steady);207        self.phase = .teardown;208        const storage = self.storage;209        self.* = undefined;210        return storage;211    }212};

1/// Demonstrates an implementation of the caller-provisioned rejecting owner2/// protocol, re-exported from the package root as3/// `ProvisionedRejectingFixture`. The owner manages a bounded number of slots,4/// up to 8, with each slot having a positive byte width, backed by5/// caller-supplied 16-byte aligned memory. Calling submit when full returns6/// Full after incrementing both submitted and rejected counts if both7/// increments fit, or returns AccountingOverflow before mutation if an8/// increment would overflow usize. The payload is preserved along either9/// rejection path. Calling cleanupOne pops and zeroes a single slot, while10/// deinit returns the entire original slice without executing a cleanup loop,11/// requiring the caller to keep borrowed bytes alive.12pub const RejectingOwner = struct {13    /// This constant specifies a maximum of 8 allowed slots for14    /// `RejectingOwner`. This slot limit applies regardless of the slot width,15    /// which must be positive and yield a product that fits in `usize`.16    pub const slots_max: usize = 8;17    /// This constant specifies the 16-byte storage alignment required by18    /// `RejectingOwner.Storage`, which remains the responsibility of the caller19    /// to supply.20    pub const storage_alignment: usize = 16;21    /// Defines the storage type accepted and used by `RejectingOwner`, declared22    /// as `[]align(16) u8`. This slice represents a mutable buffer borrowed23    /// from the caller for the duration of the owner's active life. Ownership24    /// of the memory remains with the caller.25    pub const Storage = []align(storage_alignment) u8;26    /// Specifies the configuration limits for `RejectingOwner`, containing27    /// `slots: usize` and `slot_bytes: usize`. Valid limits require both fields28    /// to be positive, `slots` to be less than or equal to 8, and their29    /// arithmetic product to fit within `usize` without overflow.30    pub const Limits = struct {31        slots: usize,32        slot_bytes: usize,33    };34    /// Stores the derived dimensional parameters of `RejectingOwner`, including35    /// `slots: usize`, `slot_bytes: usize`, and `storage_bytes: usize`. The36    /// `storage_bytes` field holds the exact product of `slots` and37    /// `slot_bytes`, representing the total storage required by the owner.38    pub const Capacity = struct {39        slots: usize,40        slot_bytes: usize,41        storage_bytes: usize,4243        /// This error type reports `InvalidLimit` on zero slots or width,44        /// `CapacityOverflow` if their product overflows `usize`, and45        /// `CapacityExceeded` if the slot count exceeds 8 after the product46        /// check. These outcomes represent derivation failures rather than47        /// domain `Exhaustion` conditions like `Full` or `AccountingOverflow`.48        pub const DeriveError = error{49            InvalidLimit,50            CapacityOverflow,51            CapacityExceeded,52        };5354        /// Derives the required `Capacity` from input `Limits` without55        /// performing memory allocation. It evaluates error conditions in a56        /// strict sequence: returns `error.InvalidLimit` if either `slots` or57        /// `slot_bytes` is zero, returns `error.CapacityOverflow` if computing58        /// `slots * slot_bytes` overflows `usize`, and returns59        /// `error.CapacityExceeded` if `slots` exceeds 8 after the checked60        /// product succeeds. On valid inputs, it returns a `Capacity` instance61        /// recording the slot count, slot width, and computed storage byte62        /// count.63        pub fn derive(limits: Limits) DeriveError!Capacity {64            if (limits.slots == 0 or limits.slot_bytes == 0) {65                return error.InvalidLimit;66            }67            const storage_bytes = try capacity.mul(68                usize,69                limits.slots,70                limits.slot_bytes,71            );72            if (limits.slots > slots_max) return error.CapacityExceeded;73            return .{74                .slots = limits.slots,75                .slot_bytes = limits.slot_bytes,76                .storage_bytes = storage_bytes,77            };78        }79    };80    /// This error set comprises Full and AccountingOverflow. Full indicates81    /// that all slots are occupied and the attempt is successfully recorded in82    /// submitted and rejected counters while payload and used count remain83    /// unchanged. AccountingOverflow occurs when an increment required by the84    /// selected submission path would exceed usize, rather than when a valid85    /// increment merely reaches the maximum value. This error returns before86    /// any payload or counter mutation occurs. Only counters relevant to the87    /// selected path are checked, specifically submitted and rejected for full88    /// rejection, or submitted and accepted for successful admission.89    pub const Exhaustion = error{90        Full,91        AccountingOverflow,92    };93    /// Specifies the error set returned by `init`, formed as the union of94    /// `Capacity.DeriveError` (`error{InvalidLimit, CapacityOverflow,95    /// CapacityExceeded}`) and `error{StorageTooShort}`. It captures failure96    /// during limit derivation or when the supplied caller storage slice97    /// contains fewer bytes than derived `storage_bytes`.98    pub const InitError = Capacity.DeriveError || error{StorageTooShort};99    /// Maintains diagnostic accounting counters for `RejectingOwner`, tracking100    /// `submitted`, `accepted`, and `rejected` operations initialized to zero.101    /// Submissions increment counters only along execution paths where102    /// arithmetic fits within `usize` without overflow. An attempt that fails103    /// because the owner is full is recorded by incrementing both `submitted`104    /// and `rejected`, leaving `accepted` unchanged.105    pub const Usage = struct {106        submitted: usize = 0,107        accepted: usize = 0,108        rejected: usize = 0,109    };110    /// Declares the static `WorkLimits` for `RejectingOwner`, configuring111    /// `transition_steps_max` as 1, `cleanup_steps_per_call_max` as 1, and112    /// `cleanup_calls_at_capacity_max` as 8. These numbers represent declared113    /// owner work units rather than elapsed execution time or hardware cycle114    /// counts. In particular, each cleanup invocation executes `@memset` across115    /// an entire slot, so the actual runtime work scales with `slot_bytes`.116    pub const work_limits: capacity.WorkLimits = .{117        .transition_steps_max = 1,118        .cleanup_steps_per_call_max = 1,119        .cleanup_calls_at_capacity_max = slots_max,120    };121    /// Declares the compile-time `Declaration` capturing formal specification122    /// metadata for `RejectingOwner`. It binds the slot product capacity model,123    /// the overload policy `reject_before_mutation` documenting payload124    /// preservation alongside diagnostic counter updates, open risk statuses125    /// for transitive and foreign risks, the bounded cleanup work equation, and126    /// obligation keys. This declaration documents design contracts and127    /// provides metadata for verification tools without executing runtime128    /// checks or proving implementation correctness.129    pub const claim: capacity.Declaration = .{130        .source = .{131            .id = "alloc.provisioned_rejecting_fixture",132            .kind = .phase_static,133            .limit_source = .caller,134            .storage = .{135                .covered = &.{136                    .{137                        .id = "caller_slot_storage",138                        .lifetime = .transferred,139                        .detail = "caller slot storage",140                    },141                },142                .excluded = &.{143                    "caller-owned payloads",144                },145            },146            .capacity = .{147                .inputs = &.{148                    capacity.bindInput(Limits, "slots", "slots"),149                    capacity.bindInput(Limits, "slot_bytes", "slot_bytes"),150                },151                .type_selectors = &.{},152                .nodes = &.{153                    .{ .input = 0 },154                    .{ .input = 1 },155                    .{ .product = .{ .left = 0, .right = 1 } },156                },157                .assertions = &.{.{158                    .scope = .closure_total,159                    .measure = .retained,160                    .relation = .exact,161                    .expression = 2,162                }},163            },164            .overload = .{165                .kind = .reject_before_mutation,166                .detail = "full submission changes only submitted and rejected counters",167            },168            .risks = .{169                .transitive = .{170                    .status = .open,171                    .detail = "fixture has no callees",172                },173                .foreign = .{174                    .status = .open,175                    .detail = "fixture has no foreign resources",176                },177            },178            .work = .{ .equation = "transition <= 1 and cleanup <= slots" },179            .obligations = &.{180                .{ .key = "alloc_provisioned_rejecting_capacity_capacity_model", .role = .capacity_model },181                .{ .key = "alloc_provisioned_rejecting_capacity_overload", .role = .overload },182                .{ .key = "alloc_provisioned_rejecting_capacity_work_bound", .role = .work_bound },183            },184        },185        .bindings = .{186            .owner = @This(),187            .seal = .{188                .family = capacity.selector(@This().activate),189                .premise = .{190                    .class = .checked_semantic_fact,191                    .authority = .checker,192                },193            },194            .teardown = .{195                .family = capacity.selector(@This().deinit),196                .premise = .{197                    .class = .checked_semantic_fact,198                    .authority = .checker,199                },200            },201        },202    };203204    phase: capacity.Phase,205    capacity: Capacity,206    storage: Storage,207    used: usize = 0,208    usage: Usage = .{},209210    /// Initializes a `RejectingOwner` instance using caller storage and211    /// configuration limits. It executes `Capacity.derive` first and then212    /// checks that `storage.len` is at least `derived.storage_bytes`, returning213    /// `error.StorageTooShort` if the buffer is insufficient. On success, it214    /// preserves the original storage slice, sets `phase` to `initialization`,215    /// initializes `used` to 0, and sets `usage` counters to 0. The function216    /// performs no dynamic memory allocation.217    pub fn init(storage: Storage, limits: Limits) InitError!RejectingOwner {218        const derived = try Capacity.derive(limits);219        if (storage.len < derived.storage_bytes) return error.StorageTooShort;220        return .{221            .phase = .initialization,222            .capacity = derived,223            .storage = storage,224        };225    }226227    /// Transitions the owner from `initialization` to `steady` phase. It228    /// verifies that the current phase is `initialization` using a debug229    /// assertion. Activation acquires no system resources and performs no230    /// memory allocations.231    pub fn activate(self: *RejectingOwner) void {232        std.debug.assert(self.phase == .initialization);233        self.phase = .steady;234    }235236    /// Submits a byte value into the owner, guarded by a debug assertion that237    /// the current phase is `steady`. When capacity is exhausted because `used`238    /// equals `capacity.slots`, the function checks that `submitted` and239    /// `rejected` will not overflow `std.math.maxInt(usize)`. If accounting240    /// fits, it increments both counters and returns `error.Full` while241    /// preserving stored payload and slot count. If any counter addition would242    /// overflow `usize`, it returns `error.AccountingOverflow` before any243    /// mutation occurs. On successful submission, it increments244    /// `usage.submitted`, fills all bytes of the next slot with `byte`,245    /// increments `used`, and increments `usage.accepted`. The operation246    /// performs no hidden allocations and provides no automatic state reset or247    /// buffer reuse beyond calling `cleanupOne`.248    pub fn submit(self: *RejectingOwner, byte: u8) Exhaustion!void {249        std.debug.assert(self.phase == .steady);250        if (self.used == self.capacity.slots) {251            if (self.usage.submitted == std.math.maxInt(usize)) {252                return error.AccountingOverflow;253            }254            if (self.usage.rejected == std.math.maxInt(usize)) {255                return error.AccountingOverflow;256            }257            self.usage.submitted += 1;258            self.usage.rejected += 1;259            return error.Full;260        }261        if (self.usage.submitted == std.math.maxInt(usize)) {262            return error.AccountingOverflow;263        }264        if (self.usage.accepted == std.math.maxInt(usize)) {265            return error.AccountingOverflow;266        }267        self.usage.submitted += 1;268        const offset = self.used * self.capacity.slot_bytes;269        @memset(self.storage[offset..][0..self.capacity.slot_bytes], byte);270        self.used += 1;271        self.usage.accepted += 1;272    }273274    /// Removes a single slot from the owner, guarded by a debug assertion that275    /// the phase is `steady`. If `used` is 0, it returns `false` without276    /// modifying state. When slots are present, it decrements `used`, zeroes277    /// all bytes in the removed slot using `@memset`, and returns `true`. The278    /// function leaves `usage` accounting counters unchanged. It performs no279    /// dynamic memory allocation, does not terminate or teardown the owner, and280    /// executes cleanup work that scales with `slot_bytes`.281    pub fn cleanupOne(self: *RejectingOwner) bool {282        std.debug.assert(self.phase == .steady);283        if (self.used == 0) return false;284        self.used -= 1;285        const offset = self.used * self.capacity.slot_bytes;286        @memset(self.storage[offset..][0..self.capacity.slot_bytes], 0);287        return true;288    }289290    /// Deinitializes the owner, asserting that the owner is in the `steady`291    /// phase. It transitions `phase` to `teardown`, sets the owner instance to292    /// `undefined`, and returns the original caller-supplied slice in its293    /// entirety. The function does not call `cleanupOne` or zero out remaining294    /// occupied slot payloads, leaving any required scrubbing or memory295    /// sanitization to the caller.296    pub fn deinit(self: *RejectingOwner) Storage {297        std.debug.assert(self.phase == .steady);298        self.phase = .teardown;299        const storage = self.storage;300        self.* = undefined;301        return storage;302    }303};

1/// Specifies the structural protocol expected of a memory owner across two2/// independent axes: storage acquisition, defined by `StorageSource`, and3/// exhaustion behavior, defined by `OverloadShape`. Four named constants4/// represent the valid combinations: `allocator_exact`, `allocator_rejecting`,5/// `provisioned_exact`, and `provisioned_rejecting`. This classification6/// constrains required container declarations, field layouts, and lifecycle7/// function signatures during compile-time shape validation. It does not8/// inspect function bodies, verify that resource bounds are maintained at9/// runtime, or prove the dynamic correctness of owner operations. An `exact`10/// classification indicates only that the shape contract requires no11/// steady-state exhaustion error. It does not promise that operational methods12/// are infallible or that runtime failures cannot occur.13pub const OwnerShape = struct {14    storage_source: StorageSource,15    overload_shape: OverloadShape,1617    /// Selects the storage acquisition mechanism required during owner18    /// initialization. The `allocator_backed` variant requires the owner's19    /// `init` function to receive a standard `std.mem.Allocator` parameter. The20    /// `caller_provisioned` variant requires `init` to receive an aligned slice21    /// conforming to the owner's declared `Storage` type. The enumeration22    /// defines structural initialization signatures only. Neither variant23    /// enforces memory lifetimes or guarantees that callers retain backing24    /// storage for the required duration of the owner.25    pub const StorageSource = enum {26        allocator_backed,27        caller_provisioned,28    };2930    /// The exact overload shape requires no Exhaustion declaration. The31    /// rejecting overload shape requires a finite nonempty Exhaustion error set32    /// and at least one non-lifecycle pointer-receiver method whose return type33    /// is an error set or error union containing all Exhaustion errors. The34    /// return type does not have to be an error union. This signature check35    /// does not prove error reachability.36    pub const OverloadShape = enum {37        exact,38        rejecting,39    };4041    /// This shape value selects `allocator_backed` storage paired with an42    /// `exact` overload surface. This identifier serves as a declaration value43    /// describing the shape and does not run validation checks.44    pub const allocator_exact: OwnerShape = .{45        .storage_source = .allocator_backed,46        .overload_shape = .exact,47    };4849    /// This shape value selects the pairing of `allocator_backed` storage with50    /// a `rejecting` overload surface.51    pub const allocator_rejecting: OwnerShape = .{52        .storage_source = .allocator_backed,53        .overload_shape = .rejecting,54    };5556    /// This shape value selects the pairing of `caller_provisioned` storage57    /// with an `exact` overload surface.58    pub const provisioned_exact: OwnerShape = .{59        .storage_source = .caller_provisioned,60        .overload_shape = .exact,61    };6263    /// This shape value selects the pairing of `caller_provisioned` storage64    /// with a `rejecting` overload surface.65    pub const provisioned_rejecting: OwnerShape = .{66        .storage_source = .caller_provisioned,67        .overload_shape = .rejecting,68    };69};

1/// Defines three static bounds for owner lifecycle and maintenance work:2/// `transition_steps_max`, `cleanup_steps_per_call_max`, and3/// `cleanup_calls_at_capacity_max`. Structural validation requires4/// `transition_steps_max` to be greater than zero. The cleanup bounds must be5/// either both zero or both nonzero, and their arithmetic product must fit6/// within `usize` without overflow. These bounds are literal numeric7/// declarations checked solely for structural validity. Validation does not8/// measure CPU instructions, inspect loop constructs, or evaluate wall-clock9/// duration. In implementations providing cleanup routines, the work performed10/// by each cleanup step may depend on the extent of stored data rather than a11/// constant processing cost.12pub const WorkLimits = struct {13    transition_steps_max: usize,14    cleanup_steps_per_call_max: usize,15    cleanup_calls_at_capacity_max: usize,16};

1/// Defines the lifecycle phases shared across allocator guards:2/// `initialization`, `steady`, and `teardown`. Runtime guards use these values3/// to classify incoming raw allocator calls. Under this classification,4/// `initialization` permits every raw operation, `steady` marks all raw5/// operations as violations, and `teardown` permits only deallocations while6/// marking allocations, resizes, and remaps as violations. Depending on the7/// selected guard type, a violation either triggers an immediate panic or8/// increments audit counters before forwarding the call to the backing9/// allocator. The enumeration itself is an unadorned data type that enforces no10/// transition rules or operational policies on other owners.11pub const Phase = enum(u8) {12    initialization,13    steady,14    teardown,15};

1/// Enumerates the first structural check failure detected when validating an2/// owner type against an expected `OwnerShape`. Tags cover missing or malformed3/// declarations, incorrect runtime fields, mismatched lifecycle signatures,4/// prohibited allocator capabilities, invalid exhaustion declarations, and5/// missing or invalid claims. When an owner declares an invalid claim,6/// `validateOwnerShape` collapses the underlying `DeclarationViolation` into7/// the single tag `invalid_claim`. In contrast, `requireOwnerShape` validates8/// the claim directly through `declaration.require` before running shape9/// checks, emitting detailed compile errors for specific declaration failures.10/// Because compile-time reflection can encounter malformed syntax or illegal11/// type definitions in user declarations, passing arbitrary malformed types to12/// validation functions may produce compiler errors rather than returning an13/// optional violation cleanly.14pub const OwnerShapeViolation = enum {15    owner_not_struct,16    missing_phase,17    wrong_phase_type,18    comptime_phase,19    missing_capacity,20    wrong_capacity_type,21    comptime_capacity,22    missing_limits_declaration,23    wrong_limits_declaration,24    missing_capacity_declaration,25    wrong_capacity_declaration,26    missing_storage_alignment,27    wrong_storage_alignment,28    invalid_storage_alignment,29    missing_storage_declaration,30    wrong_storage_declaration,31    missing_storage,32    wrong_storage_type,33    comptime_storage,34    missing_storage_bytes,35    wrong_storage_bytes,36    comptime_storage_bytes,37    missing_work_limits,38    wrong_work_limits,39    invalid_work_limits,40    missing_claim_declaration,41    wrong_claim_declaration,42    invalid_claim,43    missing_exhaustion_declaration,44    wrong_exhaustion_declaration,45    exhaustion_not_observable,46    stored_allocator,47    missing_capacity_derive,48    wrong_capacity_derive,49    missing_init,50    wrong_init,51    missing_activate,52    wrong_activate,53    missing_deinit,54    wrong_deinit,55    steady_allocator_parameter,56    steady_allocator_result,57};

1/// Symbolic rounding descriptor targeting a memory boundary: `Align` pairs a2/// 16-bit expression node index (`node`) with an `Alignment` rule. Structural3/// validation requires the target node index to strictly precede the position4/// of the current node. This struct describes a symbolic rounding calculation5/// for byte capacity expressions, rather than providing guarantees about6/// allocated pointer addresses.7pub const Align = struct {8    node: u16,9    alignment: Alignment,10};

1/// The `Alignment` union represents an alignment requirement as either a2/// literal `u64` value or a `concrete_type` referencing a `u16` selector index.3/// Validation requires a literal value to be a non-zero power of two, or a4/// concrete index to reside within the valid selector range. Typed validation5/// examines selector size and alignment facts for concrete selections. A view6/// provides only the selector identifier for concrete selection, whereas a7/// literal `Alignment` retains its explicit numeric value. The type provides no8/// runtime allocation guarantee.9pub const Alignment = union(enum) {10    literal: u64,11    concrete_type: u16,12};

1/// Formal capacity claim for a completed expression: `Assertion` binds a2/// `Scope`, a `Measure`, and a `Relation` to a 16-bit node index3/// (`expression`). Structural validation checks that the referenced expression4/// index points to a valid node within the specification node array.5/// Constructing or validating an `Assertion` does not invoke runtime assertion6/// checks, evaluate expression values, or verify agreement with derived7/// allocation bounds.8pub const Assertion = struct {9    scope: Scope,10    measure: Measure,11    relation: Relation,12    expression: u16,13};

1/// `BoundedFieldOrdinalPath` represents a static path through nested structs2/// using a fixed array of eight `u16` field ordinals, an active `u8` length,3/// and a borrowed diagnostic string. The ordinals are zero-based field indices4/// in nested structs rather than memory byte offsets. The active length must5/// range from 1 to 8. The diagnostic string must consist of 1 to 256 bytes6/// formed by non-empty dot-separated ASCII segments containing letters, digits,7/// or underscores, with uppercase characters permitted. Typed validation8/// follows the actual field indices and verifies the leaf class. Structural9/// validation checks diagnostic syntax without resolving the diagnostic10/// spelling against field definitions. The computed hash covers the active11/// length and active ordinals while excluding the diagnostic string and unused12/// tail ordinals. The structure does not perform runtime navigation operations.13pub const BoundedFieldOrdinalPath = struct {14    ordinals: [field_path_depth_max]u16 = @splat(0),15    len: u8,16    diagnostic: []const u8,17};

1/// Character occurrence counter for a byte slice: `ByteCount` pairs a 16-bit2/// input index (`input`) with an 8-bit byte value (`byte`). When referenced by3/// a collection projection node, validation verifies that the addressed input4/// exists and possesses a `byte_collection` leaf classification. The struct5/// declaratively describes counting occurrences of the specified byte within6/// the input slice without scanning memory or computing sums.7pub const ByteCount = struct {8    input: u16,9    byte: u8,10};

1/// Multiplication factor operand in a scaling expression: `Coefficient` is a2/// tagged union representing either a 64-bit constant (`literal`), an3/// unresolved integer parameter index (`unsigned_comptime_parameter`), a4/// generic type parameter index (`size_of_type_parameter`), or a concrete type5/// selector index (`size_of_concrete_type`). The parameter variants act as6/// declarative placeholders whose concrete values are not resolved by this7/// module. Structural validation checks that `size_of_concrete_type` references8/// an index within the specification type selector list. Construction and9/// validation do not compute products or perform arithmetic multiplication.10pub const Coefficient = union(enum) {11    literal: u64,12    unsigned_comptime_parameter: u16,13    size_of_type_parameter: u16,14    size_of_concrete_type: u16,15};

1/// Measurement extraction from collection inputs: `CollectionProjection` is a2/// tagged union supporting either a `length` query taking a 16-bit input index3/// or a `byte_count` query holding a `ByteCount` descriptor. Unlike binary4/// arithmetic operators, these indices address entries in the specification5/// input list rather than expression nodes. Structural validation rejects6/// scalar integer inputs, permitting `length` on both general slices and byte7/// slices while restricting `byte_count` exclusively to byte slices.8pub const CollectionProjection = union(enum) {9    length: u16,10    byte_count: ByteCount,11};

1/// Relational operator tag for conditional expressions: `Comparison` defines2/// the tags `equal`, `not_equal`, `less_than`, `less_or_equal`, `greater_than`,3/// and `greater_or_equal` for use inside a `Predicate`. Constructing a4/// comparison tag specifies the intended condition between two node values.5/// This module does not evaluate predicates or compare actual input values.6pub const Comparison = enum {7    equal,8    not_equal,9    less_than,10    less_or_equal,11    greater_than,12    greater_or_equal,13};

1/// Branching expression selecting between alternative expressions:2/// `Conditional` holds a `Predicate` condition together with two 16-bit node3/// indices, `when_true` and `when_false`. Validation requires all referenced4/// nodes, including both predicate operands and both branch targets, to appear5/// earlier in the expression sequence than the conditional node itself. The6/// structure represents branch selection declaratively without executing either7/// branch or verifying path reachability.8pub const Conditional = struct {9    predicate: Predicate,10    when_true: u16,11    when_false: u16,12};

1/// Specification input parameter holding compile-time type information: `Input`2/// defines an external input with an identifier string (`id`), a compile-time3/// limit type (`limits_type`), a navigation path (`field_path`), and an4/// expected category (`leaf_class`). The identifier must contain 1 to 64 bytes5/// beginning with a lowercase ASCII letter followed by lowercase alphanumeric6/// characters or underscores, and must be unique across all inputs. Because7/// `limits_type` stores a compile-time type, constructing an `Input` occurs at8/// compile time, borrowing string slices for the identifier and path9/// diagnostic. Typed validation confirms that `limits_type` matches the10/// expected limits type and that following the ordinal path through that type11/// yields the declared `leaf_class`.12pub const Input = struct {13    id: []const u8,14    limits_type: SemanticType,15    field_path: BoundedFieldOrdinalPath,16    leaf_class: LeafClass = .unsigned_integer,17};

1/// Type-erased description of a specification input: `InputView` retains the2/// identifier string (`id`), ordinal path (`field_path`), and classification3/// tag (`leaf_class`) while omitting the compile-time type binding. It holds4/// borrowed string slices suitable for runtime inspection and digest5/// computation. Structural validation checks identifier syntax and path bounds,6/// but cannot verify whether the path corresponds to a field in any concrete7/// Zig type.8pub const InputView = struct {9    id: []const u8,10    field_path: BoundedFieldOrdinalPath,11    leaf_class: LeafClass = .unsigned_integer,12};

1/// Category of data held at the termination of a field path: `LeafClass`2/// classifies inputs as `unsigned_integer`, `signed_integer`, `collection`, or3/// `byte_collection`. When resolving fields in `bindInput`, integers up to 644/// bits produce integer classes, slices of `u8` yield `byte_collection`, and5/// slices of other element types become `collection`. Expression validation6/// enforces that `Node.input` references only integer classes, collection7/// length projections accept both slice classes, and byte count projections8/// target only `byte_collection`.9pub const LeafClass = enum {10    unsigned_integer,11    signed_integer,12    collection,13    byte_collection,14};

1/// The `Measure` enumeration selects a quantity label within an `Assertion`2/// using tags `reserved`, `committed`, `live`, or `retained`. The measurement3/// tag belongs directly to the `Assertion` rather than to an expression node.4/// This module does not measure allocations or evaluate runtime quantities.5/// Scope and supporting evidence are supplied by an enclosing claim and6/// downstream analysis.7pub const Measure = enum {8    reserved,9    committed,10    live,11    retained,12};

1/// Expression graph node union: `Node` defines the operations of the capacity2/// expression language through tags `constant`, `input`, `add`, `maximum`,3/// `scale`, `product`, `alignment`, `ceiling_division`, `conditional`,4/// `next_power_of_two`, and `collection`. Nodes form an ordered acyclic graph5/// bounded to at most 64 entries in a valid specification. Structural6/// validation requires operand node indices to strictly precede the current7/// node position, while inputs and collection projections must address valid8/// inputs matching their required leaf classes. Validation does not evaluate9/// expressions, check for division by zero, guard against arithmetic overflow,10/// or verify value positivity.11pub const Node = union(enum) {12    constant: u64,13    input: u16,14    add: Pair,15    maximum: Pair,16    scale: Scale,17    product: Pair,18    alignment: Align,19    ceiling_division: Pair,20    conditional: Conditional,21    next_power_of_two: u16,22    collection: CollectionProjection,23};

1/// Binary operand reference for node expressions: `Pair` holds two 16-bit2/// unsigned integer indices, `left` and `right`. Both indices address earlier3/// nodes in the ordered expression array rather than input indices. Structural4/// validation enforces this directed acyclic graph ordering by requiring that5/// both indices strictly precede the position of the containing node.6pub const Pair = struct {7    left: u16,8    right: u16,9};

1/// Comparison expression linking two node operands: `Predicate` combines a2/// `Comparison` operator with two 16-bit node indices, `left` and `right`. When3/// validated inside a `Conditional` node, both operand indices must strictly4/// precede the containing node index. The structure defines a declarative5/// relational test without evaluating operands or storing boolean results.6pub const Predicate = struct {7    comparison: Comparison,8    left: u16,9    right: u16,10};

1/// Comparison intent for an asserted bound: `Relation` distinguishes whether an2/// expression represents an `upper_bound` or an `exact` quantity in an3/// `Assertion`. The tag declares the intended relation between the selected4/// `Measure` and the target expression node. Structural validation verifies5/// that the referenced expression node index falls within the defined node6/// array, but does not check whether the mathematical relationship holds true.7pub const Relation = enum {8    upper_bound,9    exact,10};

1/// Symbolic multiplication of a node by a scaling factor: `Scale` combines a2/// 16-bit expression node index (`node`) with a `Coefficient` multiplier.3/// Validation requires that the referenced node index appears earlier in the4/// expression sequence, and enforces selector bounds if the coefficient5/// references a concrete type. The structure describes a mathematical scaling6/// operation without calculating a product or checking for integer overflow.7pub const Scale = struct {8    node: u16,9    coefficient: Coefficient,10};

1/// The `Scope` enumeration provides the sole tag `closure_total` to label the2/// evaluation scope of an `Assertion`. The module provides no evaluator,3/// automatic traversal of an owner graph, or proof of transitive coverage. A4/// source type alone does not establish a precise dynamic footprint for an5/// operation.6pub const Scope = enum {7    closure_total,8};

1/// Typed capacity specification holding semantic bindings: `Spec` bundles2/// borrowed slices of typed `Input` definitions, ordered `Node` entries,3/// `Assertion` claims, and optional `TypeSelector` bindings. Valid4/// specifications contain up to 48 inputs, up to 16 type selectors, 1 to 645/// nodes, and 1 to 8 assertions, with inputs and type selectors permitted to be6/// empty. Because `Input` and `TypeSelector` contain compile-time type7/// references, a `Spec` is constructed at compile time and does not validate8/// invariants upon instantiation. The enclosing owner declaration validation9/// routine invokes the internal typed `validate` function to check structural10/// and layout rules.11pub const Spec = struct {12    inputs: []const Input,13    nodes: []const Node,14    assertions: []const Assertion,15    type_selectors: []const TypeSelector = &.{},16};

1/// Compile-time metadata binding for a referenced memory type: `TypeSelector`2/// pairs an identifier string (`id`) with a compile-time type3/// (`selected_type`), a size in bytes (`byte_size`), and a byte alignment4/// requirement (`byte_alignment`). Identifiers must be unique across all5/// selectors in a specification. Constructing a selector through `bindType`6/// captures the results of `@sizeOf` and `@alignOf` without taking ownership of7/// the underlying type. Typed validation verifies that the stored size and8/// alignment match the type, and that alignment is a non-zero power of two.9pub const TypeSelector = struct {10    id: []const u8,11    selected_type: SemanticType,12    byte_size: u64,13    byte_alignment: u64,14};

1/// `TypeSelectorView` exposes only a borrowed identifier while omitting2/// `selected_type`, `byte_size`, and `byte_alignment`. Structural validation3/// verifies identifier grammar and confirms uniqueness across all selectors in4/// the view. The digest incorporates the selector identifier without erased5/// semantic type or layout details. An entire specification digest cannot be6/// assumed independent of host layout because other graph nodes may encode7/// concrete layout values.8pub const TypeSelectorView = struct {9    id: []const u8,10};

1/// Type-erased view of a capacity specification: `View`, re-exported at the2/// package root as `SpecView`, represents a specification using `InputView` and3/// `TypeSelectorView` slices alongside expression nodes and assertions. All4/// slices are borrowed, and callers can construct or provide a `View` at5/// runtime because it contains no compile-time type fields. The internal6/// compile-time `view` constructor produces view slices with static storage7/// lifetime, but arbitrary runtime instances do not own underlying memory or8/// guarantee static persistence.9pub const View = struct {10    inputs: []const InputView,11    nodes: []const Node,12    assertions: []const Assertion,13    type_selectors: []const TypeSelectorView = &.{},14};

1/// Failure reason for capacity specification validation: `Violation`,2/// re-exported at the package root as `SpecViolation`, enumerates the first3/// structural or typed rule failure encountered during validation. The4/// specification does not enforce any rule that rejects unused or unreferenced5/// graph nodes. An invalid assertion expression failure specifically denotes a6/// referenced node index that is out of bounds rather than an arithmetic7/// evaluation error.8pub const Violation = enum {9    limits_type_mismatch,10    input_overflow,11    input_id_invalid,12    input_id_duplicate,13    input_field_path_invalid,14    type_selector_overflow,15    type_selector_id_invalid,16    type_selector_id_duplicate,17    type_selector_fact_invalid,18    nodes_missing,19    node_overflow,20    node_outside_fragment,21    assertions_missing,22    assertion_overflow,23    assertion_expression_invalid,24};

1/// Computes the checked sum of two integer values of type `T`. It delegates to2/// the `@addWithOverflow` builtin, returning `error.CapacityOverflow` if3/// arithmetic overflow or carry occurs. The function imposes no domain-specific4/// maximum bounds or byte limit policies, leaving application limits to owner5/// capacity derivation. On success, it returns the sum as a value of type `T`.6pub inline fn add(comptime T: type, lhs: T, rhs: T) error{CapacityOverflow}!T {7    const result = @addWithOverflow(lhs, rhs);8    if (result[1] != 0) return error.CapacityOverflow;9    return result[0];10}

1/// Computes the checked product of two integer values of type `T`. It delegates2/// to the `@mulWithOverflow` builtin, returning `error.CapacityOverflow` if3/// arithmetic overflow occurs. The function enforces no external range policies4/// or domain limits beyond the representation limits of type `T`. On success,5/// it returns the product as a value of type `T`.6pub inline fn mul(comptime T: type, lhs: T, rhs: T) error{CapacityOverflow}!T {7    const result = @mulWithOverflow(lhs, rhs);8    if (result[1] != 0) return error.CapacityOverflow;9    return result[0];10}

1/// Recursively inspects a compile-time type to detect whether it exposes an2/// allocator capability. The traversal follows typed pointers, arrays, vectors,3/// optionals, error-union payloads, struct and union fields, and container4/// receiver methods whose return types lead to an allocator. It maintains a5/// compile-time tuple of visited containers to prevent infinite loops on6/// recursive data structures, and recognizes `std.mem.Allocator` as an7/// immediate capability. For bare function types, the check examines only the8/// return type, without scanning parameter lists. This public recursive9/// inspector differs from the narrower internal scanner used by10/// allocator-backed shapes, which inspects only immediate field types and11/// container allocator methods. The function does not inspect function bodies,12/// detect global allocator variables, or track capabilities through type-erased13/// pointers such as `*anyopaque`. It does not prove that runtime execution is14/// free from allocation side effects.15pub fn typeHasAllocatorCapability(comptime T: type) bool {16    @setEvalBranchQuota(1_000_000);17    return typeHasAllocatorCapabilitySeen(T, .{});18}

1/// This validator limit specifies a maximum of 16 covered storage records in2/// `SourceEnvelope.storage.covered`, requiring a valid list to be non-empty.3pub const covered_max: usize = 16;

1/// declarationEnvelopeDigest computes the digest of a compile-time Declaration2/// by converting its source envelope through sourceView and hashing the3/// resulting EnvelopeView with envelopeDigest. Because the view omits bindings,4/// changes to bindings such as the owner type, seam functions, or premises do5/// not affect the digest. The underlying capacity digest also omits semantic6/// types and sizing facts. The resulting hash establishes a content identity7/// for selected source specification fields rather than an identity for the8/// whole implementation or its evidence.9pub fn declarationEnvelopeDigest(comptime value: Declaration) [digest_bytes]u8 {10    return envelopeDigest(sourceView(value.source));11}

1/// The current implementation of `declareDynamicUnbounded` checks a canonical2/// dotted `id` at compile time and discards `Owner`. It does not inspect3/// whether `Owner` actually allocates, install behavior, record observer4/// metadata, or register a proven bound.5pub fn declareDynamicUnbounded(comptime id: []const u8, comptime Owner: type) void {6    requireCanonicalId(id);7    _ = Owner;8}

1/// declareWarmRetained declares a weak capacity owner associated with warm2/// retained memory. It checks at compile time that the provided id satisfies3/// canonical dotted identifier syntax and discards the Owner type parameter.4/// The function records no observer claims and performs no actual5/// retention policy, owner shape, or capacity bound checks.6pub fn declareWarmRetained(comptime id: []const u8, comptime Owner: type) void {7    requireCanonicalId(id);8    _ = Owner;9}

1/// This validator limit defines a maximum of 8 canonical dependency2/// identifiers, permitting an empty list.3pub const dependencies_max: usize = 8;

1/// envelopeDigest hashes the content of an EnvelopeView using SHA-256 under the2/// domain tiny.alloc.claim-declaration/v2, and is exported from root.zig as3/// declarationSourceEnvelopeDigest. The digest builder length-frames every4/// field and ordered list element, incorporating storage details, the capacity5/// specification digest, overload policy, risks, optional work equations,6/// dependencies, and obligations. Because the view contains no bindings, all7/// typed bindings and premises are excluded from the digest. The function8/// performs no validation or formal proof, requiring callers to provide a valid9/// bounded view.10pub fn envelopeDigest(value: EnvelopeView) [digest_bytes]u8 {11    var builder = DigestBuilder.init();12    builder.addBytes("id", value.id);13    builder.addEnum("kind", value.kind);14    builder.addEnum("limit_source", value.limit_source);15    addStorage(&builder, value.storage);16    builder.addDigest("capacity", spec.digest(value.capacity));17    addOverload(&builder, value.overload);18    addRisk(&builder, "transitive", value.risks.transitive);19    addRisk(&builder, "foreign", value.risks.foreign);20    addWork(&builder, value.work);21    addTextList(&builder, "dependencies", value.dependencies);22    addObligations(&builder, value.obligations);23    return builder.finish();24}

1/// This validator limit defines a maximum of 16 excluded descriptive strings in2/// a valid non-empty list, without enforcing a uniqueness check.3pub const excluded_max: usize = 16;

1/// This validator limit specifies a maximum of 64 bytes for canonical dotted2/// claim, dependency, or trust identifiers, under the root alias3/// `claim_id_bytes_max`.4pub const id_bytes_max: usize = 64;

1/// identifierValid checks whether a byte slice adheres to canonical dotted2/// identifier grammar, returning true on success. The slice must contain 1 to3/// 64 bytes divided into at least two non-empty segments separated by dots.4/// Segment characters are restricted to lowercase ASCII letters, digits, and5/// underscores, and segments may begin with a digit or underscore. The function6/// validates canonical identifier syntax only, without performing external7/// registry lookups or enforcing claim-local key grammar.8pub fn identifierValid(id: []const u8) bool {9    if (id.len == 0 or id.len > id_bytes_max) return false;10    var segments: usize = 1;11    var segment_length: usize = 0;12    for (id) |byte| {13        if (byte == '.') {14            if (segment_length == 0) return false;15            segments += 1;16            segment_length = 0;17            continue;18        }19        const lower = byte >= 'a' and byte <= 'z';20        const digit = byte >= '0' and byte <= '9';21        if (!lower and !digit and byte != '_') return false;22        segment_length += 1;23    }24    return segment_length != 0 and segments >= 2;25}

1/// This validator limit specifies a maximum of 24 named obligation records,2/// requiring a valid list to be non-empty.3pub const obligations_max: usize = 24;

1/// `record` enters a witness annotation into the Stardust claim table for the2/// enclosing test. It is `inline`, so the test stays the compiler's analysis3/// owner and the recorded row names that test even outside `comptime`. Without4/// the Stardust observer, as under an unpatched compiler or in a release, the5/// call records nothing, while `witness` still checks the obligation key.6pub inline fn record(comptime annotation: WitnessAnnotation) void {7    comptime observer.witness(annotation);8}

1/// selector takes any compile-time value and returns an anonymous struct type2/// containing a public constant named declaration initialized to that value.3/// This helper allows compile-time type fields to transport typed references4/// and values. The requirement that declaration resolve to a function is not5/// checked by selector itself, but is imposed only when validating a phase6/// binding family. The function neither validates the wrapped value nor creates7/// a callable runtime closure.8pub fn selector(comptime value: anytype) type {9    return struct {10        pub const declaration = value;11    };12}