docs: document the splinter.public_buckets contract

[sidgaikwad]

Fixes #181 (suggestion 1 — documenting the contract; the fail-loud and self-contained-fallback options are left alone, since both change a security lint's behavior and are yours to call).

The problem

Since #170, 0025_public_bucket_allows_listing no longer reads storage.buckets. It reads the bucket list from a setting:

coalesce(nullif(current_setting('splinter.public_buckets', true), '')::jsonb, '[]'::jsonb)

That setting is populated by the preamble in splinter.sql, transaction-locally:

perform pg_catalog.set_config('splinter.public_buckets', buckets, true);

So a consumer that runs the lint query outside that transaction reads an empty bucket list and gets zero findings — which reads as "no affected buckets" rather than "this lint never evaluated anything."

Reproduced

Against supabase/postgres:17.6.1.136 with one public bucket and one broad PERMISSIVE SELECT policy on storage.objects (for select to anon using (true)) — same file, same database, same exposure, only the invocation differs:

Invocation	0025 findings
psql --single-transaction -f splinter.sql	1 — public_bucket_allows_listing / WARN / {SECURITY}
psql -f splinter.sql	0

The second run is silently green while the bucket is still listable.

What this changes

A ### Storage lints and splinter.public_buckets`` section in the README, placed next to the existing pgrst.db_schemas one and following its shape: what the setting is, that the preamble sets it transaction-locally, the `--single-transaction` invocation, and what an invisible setting produces.

It also notes the same constraint for splinter.json consumers. bin/compile_json.py emits setup (from compile.HEADER) and per-lint query as separate fields, and HEADER is exactly this preamble — plus set local search_path = '', which needs a transaction for the same reason. The manifest's own docstring describes setup as a "prelude run once, verbatim, before the lints", which doesn't say the lints must share its transaction.

Scope

Docs only — no lint or compiler changes, so splinter.sql and splinter.json are untouched.

Two things from the issue I deliberately did not address, both still open for a maintainer decision:

• Fail-loud vs fail-open. Distinguishing an absent setting from a legitimately empty [] is the actual fix for the hazard; this PR only makes the contract discoverable.
• The qual-matching addendum. The reporter notes bucket_id IN ('my-bucket'), 'my-bucket' = bucket_id and bucket_id = 'my-bucket' AND true match none of 0025's enumerated patterns, so those buckets yield no finding while staying listable. That's a separate lint change, and I'd be happy to take it as its own PR if you want it.