[fas89]

Follow-up to #734, which made fluid validate --env <env> --strict fail on an overlay patch that lands on another entry (overlay_patch_retargeted) but left the bundle path out. Pipeline stage 2 runs exactly fluid validate <bundle> --env <env> --strict, and a bundle is never re-overlaid, so validate on the frozen bundle could not see the warning: it was only logged by fluid bundle, and the bundle passed.

What changes

• fluid bundle --env merges the overlay inside loader.collect_overlay_warnings(), says each collected warning once, and records it in MANIFEST.json under source.overlayWarnings. The key is written only when there is a warning. The source block is outside the merkle root, so the bundle digest is unchanged (the sample bundle keeps main's sha256:6238f9…). For --format tgz it prints overlay warnings: N recorded in the bundle; ....
• fluid validate <bundle>.tgz reports each recorded warning as a finding ([warning] overlay: MANIFEST.json: ..., code OVERLAY-WARNING), so --strict fails on it. It shows in --format json and --report too.
• The bundle path now prints what the contract-file path prints. A passing bundle lists its warnings, not only their count. --quiet used to print nothing at all; it now prints ERROR: lines, a recorded overlay warning as WARNING:, and under --strict each warning as ERROR (--strict):. When warnings alone fail --strict, it says Validation failed: warnings treated as errors (--strict).
• A bundle without the record (one built before this change) has none recorded and validates as before.

Two fixes the pre-PR defect scan found, as separate commits:

• A collector block that raises now logs what it took. A patch retargeted before another overlay entry failed the merge was otherwise never shown. That was a regression in the first cut of fluid bundle, and it was already the case in feat: trigger.type continuous (0.7.6 preview) is never scheduled; --strict fails on a retargeted overlay patch #734's fluid validate --env and fluid contract-validation --env. The fix is in collect_overlay_warnings, so it covers all three.
• A hand-edited record cannot drive the terminal. Editing overlayWarnings keeps the digest. Escape sequences in it could move the cursor or forge lines, and a lone surrogate crashed validate before it wrote --report. Non-printable characters are now escaped as repr writes them, as the block's other values are quoted with !r. _cprint_literal also passes highlight=False, like _cprint_json, because Rich's highlighter is quadratic in a run of <.

Not in this PR

• fluid contract-validation <bundle> and fluid test <bundle> do not read the record. The CHANGELOG says so and points at the contract file with --env. Generated pipelines run those commands on the contract file.
• Other bundle findings still print MANIFEST- or contract-derived text unescaped, for example the expected digests in MANIFEST-TAMPER. That is already the case on main.

Documentation

• Docs PR linked:
  • Docs PR: docs: a bundle records a retargeted overlay patch, and fluid validate --strict fails on it (forge-cli #735) forge_docs#158
• No docs needed
• Docs TODO

forge_docs#158 updates cli/validate.md (the bundle bullet under --env, "Validating a bundle", and OVERLAY-WARNING), cli/bundle.md (source.overlayWarnings) and concepts/environments-and-overlays.md. It needs review.

Also fixed: the overlay CLI tests under a leaked debug level

tests/cli/conftest.py sets FLUID_LOG_LEVEL=DEBUG, and some xdist workers keep it. At DEBUG the loader also logs a warning the command reports, so #734's TestValidateStrict tests counted it twice (assert 2 == 1). That is how they failed on main's CI for 1320619b. The CLI subprocesses in tests/test_overlay_keyed_merge.py now drop FLUID_LOG_LEVEL, FLUID_DEBUG and FLUID_SHOW_REGISTRATION, as tests/output_ports already does. The file passes with and without FLUID_LOG_LEVEL=DEBUG set.

Borrowed

• The record follows SLSA Provenance v1, which keeps the artifact digest (subject) apart from run metadata (runDetails). The MANIFEST source block already had that split, so the record is metadata about the build and not bundle content.
• SARIF was considered and not used: it is a full diagnostics format, and this is one list of strings in an advisory block.

Test plan

• tests/test_overlay_keyed_merge.py:
  • TestValidateBundleStrict (11 tests), the reader unit test and a collector test. Every test that can fail did fail against the code before its fix: 8 against main, and the 4 gate-fix tests against the first cut. The other 2 pass on main by design: they are additivity guards (a keyed overlay records nothing, and a bundle without the record still passes --strict).
• Ran the real CLI:
  • fluid bundle contract.fluid.yaml --env prod --format tgz with a positional 0.7.5 overlay, then fluid validate runtime/bundle.tgz --env prod --strict (the stage-2 command), exits 1 and names the patch.
  • Also checked plain, --quiet, --quiet --strict, --format json, --report, an env mismatch next to the warning, --out - YAML (stdout stays clean), hand-edited overlayWarnings shapes, and fluid plan + fluid apply --dry-run on a bundle that carries the record.
• ruff check fluid_build/ tests/, black --check (24.10.0), lint-imports (6 kept) and scripts/mypy_strict.py all pass.
• Full suite (-n 6, ~50 min at load avg ~124): 27,059 passed. The 10 failures and 2 errors are all environmental or already on main:
  • 6 fail the same way on a clean canonical/main export: the dlt allow-list tests (4) and the duckdb sandbox temp-root tests (2).
  • 2 collection errors: bashlex is not installed in the local venv.
  • 3 are load: two wall-clock perf budgets, and a Hypothesis "input generation is slow" health check.
  • 1 dotenv test passes in isolation; it depends on xdist ordering.
  • The local venv's sqlglot install is broken (a stale sqlglotc compiled extension). For the run it was shadowed with a working pure-Python sqlglot through PYTHONPATH.

[github-actions]

📄 Documentation Reminder

This PR appears to be missing a documentation reference. Our docs live in a separate repo.

Please update the PR description with one of:

• Link a docs PR — check the "Docs PR linked" box and paste the URL
• Mark as no docs needed — check "No docs needed" with a justification
• Acknowledge docs TODO — check "Docs TODO" and create the docs PR before merge

See the Contributing Guide for details.