docs: correctness + cloud-accuracy sweep, version normalisation, GHCR container publishing (v1.0.3)#10
Merged
Merged
Conversation
The docs repeatedly claimed pg_hardstorage "works against managed PG" (RDS, Aurora, Cloud SQL, Azure Database, Aiven, Supabase, Neon) — the comparison page even sold it as the #1 reason to choose the tool. That is false: the data plane is physical replication (a physical slot plus BASE_BACKUP), and fully-managed DBaaS do not expose BASE_BACKUP / physical replication to customers, so it cannot take a physical base backup of them. This contradicted the README and the site's how-it-works page, and a prospective user flagged it. Standardise every page on the truth: pg_hardstorage targets PostgreSQL you run yourself (bare metal, VMs, containers, Patroni, CloudNativePG). The genuine architectural advantage is no SSH / no OS access / no archive_command on the host — not managed-DBaaS support. Managed DBaaS are explicitly out of scope. Also fixes the CLI long-description source (internal/cli/wal.go) so the generated reference page does not regress.
Follow-on to the managed-DBaaS fix. Five parallel audits cross-checked doc claims against the code; corrected every verifiable mismatch: Counts/versions: - storage backends "five"->"six" (scp was omitted); LLM providers "eight"->one (only the OpenAI-compatible client + a test mock are registered); CLI page count 202->216; KMS 4-vs-5 wording reconciled. - PG support: faq had PG18 "first-class from v0.9" backwards (15/16/17 are required in CI; 18 is allow-failure); release notes said the default sandbox is PG17 (it is PG18). Nonexistent/renamed CLI in tutorials & ops guides: - llm propose backup-schedule (->llm ask), restore --confirm (->--force), backup --no-compression (removed), doctor --json (->-o json), agent status (->status <deployment>), agent --step-down (planned), verify --sandbox-backend/--firecracker-* (yaml, not flags), audit export-bundle -o (->--out), `pg_hardstorage simple` (->pg_hardstorage_simple). Dropped the fictional restore second-prompt. Overstated readiness: - "wal push/fetch/list/repair are scaffold for now" — they are fully implemented (removed, source + generated page). - CNPG-I marked as shipped in the comparison + a runnable tutorial — it is v0.5 roadmap; added roadmap markers/admonition. - skill cosign-signing and --allow-unsigned-skill described as present — signing is roadmap; reworded. Crypto/signing: - AES-256-GCM-SIV claimed as the default/shipping cipher across ~12 pages — the code ships plain AES-256-GCM (repo's own SPEC_DRIFT and release notes confirm). Reframed: GCM ships today, GCM-SIV is the planned default. Kept the FIPS "BoringCrypto lacks GCM-SIV" rationale. - audit/evidence bundles and skill signatures described as cosign — they are Ed25519 (agent keyring); cosign is for release artefacts. - SLSA page aligned to the real pipeline: provenance via slsa-github-generator (.intoto.jsonl) not `cosign attest`; container images + FIPS image marked not-yet-shipped (release runs --skip=docker). - transparency-log anchoring framed as self-hosted today, external Rekor as roadmap. Source: removed the stale "scaffold" line from internal/cli/wal.go (gofmt-clean, builds).
Web-checked (June 2026) each named managed provider against its own replication documentation; all six withhold customer-reachable BASE_BACKUP / physical replication: - RDS, Aurora: external physical replication / pg_basebackup unsupported - Cloud SQL, Azure Database: only logical replication/decoding to external consumers; physical is internal managed-HA - Neon: custom pageserver storage, no traditional pg_basebackup - Supabase (hosted): can publish logically, cannot be a physical replica Added to the FAQ: the per-provider rationale, the general BASE_BACKUP test, and an explicit "What we have not verified" admonition (list not exhaustive, vendor behaviour changes, run `wal preflight` to confirm; self-hosted distributions including self-hosted Supabase are supported).
Cross-checked all version references after a reviewer spotted v0.9.2 in
the docs. Shipped packages are already correct (goreleaser versions
every artifact from the git tag via {{ .Version }}). The stale strings
were all in the docs/examples:
- SLSA + PCI-DSS verification examples: v0.9.2 artifact/image names ->
1.0.1 (tarball, sbom, ghcr image tags).
- getting-started install: v0.1.1 download URL / .deb / .rpm / docker
pull / `version` output -> 1.0.1, and the tarball asset name corrected
to the real versioned form pg_hardstorage_1.0.1_linux_amd64.tar.gz.
- `version`-output examples (build-from-source, fips-variant) and the
ldflags example: v0.9.x / v0.9.0-dev -> v1.0.x / v1.0.0-dev.
- "ships / installed" capability statements (kms long-desc + generated
page, source/llm-provider/tier2 plugin contracts, getting-started-
simple prereq, control-plane example agent version): de-versioned or
-> v1.0.
Left intentionally: v1.0 release-notes historical narrative ("since
v0.9"), schema-since lineage markers, the miekg/pkcs11@v1.1.1 dependency
pin, and example-plugin/skill versions — none are shipped-package
versions.
So the install / SLSA / SBOM / cosign / docker examples never go stale
again: each command block now sets `VERSION=1.0.1` once (with a pointer
to the latest-release page) and references ${VERSION} in artifact names,
release tags, and image tags. Sample `version`-*output* lines stay
literal (a variable doesn't apply to printed output).
Also fixed an `audit export-bundle -o` -> `--out` in the PCI-DSS
evidence-bundle example (same flag bug already corrected elsewhere; -o
is the output-format selector, not a file path).
Files: tutorials/getting-started.md, compliance/slsa-l3-provenance.md,
compliance/pci-dss.md.
Container publishing (gated, safe-by-default): - release.yml: add docker/setup-qemu + setup-buildx and gate the `--skip=docker` removal on a PUBLISH_CONTAINERS repo variable, so the release still ships binaries/.deb/.rpm/Homebrew when GHCR isn't yet enabled, and publishes signed multi-arch images once it is. - .goreleaser.yaml: add `docker_signs` (keyless cosign image signatures). - ci.yml: add a `goreleaser check` step so the release config is validated on every push (the packaging job previously only shellcheck + helm lint). Docs for v1.0.3: - SLSA page: container-images section reframed from "not yet shipped" to "wired, gated on GHCR enablement"; cosign image signatures documented as shipping once enabled, image-level SLSA provenance kept as roadmap. - CHANGELOG: new [1.0.3] — 2026-06-24 section (doc-correctness sweep + container publishing). - Example default VERSION bumped 1.0.1 -> 1.0.3; sample version outputs updated. Broken in-repo path claims fixed (file-existence audit): - pkcs11-variant.md: internal/plugin/encryption/pkcs11 -> .../kms/pkcs11 - CONTRIBUTING.md: docs/SPEC.md -> SPEC.md (repo root) - SECURITY.md: docs/operator-guide.md -> docs/operations/operator-guide.md - firecracker-sandbox.md: dropped the non-existent scripts/ firecracker-rootfs.sh claim - reference/plugins/index.md: dropped non-existent cmd/pg_hardstorage_fips
The wal/kms long-description edits changed the source; regenerate the generated artefacts so the docs-regen drift gate passes (man pages for kms/wal now reflect the source; wal.md canonical spacing restored).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Audit-driven documentation correctness pass plus the wiring to publish container images, prepared as v1.0.3.
Why
A prospective user spotted the docs claiming pg_hardstorage "works against managed PG (RDS, Cloud SQL, Azure DB)" while the site's
/how-it-workspage said the opposite. The site is correct: the data plane is physical replication (BASE_BACKUP+ physical slot), which fully-managed DBaaS don't expose. That triggered a full claim audit against the codebase.What's in here
0.9.2/0.1.1/0.9.xreferences → current; download/verify examples now use aVERSIONvariable so they don't go stale.SPEC.md, operator-guide link, the absentscripts/firecracker-rootfs.sh,cmd/pg_hardstorage_fips).setup-qemu+setup-buildx,docker_signs(keyless cosign image signatures), and--skip=dockergated on aPUBLISH_CONTAINERSrepo variable (default safe — ships binaries/.deb/.rpm/brew; publishes signed images once GHCR is enabled). Added agoreleaser checkCI step.[1.0.3]section.Validated locally
YAML parse (goreleaser + workflows),
go build ./internal/cli, file-existence audit, cloud web-verification.Needs CI / pre-tag
goreleaser check(this PR's new step), andmake docs-deps && docs-build docs-regen docs-doctest. Image publishing additionally needs the org to enable GHCR Actions package-write + setPUBLISH_CONTAINERS=true. Image-level SLSA provenance remains roadmap.