Repository navigation
v0.4.7
Gonimbus v0.4.7 Release Notes
Release Date: 2026-11-09
Status: Machine-readable version --json, throttled probe retries, Gen-2 release provenance and registry verification, durable storage architecture ratification, and digest-pinned runner contracts
Summary
v0.4.7 adds gonimbus version --json [--extended] (and allows CLI startup in
scrubbed environments without HOME), retries throttled standalone provider
probe operations (HEAD and body-compare GET) during transfer reflow with
AIMD-aware concurrency slot release, upgrades release provenance to Gen-2
(exact signing-subkey enforcement, workflow SHA-256 pinning, clean-room
published-release staging, post-publication Go proxy / Homebrew / Scoop
registry verification, and public-surface hygiene scanning), ratifies the
durable storage architecture (ADR-0007, ADR-0008, DDR-0001), and codifies
the raw-asset byte-for-byte packaging and receipt-jsonl-v1 segment-pruning
contracts for digest-pinned automation runners.
gonimbus version --json [--extended]and scrubbed-environment startup.
gonimbus version --jsonemits a single-line JSON object (name,version,
commit,built_at,go,platform), and--json --extended(-e) adds
os,arch,gofulmen,crucible, and Go module build info (module_path,
vcs_revision,vcs_time,vcs_modified). Humangonimbus version [--extended]output is unchanged, extra positional arguments are rejected,
and CLI startup no longer exits whenHOMEandXDG_CONFIG_HOMEare unset
(env -i) and no explicit--configpath is given.- AIMD-aware retry for throttled reflow probes. Standalone provider
HEAD
and body-compareGETprobe calls inpkg/reflowandtransfer reflow
retryprovider.ErrThrottledup to the configured retry budget (RetryMax,
default 3 retries / 4 total attempts), releasing the adaptive concurrency
limiter slot before sleeping between attempts and feeding each attempt outcome
throughObserveProviderResult. Optional pre-transfer sourceHEADon CLI
reflow runs also routes fatal non-404 errors (such as exhausted
ErrThrottled) throughRecordFatalError. - Gen-2 release provenance, registry verification, and surface hygiene.
Release verification enforces the exact OpenPGP signing subkey
(config/release/signing-subkey.txt) across tag, manifest signature, and
post-tag selector checks; pins.github/workflows/*.ymldigests in
config/release/release-workflow.sha256; attaches
expected-fingerprints.txtandexpected-fingerprints.ndjsonalongside the
public keys on each immutable GitHub Release; addsmake release-stage-publishedfor clean-room published release verification and
make release-verify-registriesfor post-publication Go proxy, Homebrew tap,
and Scoop bucket verification; and addsmake surface-scanfor repository
and release-surface hygiene. - Durable storage architecture ratification. Ratifies
ADR-0007(Accepted,
2026-09-30), addsADR-0008(storage strata and durable-first bulk state)
andDDR-0001(index semantics and representation parity), and publishes
docs/architecture/durable-storage.mdand
docs/architecture/canonical-state-conformance.md. - Raw-asset packaging invariant and
receipt-jsonl-v1segment-pruning
contract. Codifies the byte-for-byte raw-executable contract across GitHub
Releases,3leaps/homebrew-tap, and3leaps/scoop-bucket(including the
Windows Scoopshims\gonimbus.exevsscoop which gonimbusdistinction for
SHA-256 verifiers and the minor-line@0.4retention rule forv0.5.0), and
documents and contract-tests the fourreceipt-jsonl-v1segment-pruning
accounting invariants.
Highlights
gonimbus version --json [--extended] and scrubbed-environment startup
Automation runners that verify the gonimbus binary before granting storage
credentials or home-directory access can now query build identity as structured
JSON in a scrubbed environment (env -i gonimbus version --json [--extended]):
gonimbus version --jsonwrites a single newline-terminated JSON object to
stdout withname,version,commit,built_at,go, andplatform.gonimbus version --json --extended(or-e) addsos,arch,gofulmen,
crucible, and Goruntime/debug.ReadBuildInfofields (module_path,
vcs_revision,vcs_time,vcs_modified) when present in the binary.- When
--configis not specified and neitheros.UserConfigDir()nor
os.UserHomeDir()resolves (for example underenv -i),gonimbusskips
adding a user-home configuration search path instead of exiting with code 51,
while explicit--config <missing-file>remains fail-closed.
AIMD-aware retry for throttled provider probes in transfer reflow
Previously, standalone destination HEAD and body-compare GET probes during
transfer reflow collision checks and destination inspection executed a single
provider call and aborted the run immediately on provider.ErrThrottled (HTTP 429 / SlowDown / RESOURCE_EXHAUSTED).
In v0.4.7:
pkg/reflowand CLI reflow destination probes retryprovider.ErrThrottled
up toRetryMax(default 3 retries / 4 total attempts) with exponential
backoff (RetryBaseDelay, default 200ms, capped at 30s).- Each attempt acquires the adaptive concurrency limiter slot, executes one
probe call, releases the slot, and reports the attempt result once to
ObserveProviderResultbefore sleeping outside the limiter slot, preventing
slot starvation even at--parallel 1. - Non-throttle errors (such as
404 NotFoundor403 AccessDenied) return
immediately without retry, and context cancellation or resumable fatal-abort
signals interrupt backoff sleeps immediately.
Carried Clarification (receipt-jsonl-v1 segment pruning)
For downstream consumers validating gonimbus.index.query_receipt.v1
(--output-format receipt-jsonl-v1, schema_version: "1.0.0") across v0.4.3–v0.4.7:
results.examinedcounts rows visited inside walked segments only
(results.examined <= declared.rows); manifest-pruned segments are never
opened, hashed, or row-scanned. Do not assertresults.examined == declared.rowsorsegments.walked == segments.declaredon patterned
queries.segments.manifest_prunedmay be non-zero for any--patternquery whose
pattern yields a non-empty literal key prefix (match.DerivePrefix(pattern) != ""), pruning both leading (MaxRelKey < prefix) and trailing (`MinRelKeyprefix` without prefix match) segments.
segments.verified == segments.walkedholds unconditionally on verified
durable queries (every walked segment file descriptor is SHA-256 verified
before its rows are yielded, including 0-row segments), and
segments.walked + segments.manifest_pruned == segments.declaredholds
wheneverresults.truncated == false(with
segments.walked + segments.manifest_pruned <= segments.declaredwhen
--limitstops enumeration early).- An unpatterned query (
--patternomitted) — or a wildcard-leading pattern
with an empty literal prefix (such as**/*.xml) — never prunes segments
(segments.manifest_pruned == 0).
See
Verified query receipt framing
and
Version-gated downstream inventory.
Raw-asset packaging contract and digest-pinned runner guidance
- Official
gonimbusGitHub Releases publish unwrapped, standalone platform
executables (gonimbus-darwin-arm64,gonimbus-linux-amd64,
gonimbus-linux-arm64,gonimbus-windows-amd64.exe,
gonimbus-windows-arm64.exe) listed directly in signedSHA256SUMSand
SHA512SUMS. 3leaps/homebrew-tap(Formula/gonimbus.rb) and3leaps/scoop-bucket
(bucket/gonimbus.json) install those exact release assets byte-for-byte (no
source rebuilds, bottles, wrapper scripts, or archive repackaging), enforced
bymake release-verify-registries.- On Windows Scoop,
~\scoop\shims\gonimbus.exeonPATHis Scoop's
generic launcher shim; SHA-256 verifiers checkingSHA256SUMSon Windows
must hash the resolved target ofscoop which gonimbus
(~\scoop\apps\gonimbus\current\gonimbus-windows-<arch>.exe).
Gen-2 release provenance, registry verification, and durable storage architecture
- Gen-2 release provenance (
make release-preflight,make release-stage-published,make release-verify-registries,make surface-scan). Release verification pins the exact OpenPGP signing subkey
(config/release/signing-subkey.txt), verifies workflow file digests against
config/release/release-workflow.sha256, attachesexpected-fingerprints.txt
andexpected-fingerprints.ndjsonto the release asset set, clean-room
verifies the published immutable GitHub Release indist/published, and
verifies Go module proxy, Homebrew tap, and Scoop bucket parity against the
staged release and tagged commit. - Durable storage architecture (
ADR-0007,ADR-0008,DDR-0001). See
Durable storage architecture
and
Canonical-state conformance.
Library API
There are no breaking changes to the Stable embedded library API.
Release provenance
- Before importing a downloaded public key, establish the expected GPG signing
key, exact signing subkey, and minisign public-key fingerprint through an
independently trusted maintainer channel. Follow the complete
release-verification guide. - The tagged public verification material is
the OpenPGP key,
the minisign public key,
the pinned signing subkey,
and the expected fingerprint anchors,
and both public keys and both fingerprint anchor files are attached to the
GitHub release as assets. - Release tags are GPG-signed. After validating the public material against
the committed anchors, verify withgit tag -v v0.4.7. - Checksum manifests are signed with minisign and PGP; the published assets are
byte-identical to the signed set, GitHub release immutability is verified at
publication time (make release-stage-published), and Go proxy, Homebrew tap,
and Scoop bucket parity are verified against the staged release (make release-verify-registries). - The tag workflow is read-only: it verifies the signed tag against the public
pin committed in the tagged commit, builds, and hands the artifacts to the
maintainer ceremony. It does not create the release.
Install
brew install 3leaps/tap/gonimbus # macOS Apple Silicon, Linux
sfetch --repo 3leaps/gonimbus --tag v0.4.7 --dest-dir ~/.local/bin
go install github.com/3leaps/gonimbus/cmd/gonimbus@v0.4.7scoop bucket add 3leaps https://github.com/3leaps/scoop-bucket
scoop install gonimbusVerification
gonimbus version --json --extendedreports"version":"0.4.7".- Existing durable and SQLite artifacts are read as-is; no rebuild is required.
- Downstream inventory consumers that pin an approved binary must admit
v0.4.7explicitly.
See CHANGELOG.md for the full list.