tiny.reducer.bytes.model

1//! Data model for byte reduction: the error types, the oracle interface, and2//! the settings of a run. A run works against the caller's function that3//! answers whether one candidate still reproduces the defect, the *oracle*,4//! whose type is `InterestingFn`. The oracle answers *interesting* when a5//! candidate (one shorter byte sequence built by deleting a run of bytes from6//! the current sequence and handed to the oracle) satisfies the failure7//! property under investigation, and answers *uninteresting* when the candidate8//! does not show that failure.9//!10//! ## Error Classification11//!12//! The errors the package raises itself fall into two sets:13//! - `Exhaustion` covers a resource bound and a conflicting use of the14//!   workspace: `InputCapacityExceeded` and `ReductionStorageInUse`.15//! - `InputError` covers a broken contract and an insufficient budget:16//!   `AttemptBudgetExhausted` and `InitialInputUninteresting`.17//!18//! The `Error` alias lists those framework errors, while `reduce()` returns19//! `anyerror!Result`, because a caller's callback may return any error at all,20//! including one whose name matches a standard error name. An error the oracle21//! returns travels straight out through `reduce()`, ending the run and giving22//! up the lease this call acquired.2324/// This error set gathers the errors the reduction framework produces directly.25/// The set leaves out the errors a caller's predicate returns, which `reduce()`26/// passes through as `anyerror`, so that error travels outward to the caller.27pub const Error = Exhaustion || InputError;2829/// These failures arise from the workspace bounds or from another run already30/// holding the workspace.31pub const Exhaustion = error{32    /// The input slice is longer than the `Limits.max_input_bytes` the33    /// `Storage` instance was allocated for.34    InputCapacityExceeded,3536    /// The `Storage` instance is already held by a running reduction or by a37    /// `Result` whose `deinit()` has yet to be called, so a reentrant call, and38    /// a second call made while the first run's result is still live, are both39    /// refused before any workspace byte changes.40    ReductionStorageInUse,41};4243/// These failures arise from the state of the input or from too small an44/// attempt budget.45pub const InputError = error{46    /// `Settings.max_attempts` is zero. The check runs before the workspace is47    /// acquired, so no workspace memory is taken or written.48    AttemptBudgetExhausted,4950    /// The oracle answered uninteresting for the initial input. A run starts51    /// from a witness, an input that already reproduces the failure under52    /// investigation.53    InitialInputUninteresting,54};5556/// Oracle's answer about one candidate byte slice.57pub const Interesting = enum {58    /// The candidate reproduces the failure, or shows the property under59    /// investigation, so the search takes this shorter candidate as its new60    /// current sequence.61    interesting,6263    /// The candidate does not show the property under investigation, so the64    /// search drops this candidate and tries another deletion.65    uninteresting,66};6768/// Status recording which stopping condition the search reached.69pub const Completion = enum {70    /// Every occurrence deletion of one byte from the returned output was put71    /// to the oracle and came back uninteresting. Given a deterministic oracle72    /// that decides from the candidate's content alone, no single byte comes73    /// out of the result while the result stays interesting. 1-minimality is a74    /// local guarantee, and it leaves open whether the result is globally75    /// shortest.76    one_minimal,7778    /// The number of oracle calls reached `Settings.max_attempts` before the79    /// single-byte sweep could finish. The returned slice is an interesting80    /// subsequence of the initial input. The 1-minimality guarantee is given81    /// up, because the search stopped before trying every single-byte deletion,82    /// and that holds even when the result happens to be minimal.83    budget_exhausted,84};8586/// Type of the caller's oracle function pointer.87///88/// ## Calling Convention and Contract89///90/// - **Candidate slice:** on attempt 1 the callback receives the caller's own91///   `initial` slice, before any copy. On every later attempt it receives a92///   slice into the scratch lane, and the next iteration overwrites those93///   bytes, so the callback retains no slice into a candidate buffer past its94///   return.95/// - **Context pointer:** the caller keeps the context alive for the whole96///   synchronous call of `reduce()`, and the cast `@ptrCast(@alignCast(ctx))`97///   matches the real type and alignment of what the pointer points at.98/// - **Answers and errors:** the callback answers interesting for the specific99///   failure or symptom under investigation and uninteresting for everything100///   else, which covers a candidate that fails to parse, holds invalid UTF-8,101///   or hits an unrelated error. Returning a Zig error ends the run at once.102/// - **Side effects and determinism:** a side effect such as logging or the103///   callback's own scratch allocation is allowed as long as the answer for a104///   given candidate stays the same. The minimality claims rest on an oracle105///   that is deterministic and decides from the candidate's content alone,106///   which is an assumption about the caller's code.107pub const InterestingFn = *const fn ([]const u8, *anyopaque) anyerror!Interesting;108109/// Options that control how a run executes.110pub const Settings = struct {111    /// Largest number of oracle calls a run may make, counting the call on the112    /// caller's own input. It defaults to `10_000`.113    ///114    /// - Zero returns `error.AttemptBudgetExhausted` before the workspace is115    ///   acquired.116    /// - One, with a nonempty interesting input, ends the run after attempt 1117    ///   with `Completion.budget_exhausted` and keeps the input as it arrived.118    /// - One, with an empty interesting input, ends the run with119    ///   `Completion.one_minimal`, because a zero-length input has no deletion120    ///   to try.121    ///122    /// The ceiling counts oracle calls alone: bytes copied, memory the callback123    /// allocates, and wall-clock time all sit outside it, so a callback that124    /// loops forever leaves `reduce()` running forever.125    max_attempts: usize = 10_000,126};

1/// Module holding the data types, the oracle function interface, the error2/// sets, and the execution settings.3pub const model = @import("model.zig");