jakman85andClaude Opus 5
830983b791
The implementation landed in the preceding WIP commit had never been executed. This finishes it: the arithmetic is re-measured, the guard and its allowlist are attacked, and the header's one factual error is corrected. WHAT ENVSUBST ACTUALLY IS. The header credited `github.com/drone/envsubst`. The pinned flux 2.4.0 binary in the dev image embeds `github.com/fluxcd/pkg/[email protected]` — Flux's own fork of drone/envsubst ("This package is a fork of drone/envsubst", its README) — read straight out of the binary with `grep -ao`. Same behaviour, different module; the header now says so and says how to check, because a claim about a dependency that nobody can re-derive is how the last wrong assumption survived. RE-MEASURED, NOT ASSERTED. Every row of the DOLLAR-RUN ARITHMETIC table was re-run through `flux envsubst` (flux 2.4.0, DEFINED=VALUE) and every row holds: `$$`->`$`, `$$$`->`$$`, `$${D}`->`${D}`, `$$${D}`->`$VALUE` (odd run: the brace is LIVE), `$$$${D}`->`$${D}`, `DO $$ x $$;`->`DO $ x $;`, and `$$${ARR[0]}` dies with "missing closing brace" while `$${ARR[0]}` is fine. `--strict` output was byte-identical to non-strict, exit 0 both ways (`cmp`) — strict mode is blind to this whole class, which is why a source assertion is the only guard available. The header now carries the 30-second reproduction, flagged to be re-measured on any FLUX_VERSION bump. END TO END ON THE REAL PATH. With the pre-16b7fcd manifest restored, `kubectl kustomize apps/wave-0` emits `DO $$` — valid SQL, and exactly what the `kubectl apply` verification saw — while the same stream through `flux envsubst --strict` emits `DO $` and `$;` and exits 0. That two-command contrast IS the incident. THE GUARD IS NOT TRIVIALLY SATISFIABLE — 16 adversarial cases, all as intended, run against a throwaway copy of the tree so nothing could be left behind: * an unmarked `$$` under a substituted path FAILS (DOLLAR-COLLAPSE); so do an odd `$$${...}` (DOLLAR-HALF-ESCAPED) and an even `$$$${...}` (OVER-ESCAPED); * a stale entry FAILS three ways — context no longer in the file, context that only covers an already-accepted `$${` escape and so excuses nothing, and a path that is not a file in the repo; * the allowlist cannot blanket-exempt a path: a 2-char context is rejected (<24), a `.*` wildcard is matched VERBATIM and therefore rejected as stale, a 24-char context carrying no dollar run is rejected, a 4-char reason is rejected (<40) — and, the central case, a genuine entry covers only the span its context matches, so a SECOND `$$` elsewhere in the same file still fails. Two genuine entries for two real occurrences do pass, so the mechanism is usable rather than merely unsatisfiable; * the CLASS, not the instance: the pre-fix `DO $$ ... $$;` reconstructed in a NEW ConfigMap under apps/wave-2 fails at both dollar runs, and restoring the real pre-16b7fcd apps/wave-0/nextcloud-db.yaml verbatim fails the check at lines 384 and 391. The guard rejects the exact commit that broke production. The scratch fixtures lived only in the throwaway copy; `git status` on this branch stayed clean throughout, which is the other half of the last attempt's unfinished business. LEGITIMATE USES EXIST AND STAY GREEN. 18 `$${...}` escapes (unifi cloud-init, the gitea and nextcloud OIDC bootstrap scripts, two longhorn comments) pass unremarked, and the 2 non-braced `$$` occurrences are the two allowlist entries. Those two are shell comments inside block scalars, and `kubectl kustomize` confirms the comment text really does survive into the stream envsubst reads — so they are genuine, reaching content whose collapse is cosmetic, not a hypothetical the allowlist was invented to excuse. STILL NOT PROVEN, AND STILL NOT PROXIED: that a change was verified through a substituting path. Which command a human ran is a fact about a shell session; git stores the manifest, never the invocation, so it is not statically decidable here and no honest formulation exists. Grepping commit prose for `kubectl apply` would be satisfiable by rewording and would fire on the break-glass runbooks whose whole content is that command. The answer is to move the proof off the verification path and onto the source, which is what assertion (7) does. No ci/l0.sh stage: the `conformance.home.k3s/scope: "whole-repo"` annotation is what wires it, and whole-repo-invariants-wired fails the gate on a hand-written stage. Co-Authored-By: Claude Opus 5 <[email protected]>
53 lines
4.2 KiB
Plaintext
53 lines
4.2 KiB
Plaintext
# =============================================================================
|
|
# dollar-collapse.allow — the reviewed exceptions to assertion (7) of
|
|
# conformance/tests/l0-static/flux-postbuild-substitution/check.sh.
|
|
#
|
|
# WHY THIS FILE EXISTS
|
|
# --------------------
|
|
# Flux's postBuild substitution runs github.com/fluxcd/pkg/envsubst (Flux's fork of
|
|
# github.com/drone/envsubst; the module path is embedded in the pinned flux 2.4.0
|
|
# binary, and check.sh's header says how to read it back out) over everything a
|
|
# substituted Kustomization renders, and that scanner consumes dollars in PAIRS,
|
|
# emitting ONE dollar per pair — unconditionally, wherever they appear, not only in
|
|
# front of a brace. A run of N dollars becomes floor(N/2) dollars, and an ODD run
|
|
# leaves one live dollar behind (so `$$${X}` is NOT escaped; it expands).
|
|
#
|
|
# Consequence: there is NO way to ship a literal `$$` through a substituted path.
|
|
# On 2026-09-13 that broke the nextcloud-db grant reconciler — a dollar-quoted
|
|
# PL/pgSQL `DO $$ ... $$;` block reached Postgres as `DO $ ... $;` and every
|
|
# Flux-reconciled run died with `syntax error at or near "$"`. It had passed review
|
|
# because it was hand-applied with `kubectl apply`, which runs no envsubst at all.
|
|
# See commit 16b7fcd and check.sh's DOLLAR-RUN ARITHMETIC table (measured against
|
|
# flux 2.4.0, not inferred).
|
|
#
|
|
# From the source text alone, a doubled dollar the author WANTS collapsed and one
|
|
# that must arrive verbatim are indistinguishable. check.sh therefore accepts exactly
|
|
# one shape without comment — a run of EXACTLY TWO dollars immediately followed by
|
|
# `{`, the escape contract clusters/base/apps-vms.yaml already documents and that 18
|
|
# reviewed occurrences already depend on — and FAILS every other run of two or more
|
|
# dollars unless it is named here.
|
|
#
|
|
# ADDING AN ENTRY IS A DECISION, NOT A MUTE BUTTON
|
|
# -----------------------------------------------
|
|
# One entry per line, exactly three `|`-separated fields:
|
|
#
|
|
# <repo-relative path> | <verbatim context> | <reason>
|
|
#
|
|
# * the context must be a VERBATIM substring of the file AS STORED IN GIT (for a
|
|
# folded/JSON-ish scalar that means the escaped bytes, e.g. `\n` and `—`
|
|
# spelled literally), at least 24 characters long, containing the dollar run it
|
|
# excuses, and containing no `|` — shift the window if a pipe is in the way;
|
|
# * the reason must be at least 40 characters and should say what envsubst will
|
|
# actually EMIT and why that is acceptable;
|
|
# * an entry covers only the dollar runs inside the region its context matches, so
|
|
# it can never silently cover a new occurrence that lands elsewhere in the file;
|
|
# * check.sh FAILS a stale entry — one whose context no longer matches, or which
|
|
# excuses nothing any more. Delete it rather than leaving it to rot into a
|
|
# blanket exemption for whatever lands in that file next.
|
|
#
|
|
# If the collapse would change BEHAVIOUR, this file is the wrong answer. Rewrite the
|
|
# content without dollars (16b7fcd) or double them again (`$$$$` -> `$$`).
|
|
# =============================================================================
|
|
apps/wave-0/gitea.yaml | # NOTE the `$$` escape below \u2014 it is load-bearing. apps-wave-0 declares postBuild. | Prose, not code: this is a comment INSIDE the gitea OIDC bootstrap shell script, and the two dollars are the sentence quoting the escape idiom it goes on to explain. envsubst renders it as "the `$` escape below", which is cosmetically wrong and behaviourally inert — a shell comment. Cannot be written correctly at all: `$$$$` would render `$$` but would then be wrong in the source a reader sees in git, and the file has no non-dollar way to name the idiom. Reviewed and accepted as cosmetic.
|
|
apps/wave-1/nextcloud.yaml | # NOTE the `$$` escape below \u2014 it is load-bearing. apps-wave-1 declares postBuild. | Identical case to the gitea entry above, in the nextcloud OIDC bootstrap script: a shell comment quoting the escape idiom, rendered by envsubst as "the `$` escape below". Cosmetic only — the collapse happens inside a `#` comment line that no interpreter reads, and the escaped expansion the comment is describing is on a later line and is unaffected. Reviewed and accepted as cosmetic.
|