@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/cost-rca/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: cost-rca
+description: Quantify what a context/caching/model change did to token spend and dollars, from measured usage data, never estimates. Use when the user asks "how much did that cost", "did caching save money", "why did my bill spike", or "token delta". Not for choosing which model to use (use `model-tiering`) or comparing models head-to-head (use `model-bakeoff`).
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Cost-Impact RCA
+
+Answer "what did this change do to cost, and why" with MEASURED evidence, not guesses.
+Deterministic-first: the script measures; you narrate and price live.
+
+## Non-negotiables
+
+- **Measured tokens only.** Never quote `tokens_estimate` or the ledger's `est_cost_usd`
+  as the answer. `scripts/cost_rca.py` already excludes estimate-only rows and surfaces
+  them separately as *unmeasured spend* — call that out, do not price it as if measured.
+- **Price LIVE, never from memory.** Rate cards drift. Fetch the current per-MTok price
+  for each bucket (input / output / cache-read / cache-write) at analysis time and CITE
+  the source. Prices from training data are `[UNVERIFIED]` and must not drive a number.
+- **Per bucket, not a blended rate.** Cache-read is ~10× cheaper than input and cache-write
+  is ~1.25× input on Anthropic's card — a blended rate hides the whole point of the RCA.
+
+## Procedure
+
+1. **Aggregate measured tokens** (deterministic):
+   ```
+   python3 scripts/cost_rca.py --ledger ~/.bookmark/cost-ledger.jsonl [--run-id R] [--since ISO] [--group-by model] --json
+   ```
+   Output gives, per model and in total: `inbound`, `outbound`, `cache_read`, `cache_write`,
+   `total_tokens`, `context_utilization` (peak input-side vs the model's window), and the
+   `estimate_only_rows` count. For a before/after RCA, run it twice (two `--since`/`--run-id`
+   windows) and diff the buckets — that diff IS the token delta.
+
+2. **Fetch the current rate card LIVE** for each model present. Order:
+   `/api-registry:lookup <provider>` → the `claude-api` skill (for Anthropic) →
+   WebSearch the provider's official pricing page. Record per-MTok: input, output,
+   cache-read (5-min/1-hr as applicable), cache-write. Cite each. Mark confidence
+   (✅ official docs / ⚠️ secondary / ❓ unverified).
+
+3. **Price each bucket**: `dollars_bucket = tokens_bucket / 1_000_000 * price_bucket`.
+   Report per bucket AND per model, then the total. Show the arithmetic — the reader
+   must be able to re-derive it.
+
+4. **Context-window utilization**: report `peak_input_side / context_window`. High
+   utilization + high cache-write with low cache-read is the classic "cache thrash"
+   signature — a candidate root cause for a cost regression. Confirm the current window
+   live (windows change); the script's baked-in windows are advisory.
+
+5. **Root cause + lever** (blameless): name the token-level cause (e.g. "system prompt
+   re-sent uncached each call → all inbound, zero cache-read"), then the smallest durable
+   lever (stable-prefix ordering for cache hits, prompt trim, tier swap, context offload).
+   Quantify the projected saving in tokens AND live dollars.
+
+## Output shape
+
+Lead with the headline dollar/token delta and the ✅/⚠️/❓ confidence on the pricing.
+Then the per-bucket table (tokens · live $/MTok · $), then the root cause and the lever
+with its projected saving. Keep the ledger path + pricing citations in a footer so the
+number is auditable.

package/skills/data-plane-worktrees/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: build-loop:data-plane-worktrees
+description: "Decide how a build/worktree safely isolates mutable non-Git state (databases, caches, volumes, indexes) so parallel work doesn't collide. Use when the user asks \"is it safe to run this in parallel\" or \"will this migration collide with the other branch\", or a run touches a database/cache/volume. Covers SQLite and PostgreSQL databases, generated search/vector indexes, Docker volumes, mutable file trees, and external cloud/account namespaces."
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Data-Plane Worktrees
+
+Treat a Git worktree as source-plane isolation only. Inventory and isolate every
+mutable resource the run can read or write before implementation starts.
+
+## Classify every surface
+
+| Isolation | Use for | Required evidence |
+|---|---|---|
+| `per_worktree` | SQLite copies, generated indexes, mutable file stores, disposable local state | `path` under the allocated run data root |
+| `shared_readonly` | Canonical raw inputs, fixtures, large immutable corpora | `writable: false` |
+| `shared_serialized` | A central writer that cannot be cloned, such as a canonical index updater | Stable `writer` key naming the serialization authority |
+| `external_namespaced` | PostgreSQL databases/schemas, Compose projects, buckets, queues, cloud accounts | Stable `namespace` unique to the run |
+
+Prefer `per_worktree`. Use shared mutation only when cloning or namespacing is
+not practical and one explicit writer serializes all changes.
+
+## Workflow
+
+1. Read the run identity and baseline manifest from
+   `.build-loop/state.json.execution.{build_loop_id,data_manifest_path,data_root}`.
+   Fresh isolated runs create these fields automatically.
+2. Inventory all non-Git state read or written by code, tests, migrations,
+   services, hooks, and generated artifacts. Treat an omitted surface as an
+   unresolved isolation risk.
+3. Add each surface through the validator before any adapter provisions or
+   mutates it:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/data_plane.py" add \
+     --workdir "$PWD" \
+     --manifest "$DATA_MANIFEST" \
+     --surface-json '<surface-json>'
+   ```
+
+4. Run `validate` before the first write. A collision, escaping path, invalid
+   shared writer, or malformed peer manifest fails closed.
+5. Let the repository-specific adapter perform the actual copy, migration,
+   service provisioning, or namespace creation. The generic lifecycle never
+   guesses credentials or destroys external resources.
+6. After adapter cleanup or an explicit retain decision, record each writable
+   surface as `closed`, `retained`, or `not_owned`:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/data_plane.py" close \
+     --manifest "$DATA_MANIFEST" \
+     --surface-id '<surface-id>' \
+     --status closed
+   ```
+
+7. Run `terminal` before branch closeout. The canonical closeout gate repeats
+   this check and blocks active, deferred, or errored owned surfaces.
+
+## Surface shape
+
+```json
+{
+  "id": "search-index",
+  "kind": "generated-index",
+  "authority": "derived",
+  "isolation": "per_worktree",
+  "writable": true,
+  "resource_key": "index:search:<run-id>",
+  "path": "search-index",
+  "status": "active"
+}
+```
+
+Use a stable `resource_key` for the underlying resource, not a display label.
+Two active manifests may share a key only when both use `shared_serialized` and
+declare the same non-empty `writer`.
+
+## Database and file rules
+
+- SQLite: snapshot into the run data root; never open the canonical file for
+  writes from two worktrees.
+- PostgreSQL: prefer database-per-run for migrations. Schema-per-run is
+  acceptable only when extensions, roles, and database-level DDL are out of
+  scope.
+- Generated indexes: build per run; merge source changes first, then rebuild the
+  canonical index once through its declared writer.
+- Docker/Compose: derive a unique project and volume namespace from the run id.
+- Sensitive or large raw files: mount or reference read-only; keep copied
+  derivatives in the run data root.
+
+The run data root lives at canonical `.build-loop/data/<run-id>/`, outside the
+linked source worktree. Putting ignored data inside a linked worktree makes
+normal non-force `git worktree remove` fail.
+
+## Migration rehearsal (isolated — production never touched)
+
+Run on **Fable** (DB actions pin Frontier tier — see `skills/model-tiering`). Rehearse migration-first deploys against a throwaway **local** DB before any production migration. Hard guard: assert the target URL contains `@127.0.0.1:` (or your local host) AND a `rehearsal` marker before every create/apply/drift/teardown; never read `DATABASE_URL`/`DIRECT_URL` when they point at prod.
+
+1. Create ephemeral DB (`atomize_rehearsal_<run>`), materialize the **base (origin/main) schema** so ALTER targets and FK parents exist.
+2. Apply each migration in order (`psql -v ON_ERROR_STOP=1 -f`); re-apply to prove **idempotency** (exit 0 both times).
+3. Drift-check the migrated DB vs the branch datamodel — exit 0 = no missing columns/tables (no runtime `P2022`).
+4. Functional-test the new CHECK/FK constraints (bad value rejected, good value accepted).
+5. Drop the ephemeral DB **and any cluster-global roles/extensions you created** (roles are not per-DB — verify 0 remain).
+
+**Prisma 7 CLI (verified 2026-07-22 — several v6 flags were removed):**
+
+```bash
+export PRISMA_MIGRATE_URL="postgresql://<user>@127.0.0.1:5432/atomize_rehearsal_<run>"  # highest precedence in prisma.config.ts
+# base schema DDL from a datamodel (--from-url REMOVED; --to-schema-datamodel REMOVED → use --to-schema):
+git show origin/main:prisma/schema.prisma > /tmp/base.prisma
+npx prisma migrate diff --from-empty --to-schema /tmp/base.prisma --script -o /tmp/base.sql
+psql -v ON_ERROR_STOP=1 -d atomize_rehearsal_<run> -f /tmp/base.sql
+# drift: migrated live DB vs branch datamodel (-o REQUIRED — env-injection notices pollute stdout):
+npx prisma migrate diff --from-config-datasource prisma.config.ts --to-schema prisma/schema.prisma --exit-code -o /tmp/drift.txt
+```
+
+Supabase-CLI migrations (`supabase/migrations/*.sql`) are plain SQL applied by `supabase migration up`/`db push` — apply them with `psql` in the rehearsal, NOT `prisma migrate deploy` (Prisma's `migrations.path` tracks `prisma/migrations` only). Additive `add column if not exists` (nullable) + `NOT VALID`→`VALIDATE CONSTRAINT` is the safe pattern; `VALIDATE` full-scans the table under SHARE UPDATE EXCLUSIVE (writes continue) — schedule off-peak when large.
+
+## Verification
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/data_plane.py" validate \
+  --workdir "$PWD" --manifest "$DATA_MANIFEST" --run-id "$BUILD_LOOP_ID"
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/data_plane.py" terminal \
+  --workdir "$PWD" --manifest "$DATA_MANIFEST" --run-id "$BUILD_LOOP_ID"
+```
+
+Validation cost scales with active manifest and surface count; it does not copy
+databases or rebuild indexes. Adapter-specific provisioning cost remains
+explicit in the plan and performance evidence.
+
+For the lifecycle contract and closeout integration, read
+`docs/SPEC-run-worktree-isolation.md` and `scripts/data_plane.py`.

package/skills/data-plane-worktrees/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Data-Plane Worktrees"
+  short_description: "Isolate mutable state across Git worktrees"
+  default_prompt: "Use $data-plane-worktrees to isolate this database and generated-state workflow across concurrent Git worktrees."

package/skills/database-practice/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: build-loop:database-practice
+description: "Measure a database before changing it, and prove an object is dead before retiring it. Use when a build creates or alters a table, column, or index; when a query is slow or the user asks why the database is slow; or when someone proposes dropping an empty table. NOT for worktree or data-plane isolation (use data-plane-worktrees). Runs the read-only attribution set, reads the runtime counters, and applies the retirement gate. The binding rules live in references/database-agent-constitution.md; this skill is the procedure that produces the evidence those rules require."
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Database Practice
+
+The rules are in `references/database-agent-constitution.md` — "Object Lifecycle
+And Population Contract" and "Cost Attribution And Retirement". This skill is how
+you generate the evidence they demand.
+
+Two things go wrong without it. A plan names a slow thing without naming its
+share, and optimizes the wrong 5%. An audit calls an empty table dead, and drops
+an object something still reads.
+
+## Procedure
+
+1. **Open the counter window.** `pg_postmaster_start_time()` and
+   `pg_stat_database.stats_reset`. Every counter below is "since" that timestamp,
+   and the window length is part of every claim you make from it. A 200-day
+   counter history is a stronger liveness record than the 30-day observation
+   period you were about to propose starting.
+2. **Attribute the time.** Run section 2 of the query set. Rank your proposal
+   against what is actually there. If it is not in the top 25, say so in the plan.
+3. **Read the shape, not the name.** Sections 3, 6, 7, 8, 9 catch the five cost
+   shapes below. Each has a fingerprint you can see without an execution plan.
+4. **Establish liveness before retirement.** Section 4, then the gate.
+5. **Attach before/after.** `calls`, `mean_exec_time`, `total_exec_time`,
+   `rows/calls`, `temp_blks_written`, and `idx_scan` for every index touched.
+   "The query looks faster" and "the build is green" are not evidence.
+
+Run everything inside `BEGIN READ ONLY` with a statement timeout. Never run the
+attribution set against production from an unbounded session.
+
+## The five shapes, with their fingerprints
+
+Ordered by observed share of database execution time in a real production
+instance (12 GB, PostgreSQL 17, 299 hours of tracked execution across 48M calls),
+not by textbook severity.
+
+| Share | Shape | Fingerprint | Fix |
+|---:|---|---|---|
+| 49.3% | Insert against a vector index larger than cache | 485,596 `INSERT`s at ~1,000 ms each into two pgvector tables; cost is nearly flat in row count | Split fixed from marginal cost first (below), then batch harder or shrink the index |
+| 14.8% | Predicate on a TOASTed column | mean in the tens of seconds on a table of only tens of thousands of rows; `pg_total_relation_size` far above heap + indexes | Derived scalar column (`content_length`), indexed, filtered on instead |
+| 8.9% | Per-row lookup through jsonb + trigram | high `calls`, mid-hundreds `mean_ms`, no supporting composite index | Composite index on the real filter columns; move the fuzzy match behind an exact one |
+| 4.5% | Vector similarity read | ~1 s mean against an HNSW index larger than `shared_buffers` | Size the graph to cache, or raise the cache |
+| — | Index maintenance charged to writes | index `idx_scan` near zero while its table takes hundreds of thousands of inserts | Drop it, or accept the write cost explicitly |
+
+### Split fixed from marginal before you "batch harder"
+
+`rows / calls = 1.00` looks like an unbatched loop and usually is. It was not
+here: the writer already batched, at four rows per statement, and the table
+simply produced one chunk for most articles.
+
+Regress `mean_exec_time` against `rows / calls` across the normalized statement
+variants pg_stat_statements already gives you for free. In this instance the
+call-weighted fit was **957 ms fixed per statement + 47 ms per row** — 95% fixed
+at one row per statement, still 84% fixed at the batch size actually in use. The
+fixed part is first-touch random I/O into an HNSW graph that cannot be cached;
+the marginal part is the real per-row index maintenance.
+
+The fit is observational — it reads variants the workload happened to produce, so
+batch size may correlate with row width and the projection is a hypothesis, not a
+result. Rehearse the new batch size against a copy before shipping it.
+
+That decomposition picks the fix. A high marginal cost means batch. A high fixed
+cost means the batch is too small for the overhead it is paying, or the index
+does not fit in cache — and raising this batch from 4 to 64 moves per-row cost
+from 286 ms to 62 ms without touching the index at all. Guessing which, without
+the split, optimizes the wrong term.
+
+Two numbers from the same instance make the index row concrete: a 2.31 GB HNSW
+index recorded **31 lifetime index scans across 214 days** while being maintained
+on 265,000 inserts, and a second HNSW index of 345 MB recorded **5**. Both were
+being paid for on every write. Meanwhile `shared_buffers` was 256 MB against a
+12 GB database — the graph could never be cached, so every insert was random I/O.
+
+Spill in the same instance: 336,253 temp files and 2,053 GB written, against a
+`work_mem` of 3.4 MB, with one CTE writing 41.8 GB across 91 calls.
+
+## Liveness: reading the counters
+
+| Signal | Reads as |
+|---|---|
+| `idx_scan > 0` | An application issued a filtered query. Audit scripts issue `count(*)`/`count(col)`, which are sequential scans, so an index scan is not audit noise |
+| `seq_scan` well above the median across peer tables | Real sequential reads on top of the audit/monitor floor |
+| `n_tup_ins > 0` with `n_live_tup = 0` | Written and purged — a working queue or retention job, not a dead table |
+| `n_tup_ins = 0` across the whole window | Never written since the counters started |
+| Query-text match in `pg_stat_statements` | A lower bound only — blind to dynamic SQL, views, routines, and evicted entries |
+
+`n_live_tup` is a stale planner estimate and must never decide emptiness. In the
+instance above it read seven populated tables as empty, one of them holding 148
+rows.
+
+Static source matching is the weaker method and errs both ways: it counted
+documentation and generated-client references as evidence of life for two tables
+that runtime showed had zero access in 214 days, and it flagged two others for
+retirement that runtime showed were being read.
+
+## Track tables — the map, and the diff against last time
+
+The attribution set answers "where does the time go today". The table map
+answers "what changed since the last time we looked", which is the question a
+schema change or a hot query needs. `scripts/db_table_map.py` collects every
+counter this skill reads, in one read-only transaction, and writes a JSON map
+plus a Markdown report with a **Shapes** section that names which of the five
+cost shapes each finding matches.
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/database-practice/scripts/db_table_map.py" \
+  --dsn "$DATABASE_URL" --statement-timeout 25 \
+  --out-json docs/10-reports/database-audits/$(date +%F)-database-map.json \
+  --out-md   docs/10-reports/database-audits/$(date +%F)-database-map.md
+# next time, diff against the previous JSON:
+python3 .../db_table_map.py --dsn "$DATABASE_URL" --prev docs/10-reports/database-audits/<prev>.json ...
+```
+
+The script strips the URI parameters psql rejects (`pgbouncer`, `connection_limit`,
+`pool_timeout`), refuses any DDL or DML, and wraps everything in `BEGIN READ ONLY`
+with a `SET LOCAL statement_timeout`. Commit both files under the project's
+`docs/**/database-audits/` directory; re-run with `--prev` whenever a migration
+lands or a query enters the top 25. A liveness verdict that flips, an index whose
+`idx_scan` stays flat while its table's inserts grow, or a size delta over 10%
+is the diff's job to surface.
+
+Verified 2026-09-05 against a 12 GB PostgreSQL 17.4 instance through a
+transaction-mode pooler: 128 tables, 529 indexes, 23 shape findings in one pass.
+
+## Vector and graph shapes
+
+pgvector indexes and knowledge graphs stored in plain SQL have their own
+fingerprints — a filtered similarity query that silently under-returns, an HNSW
+graph larger than `shared_buffers` maintained on every insert, a function whose
+`hnsw.*` settings never reached production, an adjacency table without a covering
+index in both directions, a materialized-neighbourhood cache with a hot-row update
+profile. `references/vector-and-graph-tuning.md` carries each fingerprint, the
+fix, and the pgvector settings (`ef_search` default 40; `iterative_scan`
+`relaxed_order` / `strict_order` from 0.8.0; `m` / `ef_construction`; function-scoped
+`ALTER FUNCTION ... SET` because a session `SET` is lost under a transaction-mode
+pooler).
+
+## Fingerprint → first action
+
+| Fingerprint (from the map or the query set) | First action |
+|---|---|
+| `INSERT` with `rows/calls` = 1.00 into a table with an HNSW/GIN index | Split fixed from marginal cost (regress `mean_exec_time` on `rows/calls`), then batch or shrink the index |
+| Index `idx_scan` near zero while its table takes ≥ 10⁵ inserts | Retirement gate: rename → observe → drop, or record why it is kept |
+| HNSW index larger than `shared_buffers` | Size the graph to cache (fewer dimensions, halfvec, partial index) or raise the cache; never assume the graph is resident |
+| Filtered vector query returns fewer rows than `LIMIT` | `ALTER FUNCTION ... SET hnsw.iterative_scan = relaxed_order` (function-scoped), then measure recall against an exact scan |
+| Vector function's `proconfig` lacks the `hnsw.*` settings the repo's SQL declares | Drift: restore with a migration and add a check that reads `pg_proc.proconfig` |
+| `pg_total_relation_size` ≫ heap + indexes (TOAST) on a filtered table | Derived scalar column beside the wide one; filter and sort on the scalar |
+| High `n_tup_upd` on a small table (hot rows) | Check HOT-update ratio and fillfactor; move the churn to an append-only side table |
+| `temp_blks_written` on a CTE or sort | Raise `work_mem` for that role or query only, after rehearsing against a copy |
+| `n_live_tup` = 0 but `idx_scan` > 0 | Not empty. `n_live_tup` is an estimate; run the exact `count(*)` from section 5 |
+
+## Sonnet-tier runbook
+
+Each step names the command, the output you must have in hand, and the stop
+condition. Do not skip to a fix; the evidence is the deliverable.
+
+1. **Window.** Run section 1 of the query set (or the map's "Counter window"). Have: `pg_postmaster_start_time`, `stats_reset`, window length in days. Stop if the window is under 14 days — say so in the plan; the counters cannot support a retirement claim yet.
+2. **Map.** Run `db_table_map.py` with `--out-json` and `--out-md` (and `--prev` when a previous map exists). Have: the Markdown report committed under `docs/**/database-audits/`. Stop if the script reports `pg_stat_statements` missing — attribution (step 3) is then a lower bound and the plan must say so.
+3. **Attribute.** Read the map's "Top statements by total_exec_time". Have: the share of DB time your proposal touches, quoted as a percentage. Stop if it is not in the top 25 — record the proposal as low-leverage and do not spend a migration on it without a stated reason.
+4. **Shape.** Read the map's "Shapes" section and the fingerprint table above. Have: one named shape per finding you intend to act on, with its evidence line. Stop if a finding matches no shape — escalate to a stronger tier with the evidence.
+5. **Liveness before retirement.** For any drop or rename, run the retirement gate below. Have: every checkbox with its evidence. Stop at the first unchecked line.
+6. **Before/after.** For every index or statement you change, record `calls`, `mean_exec_time`, `total_exec_time`, `rows/calls`, `temp_blks_written`, and `idx_scan` from the map before and after, and re-run the map with `--prev`. "The query looks faster" is not evidence.
+
+**Escalate to a stronger tier when:** the proposal is DDL on a table over 1 GB; any HNSW or GIN rebuild; any change to a function's `proconfig` or to `shared_buffers` / `work_mem`; attribution is ambiguous between two shapes; or the retirement gate depends on an owner who has not answered. State what was measured so far in the hand-off.
+
+## Retirement gate
+
+Every line holds, or the object stays:
+
+- [ ] A named owner confirms the feature state and its replacement.
+- [ ] Repository search covers raw SQL, ORM model names, mapped names, generated
+      clients, scripts, tests, and documentation.
+- [ ] Database dependencies cover foreign keys, views, materialized views,
+      routines, triggers, policies, and publications.
+- [ ] External workers, cron jobs, queues, dashboards, and integrations checked.
+- [ ] Runtime counters show zero reads and zero writes across a stated window,
+      and the window's start date is stated with it.
+- [ ] Retention, compliance, backup, and restore requirements resolved.
+- [ ] The change is a staged rename → deny → observe → drop.
+- [ ] Tests pass against the staged change.
+
+Stage one is always a rename with the old name left as a view, or a revoke. A
+drop that has not survived a rename has not been tested.
+
+## Query set
+
+`references/diagnostic-queries.sql` — counter window, time attribution,
+single-row-insert fingerprint, per-table liveness, exact emptiness, index cost vs
+benefit, duplicate indexes, temp spill, TOAST ratio, and the column population
+check. Verified green against PostgreSQL 17.4 on Supabase.
+`references/vector-and-graph-tuning.md` — pgvector/HNSW and graph-in-SQL
+fingerprints and fixes. `scripts/db_table_map.py` — the table map and diff.

package/skills/database-practice/references/diagnostic-queries.sql

@@ -0,0 +1,126 @@
+-- Read-only PostgreSQL diagnostic set for build-loop:database-practice.
+-- Run inside BEGIN READ ONLY with a statement timeout. Requires pg_stat_statements
+-- for sections 2-3; every other section works on a stock instance.
+--
+-- psql "$DATABASE_URL" -X -A -F $'\t' -v ON_ERROR_STOP=1 \
+--   -c 'set statement_timeout=30000' -f diagnostic-queries.sql
+
+-- 1. Counter window. Everything below is "since" these timestamps.
+--    stats_reset NULL means never reset; use postmaster start as the floor.
+select pg_postmaster_start_time()                       as counters_since,
+       now() - pg_postmaster_start_time()               as window_length,
+       (select stats_reset from pg_stat_database
+         where datname = current_database())            as stats_reset;
+
+-- 2. Where the time actually goes. Rank every proposal against this.
+select round((total_exec_time / 3600000)::numeric, 2)                          as hours,
+       round((100.0 * total_exec_time
+              / sum(total_exec_time) over ())::numeric, 2)                     as pct_of_db_time,
+       calls,
+       round(mean_exec_time::numeric, 1)                                       as mean_ms,
+       round((rows::numeric / nullif(calls, 0)), 2)                            as rows_per_call,
+       temp_blks_written,
+       left(regexp_replace(query, '\s+', ' ', 'g'), 160)                       as statement
+  from pg_stat_statements
+ where dbid = (select oid from pg_database where datname = current_database())
+ order by total_exec_time desc
+ limit 25;
+
+-- 3. Single-row-insert fingerprint: rows_per_call = 1.00 on a high-call INSERT.
+select calls, round(mean_exec_time::numeric, 1) as mean_ms,
+       round((total_exec_time / 3600000)::numeric, 2) as hours,
+       left(regexp_replace(query, '\s+', ' ', 'g'), 100) as statement
+  from pg_stat_statements
+ where query ~* '^\s*insert' and rows = calls and calls > 1000
+ order by total_exec_time desc
+ limit 15;
+
+-- 4. Per-table liveness. idx_scan > 0 means an application issued a filtered
+--    query; audit scripts only produce seq_scan. Compare seq_scan against the
+--    median across peers to find the audit/monitor floor.
+select relname,
+       n_live_tup, n_dead_tup,
+       n_tup_ins, n_tup_upd, n_tup_del,
+       seq_scan, coalesce(idx_scan, 0) as idx_scan,
+       last_autovacuum, last_autoanalyze
+  from pg_stat_user_tables
+ order by (coalesce(idx_scan, 0) + seq_scan) asc;
+
+-- 5. Exact emptiness. NEVER decide this from n_live_tup, which is a stale
+--    planner estimate. Generates the count statements; run the output.
+select format('select %L as tbl, count(*) from %I.%I;', relname, schemaname, relname)
+  from pg_stat_user_tables
+ where n_live_tup = 0
+ order by relname;
+
+-- 6. Index cost vs benefit. An index with idx_scan near zero is paid for on
+--    every insert and never read. Check size against shared_buffers.
+select t.relname                              as tbl,
+       i.relname                              as idx,
+       am.amname                              as method,
+       coalesce(s.idx_scan, 0)                as scans,
+       pg_size_pretty(pg_relation_size(i.oid)) as size,
+       pg_get_indexdef(i.oid)                 as definition
+  from pg_class i
+  join pg_index x  on x.indexrelid = i.oid
+  join pg_class t  on t.oid = x.indrelid
+  join pg_namespace n on n.oid = i.relnamespace and n.nspname = 'public'
+  join pg_am am on am.oid = i.relam
+  left join pg_stat_user_indexes s on s.indexrelid = i.oid
+ order by coalesce(s.idx_scan, 0) asc, pg_relation_size(i.oid) desc;
+
+select name, setting, unit from pg_settings
+ where name in ('shared_buffers', 'work_mem', 'effective_cache_size',
+                'max_connections', 'max_parallel_workers_per_gather');
+
+-- 7. Duplicate indexes on the same expression.
+select indrelid::regclass as tbl, count(*) as copies,
+       array_agg(indexrelid::regclass) as indexes
+  from pg_index
+ group by indrelid, indkey::text, indexprs::text, indpred::text
+having count(*) > 1;
+
+-- 8. Work spilling to disk. temp_bytes is a first-class latency signal.
+select temp_files, pg_size_pretty(temp_bytes) as temp_written,
+       blks_read, blks_hit,
+       round(100.0 * blks_hit / nullif(blks_hit + blks_read, 0), 2) as cache_hit_pct,
+       deadlocks
+  from pg_stat_database
+ where datname = current_database();
+
+select round((total_exec_time / 1000)::numeric, 0) as sec, calls,
+       round((temp_blks_written * 8192 / 1e9)::numeric, 2) as temp_gb,
+       left(regexp_replace(query, '\s+', ' ', 'g'), 140) as statement
+  from pg_stat_statements
+ where temp_blks_written > 0
+ order by temp_blks_written desc
+ limit 10;
+
+-- 9. TOAST ratio. A large gap between total size and heap+index size means the
+--    row is wide, and any predicate on the wide column de-TOASTs on every scan.
+select c.relname,
+       pg_size_pretty(pg_total_relation_size(c.oid))                     as total,
+       pg_size_pretty(pg_relation_size(c.oid))                           as heap,
+       pg_size_pretty(pg_indexes_size(c.oid))                            as indexes,
+       pg_size_pretty(pg_total_relation_size(c.oid)
+                      - pg_relation_size(c.oid)
+                      - pg_indexes_size(c.oid))                          as toast,
+       s.seq_scan
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace and n.nspname = 'public'
+  left join pg_stat_user_tables s on s.relid = c.oid
+ where c.relkind = 'r'
+ order by pg_total_relation_size(c.oid) desc
+ limit 15;
+
+-- 10. Column population contract check. Any column a reader consumes that comes
+--     back 100% empty on a populated table is a write-contract gap. Generates
+--     the per-column statements. Set the table filter first:
+--       set bl.tbl = 'rss_sources';
+select format(
+         'select %L as col, count(*) as rows, count(%I) as populated from %I.%I;',
+         table_name || '.' || column_name, column_name, table_schema, table_name)
+  from information_schema.columns
+ where table_schema = 'public' and is_nullable = 'YES'
+   and table_name = coalesce(current_setting('bl.tbl', true), table_name)
+ order by table_name, ordinal_position;