alloc_phase.input

1/// Packed boolean structure that enables specific input capabilities on an2/// owner at compile time. All four fields default to `false`:3///4/// * `reader`: Enables stream acquisition through `read`.5///6/// * `file`: Enables filesystem acquisition through `readFile` and7/// `readFileWindow`.8/// * `preflight`: Enables size admission checks through `preflight`.9/// * `map_file_too_big`: Maps `error.FileTooBig` from an underlying `readFile`10/// call into a capacity rejection instead of propagating the raw I/O error.11///12/// Because an owner must support at least one input mechanism, specification13/// validation requires either `reader` or `file` to be enabled. Mapping14/// file-size errors requires filesystem support, so `map_file_too_big` can be15/// enabled only when `file` is also set to `true`. Individual acquisition16/// methods verify their corresponding flags at compile time and raise a compile17/// error when invoked without the required capability enabled.18pub const Acquisition = packed struct {19    reader: bool = false,20    file: bool = false,21    preflight: bool = false,22    map_file_too_big: bool = false,23};

1/// Error set returned when capacity derivation fails.2///3/// Members:4///5/// * `CapacityOverflow`: Adding one lookahead byte to the configured byte limit6/// overflowed the range of `usize`.7pub const DeriveError = error{CapacityOverflow};

1/// Defines the policy applied when an input exceeds the configured capacity2/// limit.3///4/// Tags:5///6/// * `terminal`: Permanently seals the owner upon capacity rejection. Any7/// subsequent acquisition attempt returns the capacity error immediately8/// without performing I/O or incrementing rejection counters.9/// * `recoverable`: Preserves owner availability across rejections. Oversized10/// inputs increment the rejection counter but leave the underlying storage free11/// for subsequent attempts.12///13/// Recovery designates the ability to reuse the allocated storage for later14/// inputs. It does not provide source-position rollback, record framing, or15/// automatic input drainage.16pub const Overload = enum {17    terminal,18    recoverable,19};

1/// Constructs an allocator-backed owner type for a single reusable input buffer2/// based on a static specification structure.3///4/// The `Spec` type parameter must satisfy several structural requirements:5///6/// * `Limits`: Structure defining input limits. It must contain the field7/// designated by `limit_field` typed as `usize`.8/// * `Capacity`: Structure defining storage requirements. It must expose a9/// `derive(limits: Limits) DeriveError!Capacity` function, the field named by10/// `limit_field` typed as `usize`, and `storage_bytes` typed as `usize`.11/// * `DeriveError`: Error set returned by `Capacity.derive`.12/// * `Exhaustion`: Error set returned when storage cannot admit an input.13/// * `Status`: Reporting structure returned by `status`. It must be a struct14/// containing exactly seven fields for recoverable owners or eight fields for15/// terminal owners: `phase: alloc_phase.capacity.Phase`, `in_use: bool`,16/// `storage_bytes: usize`, the mapped limit, loaded, and high-water fields17/// typed as `usize`, the mapped rejection field typed as `u64`, and18/// conditionally `terminal: bool` when `overload` is `terminal`.19/// * `acquisition`: An instance of `Acquisition` specifying enabled I/O20/// capabilities.21/// * `overload`: An instance of `Overload` setting either `.terminal` or22/// `.recoverable` behavior.23/// * Field mappings: `limit_field`, `loaded_field`, `high_water_field`, and24/// `rejected_field` specify field names on `Capacity` or `Status`. Callers must25/// supply distinct names for these fields. Compile-time validation verifies26/// field presence and total field counts, but this validation does not prove27/// that mapped field names are mutually distinct.28/// * Error instances: `in_use_error` and `capacity_error` must both have type29/// `Spec.Exhaustion`.30/// * `claim`: A static `alloc_phase.capacity.Declaration` metadata descriptor.31///32/// The owner asserts that `storage_bytes` strictly exceeds the configured byte33/// limit. While standard `deriveCapacity` derivation provides an exact `limit +34/// 1` layout, custom `Capacity.derive` implementations may describe larger35/// storage: derivation computes a `Capacity` value, while `init` allocates.36///37/// A successful read operation returns a borrowed `[]const u8` slice pointing38/// directly into the owned buffer and marks the owner as in use, including when39/// the input is empty. Borrowers must consume or copy these bytes elsewhere40/// before calling `release`. Slices must not be accessed after releasing the41/// owner.42///43/// A struct copy shares allocated storage but duplicates internal bookkeeping.44/// Copies are not independent owners: transferring exclusive ownership requires45/// callers to stop using the original. Callers must serialize operations and46/// ensure cleanup occurs exactly once.47///48/// The owner is not thread-safe and performs no internal synchronization.49/// Callers accessing an owner across threads must provide external mutual50/// exclusion.51///52/// Lifecycle checks across initialization, steady operation, and teardown are53/// enforced through debug assertions rather than explicit always-executed phase54/// panics.55pub fn OneRegion(comptime Spec: type) type {56    comptime requireSpec(Spec);57    return struct {58        phase: alloc_phase.capacity.Phase,59        capacity: Spec.Capacity,60        bytes: []u8,61        in_use: bool = false,62        terminal: bool = false,63        loaded_bytes: usize = 0,64        high_water_bytes: usize = 0,65        rejected_count: u64 = 0,6667        const Self = @This();6869        /// Result structure returned by `readFileWindow` representing a bounded70        /// slice of a file read at a positional offset.71        ///72        /// Fields:73        ///74        /// * `bytes`: Borrowed const byte slice containing admitted data. Its75        /// length is at most the requested window size.76        /// * `complete`: Boolean flag set to `true` when `read_bytes <=77        /// window_bytes`.78        ///79        /// The `complete` flag describes only this positional read and does not80        /// make an immutable snapshot against concurrent modification during or81        /// after it.82        pub const FileWindow = struct {83            bytes: []const u8,84            complete: bool,85        };8687        /// Type alias for `Spec.Limits`. Defines the input limit constraints88        /// supplied by the caller.89        pub const Limits: type = Spec.Limits;90        /// Type alias for `Spec.Capacity`. Holds derived storage dimensions,91        /// including the mandatory `storage_bytes` field.92        pub const Capacity: type = Spec.Capacity;93        /// Type alias for `Spec.Exhaustion`. Represents the error set returned94        /// when input operations encounter a busy buffer or exceed configured95        /// capacity.96        pub const Exhaustion: type = Spec.Exhaustion;97        /// Error set representing failures that can occur during98        /// initialization. Combines allocator allocation errors with99        /// `Spec.DeriveError`.100        pub const InitError = std.mem.Allocator.Error || Spec.DeriveError;101        /// Static capacity declaration describing the memory allocation102        /// semantics of the generated owner.103        ///104        /// The declaration retains the complete `Spec.claim.source` envelope105        /// while establishing fresh bindings for the generated owner:106        ///107        /// * `owner`: Binds the generated owner type `Self`.108        /// * `source`: Binds the originating `Spec` configuration type.109        /// * `seal`: Binds the `activate` method selector under the110        /// `checked_semantic_fact` class with `checker` authority.111        /// * `teardown`: Binds the `deinit` method selector under the112        /// `checked_semantic_fact` class with `checker` authority.113        ///114        /// The bindings defined on `Spec.claim.bindings` are not reused.115        /// Assigning premise labels to these new bindings does not prove their116        /// truth. Local specification checks verify only that `claim` has type117        /// `alloc_phase.capacity.Declaration`. Separate structural and118        /// declaration checking verifies lifecycle declaration shape, but that119        /// check does not prove whole-program allocation freedom.120        pub const claim: alloc_phase.capacity.Declaration = .{121            .source = Spec.claim.source,122            .bindings = .{123                .owner = Self,124                .source = Spec,125                .seal = .{126                    .family = alloc_phase.capacity.selector(Self.activate),127                    .premise = .{128                        .class = .checked_semantic_fact,129                        .authority = .checker,130                    },131                },132                .teardown = .{133                    .family = alloc_phase.capacity.selector(Self.deinit),134                    .premise = .{135                        .class = .checked_semantic_fact,136                        .authority = .checker,137                    },138                },139            },140        };141142        /// Initializes a new input region by deriving capacity and allocating143        /// the backing byte slice.144        ///145        /// The function derives capacity by evaluating146        /// `Capacity.derive(limits)`. When derivation succeeds, it allocates147        /// `capacity.storage_bytes` through the provided allocator. The148        /// initialized owner enters the `.initialization` phase and retains the149        /// allocated slice. The allocator handle itself is not stored on the150        /// instance, so callers must provide the same allocator during151        /// deinitialization.152        ///153        /// Initialization fails with `Spec.DeriveError` if capacity derivation154        /// fails, or with `error.OutOfMemory` if memory allocation fails.155        /// Before returning, debug assertions verify that the allocated slice156        /// length equals `storage_bytes` and strictly exceeds the configured157        /// byte limit.158        pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Self {159            const capacity = try Capacity.derive(limits);160            const bytes = try allocator.alloc(u8, capacity.storage_bytes);161            const storage = Self{162                .phase = .initialization,163                .capacity = capacity,164                .bytes = bytes,165            };166            storage.assertRegion();167            return storage;168        }169170        /// Transitions the owner from the initialization phase into steady171        /// operation.172        ///173        /// Callers must activate the owner before performing input operations.174        /// The function verifies through debug assertions that the owner175        /// resides in the `.initialization` phase and that the backing buffer176        /// satisfies region invariants. Once activated, `phase` transitions to177        /// `.steady`, permitting acquisition calls.178        pub fn activate(self: *Self) void {179            std.debug.assert(self.phase == .initialization);180            self.assertRegion();181            self.phase = .steady;182        }183184        /// Performs a size admission check for an expected input length without185        /// executing I/O or modifying buffer contents.186        ///187        /// This method requires `Spec.acquisition.preflight` to be enabled at188        /// compile time. Before evaluating the size, it verifies that the owner189        /// is available in steady operation. If an operation is currently190        /// active, it returns `Spec.in_use_error`. If the owner was previously191        /// sealed in a terminal state, it returns `Spec.capacity_error`.192        ///193        /// The proposed length `input_bytes` is cast to `usize`. If the value194        /// overflows `usize` or exceeds the configured byte limit, the method195        /// invokes internal rejection, incrementing the saturating rejection196        /// counter and applying the configured overload policy before returning197        /// `Spec.capacity_error`.198        ///199        /// A successful preflight check confirms only that the proposed size200        /// fits within the configured limit. It does not reserve storage, lock201        /// the buffer, or establish an atomic guarantee between checking a size202        /// and executing a later read.203        pub fn preflight(self: *Self, input_bytes: u64) Exhaustion!void {204            comptime requireAcquisition(Spec.acquisition.preflight, "preflight");205            try self.requireAvailable();206            const bounded = std.math.cast(usize, input_bytes) orelse207                return self.reject();208            if (bounded > self.limitBytes()) return self.reject();209        }210211        /// Reads data from a stream reader into the owned buffer and admits the212        /// resulting slice if its length falls within the configured limit.213        ///214        /// This method requires `Spec.acquisition.reader` to be enabled at215        /// compile time. It requires the owner to be available in steady216        /// operation, returning `Spec.in_use_error` if an active borrow exists217        /// or `Spec.capacity_error` if the owner is terminal.218        ///219        /// The method invokes `reader.readSliceShort` over the allocated220        /// storage slice. If reading from the underlying stream returns a221        /// `ShortError` such as `ReadFailed`, that error propagates directly to222        /// the caller. A read failure can occur after writing bytes into the223        /// buffer and consuming bytes from the stream, without establishing a224        /// borrow or recording a rejection. The method promises neither buffer225        /// rollback nor stream rewind nor record framing.226        ///227        /// When reading completes without stream error, the read byte count is228        /// evaluated:229        ///230        /// * If the count is at most the configured limit, the slice231        /// `self.bytes[0..input_bytes]` is admitted. The owner records the232        /// loaded length, updates the high-water mark, sets `in_use` to `true`,233        /// and returns the borrowed slice.234        /// * If the count exceeds the configured limit, the method rejects the235        /// input. It increments the rejection counter, transitions to terminal236        /// if configured, and returns `Spec.capacity_error`.237        ///238        /// When using helper-based capacity derivation through239        /// `deriveCapacity`, an oversized input fills the `limit + 1` storage240        /// bytes and triggers a capacity rejection after reading. This consumes241        /// `limit + 1` bytes from the stream without draining trailing input.242        /// Because reader implementations may buffer additional data,243        /// subsequent reads cannot assume framing alignment with a subsequent244        /// record.245        pub fn read(246            self: *Self,247            reader: *std.Io.Reader,248        ) (Exhaustion || std.Io.Reader.ShortError)![]const u8 {249            comptime requireAcquisition(Spec.acquisition.reader, "reader");250            try self.requireAvailable();251            const input_bytes = try reader.readSliceShort(self.bytes);252            return try self.admit(input_bytes);253        }254255        /// Reads a file from a directory into the bounded buffer and admits the256        /// resulting slice if the read length does not exceed the configured257        /// limit.258        ///259        /// This method requires `Spec.acquisition.file` to be enabled at260        /// compile time. It checks that the owner is available in steady261        /// operation before opening the file.262        ///263        /// Reading is executed through `dir.readFile` into the allocated buffer264        /// slice. Under the pinned standard library implementation, an ordinary265        /// oversized file fills the buffer prefix before admission rejects the266        /// input. Opening errors propagate directly, while a read error can267        /// occur after partial buffer writes and no borrow is admitted.268        ///269        /// Handling of `error.FileTooBig` depends on compile-time270        /// configuration:271        ///272        /// * When `Spec.acquisition.map_file_too_big` is `true`,273        /// `error.FileTooBig` is converted into a capacity rejection. This274        /// increments the rejection counter, transitions to terminal if275        /// configured, and returns `Spec.capacity_error`.276        /// * When `Spec.acquisition.map_file_too_big` is `false`,277        /// `error.FileTooBig` propagates directly to the caller without278        /// incrementing the rejection counter or modifying terminal state.279        ///280        /// All other filesystem I/O errors propagate directly to the caller281        /// without a capacity rejection or terminal transition under either282        /// setting. On success, the method returns a borrowed slice of the283        /// admitted bytes and marks the owner as in use.284        pub fn readFile(285            self: *Self,286            dir: std.Io.Dir,287            io: std.Io,288            file_path: []const u8,289        ) ![]const u8 {290            comptime requireAcquisition(Spec.acquisition.file, "file");291            try self.requireAvailable();292            const file = if (comptime Spec.acquisition.map_file_too_big)293                dir.readFile(io, file_path, self.bytes) catch |err| switch (err) {294                    error.FileTooBig => return self.reject(),295                    else => return err,296                }297            else298                try dir.readFile(io, file_path, self.bytes);299            return try self.admit(file.len);300        }301302        /// Reads a bounded positional window from a file at a specified offset303        /// without treating trailing bytes as a capacity rejection.304        ///305        /// This method requires `Spec.acquisition.file` to be enabled at306        /// compile time. Callers must supply a window size satisfying `0 <307        /// window_bytes <= limit`, which debug assertions verify. The owner308        /// must be available in steady operation before opening the target309        /// file.310        ///311        /// The method opens the file and reads up to `window_bytes + 1` bytes312        /// at the specified offset using positional I/O into `self.bytes[0 ..313        /// window_bytes + 1]`. Any filesystem I/O error during open or read314        /// propagates directly to the caller without a capacity rejection or315        /// borrow, though the buffer may be partially written.316        ///317        /// The read byte count determines completion and admission:318        ///319        /// * If the number of read bytes is less than or equal to320        /// `window_bytes`, `complete` is set to `true`.321        /// * If reading produces `window_bytes + 1` bytes, additional data322        /// exists beyond the window, setting `complete` to `false`. This323        /// condition does not trigger a capacity rejection or modify terminal324        /// status, even on terminal owners.325        ///326        /// The method admits `@min(read_bytes, window_bytes)`, which marks the327        /// owner as in use and returns a borrowed slice. An immediate EOF328        /// returning zero bytes still establishes an admitted zero-byte borrow.329        /// The `complete` flag describes only this positional read and is not330        /// an instantaneous snapshot against concurrent modifications.331        pub fn readFileWindow(332            self: *Self,333            dir: std.Io.Dir,334            io: std.Io,335            file_path: []const u8,336            offset: u64,337            window_bytes: usize,338        ) !FileWindow {339            comptime requireAcquisition(Spec.acquisition.file, "file");340            try self.requireAvailable();341            std.debug.assert(window_bytes > 0);342            std.debug.assert(window_bytes <= self.limitBytes());343            var file = try dir.openFile(io, file_path, .{});344            defer file.close(io);345            const read_bytes = try file.readPositionalAll(346                io,347                self.bytes[0 .. window_bytes + 1],348                offset,349            );350            const complete = read_bytes <= window_bytes;351            const admitted = try self.admit(@min(read_bytes, window_bytes));352            return .{ .bytes = admitted, .complete = complete };353        }354355        /// Releases an active borrow, allowing the internal buffer to be reused356        /// by future input operations.357        ///358        /// Callers must call this method only when the owner is in the359        /// `.steady` phase, holds an active borrow (`in_use` is `true`), and is360        /// not in a terminal state. Debug assertions verify these361        /// preconditions.362        ///363        /// Calling release sets `in_use` to `false` and resets `loaded_bytes`364        /// to zero. It does not overwrite or sanitize existing byte values in365        /// the buffer. Historical tracking metrics, including the high-water366        /// mark and the cumulative rejection count, remain intact across367        /// release calls.368        pub fn release(self: *Self) void {369            std.debug.assert(self.phase == .steady);370            std.debug.assert(self.in_use);371            std.debug.assert(!self.terminal);372            self.in_use = false;373            self.loaded_bytes = 0;374        }375376        /// Constructs and returns a snapshot of owner metrics and lifecycle377        /// state as a `Spec.Status` structure.378        ///379        /// The method copies configured status fields by value under caller380        /// serialization. Because the owner does not use atomic operations or381        /// internal synchronization, this method does not produce a coherent382        /// snapshot across concurrent unsynchronized access.383        ///384        /// The returned snapshot contains the following fields:385        ///386        /// * `phase`: Current lifecycle phase (`.initialization`, `.steady`, or387        /// `.teardown`).388        /// * `in_use`: Boolean flag indicating whether a borrowed buffer slice389        /// is currently outstanding.390        /// * `terminal`: Present on terminal owners to indicate whether391        /// capacity exhaustion permanently sealed the owner.392        /// * Configured limit field: Configured maximum byte limit derived from393        /// capacity.394        /// * `storage_bytes`: Total declared capacity of the buffer. Because395        /// this value reflects declared specification capacity, it does not396        /// represent a live allocation measurement and remains readable after397        /// teardown.398        /// * Configured loaded field: Number of admitted bytes currently held399        /// by an active borrow. This field is zero whenever the owner is not in400        /// use.401        /// * Configured high-water field: Largest admitted byte count observed402        /// across all successful reads since initialization. Oversized inputs403        /// rejected during admission do not update this value.404        /// * Configured rejected field: Cumulative saturating count of capacity405        /// rejections.406        pub fn status(self: *const Self) Spec.Status {407            var result: Spec.Status = undefined;408            result.phase = self.phase;409            result.in_use = self.in_use;410            if (comptime @hasField(Spec.Status, "terminal")) {411                result.terminal = self.terminal;412            }413            @field(result, Spec.limit_field) = self.limitBytes();414            result.storage_bytes = self.capacity.storage_bytes;415            @field(result, Spec.loaded_field) = self.loaded_bytes;416            @field(result, Spec.high_water_field) = self.high_water_bytes;417            @field(result, Spec.rejected_field) = self.rejected_count;418            return result;419        }420421        /// Deinitializes the owner and frees its allocated byte buffer using422        /// the provided allocator.423        ///424        /// Callers must supply the same allocator used for `init`. The method425        /// verifies through debug assertions that the owner has not already426        /// entered teardown and that no borrowed slice is currently in use427        /// (`in_use` is `false`).428        ///429        /// Deinitialization transitions `phase` to `.teardown`, frees the430        /// allocated memory slice, clears the internal buffer slice to empty,431        /// and resets `loaded_bytes` to zero. Callers may invoke this method432        /// while the owner is still in the `.initialization` phase to clean up433        /// resources after a failed startup sequence. Cumulative metrics and434        /// capacity declarations remain stored on the instance after435        /// deinitialization completes.436        pub fn deinit(self: *Self, allocator: std.mem.Allocator) void {437            std.debug.assert(self.phase != .teardown);438            std.debug.assert(!self.in_use);439            self.assertRegion();440            self.phase = .teardown;441            allocator.free(self.bytes);442            self.bytes = &.{};443            self.loaded_bytes = 0;444        }445446        /// Verifies that the owner is ready to accept a new input operation.447        ///448        /// Debug assertions confirm that the owner resides in the `.steady`449        /// phase, that buffer invariants hold, and that previous loaded bytes450        /// did not exceed the limit. If the owner is marked terminal, the451        /// function returns `Spec.capacity_error` without incrementing the452        /// rejection counter. If a borrow is currently active, it returns453        /// `Spec.in_use_error` without incrementing the rejection counter. When454        /// available, debug assertions verify that `loaded_bytes` is zero.455        fn requireAvailable(self: *Self) Exhaustion!void {456            std.debug.assert(self.phase == .steady);457            self.assertRegion();458            std.debug.assert(self.loaded_bytes <= self.limitBytes());459            if (self.terminal) return Spec.capacity_error;460            if (self.in_use) return Spec.in_use_error;461            std.debug.assert(self.loaded_bytes == 0);462        }463464        /// Admits a specified number of bytes into the region or rejects the465        /// payload if it exceeds the configured limit.466        ///467        /// Debug assertions verify that the owner is in steady operation468        /// without an active borrow or terminal state, and that the requested469        /// byte count does not exceed allocated storage. If `input_bytes`470        /// exceeds the configured byte limit, the function invokes `reject`.471        /// Otherwise, it marks the buffer as in use, records `loaded_bytes`,472        /// updates `high_water_bytes` if the new length exceeds previous473        /// admissions, and returns a borrowed slice over the admitted bytes.474        fn admit(self: *Self, input_bytes: usize) Exhaustion![]const u8 {475            std.debug.assert(self.phase == .steady);476            std.debug.assert(!self.in_use);477            std.debug.assert(!self.terminal);478            std.debug.assert(input_bytes <= self.capacity.storage_bytes);479            if (input_bytes > self.limitBytes()) return self.reject();480            self.in_use = true;481            self.loaded_bytes = input_bytes;482            self.high_water_bytes = @max(self.high_water_bytes, input_bytes);483            return self.bytes[0..input_bytes];484        }485486        /// Records an input capacity rejection and updates owner overload487        /// state.488        ///489        /// Debug assertions verify that the owner is in steady operation, is490        /// not in use, is not already terminal, and holds zero loaded bytes. If491        /// `Spec.overload` is configured as `.terminal`, the owner enters the492        /// terminal state. The cumulative rejection counter is incremented493        /// using saturating addition, and the function returns494        /// `Spec.capacity_error`.495        fn reject(self: *Self) Exhaustion {496            std.debug.assert(self.phase == .steady);497            std.debug.assert(!self.in_use);498            std.debug.assert(!self.terminal);499            std.debug.assert(self.loaded_bytes == 0);500            self.terminal = Spec.overload == .terminal;501            self.rejected_count +|= 1;502            return Spec.capacity_error;503        }504505        /// Helper function returning the configured byte limit stored on506        /// `self.capacity` using the field name defined by `Spec.limit_field`.507        fn limitBytes(self: *const Self) usize {508            return @field(self.capacity, Spec.limit_field);509        }510511        /// Helper function asserting that the backing byte slice length matches512        /// `storage_bytes` and strictly exceeds the configured byte limit.513        fn assertRegion(self: *const Self) void {514            std.debug.assert(self.bytes.len == self.capacity.storage_bytes);515            std.debug.assert(self.capacity.storage_bytes > self.limitBytes());516        }517    };518}

1/// Derives an instance of `Capacity` from a given `Limits` structure by adding2/// one lookahead byte to the configured input limit.3///4/// The input limit is retrieved from the field named by `limit_field` on5/// `limits`. Both the limit field on `Limits` and `Capacity` and the6/// `storage_bytes` field on `Capacity` must be typed as `usize`. When addition7/// overflows `usize`, the function returns `error.CapacityOverflow`. A limit of8/// zero derives a storage size of one byte.9///10/// The returned `Capacity` structure initializes only the field named by11/// `limit_field` and `storage_bytes`. Any additional fields present on12/// `Capacity` remain undefined. Callers must keep `limit_field` distinct from13/// `storage_bytes` so that writing `storage_bytes` does not overwrite the limit14/// field.15pub fn deriveCapacity(16    comptime Limits: type,17    comptime Capacity: type,18    comptime limit_field: []const u8,19    limits: Limits,20) DeriveError!Capacity {21    comptime requireCapacityTypes(Limits, Capacity, limit_field);22    const limit_bytes = @field(limits, limit_field);23    const storage_bytes = try alloc_phase.capacity.add(usize, limit_bytes, 1);24    std.debug.assert(storage_bytes > limit_bytes);25    std.debug.assert(storage_bytes != 0);26    var capacity: Capacity = undefined;27    @field(capacity, limit_field) = limit_bytes;28    capacity.storage_bytes = storage_bytes;29    return capacity;30}

1//! ## Package overview2//!3//! When we ingest external input from streams or files, we want to accept4//! bounded payloads using a single reusable byte allocation without allocating5//! on every message or resizing buffers on the fly. We configure an explicit6//! upper bound on accepted length, allocate storage once, and reuse that7//! storage across successive operations while detecting oversized inputs before8//! admitting them.9//!10//! ## One buffer and lookahead11//!12//! The core challenge in bounded ingestion sits at the boundary of the limit.13//! If we configure our system to accept at most `n` bytes and allocate an14//! `n`-byte buffer, filling that buffer completely leaves an ambiguity: did the15//! input stream end precisely at `n` bytes, or does more data remain waiting in16//! the channel? To resolve whether the input fits or exceeds our boundary, this17//! implementation reserves space for one extra byte. For an accepted limit of18//! `n` bytes, the backing buffer holds `n + 1` bytes. When we read from the19//! source into the buffer:20//!21//! - If the source yields between 0 and `n` bytes before reaching end-of-file,22//!   the input fits within our configured boundary and we admit it.23//! - If the source yields `n + 1` bytes, the input exceeds our limit and we24//!   reject it immediately, without allocating a second buffer.25//!26//! We term this calculation *capacity derivation*. The standard helper27//! `deriveCapacity` computes this boundary for an owner. Given a configuration28//! structure containing a byte limit field of type `usize`, it uses checked29//! integer addition to compute `n + 1`. If adding one to the limit overflows30//! `usize`, derivation fails with `error.CapacityOverflow`. When a caller31//! configures a limit of zero, derivation reserves one byte, which allows an32//! empty input to be distinguished from an input containing data.33//!34//! The `deriveCapacity` helper initializes only two fields in the resulting35//! capacity record: the configured limit and the derived `storage_bytes`. The36//! limit field name and `storage_bytes` must be distinct. Any additional fields37//! declared on the capacity type remain undefined, so a custom capacity type38//! that requires extra fields must populate them in a custom derivation39//! function.40//!41//! The generic container `OneRegion(Spec)` produces an allocator-backed owner42//! around this storage model. While `deriveCapacity` enforces the standard `n +43//! 1` sizing rule, a custom derivation function may describe larger storage44//! when required by domain constraints: derivation computes a `Capacity` value,45//! while `init` allocates the storage. The owner asserts that `storage_bytes`46//! strictly exceeds the configured input limit.47//!48//! ## A successful borrow and release49//!50//! Because a single byte buffer is reused across requests, concurrent access51//! would corrupt in-flight payloads. An outstanding borrow represents temporary52//! exclusive access granted to an admitted input. Until that borrow is53//! relinquished, the owner enforces busy protection across subsequent54//! acquisition and preflight calls.55//!56//! The lifecycle of an input owner progresses through three sequential phases:57//! initialization, steady operation, and teardown. Calling `init` enters the58//! initialization phase, calling `activate` advances to steady operation, and59//! calling `deinit` enters teardown. Calling `deinit` requires that no borrow60//! remains outstanding. If startup fails prior to activation, `deinit` can be61//! called directly from the initialization phase to free the buffer.62//!63//! During initialization, `init` derives the capacity and requests a single64//! contiguous slice of `storage_bytes` from the provided allocator. If capacity65//! derivation overflows or the allocator fails, `init` returns an error union66//! of `DeriveError` and `std.mem.Allocator.Error`. Once allocated, the owner67//! retains the byte slice but does not retain an allocator handle. In steady68//! operation, the owner methods do not call the initialization allocator. The69//! absence of a retained allocator on the owner does not prevent arbitrary70//! readers or filesystem code from allocating dynamically or performing71//! external work.72//!73//! Phase transitions are guarded by debug assertions (`std.debug.assert`),74//! which verify that `activate` is called only from the initialization phase75//! and that `deinit` is called with no active borrow. These debug assertions76//! differ from the explicit wrong-phase panics enforced by the separate phase77//! allocator.78//!79//! In steady operation, calling `read` ingests data into the buffer and admits80//! the payload if the returned length does not exceed the configured limit. A81//! successful read returns a borrowed constant slice (`[]const u8`) and sets82//! the internal `in_use` flag. Even an empty zero-byte read establishes an83//! active borrow and marks the owner busy. While `in_use` remains true, any84//! attempt to read, window, or preflight another input returns `in_use_error`.85//! This failure indicates a busy owner and does not increment the capacity86//! rejection counter.87//!88//! When the caller finishes processing the borrowed slice, it invokes89//! `release`. Calling `release` sets `in_use` to false and resets the loaded90//! byte counter to zero. It does not zero or scrub the underlying memory, nor91//! does it reset historical rejection counts or high-water marks.92//!93//! Because reads overwrite the backing buffer, a caller that needs to retain94//! admitted bytes across subsequent operations must copy them into separate95//! storage before calling `release`. A fixed stack array provides a convenient96//! target for preserving small records without allocating heap memory.97//!98//! Copies of an owner struct share the underlying byte slice while duplicating99//! internal bookkeeping. Because copies are not independent owners, callers100//! must serialize operations and ensure that cleanup occurs exactly once.101//! Calling `deinit` requires that no borrow remains outstanding, transitions102//! the phase to teardown, and frees the slice using the same allocator passed103//! during initialization. The owner provides no secondary abort or partial104//! teardown routines.105//!106//! In the Issue tool, body storage adopts this borrow discipline. Its107//! `BodySource` container pairs a borrowed slice of the input region with an108//! optional pointer to the owner. When processing finishes or an empty body109//! triggers an early exit, the consumer releases the borrow before reporting110//! results. Command-line arguments provided directly in the process invocation111//! bypass the input region entirely, leaving the buffer available for file or112//! standard-input ingestion.113//!114//! ## Failure and recovery115//!116//! When an incoming payload exceeds the configured limit, the owner rejects the117//! admission. How the owner responds to this overload depends on whether it is118//! configured with a terminal or recoverable policy:119//!120//! - A terminal owner treats an oversized input as a permanent boundary fault.121//!   Upon rejection, it increments a saturating 64-bit rejection counter, sets122//!   an internal `terminal` flag, and refuses all subsequent read attempts with123//!   `capacity_error` without incrementing the counter again.124//! - A recoverable owner increments the rejection counter but leaves `terminal`125//!   false. Storage remains immediately available to accept another input126//!   without an acknowledgement step.127//!128//! Recovery denotes the ability to reuse the owned memory buffer for a future129//! request: it does not imply stream rewinding, transaction rollback, or130//! automatic framing.131//!132//! When reading from a stream through `Reader.readSliceShort`, capacity133//! rejection under the standard derivation helper occurs after reading up to134//! `limit + 1` logical bytes into the buffer. The owner does not drain any135//! remaining bytes left in the underlying stream. If an external caller136//! attempts to read from that same stream again, the retry does not guarantee137//! alignment with the start of a logical record. User reader implementations138//! may also maintain internal buffers or perform dynamic allocations outside139//! the owner's knowledge. If a stream encounters an I/O failure such as140//! `ReadFailed`, the failure can consume source bytes and overwrite buffer141//! contents. In that situation, no borrow is admitted and the owner's capacity142//! rejection counter does not increment.143//!144//! To avoid reading unwanted bytes when an input size is known beforehand, an145//! application can call `preflight`. The `preflight` method accepts an expected146//! size as a 64-bit integer, checks that the owner is available, and verifies147//! that the size fits within `usize` and does not exceed the limit. If the148//! proposed size cannot be represented in `usize` or exceeds the limit,149//! `preflight` rejects the request, updates rejection accounting, and returns150//! `capacity_error`. A successful preflight verifies available space, but it151//! neither reserves storage nor forms an atomic transaction with a subsequent152//! read.153//!154//! Calling `status` returns a snapshot structure by value containing the155//! current phase, the `in_use` flag, the configured limit, the declared storage156//! size, the currently loaded bytes, the high-water mark of admitted bytes, the157//! cumulative rejection count, and the terminal flag for terminal owners. The158//! high-water mark records the largest admitted input, ignoring rejected159//! attempts. Following `deinit`, the historical counters and declared capacity160//! fields remain readable in the returned status snapshot, which means161//! `storage_bytes` reports declared storage size rather than live retained heap162//! memory.163//!164//! The Peek image decoding pipeline relies on a recoverable configuration. Its165//! loader reads image files into the input buffer, holds the borrow while166//! decoding pixel data into external image structures, and releases the owner167//! immediately after decoding. If an oversized image is rejected, the owner168//! remains active, enabling subsequent file reads to reuse the same memory169//! allocation.170//!171//! ## Whole files versus windows172//!173//! Reading files introduces distinct concerns regarding whole-file ingestion174//! versus positional slice inspection.175//!176//! Calling `readFile` reads an input file into the bounded buffer using the177//! standard library directory interface. When reading an ordinary file whose178//! size exceeds the limit, the reader fills the buffer prefix and the owner179//! rejects the operation. The acquisition specification provides a180//! configuration flag named `map_file_too_big`:181//!182//! - When `map_file_too_big` is enabled, an underlying `FileTooBig` error183//!   returned by the filesystem maps directly into the owner's capacity184//!   rejection, incrementing the rejection counter and setting the terminal185//!   flag if configured.186//! - When `map_file_too_big` is disabled, `FileTooBig` propagates outward as a187//!   filesystem error, bypassing rejection accounting and leaving the terminal188//!   flag unset.189//! - Other filesystem errors, such as missing files or access faults, propagate190//!   unchanged under either setting without modifying capacity counters.191//!192//! When inputs exceed the capacity of our buffer, reading the entire file at193//! once is impossible. Instead, we inspect bounded portions of the file using194//! `readFileWindow`.195//!196//! Calling `readFileWindow` requires that file acquisition is enabled, that197//! storage is available, and that the requested window length satisfies `0 <198//! window_bytes <= limit`. The method reads up to `window_bytes + 1` bytes at a199//! specified file offset, admits `min(read_count, window_bytes)`, and returns a200//! `FileWindow` structure containing the borrowed slice and a boolean201//! `complete` flag.202//!203//! If the file contains bytes beyond the requested window, the lookahead byte204//! is populated, `complete` is set to false, and the admitted slice contains205//! exactly `window_bytes`. An incomplete window read does not trigger a206//! capacity rejection, even when the owner is configured as terminal. If the207//! offset sits at end-of-file, a zero-byte read completes successfully and208//! still establishes an active borrow. The `complete` flag describes only the209//! result of this specific positional read: it does not provide an210//! instantaneous file-length snapshot or guarantee that the file will not grow211//! concurrently.212//!213//! Glom demonstrates how windowed ingestion coordinates with record framing.214//! Glom ingests structured transcript files using a terminal input owner with215//! preflight enabled. Because individual transcript records vary in length and216//! files can grow large, its parser reads a positional window from the file. If217//! `complete` is false, the window ended before the end of the file. Glom218//! inspects the admitted bytes for the last newline character, processes219//! complete lines up to that delimiter, releases the borrow, and advances its220//! file offset to resume reading. If a maximum-sized window contains no newline221//! delimiter at all, the consumer itself raises a record-framing error. Framing222//! logic remains the responsibility of the consumer, while the input region223//! guarantees only the bounded byte window.224//!225//! ## Declaration scope and interface shapes226//!227//! To integrate an input owner with verification and capacity tooling, we228//! encapsulate its configuration within a `Spec` structure. A specification229//! packages input limit and capacity types, error sets, status layout, enabled230//! acquisition capabilities, overload policy, and a formal capacity231//! `Declaration`.232//!233//! The status structure must declare exactly seven fields for recoverable234//! owners or eight fields for terminal owners. While the generic checker235//! validates the field count and types, it does not verify that custom field236//! mappings are distinct from one another. We must supply distinct field names237//! to prevent diagnostic collisions.238//!239//! The capacity `Declaration` establishes the structural contract of the owner240//! for this example:241//!242//! - Validation of `phase_static` requires valid seal and teardown bindings.243//!   The tag describes a claim and does not govern actual allocation behavior244//!   or enforce an operational lifetime. The limit source is marked as245//!   `.caller`, indicating that limits are supplied at initialization.246//! - The storage section specifies covered memory, naming the single247//!   steady-state input buffer and describing its purpose. Excluded clauses248//!   document runtime resources that sit outside the claim, such as stream249//!   reader handles and destination parsing structures.250//! - The capacity model defines an expression graph capturing the `n + 1`251//!   derivation. An input node binds the limit field, an integer constant node252//!   provides the literal 1, and an addition node sums them. An assertion253//!   declares that total retained storage matches this expression.254//! - The overload policy is declared as `.drop`, documenting that oversized255//!   input is rejected while storage remains available for a later attempt. The256//!   `.drop` policy does not preserve previously released payload bytes:257//!   subsequent reads can overwrite released bytes in the backing buffer.258//! - Transitive and foreign operational risks are marked as `.open`,259//!   acknowledging that reader streams or filesystem calls can incur effects260//!   outside the region boundaries.261//! - The declaration lists obligations for the capacity model and the overload262//!   policy.263//!264//! When `OneRegion(Spec)` generates an owner, it constructs fresh bindings265//! linking the owner type, the specification, and selectors for `activate` and266//! `deinit`. It does not reuse any bindings declared on `Spec.claim`. Claim267//! declarations and premise labels such as `.checked_semantic_fact` provide268//! structural metadata for verification tools: they do not establish proven269//! semantic facts or whole-program safety guarantees.270//!271//! We validate this generated structure at compile time using272//! `alloc_phase.capacity.requireAllocatorRejectingOwnerShape(Storage)`. This273//! function performs structural reflection, checking that the owner provides274//! required lifecycle functions, exposes an exhaustion error set on receiver275//! methods, and presents a compatible claim.276//!277//! The following test illustrates a specification and recoverable input owner:278//!279//! ```zig280//! const std = @import("std");281//! const alloc_phase = @import("alloc_phase");282//!283//! pub const InputLimits = struct {284//!     max_bytes: usize,285//! };286//!287//! pub const InputCapacity = struct {288//!     max_bytes: usize,289//!     storage_bytes: usize,290//!291//!     pub fn derive(limits: InputLimits) alloc_phase.input.DeriveError!InputCapacity {292//!         return alloc_phase.input.deriveCapacity(InputLimits, InputCapacity, "max_bytes", limits);293//!     }294//! };295//!296//! pub const InputExhaustion = error{297//!     InputStorageBusy,298//!     InputCapacityExceeded,299//! };300//!301//! pub const InputStatus = struct {302//!     phase: alloc_phase.capacity.Phase,303//!     in_use: bool,304//!     max_bytes: usize,305//!     storage_bytes: usize,306//!     loaded_bytes: usize,307//!     high_water_bytes: usize,308//!     rejected_count: u64,309//! };310//!311//! pub const Spec = struct {312//!     pub const Limits = InputLimits;313//!     pub const Capacity = InputCapacity;314//!     pub const Exhaustion = InputExhaustion;315//!     pub const Status = InputStatus;316//!     pub const DeriveError = alloc_phase.input.DeriveError;317//!     pub const acquisition: alloc_phase.input.Acquisition = .{318//!         .reader = true,319//!         .preflight = true,320//!     };321//!     pub const overload: alloc_phase.input.Overload = .recoverable;322//!     pub const limit_field = "max_bytes";323//!     pub const loaded_field = "loaded_bytes";324//!     pub const high_water_field = "high_water_bytes";325//!     pub const rejected_field = "rejected_count";326//!     pub const in_use_error: Exhaustion = error.InputStorageBusy;327//!     pub const capacity_error: Exhaustion = error.InputCapacityExceeded;328//!329//!     pub const claim: alloc_phase.capacity.Declaration = .{330//!         .source = .{331//!             .id = "guide.recoverable_reader",332//!             .kind = .phase_static,333//!             .limit_source = .caller,334//!             .storage = .{335//!                 .covered = &.{336//!                     .{337//!                         .id = "reusable_input_buffer",338//!                         .lifetime = .steady,339//!                         .detail = "one reusable input and lookahead byte region",340//!                     },341//!                 },342//!                 .excluded = &.{343//!                     "stream reader buffering and allocator handles",344//!                     "caller payload storage outside the borrowed window",345//!                 },346//!             },347//!             .capacity = .{348//!                 .inputs = &.{349//!                     alloc_phase.capacity.bindInput(InputLimits, "max_bytes", "max_bytes"),350//!                 },351//!                 .type_selectors = &.{},352//!                 .nodes = &.{353//!                     .{ .input = 0 },354//!                     .{ .constant = 1 },355//!                     .{ .add = .{ .left = 0, .right = 1 } },356//!                 },357//!                 .assertions = &.{358//!                     .{359//!                         .scope = .closure_total,360//!                         .measure = .retained,361//!                         .relation = .exact,362//!                         .expression = 2,363//!                     },364//!                 },365//!             },366//!             .overload = .{367//!                 .kind = .drop,368//!                 .detail = "oversized input is rejected while storage remains available for a later attempt",369//!             },370//!             .risks = .{371//!                 .transitive = .{372//!                     .status = .open,373//!                     .detail = "stream operations may perform external allocations",374//!                 },375//!                 .foreign = .{376//!                     .status = .open,377//!                     .detail = "kernel stream handles remain unmanaged",378//!                 },379//!             },380//!             .obligations = &.{381//!                 .{ .key = "input_capacity_model", .role = .capacity_model },382//!                 .{ .key = "input_overload_policy", .role = .overload },383//!             },384//!         },385//!         .bindings = .{},386//!     };387//! };388//!389//! pub const Storage = alloc_phase.input.OneRegion(Spec);390//!391//! comptime {392//!     alloc_phase.capacity.requireAllocatorRejectingOwnerShape(Storage);393//! }394//!395//! test "recoverable input storage lifecycle, borrow discipline, and reuse" {396//!     const allocator = std.testing.allocator;397//!     var storage = try Storage.init(allocator, .{ .max_bytes = 5 });398//!     defer storage.deinit(allocator);399//!     defer if (storage.in_use) storage.release();400//!401//!     storage.activate();402//!403//!     var first_reader: std.Io.Reader = .fixed("hello");404//!     const borrowed = try storage.read(&first_reader);405//!406//!     try std.testing.expectEqual(@as(usize, 5), borrowed.len);407//!     try std.testing.expectEqualStrings("hello", borrowed);408//!     try std.testing.expectError(error.InputStorageBusy, storage.preflight(0));409//!410//!     var preserved: [5]u8 = undefined;411//!     @memcpy(&preserved, borrowed);412//!413//!     storage.release();414//!415//!     try std.testing.expectEqualStrings("hello", &preserved);416//!417//!     const status_after_release = storage.status();418//!     try std.testing.expect(!status_after_release.in_use);419//!     try std.testing.expectEqual(@as(usize, 0), status_after_release.loaded_bytes);420//!     try std.testing.expectEqual(@as(usize, 5), status_after_release.high_water_bytes);421//!     try std.testing.expectEqual(@as(u64, 0), status_after_release.rejected_count);422//!423//!     try std.testing.expectError(error.InputCapacityExceeded, storage.preflight(6));424//!425//!     const status_after_reject = storage.status();426//!     try std.testing.expectEqual(@as(u64, 1), status_after_reject.rejected_count);427//!428//!     var second_reader: std.Io.Reader = .fixed("zig");429//!     const second_borrow = try storage.read(&second_reader);430//!431//!     try std.testing.expectEqualStrings("zig", second_borrow);432//!433//!     const status_final = storage.status();434//!     try std.testing.expect(status_final.in_use);435//!     try std.testing.expectEqual(@as(usize, 3), status_final.loaded_bytes);436//!     try std.testing.expectEqual(@as(usize, 5), status_final.high_water_bytes);437//!438//!     try std.testing.expectEqualStrings("hello", &preserved);439//!440//!     storage.release();441//! }442//! ```443//!444//! The source unit tests for `alloc_phase.input` assert capacity derivation445//! from 31 to 32 bytes, overflow detection at integer limits, initialization446//! failure under allocation faults, exact acceptance of fitting payloads, busy447//! errors during active borrows, saturating rejection counters on terminal448//! owners, and recoverable reuse following an oversized preflight check.449//! Additional property tests assert `n + 1` allocation sizing for limits up to450//! 4096 bytes, and consumer test suites exercise windowed reads alongside file451//! boundary handling.452453const one = @import("one.zig");454455/// Packed boolean structure that enables specific input capabilities on an456/// owner at compile time. All four fields default to `false`:457///458/// * `reader`: Enables stream acquisition through `read`.459///460/// * `file`: Enables filesystem acquisition through `readFile` and461/// `readFileWindow`.462/// * `preflight`: Enables size admission checks through `preflight`.463/// * `map_file_too_big`: Maps `error.FileTooBig` from an underlying `readFile`464/// call into a capacity rejection instead of propagating the raw I/O error.465///466/// Because an owner must support at least one input mechanism, specification467/// validation requires either `reader` or `file` to be enabled. Mapping468/// file-size errors requires filesystem support, so `map_file_too_big` can be469/// enabled only when `file` is also set to `true`. Individual acquisition470/// methods verify their corresponding flags at compile time and raise a compile471/// error when invoked without the required capability enabled.472pub const Acquisition = one.Acquisition;473/// Error set returned when capacity derivation fails.474///475/// Members:476///477/// * `CapacityOverflow`: Adding one lookahead byte to the configured byte limit478/// overflowed the range of `usize`.479pub const DeriveError = one.DeriveError;480/// Constructs an allocator-backed owner type for a single reusable input buffer481/// based on a static specification structure.482///483/// The `Spec` type parameter must satisfy several structural requirements:484///485/// * `Limits`: Structure defining input limits. It must contain the field486/// designated by `limit_field` typed as `usize`.487/// * `Capacity`: Structure defining storage requirements. It must expose a488/// `derive(limits: Limits) DeriveError!Capacity` function, the field named by489/// `limit_field` typed as `usize`, and `storage_bytes` typed as `usize`.490/// * `DeriveError`: Error set returned by `Capacity.derive`.491/// * `Exhaustion`: Error set returned when storage cannot admit an input.492/// * `Status`: Reporting structure returned by `status`. It must be a struct493/// containing exactly seven fields for recoverable owners or eight fields for494/// terminal owners: `phase: alloc_phase.capacity.Phase`, `in_use: bool`,495/// `storage_bytes: usize`, the mapped limit, loaded, and high-water fields496/// typed as `usize`, the mapped rejection field typed as `u64`, and497/// conditionally `terminal: bool` when `overload` is `terminal`.498/// * `acquisition`: An instance of `Acquisition` specifying enabled I/O499/// capabilities.500/// * `overload`: An instance of `Overload` setting either `.terminal` or501/// `.recoverable` behavior.502/// * Field mappings: `limit_field`, `loaded_field`, `high_water_field`, and503/// `rejected_field` specify field names on `Capacity` or `Status`. Callers must504/// supply distinct names for these fields. Compile-time validation verifies505/// field presence and total field counts, but this validation does not prove506/// that mapped field names are mutually distinct.507/// * Error instances: `in_use_error` and `capacity_error` must both have type508/// `Spec.Exhaustion`.509/// * `claim`: A static `alloc_phase.capacity.Declaration` metadata descriptor.510///511/// The owner asserts that `storage_bytes` strictly exceeds the configured byte512/// limit. While standard `deriveCapacity` derivation provides an exact `limit +513/// 1` layout, custom `Capacity.derive` implementations may describe larger514/// storage: derivation computes a `Capacity` value, while `init` allocates.515///516/// A successful read operation returns a borrowed `[]const u8` slice pointing517/// directly into the owned buffer and marks the owner as in use, including when518/// the input is empty. Borrowers must consume or copy these bytes elsewhere519/// before calling `release`. Slices must not be accessed after releasing the520/// owner.521///522/// A struct copy shares allocated storage but duplicates internal bookkeeping.523/// Copies are not independent owners: transferring exclusive ownership requires524/// callers to stop using the original. Callers must serialize operations and525/// ensure cleanup occurs exactly once.526///527/// The owner is not thread-safe and performs no internal synchronization.528/// Callers accessing an owner across threads must provide external mutual529/// exclusion.530///531/// Lifecycle checks across initialization, steady operation, and teardown are532/// enforced through debug assertions rather than explicit always-executed phase533/// panics.534pub const OneRegion = one.OneRegion;535/// Defines the policy applied when an input exceeds the configured capacity536/// limit.537///538/// Tags:539///540/// * `terminal`: Permanently seals the owner upon capacity rejection. Any541/// subsequent acquisition attempt returns the capacity error immediately542/// without performing I/O or incrementing rejection counters.543/// * `recoverable`: Preserves owner availability across rejections. Oversized544/// inputs increment the rejection counter but leave the underlying storage free545/// for subsequent attempts.546///547/// Recovery designates the ability to reuse the allocated storage for later548/// inputs. It does not provide source-position rollback, record framing, or549/// automatic input drainage.550pub const Overload = one.Overload;551/// Derives an instance of `Capacity` from a given `Limits` structure by adding552/// one lookahead byte to the configured input limit.553///554/// The input limit is retrieved from the field named by `limit_field` on555/// `limits`. Both the limit field on `Limits` and `Capacity` and the556/// `storage_bytes` field on `Capacity` must be typed as `usize`. When addition557/// overflows `usize`, the function returns `error.CapacityOverflow`. A limit of558/// zero derives a storage size of one byte.559///560/// The returned `Capacity` structure initializes only the field named by561/// `limit_field` and `storage_bytes`. Any additional fields present on562/// `Capacity` remain undefined. Callers must keep `limit_field` distinct from563/// `storage_bytes` so that writing `storage_bytes` does not overwrite the limit564/// field.565pub const deriveCapacity = one.deriveCapacity;

1/// Bounded reusable input buffer storage (`OneRegion`). Configures a reusable2/// byte buffer, enforces exclusive borrow and release discipline, and provides3/// recoverable or terminal overload options. See4/// [input/root.zig](input/root.zig).5pub const input = @import("input/root.zig");