From d368bb32f98f0d053ea67d827be52072f9dd762c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 1 Nov 2026 21:15:28 +0000 Subject: [PATCH] Clarify page-only delivery and artifact verification --- delivery.go | 9 ++++++--- docs/consumers/delivery.md | 19 +++++++++++++------ docs/roadmap/implementation.md | 4 +++- 3 files changed, 22 insertions(+), 10 deletions(-) diff --git a/delivery.go b/delivery.go index ee7ee1c..d363f16 100644 --- a/delivery.go +++ b/delivery.go @@ -90,9 +90,12 @@ type DeliveryAsset struct { // DeliveryRequest identifies a local tagged checkout and its explicit // destination. Build selects a managed build; Prebuilt supplies caller-owned -// build output instead. They cannot both be set. Either may be nil for -// page-only delivery when both are nil. Build with no targets, or an empty -// Prebuilt result, also performs page-only delivery. +// build output instead. They cannot both be set. The ordinary page-only request +// leaves both nil. A Build with no targets or a matching Prebuilt result with +// no targets or artifacts also performs page-only delivery. Any supplied +// Prebuilt must match the repository, module directory and path, tag, commit, +// and version; a zero BuildResult does not supply that identity. Source and +// artifact requirements for binaries apply when binary work is selected. type DeliveryRequest struct { RepositoryDir string // directory within the tagged source Git checkout. // ModuleDir selects a repository-relative module directory; empty selects diff --git a/docs/consumers/delivery.md b/docs/consumers/delivery.md index 88ce19f..0376da8 100644 --- a/docs/consumers/delivery.md +++ b/docs/consumers/delivery.md @@ -46,7 +46,9 @@ toolchain. Inside a Git checkout, `RepositoryDir` can name a subdirectory; empty selection chooses that root. Previously, a supplied checkout subdirectory acted as the selection base. Outside a checkout, the supplied directory remains the base for `ModuleDir`. -The operation may use the network and updates the Go module cache while +Preparation overrides an alternate module file selected by `GOFLAGS`, while +retaining other effective Go settings. The operation may use the network and +updates the Go module cache while preserving the caller's proxy, private-module, credential, and cache settings. If checksums are missing, Go may update `go.sum`. For binary CI delivery, prepare and commit the selected module's `go.sum` before tagging: delivery verifies the @@ -216,12 +218,17 @@ To deliver binaries built separately, set `Prebuilt` to the `BuildResult`. ReleaseKit checks its repository, module directory, declared module path, full tag, semantic version, tagged commit, normalized settings, and artifact evidence against the selected committed module. Binary results must record verified -source. The current files are checked against their recorded digests before any -hosted request. The files remain caller-owned, so callers can retain the -original bytes for retries and are responsible for cleanup. With neither +source. After cheap local and source checks, delivery performs read-only +credential preflight, verifies the local artifacts in full, and then makes +hosted writes. The current files are checked against their recorded digests +before those writes. Preflight confirms only the access evidence available from +the service, as described above. The files remain caller-owned, so callers can +retain the original bytes for retries and are responsible for cleanup. With neither artifact source, an empty managed target set, or a matching empty prebuilt -result, delivery is page-only. Do not set both `Build` and `Prebuilt` in one -request. +result, delivery is page-only. A prebuilt result with no targets or artifacts +must still identify the matching repository, module directory and path, tag, +commit, and version; a zero `BuildResult` does not. Do not set both `Build` and +`Prebuilt` in one request. ```go result, err := releasekit.Deliver(ctx, releasekit.DeliveryRequest{ diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 7bd0b64..4c12613 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -382,7 +382,9 @@ integration guide without strengthening page-only read requirements. ## Stage 9: Align delivery documentation with existing behavior -**Status:** pending. +**Status:** complete. The preflight-before-hashing and page-only regressions +pass offline. GoDoc and consumer guidance now describe matching empty results, +preparation selection, and verification before hosted writes. **Files:** `delivery.go` GoDoc and `docs/consumers/delivery.md`; review related current descriptions for consistency. This stage changes documentation only.