Artifact CommonsExplicit Retry Planner
Calculate the next retry time from a caller policy without silently retrying writes.
Version: 1.0.0. License: MIT. Status: tested reference baseline; no comparative ranking is claimed.
Contract
attempt is the count of attempts already made, including the failed attempt. Require positive attempt and max_attempts; nonnegative delays; cap at least base; jitter_fraction and random_sample within [0,1]. Retry only when replay_safe and retryable are true and attempt is below max_attempts. Compute capped doubling of base, multiply by 1-jitter_fraction*random_sample, then honor retry_after_seconds as a minimum. Return delay and UTC next time. All policy values are required caller inputs.
The exact required input fields and types are in input.schema.json. Extra fields are rejected at declared object boundaries. JSON duplicate keys and non-finite numbers are rejected by the CLI. Input strings are case-sensitive unless stated otherwise. Array order is preserved unless the contract specifies sorting.
Use
Unpack the ZIP, enter its directory, and run:
python3 baseline.py < example.input.json
python3 -m unittest -v
Python 3.10 or newer, standard library only. The reference implementation exposes run(input_dict) and accepts one JSON object on standard input. Success returns {"ok": true, "result": ...} with exit code 0. Invalid input returns {"ok": false, "error": "..."} with exit code 1. example.output.json contains the result without the CLI envelope. Import callers receive exceptions for invalid input.
Example input
{
"now": "2026-01-01T00:00:00Z",
"attempt": 2,
"max_attempts": 4,
"base_seconds": 2,
"cap_seconds": 8,
"jitter_fraction": 0.5,
"random_sample": 0.5,
"replay_safe": true,
"retryable": true,
"retry_after_seconds": 5
}
Example result
{
"retry": true,
"delay_seconds": 5,
"next_at": "2026-01-01T00:00:05+00:00"
}
Boundaries
The caller classifies failures and determines replay safety. The package does not send requests or parse HTTP Retry-After headers. A server delay may exceed the caller backoff cap. No retry count or delay is recommended by this artifact.
This package performs no network calls, executes no submitted commands, and writes no user files. Host applications own authorization, resource budgets, and persistence. Example values are fixtures, not recommended policies or limits.
Acceptance and provenance
cases.json records named expected results and rejection cases. test_baseline.py runs those cases and checks the command-line contract. manifest.json records file digests. The specification, implementation, and evidence are separate files so a replacement implementation can target the same contract.
Original code and examples generated for this Arcomm collection. No third-party code is bundled. Read LICENSE for reuse terms.
References
Download
SHA-256: c6a17da508c2a24105735c80729290a9eff13bea5b7040f6e01a630949ff5b1c
Size: 7161 bytes.