Description
A baseline artifact is structurally invalid or uses an unsupported schema version.
Baseline
type Baseline is private;
Samples and compatibility metadata loaded from a baseline file.
Baseline_Comparison_Error
Baseline_Comparison_Error : exception;
Saved or current sample data cannot be compared within the numeric domain representable by the harness's clock and iteration counters.
Baseline_Format_Error
Baseline_Format_Error : exception;
A baseline artifact is structurally invalid or uses an unsupported schema version.
Baseline_IO_Error
Baseline_IO_Error : exception;
A baseline artifact could not be written, published, or read.
Baseline_Name
function Baseline_Name (Result : Gate_Result) return String
Return the loaded baseline identity, or empty when unavailable.
Parameters
- Result
Completed gate evaluation.
Return value
Exact saved benchmark name.
Baseline_Path
function Baseline_Path (Result : Gate_Result) return String
Return the evaluated artifact path.
Parameters
- Result
Completed gate evaluation.
Return value
Path supplied to Evaluate_Gate.
Bootstrap_Method
function Bootstrap_Method (Result : Gate_Result) return String
Return the stable name of the independent bootstrap method.
Parameters
- Result
Completed gate evaluation.
Return value
Method name recorded for reproduction and machine output.
Bootstrap_Resamples
function Bootstrap_Resamples (Result : Gate_Result) return Positive
Return the number of bootstrap resamples used by the gate.
Parameters
- Result
Completed gate evaluation.
Return value
Positive resample count.
Clock_Backend
function Clock_Backend (Saved : Baseline) return String
Return the stored clock backend identity.
Parameters
- Saved
Loaded baseline.
Return value
Exact clock backend identifier.
Compare
function Compare
(Saved : Baseline;
Current : Measurement;
Fingerprint : String := "";
Practical_Threshold_Percent : Long_Float := 1.0;
Random_Seed : Long_Long_Integer := 1;
Confidence_Level_Percent : Confidence_Percentage := 95.0;
Bootstrap_Resamples : Bootstrap_Resample_Count := 2_000) return Regression
Compare a current run with an independently collected baseline using an independent circular-block bootstrap of arithmetic-mean ratios.
Parameters
- Saved
Previously loaded baseline.
- Current
Current compatible measurement.
- Fingerprint
Current environment identity; empty selects the default metadata fingerprint.
- Practical_Threshold_Percent
Smallest meaningful time change.
- Random_Seed
Deterministic bootstrap seed.
- Confidence_Level_Percent
Central interval coverage in percent.
- Bootstrap_Resamples
Number of bootstrap distributions to draw.
Return value
Compatibility, interval, change, and verdict.
Raised exceptions
- Constraint_Error
Compatible samples request more than the bounded bootstrap analysis work.
- Baseline_Comparison_Error
Sample data cannot be compared within the supported numeric domain.
Compatibility
function Compatibility (Result : Gate_Result) return Compatibility_Issue
Return the exact incompatibility reason.
Parameters
- Result
Completed gate evaluation.
Return value
Compatibility issue, or No_Compatibility_Issue.
Compatibility_Issue
type Compatibility_Issue is
(No_Compatibility_Issue,
Benchmark_Identity_Mismatch,
Environment_Fingerprint_Mismatch,
Clock_Backend_Mismatch);
Exact reason that a loaded baseline is incompatible.
Enumeration literals
- No_Compatibility_Issue
The result is not incompatible.
- Benchmark_Identity_Mismatch
Benchmark names differ.
- Environment_Fingerprint_Mismatch
Environment identities differ.
- Clock_Backend_Mismatch
Clock backend identities differ.
Compatible
function Compatible (Result : Gate_Result) return Boolean
Return whether an exact compatible comparison ran.
Parameters
- Result
Completed gate evaluation.
Return value
True when benchmark identity, fingerprint, and clock match.
Compatible
function Compatible (Result : Regression) return Boolean
Return whether clock backend and environment fingerprint match.
Parameters
- Result
Regression result.
Return value
True when comparing the runs is permitted.
Confidence_Level_Percent
function Confidence_Level_Percent (Result : Gate_Result) return Long_Float
Return the confidence level used by the independent bootstrap.
Parameters
- Result
Completed gate evaluation.
Return value
Confidence level in percent.
Current_Name
function Current_Name (Result : Gate_Result) return String
Return the exact current benchmark identity.
Parameters
- Result
Completed gate evaluation.
Return value
Current benchmark name supplied to Evaluate_Gate.
Evaluate_Gate
function Evaluate_Gate
(Path : String;
Current_Name : String;
Current : Measurement;
Fingerprint : String := "";
Policy : Gate_Policy := Permissive_Gate_Policy;
Random_Seed : Long_Long_Integer := 1;
Confidence_Level_Percent : Confidence_Percentage := 95.0;
Bootstrap_Resamples : Bootstrap_Resample_Count := 2_000) return Gate_Result
Load Path, require exact benchmark/environment identity, run the existing independent comparison, and apply Policy. This function never records or updates a baseline.
Parameters
- Path
Named baseline artifact.
- Current_Name
Exact stable identity for Current.
- Current
Current measurement.
- Fingerprint
Exact current environment identity; empty selects the default metadata fingerprint.
- Policy
Gate threshold and exceptional-state actions.
- Random_Seed
Deterministic bootstrap seed.
- Confidence_Level_Percent
Central interval coverage in percent.
- Bootstrap_Resamples
Number of bootstrap distributions to draw.
Return value
Status, decision, diagnostics, and optional statistics.
Raised exceptions
- Constraint_Error
Compatible samples request more than the bounded bootstrap analysis work.
Fail_Closed_Gate_Policy
Fail_Closed_Gate_Policy : constant Gate_Policy :=
(Practical_Threshold_Percent => 1.0,
On_Missing => Reject,
On_Invalid => Reject,
On_Incompatible => Reject,
On_Inconclusive => Reject);
CI policy that rejects every exceptional state and inconclusive result.
Fingerprint
function Fingerprint (Saved : Baseline) return String
Return the caller-defined environment fingerprint.
Parameters
- Saved
Loaded baseline.
Return value
Stored fingerprint.
Gate_Action
type Gate_Action is (Report_Only, Reject);
Whether a non-result condition is reported or rejects the gate.
Enumeration literals
- Report_Only
Preserve the status without rejecting the run.
- Reject
Reject the run.
Gate_Policy
type Gate_Policy is record
Practical_Threshold_Percent : Threshold_Percentage := 1.0;
On_Missing : Gate_Action := Report_Only;
On_Invalid : Gate_Action := Report_Only;
On_Incompatible : Gate_Action := Report_Only;
On_Inconclusive : Gate_Action := Report_Only;
end record;
Policy for a saved-baseline gate. An established Regression always rejects. Improvement and practical equivalence always pass.
Record fields
- Practical_Threshold_Percent
Smallest meaningful time change.
- On_Missing
Action when Path does not exist.
- On_Invalid
Action for malformed, corrupt, or unreadable artifacts and invalid current measurement data.
- On_Incompatible
Action for exact identity, fingerprint, or clock incompatibility.
- On_Inconclusive
Action when the confidence interval establishes neither a practical result nor a regression.
Gate_Result
type Gate_Result is private;
Policy decision and optional independent-run statistics for one gate.
Gate_Status
type Gate_Status is
(Improvement,
Practical_Equivalence,
Inconclusive,
Regressed,
Missing_Baseline,
Incompatible_Baseline,
Invalid_Baseline,
Baseline_Error);
Complete status of one baseline gate evaluation.
Enumeration literals
- Improvement
Confidence interval establishes an improvement.
- Practical_Equivalence
Complete interval lies within the threshold.
- Inconclusive
Confidence interval establishes neither result.
- Regressed
Complete interval establishes a regression.
- Missing_Baseline
Path does not exist.
- Incompatible_Baseline
Exact identity, fingerprint, or clock differs.
- Invalid_Baseline
Artifact validation failed.
- Baseline_Error
Artifact I/O or current-measurement validation prevented comparison.
Has_Statistics
function Has_Statistics (Result : Gate_Result) return Boolean
Return whether speedup and confidence queries are available.
Parameters
- Result
Completed gate evaluation.
Return value
True after a compatible independent comparison.
Load
function Load (Path : String) return Baseline
Load and validate a baseline written by Save. Version 2 validation includes required and duplicate fields, ranges, completeness, footer, and checksum. The earlier version 1 format remains readable so existing durable references can be checked, but new records always use version 2.
Parameters
- Path
Existing baseline path.
Return value
Parsed baseline and raw samples.
Raised exceptions
- Baseline_Format_Error
The artifact is malformed, partial, corrupt, duplicated, out of range, or uses an unsupported version.
Name
function Name (Saved : Baseline) return String
Return the name stored in a baseline.
Parameters
- Saved
Loaded baseline.
Return value
Stored benchmark name.
Permissive_Gate_Policy
Permissive_Gate_Policy : constant Gate_Policy := (others => <>);
Interactive policy that reports exceptional states without rejection.
Practical_Threshold_Percent
function Practical_Threshold_Percent (Result : Gate_Result) return Long_Float
Return the configured practical threshold.
Parameters
- Result
Completed gate evaluation.
Return value
Threshold in percent.
Random_Seed
function Random_Seed (Result : Gate_Result) return Long_Long_Integer
Return the deterministic bootstrap seed supplied to Evaluate_Gate.
Parameters
- Result
Completed gate evaluation.
Return value
Exact signed seed.
Reason
function Reason (Result : Gate_Result) return String
Return a human-readable decision diagnostic.
Parameters
- Result
Completed gate evaluation.
Return value
Specific status reason.
Regression
type Regression is private;
Independent-run regression result. Direct Compare remains preferable when both implementations can run in the same process.
Regression_Gate_Failure
Regression_Gate_Failure : exception;
Require raises this exception when a gate result is rejected.
Rejected
function Rejected (Result : Gate_Result) return Boolean
Return whether policy rejects the result.
Parameters
- Result
Completed gate evaluation.
Return value
True when CI should fail.
Require
procedure Require (Result : Gate_Result)
Raise Regression_Gate_Failure when Result is rejected.
Parameters
- Result
Completed gate evaluation.
Raised exceptions
- Regression_Gate_Failure
Result is rejected.
Save
procedure Save (Path : String; Name : String; Result : Measurement; Fingerprint : String := "")
Save a measurement and all retained samples. Fingerprint should identify the host, CPU policy, toolchain, switches, and revision relevant to the caller's regression policy. Empty selects Metadata.Fingerprint. The implementation writes a checksummed versioned temporary artifact in the destination directory, flushes it, and atomically replaces Path.
Parameters
- Path
Destination baseline path, atomically replaced on success.
- Name
Stable, nonempty benchmark name.
- Result
Completed measurement.
- Fingerprint
Caller-defined environment identity.
Raised exceptions
- Constraint_Error
A text field is empty, too long, or contains a newline or NUL byte.
- Baseline_IO_Error
The temporary file or atomic publication failed. An existing artifact remains unchanged before publication.
Speedup
function Speedup (Result : Gate_Result) return Long_Float
Return baseline-time/current-time ratio.
Parameters
- Result
Gate result with statistics.
Return value
Arithmetic-mean speedup.
Raised exceptions
- Program_Error
Has_Statistics is False.
Speedup
function Speedup (Result : Regression) return Long_Float
Return baseline-time/current-time ratio. Greater than one is faster.
Parameters
- Result
Compatible regression result.
Return value
Arithmetic-mean speedup.
Speedup_Confidence_High
function Speedup_Confidence_High (Result : Gate_Result) return Long_Float
Return the upper configured-confidence bootstrap speedup bound.
Parameters
- Result
Gate result with statistics.
Return value
Upper speedup bound.
Raised exceptions
- Program_Error
Has_Statistics is False.
Speedup_Confidence_High
function Speedup_Confidence_High (Result : Regression) return Long_Float
Return the upper endpoint of the independent bootstrap interval.
Parameters
- Result
Compatible regression result.
Return value
Upper configured-confidence speedup bound.
Speedup_Confidence_Low
function Speedup_Confidence_Low (Result : Gate_Result) return Long_Float
Return the lower configured-confidence bootstrap speedup bound.
Parameters
- Result
Gate result with statistics.
Return value
Lower speedup bound.
Raised exceptions
- Program_Error
Has_Statistics is False.
Speedup_Confidence_Low
function Speedup_Confidence_Low (Result : Regression) return Long_Float
Return the lower endpoint of the independent bootstrap interval.
Parameters
- Result
Compatible regression result.
Return value
Lower configured-confidence speedup bound.
Status
function Status (Result : Gate_Result) return Gate_Status
Return the complete evaluation status.
Parameters
- Result
Completed gate evaluation.
Return value
Distinct statistical or artifact status.
Status_Name
function Status_Name (Result : Gate_Result) return String
Return a stable lowercase machine name for Status.
Parameters
- Result
Completed gate evaluation.
Return value
Status name with underscores between words.
Time_Change_Confidence_High
function Time_Change_Confidence_High (Result : Gate_Result) return Long_Float
Return the upper endpoint of the current-time change interval.
Parameters
- Result
Gate result with statistics.
Return value
Upper time-change bound in percent; negative is faster.
Raised exceptions
- Program_Error
Has_Statistics is False.
Time_Change_Confidence_High
function Time_Change_Confidence_High (Result : Regression) return Long_Float
Return the upper endpoint of the current-time change interval.
Parameters
- Result
Compatible regression result.
Return value
Upper time-change bound in percent; negative is faster.
Time_Change_Confidence_Low
function Time_Change_Confidence_Low (Result : Gate_Result) return Long_Float
Return the lower endpoint of the current-time change interval.
Parameters
- Result
Gate result with statistics.
Return value
Lower time-change bound in percent; negative is faster.
Raised exceptions
- Program_Error
Has_Statistics is False.
Time_Change_Confidence_Low
function Time_Change_Confidence_Low (Result : Regression) return Long_Float
Return the lower endpoint of the current-time change interval.
Parameters
- Result
Compatible regression result.
Return value
Lower time-change bound in percent; negative is faster.
Time_Change_Percent
function Time_Change_Percent (Result : Gate_Result) return Long_Float
Return current time change relative to baseline.
Parameters
- Result
Gate result with statistics.
Return value
Percent change; negative is faster.
Raised exceptions
- Program_Error
Has_Statistics is False.
Time_Change_Percent
function Time_Change_Percent (Result : Regression) return Long_Float
Return current time change relative to baseline. Negative is faster.
Parameters
- Result
Compatible regression result.
Return value
Relative arithmetic-mean time change in percent.
Verdict
function Verdict (Result : Regression) return Comparison_Verdict
Return the practical/statistical regression verdict. A regression is established only when the complete change interval is above the practical threshold.
Parameters
- Result
Regression result.
Return value
Practical/statistical verdict.