Skip to content

v0.4.7

Choose a tag to compare

@3leapsdave 3leapsdave released this 09 Nov 23:13
· 11 commits to main since this release
Immutable release. Only release title and notes can be modified.
v0.4.7
89e1494

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 --json emits 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). Human gonimbus version [--extended] output is unchanged, extra positional arguments are rejected,
    and CLI startup no longer exits when HOME and XDG_CONFIG_HOME are unset
    (env -i) and no explicit --config path is given.
  • AIMD-aware retry for throttled reflow probes. Standalone provider HEAD
    and body-compare GET probe calls in pkg/reflow and transfer reflow
    retry provider.ErrThrottled up 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
    through ObserveProviderResult. Optional pre-transfer source HEAD on CLI
    reflow runs also routes fatal non-404 errors (such as exhausted
    ErrThrottled) through RecordFatalError.
  • 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/*.yml digests in
    config/release/release-workflow.sha256; attaches
    expected-fingerprints.txt and expected-fingerprints.ndjson alongside the
    public keys on each immutable GitHub Release; adds make release-stage-published for clean-room published release verification and
    make release-verify-registries for post-publication Go proxy, Homebrew tap,
    and Scoop bucket verification; and adds make surface-scan for repository
    and release-surface hygiene.
  • Durable storage architecture ratification. Ratifies ADR-0007 (Accepted,
    2026-09-30), adds ADR-0008 (storage strata and durable-first bulk state)
    and DDR-0001 (index semantics and representation parity), and publishes
    docs/architecture/durable-storage.md and
    docs/architecture/canonical-state-conformance.md.
  • Raw-asset packaging invariant and receipt-jsonl-v1 segment-pruning
    contract.
    Codifies the byte-for-byte raw-executable contract across GitHub
    Releases, 3leaps/homebrew-tap, and 3leaps/scoop-bucket (including the
    Windows Scoop shims\gonimbus.exe vs scoop which gonimbus distinction for
    SHA-256 verifiers and the minor-line @0.4 retention rule for v0.5.0), and
    documents and contract-tests the four receipt-jsonl-v1 segment-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 --json writes a single newline-terminated JSON object to
    stdout with name, version, commit, built_at, go, and platform.
  • gonimbus version --json --extended (or -e) adds os, arch, gofulmen,
    crucible, and Go runtime/debug.ReadBuildInfo fields (module_path,
    vcs_revision, vcs_time, vcs_modified) when present in the binary.
  • When --config is not specified and neither os.UserConfigDir() nor
    os.UserHomeDir() resolves (for example under env -i), gonimbus skips
    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/reflow and CLI reflow destination probes retry provider.ErrThrottled
    up to RetryMax (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
    ObserveProviderResult before sleeping outside the limiter slot, preventing
    slot starvation even at --parallel 1.
  • Non-throttle errors (such as 404 NotFound or 403 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:

  1. results.examined counts rows visited inside walked segments only
    (results.examined <= declared.rows); manifest-pruned segments are never
    opened, hashed, or row-scanned. Do not assert results.examined == declared.rows or segments.walked == segments.declared on patterned
    queries.
  2. segments.manifest_pruned may be non-zero for any --pattern query whose
    pattern yields a non-empty literal key prefix (match.DerivePrefix(pattern) != ""), pruning both leading (MaxRelKey < prefix) and trailing (`MinRelKey

    prefix` without prefix match) segments.

  3. segments.verified == segments.walked holds 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.declared holds
    whenever results.truncated == false (with
    segments.walked + segments.manifest_pruned <= segments.declared when
    --limit stops enumeration early).
  4. An unpatterned query (--pattern omitted) — 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 gonimbus GitHub 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 signed SHA256SUMS and
    SHA512SUMS.
  • 3leaps/homebrew-tap (Formula/gonimbus.rb) and 3leaps/scoop-bucket
    (bucket/gonimbus.json) install those exact release assets byte-for-byte (no
    source rebuilds, bottles, wrapper scripts, or archive repackaging), enforced
    by make release-verify-registries.
  • On Windows Scoop, ~\scoop\shims\gonimbus.exe on PATH is Scoop's
    generic launcher shim; SHA-256 verifiers checking SHA256SUMS on Windows
    must hash the resolved target of scoop 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, attaches expected-fingerprints.txt
    and expected-fingerprints.ndjson to the release asset set, clean-room
    verifies the published immutable GitHub Release in dist/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 with git 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.7
scoop bucket add 3leaps https://github.com/3leaps/scoop-bucket
scoop install gonimbus

Verification

  • gonimbus version --json --extended reports "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.7 explicitly.

See CHANGELOG.md for the full list.