Skip to content

ci: make public-hygiene-lint green - #4

Open
MattJackson wants to merge 4 commits into
mainfrom
ci/public-hygiene-green
Open

ci: make public-hygiene-lint green#4
MattJackson wants to merge 4 commits into
mainfrom
ci/public-hygiene-green

Conversation

@MattJackson

Copy link
Copy Markdown
Contributor

public-hygiene-lint was RED on main in this repo. Every hit is fixed by rewriting the text to
state the BEHAVIOUR rather than our internal process. No allow markers were added anywhere in
this change: a blanket allow would turn the gate into decoration.

Hits found on main, and the decision for each

  • .github/scripts/next-version.sh + .github/workflows/release-selftest.yml [internal-issue-id]
    cited an internal guard id. REWRITTEN: id dropped.
  • store-mysql/src/lib.rs [internal-issue-id] cited an internal audit command as the provenance of
    a documented gap. REWRITTEN: the gap and its reasoning are fully stated in the same comment, so
    the provenance added nothing a reader can open.
  • store-mysql/src/lib.rs [editor-directed] addressed the next editor ("do not "fix" this with a
    lock"). REWRITTEN as a statement about the code: a lock is not the fix, and the comment already
    explains why.
  • store-mysql/src/lib.rs [authoring-meta] said the redesign was "out of scope for this pass".
    REWRITTEN to state the durable fact: the redesign has not been done.

Red before green

Same invocation CI uses. Output is ASCII-folded for this description; the runs are verbatim
otherwise.

Before (on main)

$ python3 busbarAI/scripts/public-hygiene-lint.py --root .
== public-hygiene: what a customer reads, in . ==
  scanned 18 file(s) via git ls-files; 11 rules applied

  [authoring-meta] meta-commentary on how the change was authored - 1 hit(s)
      why: narrates the authoring transaction (who asked, what was in scope, who decides); a shipped file should carry no evidence that it was commissioned at all
      store-mysql/src/lib.rs:299: /// provenance marker) - real redesign work, out of scope for this pass. OPERATIONAL MITIGATION

  [editor-directed] prose addressed to whoever edits the file next - 1 hit(s)
      why: speaks to a future maintainer instead of describing the software; the object is the FILE, which is what keeps invariant prose like `do not touch the breaker` silent
      store-mysql/src/lib.rs:283: /// adversarial design reviews - do not "fix" this with a lock; both reviews independently showed

  [internal-issue-id] internal issue / task / audit-round identifier - 3 hit(s)
      why: cites a tracker or audit artifact the reader cannot open; `task #141` and `R27 #8` shipped inside operator-facing API documentation
      .github/scripts/next-version.sh:5: # release automation can't silently rot (guard #135.8). Prints "v<MAJOR>.<MINOR>.<PATCH>" to stdout.
      .github/workflows/release-selftest.yml:1: # CI self-test for the release-on-upstream version-compute logic (guard #135.8).
      store-mysql/src/lib.rs:282: /// KNOWN, DOCUMENTED, NOT-YET-CLOSED GAP (found in `/codeaudit`, confirmed by two independent

== result ==
  18 public file(s) scanned against 11 rules - 5 hit(s), 0 allowed
  public-hygiene-lint FAILED
  These lines describe how the software was BUILT, not what it does, in files a
  customer can read. Rewrite the text to state the behaviour or the invariant; if a
  line is genuinely legitimate, mark it:
    # public-hygiene-lint: allow - <why this text belongs in a public file>

After (this branch)

$ python3 busbarAI/scripts/public-hygiene-lint.py --root .
== public-hygiene: what a customer reads, in . ==
  scanned 18 file(s) via git ls-files; 11 rules applied

== result ==
  18 public file(s) scanned against 11 rules - 0 hit(s), 0 allowed
  public-hygiene-lint passed

Matthew Jackson and others added 4 commits August 8, 2026 16:00
The public-hygiene gate flags text in customer-readable files that
describes how the software was BUILT rather than what it DOES. Every hit
in this repo is rewritten to state the behaviour or the invariant; no
allow markers are added, so the gate keeps its teeth.
busbar resolves `env:` secret references during `--validate` now and exits
non-zero when one cannot resolve, so the file-drop fixture -- which names
`providers.mock.api_key: { env: MOCK_KEY }` and never exported MOCK_KEY --
described a gateway that could not start:

  busbar --validate must succeed with the file-dropped mysql plugin: stdout=
  stderr=[error] providers.mock.api_key: secret env:MOCK_KEY cannot resolve:
  environment variable 'MOCK_KEY' is unset

CI had not surfaced this one yet: the admin-API test failed first for a
different reason and aborted the run before this binary was reached.

The variable names are derived FROM the config files busbar is about to read,
rather than listed at each call site, so the next person to add a secret
reference to one of these fixtures does not also have to remember to export it --
forgetting produces a failure that never names the variable. Reading the files
back (not the strings the test built them from) is what keeps the two from
drifting apart. `tests/common/mod.rs` holds the scan; `tests/config_secrets.rs`
covers it directly.

Red-before-green against a real `busbar` built from the core branch CI tests
against, and a real mysql: before, `load_and_exercise_mysql_plugin_via_file_drop`
FAILED with the error quoted above; after, every test in the crate passes.
`e2e.rs`'s `plugin_path()` looked only at the "uplifted" `<profile>/<name>` copy
of the cdylib. A bare `cargo test` does not uplift it -- only `cargo build` does
-- so on a developer machine the lookup returned None and every test returned
early with a cheerful green:

  running 3 tests
  test load_and_exercise_mysql_plugin_via_file_drop ... ok
  test result: ok. 3 passed; ... finished in 0.00s

Nothing ran. That 0.00s is the tell, and it is easy to miss. CI is protected by
the `is_none() && CI` panic below, so this never shipped a false green there, but
it meant the only over-the-ABI coverage of this plugin was routinely not running
locally, which is where it is most useful.

`admin_api_e2e.rs` in this same crate ALREADY had this exact fix; `e2e.rs` was
never brought into line. That is the drift this closes.
@MattJackson
MattJackson force-pushed the ci/public-hygiene-green branch from c829756 to 1d4c25a Compare August 9, 2026 02:36
MattJackson added a commit that referenced this pull request Aug 12, 2026
The daily schedule's minute and hour fields had been shifted out of the cron
expression and into bundle_image, in BOTH consumer-verify.yml and release.yml:

    - cron: " * * *"          # three fields; GitHub requires five
      bundle_image: 53 9        # the missing two, as an image name

GitHub rejected the workflow file outright -- every push to dev reported a
red 'This run likely failed because of a workflow file issue' with no job and
no log -- and the daily rot check that file exists to run had never fired once.

bundle_image is now empty, which is the truthful value: this repo publishes one
kind of artifact, a signed busbar-store-*.tar.gz per target, and no container
bundle appears in any of its workflows. Empty makes the shared workflow declare
the runnable-bundle boot check NOT-APPLICABLE rather than silently skip it. The
comment claiming this repo ships a runnable bundle came from headroom-hook and
was never true here.

Pre-existing on dev (#4), independent of the durable-store work landing beside
it; fixed here because it made every push to dev read as red.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant