Add --mode, --track-state flags to aspect delivery

[gregmagolan]

Summary

Reshape aspect delivery around three orthogonal flags so it can run in environments without persistent state (local development, non-Aspect-Workflows CI) and supports always-deliver semantics:

• --mode={selective,always} (default selective) — selective uses change detection (only runs candidates that haven't already been delivered for the --task-key[:--salt] prefix). always skips change detection and runs every resolved target — closest analogue to the legacy only_on_change: false rule attribute. Useful for use cases where you want to deliver every target on every commit.
• --track-state={true,false} (default true) — opt out of recording/querying delivery state across runs. Required false for environments where the state backend isn't available.
• --dry-run (existing) is now strictly orthogonal to --mode — composes with both.

The current state backend is deliveryd. The flag is named --track-state rather than --deliveryd so the public API doesn't leak the service name; deliveryd continues to be referenced internally where it's an accurate implementation detail.

Rejected combination

--mode=selective --track-state=false is rejected at startup: change detection cannot decide what to deliver without persisted state. The error message points users to --mode=always.

Best-effort preview

--mode=always --dry-run --track-state=false is the only combination tolerant of a missing remote cache:

• With a remote cache: computes action digests and shows them in the dry-run output.
• Without one: prints a NOTE: and falls back to listing candidates without digests; everything else still works.

Every other mode still hard-errors on missing remote cache because they need digests for correctness (recording or change-detection decisions).

Combination matrix

Combination	phase 1/2	phase 3	record	query	run	deliver
--mode=selective (default)	✓	✓	✓	✓	✓	✓
--mode=selective --dry-run	✓	✓	✓	✓	—	—
--mode=selective --track-state=false	rejected at startup
--mode=always	✓	✓	✓	—	✓	✓
--mode=always --dry-run	✓	✓	✓	—	—	—
--mode=always --track-state=false	—	✓	—	—	✓	—
--mode=always --dry-run --track-state=false	optional	—	—	—	—	—

Phase 3 is the same code path across all modes (same bazel build call, same flags). What differs is what's already in any configured remote cache going in — when phase 1/2 ran first, phase 3 typically downloads its outputs; when phase 1/2 was skipped, phase 3 may build more from source / local cache, or hit cache from prior unrelated jobs.

Why --mode=always records by default

When state tracking is enabled, --mode=always records the digests and deliveries it produces. A subsequent --mode=selective run sees those digests in its change-detection check and skips them — usually what you want from a backfill. Pass --track-state=false if you specifically want --mode=always to skip recording.

Hook dispatch

bazel_trait.build_end hooks fire once per invocation, with the relevant build's exit code: phase 1/2 status when phase 1/2 ran, phase 3 status when only phase 3 ran (--mode=always --track-state=false). Features registered to that hook (e.g., ArtifactUpload's testlogs flush + profile/execlog/BEP upload) work in all modes.

Documentation

• Module docstring at the top of delivery.axl is rewritten as the public-facing reference: pipeline phases, flag set, combination matrix, failure modes, and design rationale. User-facing prose uses "change detection" to describe the what; implementation comments retain action_digest / deduplication prefix terminology where they describe the how.
• User-facing migration guide updated separately at docs.aspect.build/cli/migration/delivery (in the docs repo).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: da09e721de

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".