# =============================================================================
# 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.