@bompus/house-rules 0.11.0 → 0.13.0

package/skills/hr-sqlite/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: hr-sqlite
+description: Checklist of settings, failure patterns and measured effects for SQLite code. Use when adding or changing code that opens, queries or copies a SQLite database, or when diagnosing "database is locked", SQLITE_BUSY, slow queries or WAL growth.
+---
+
+# SQLite
+
+Run `python3 <this skill's directory>/scripts/inspect-sqlite.py <database>` first
+when you have a database file. It opens the file read-only and reports what the
+file records, the WAL size and the mount options. It cannot show connection
+settings, because SQLite does not store them in the file; read the code that
+opens the connection for those. With `--source <directory>` it also scans source
+text for each `journal_mode` mention that has no earlier `busy_timeout` in the
+same file. That scan does not establish run order or which connection a mention
+belongs to.
+
+Each item carries an evidence tier:
+
+- **M**: measured on a real workload. [The evidence](references/evidence.md)
+  gives the counts, the workload and its limits.
+- **D**: stated by the SQLite documentation, not measured here.
+- **U**: suspected or reported by one source. Do not rely on it.
+
+The numbers come from specific workloads. Before changing a setting for speed,
+measure your own with `hr-benchmarking`. Before adopting or rejecting a
+different engine, driver or pool, read
+[the tool decisions](references/tool-decisions.md).
+
+## Open a connection
+
+1. **Set `PRAGMA busy_timeout` first**, before `journal_mode` and every other
+   statement, on every connection, including short-lived probe, lock and status
+   databases. The default is 0, so any competing lock fails at once. Set it
+   long enough to cover the longest holder you expect. A deliberate fail-fast
+   probe sets 0 and says why in a comment. A connection has one busy handler,
+   and `PRAGMA busy_timeout` replaces any handler the driver or your code
+   installed (D), so where you register a custom handler, configure that and do
+   not also set the pragma. (M: a mail server's first start and a wake-lock
+   probe failed this way. A test with a holder of 300 ms failed the old order in
+   5 ms and passed once the timeout came first.)
+2. **Convert to WAL once.** Switching a brand-new file to `journal_mode=WAL`
+   takes an exclusive lock, and several processes doing it together failed.
+   Create and convert the file in one place, or retry the conversion on
+   `database is locked` and `disk I/O error`. Do not ignore a failed
+   conversion: that connection failed later statements. A busy timeout set
+   first does cover `journal_mode`. (M: 22 of 300 failures without the retry,
+   0 of 480 with it.)
+3. **Keep a WAL database on a local filesystem.** WAL needs shared memory, so
+   network filesystems do not work (D). A database on a WSL `/mnt/<drive>` mount
+   failed with `disk I/O error`; the cause was not isolated (one host).
+4. **Choose `synchronous` per store.** In WAL mode NORMAL skips the sync at
+   commit. An application crash loses nothing, but a power loss or OS crash can
+   lose the most recent commits (D). Keep FULL where lost commits cannot be
+   replayed or their side effects are not idempotent. Never choose it from a
+   microbenchmark. (M: 3.09 to 0.52 ms per message send; 4.18 to 2.93 ms
+   end-to-end median.)
+5. **Do not expect `temp_store=MEMORY` or `mmap_size` to help a small
+   database.** No difference beyond noise on a 560 KB database (M). Both are
+   untested on large databases here; measure before adopting.
+6. **Use one SQLite build per process for a WAL file.** A runtime's built-in
+   SQLite and a native module's bundled SQLite shared one process, and the WAL
+   state was corrupted in about a third of runs. The lock-registry mechanism is
+   asserted (M). Open the file with one library. Give the other a checkpointed
+   copy, and close its connections deterministically: one run in five still
+   hit SIGBUS from a connection closed only at garbage collection (M).
+7. **Set per-connection pragmas on every connection.** `busy_timeout`,
+   `synchronous`, `foreign_keys` and `cache_size` do not persist in the file;
+   `journal_mode=WAL` does (D).
+
+## Write
+
+8. **Start write transactions with `BEGIN IMMEDIATE`** and retry the whole
+   transaction on `SQLITE_BUSY`. A deferred transaction that reads and then
+   writes cannot wait: SQLite returns busy without calling the handler when
+   waiting could deadlock (D). `BEGIN IMMEDIATE` takes the write lock at once:
+   it waits behind an existing writer and blocks every other writer until it
+   ends, even if its body only reads. Using it for reads therefore serializes
+   them with writers (read from one server's source, not measured). Keep write
+   transactions short and free of I/O.
+9. **Expect a checkpoint to wait.** A long-running reader stops a checkpoint
+   from finishing, so the WAL grows (D). A `TRUNCATE` checkpoint also waits for
+   a backfill already running and for an idle reader's WAL mark. With a 2 s
+   timeout it lost to a backfill of a 420 MB WAL in about one run in three.
+   Draining the backfill first and accepting a complete `PASSIVE` backfill fixed
+   it, because a file copy only needs every frame in the database file (M).
+
+## Read
+
+10. **Keep planner statistics.** Run `PRAGMA optimize` just before closing a
+    short-lived connection. For a long-lived one, run `PRAGMA optimize=0x10002`
+    when it opens and `PRAGMA optimize` periodically. Run it after
+    `CREATE INDEX` (D). The `0x10000` bit and the automatic analysis limit
+    arrived in SQLite 3.46.0. On older releases set `PRAGMA analysis_limit`
+    yourself and run `ANALYZE` (D). Missing statistics made one query scan: 10.3
+    to 12.5 ms became 0.0075 ms. The first run on a 15 GB file took 72 to 80 s
+    and blocked writers; repeats took 0.5 to 1.2 s. Run it first at a time you
+    choose (M).
+11. **Check the plan before rewriting a query.** `EXPLAIN QUERY PLAN`, then
+    statistics. A slow query that looked like bad SQL was missing statistics
+    (M).
+12. **Index what an FTS5 index is deleted and read by.** Deleting by an
+    `UNINDEXED` column scans the whole index per row. Keep an ordinary indexed
+    table from source to rowid, delete through it, and look up hits and their
+    context by indexed rowid. Read rank first: select `rowid` ordered by `rank`
+    with a limit, then join content. (M: refresh reads 79.9 to 18.2 MiB; hit and
+    context lookups 5,742 to 134 ms after the later read-side change; rank-first
+    84 to 37 ms.)
+13. **Cover `LIKE` lookups with an index** on the columns the query reads. A
+    covering index took 7 to 10 ms to 1 to 2.4 ms (M). The built-in `lower()`
+    handles ASCII only (D).
+14. **Poll for change with `PRAGMA data_version`.** It differs between two reads
+    on one connection when another connection committed (D). Rescan only then.
+15. **Look inside SQLite before swapping a driver.** 80 to 92% of an explore
+    call was inside SQLite. Three drivers took 1,330 to 1,810 ms on an
+    indexing workload, with no clear difference (M). A driver can still differ in one call; see
+    [the tool decisions](references/tool-decisions.md).
+
+## Copy, back up and host settings
+
+16. **Copy a live database with `VACUUM INTO` or the driver's backup API**,
+    then run `PRAGMA integrity_check` on the copy. Copying the files while a
+    transaction is active can capture old and new content together (D).
+    `sqlite3 .backup` restarts whenever another connection writes, so against a
+    busy writer it can run without end (D); one run read 2.8 TB. (M: 54 s for 14
+    GB with `VACUUM INTO`; 36 s for 15.2 GB with the driver's `backup()`.)
+17. **Treat a file-level snapshot of the database and its `-wal` as a drill, not
+    a guarantee.** One restore of three live databases with their WAL files
+    passed `integrity_check` (M, one drill). Restore and check before relying on
+    the method.
+18. **Check mount options.** Online `discard` on ext4 stalled `fsync`: the main
+    thread's disk wait fell from 26.8% and 16.8% to under 1% after remounting
+    with `nodiscard`, and a weekly `fstrim` replaced it (M). The inspection
+    script prints them.
+
+## Measure
+
+19. **Report cold and warm separately.** The same `PRAGMA optimize` took 72 s
+    cold and 0.5 s warm (M).
+20. **Time the change in the real loop.** Turning foreign keys off ran 7.6
+    times faster alone and made no difference in the loop (32.9 to 32.8 s)
+    (M).
+21. **Match durability settings before comparing stores.** A ratio between two
+    stores whose `synchronous` settings differ, or are unrecorded, compares the
+    settings. One comparison reported 84 to 563 times against stores whose
+    setting was not recorded (M).
+22. **Record the SQLite version and compile options**
+    (`PRAGMA compile_options`). Two builds of the same version can differ: the
+    documentation recommends `SQLITE_DEFAULT_MEMSTATUS=0`, and one runtime's
+    build lacks it (D; see [the tool decisions](references/tool-decisions.md)).
+
+## Keep reads off the event loop
+
+23. **With a synchronous driver, run reads on a worker connection.** Node's
+    built-in `node:sqlite` runs each statement on the calling thread, so a slow
+    read holds the event loop for its whole duration. Where the application
+    shares one queued connection for reads and writes, a read also waits behind
+    any open write transaction. Route read-only queries to a separate read-only
+    connection in a worker thread. That connection sees only committed data, as a
+    snapshot, so move only reads that tolerate that; a read that must see the
+    caller's uncommitted changes stays on the writer. A text search over 86,163 messages held the
+    loop for a median 165 ms (range 97 to 308) on the writer connection and 2.5 ms
+    (2 to 4) on the worker, with no clear change in wall time (165 and 157 ms; 12
+    runs per arm, 2 ms probe) (M). Prove the routing with a test that keeps the
+    main thread busy on a latch and checks the worker read still completes; an
+    open writer transaction alone proves nothing, because in WAL mode a second
+    main-thread connection can read past it. Record
+    the longest event-loop stall, not only the query time; `hr-benchmarking`'s
+    JavaScript reference covers the probe.
+
+## What to leave out of a record
+
+Do not repeat a claim from [the withdrawn list](references/evidence.md#claims-that-did-not-hold)
+without re-measuring it. Mark anything unmeasured as such, and give the count
+and the workload with any figure.

package/skills/hr-sqlite/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "HR: SQLite"

package/skills/hr-sqlite/references/evidence.md

@@ -0,0 +1,94 @@
+# Evidence behind the checklist
+
+Measured by one owner on Linux, WSL and Windows hosts between 2026-09-01 and 2026-10-14.
+Every figure names its workload and its count where the source recorded them.
+[Tested versions](#tested-versions) lists the SQLite, driver, runtime and operating
+system versions recovered from the records of each measurement. Where a version
+could not be recovered, the table says "Not recorded".
+**M** means measured here, **D** means read from the SQLite documentation,
+**U** means unconfirmed. Treat a figure as one workload's result, not a
+benchmark.
+
+## Measured findings
+
+| Setting or pattern                               | Result                                                                                                                                                                                                                                                       | Workload and limits                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Missing planner statistics                       | One query 10.3 to 12.5 ms became 0.0075 ms after `PRAGMA optimize` (about 1,400 to 1,700 times faster, from these rounded times)                                                                                                                             | Two 15 GB copies of an application database, one cold run each. First copy: median of 5 processes by 20 passes, 15 of 183 query plans changed, first optimize 72.3 s, repeats 0.5 to 1.2 s. Second copy: 80.5 s with the cache dropped. During a cold run 1,598 of 1,602 writer probes with `busy_timeout` 0 failed and all reads succeeded                                                                                                                                                                  |
+| `synchronous` FULL to NORMAL (microbenchmark)    | 1,170 to 13.4 µs per commit                                                                                                                                                                                                                                  | 1,000 commits per run of one 3,000-character row plus one index, 5 runs per arm alternating, each in a fresh process and database on the live database's disk. Taken while online `discard` was mounted, so the FULL figure includes those stalls and was not re-measured after remounting                                                                                                                                                                                                                   |
+| `synchronous` FULL to NORMAL (application write) | 1,809 to 433 µs per event write, p99 29% worse; 318 to 18 added `fsync` calls per 300 writes; end-to-end median 4.18 to 2.93 ms (30% lower), p95 unchanged                                                                                                   | 4 to 8 runs, synthetic load; the `fsync` counts are one `strace` count each. A review panel found that effects outside the file do not roll back, so after an operating-system crash a retry could run an effect again, and nothing shown made them idempotent. The author had not checked                                                                                                                                                                                                                   |
+| `synchronous` NORMAL on a small local mail store | Message send 3.09 to 0.52 ms; p99 about 5 ms unchanged                                                                                                                                                                                                       | 3 interleaved rounds. The owner chose NORMAL over a keep-FULL recommendation                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `temp_store=MEMORY`, `mmap_size=256MB`           | No difference beyond noise                                                                                                                                                                                                                                   | 3 rounds by 4 arms on a 560 KB database. Not adopted. Untested on large databases                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Online `discard` on ext4                         | Main-thread disk wait 26.8% and 16.8% became 0.6% and 0.8%; waits of 1 s or more went from 17 and 4 to 0 and 0                                                                                                                                               | Two 240 s samples per arm and a 158 minute follow-up with 0 stalls. 2.4 TiB was discarded in about 2,290 s. Lowering the kernel's dirty-page limits did not help and was reverted. The remedy chosen was `nodiscard` plus a weekly `fstrim`                                                                                                                                                                                                                                                                  |
+| Two SQLite builds in one process                 | Committed rows reappeared and the WAL index's `mxFrame` regressed mid-run, then SIGBUS                                                                                                                                                                       | A runtime's built-in SQLite and a native module's bundled SQLite (a separate compilation) on one live WAL, in one process. About a third of runs on one corpus failed; sequential runs were clean 3 of 3 and pool-only runs were clean. Failures reproduced with checkpoints suppressed and with worker recycling off. Giving workers a checkpointed copy still produced one SIGBUS in five runs until connections were closed deterministically. The lock-registry mechanism is asserted from this evidence |
+| `TRUNCATE` checkpoint racing a WAL backfill      | About one run in three was much slower than the rest; after the fix 8 of 8 runs were normal. Timings omitted: tested versions not recorded                                                                                                                   | A `TRUNCATE` checkpoint with a 2 s busy timeout lost to the WAL valve's backfill of a 420 MB WAL and the resolver pool was dropped. The fix drains the valve first and accepts a complete `PASSIVE` backfill when `TRUNCATE` is still busy (an idle reader's WAL mark also blocks it), since a copy only needs every frame in the database file                                                                                                                                                              |
+| Zero or late `busy_timeout`                      | Two documented failures: a mail server's first start (`journal_mode` ran with no wait) and a wake-lock probe (`busy_timeout` 0)                                                                                                                              | Mail server start: a test whose child held an exclusive lock for 300 ms failed in 5 ms with `journal_mode` first and passed with `busy_timeout` first. Wake-lock probe: both starters failed with `SQLITE_BUSY` at 0; changing it to 250 ms passed five consecutive two-order runs. Other incidents were reported in transcripts and are not in the records. Two call sites in that server still use 0 with no comment; one fails with an ownership message                                                  |
+| Fresh-file WAL conversion                        | 105 of 120 concurrent runs failed before a pull request's concurrency fixes and 11 of 120 at its head; every remaining failure was `PRAGMA journal_mode=WAL`. Retrying on `database is locked` and `disk I/O error`: 0 of 480 against 22 of 300 for the head | Windows host, several processes opening a new file together; three arms round-robined over 300 runs, then two samples. Ignoring the failure did not work: the failed connection broke later statements                                                                                                                                                                                                                                                                                                       |
+| FTS5 delete by an unindexed column               | Refresh logical reads 79.9 to 18.2 MiB                                                                                                                                                                                                                       | Session-search index; the change deleted through an indexed source-to-rowid map instead of an unindexed column. The wall-clock gap on refresh was inconclusive. A service reached its 1,500 MiB cgroup cap at 1,492 MiB of file cache and 15 MiB resident; the cause of the kill is unresolved                                                                                                                                                                                                               |
+| FTS5 hit and context lookups                     | 18 native hit and context calls 5,741.6 to 133.6 ms (43 times); logical reads 21,902.88 to 118.52 MiB                                                                                                                                                        | The same index after a later change: indexed source rowids and bounded rowid lookups for reads, with a context join order that no longer scans FTS metadata. Confirmation wall-time variation 0.77% and 1.92%; 144 outputs hash-matched                                                                                                                                                                                                                                                                      |
+| Covering index and rank-first FTS                | `LIKE` 7 to 10 ms became 1 to 2.4 ms; rank-first FTS 84 to 37 ms                                                                                                                                                                                             | Code-search explore calls, output byte-identical. 80 to 92% of call time was inside SQLite. A separate change that passed an edge kind to the query and cached a name list cut rows read in 12 explores from 1.38 million to 313 thousand                                                                                                                                                                                                                                                                    |
+| Driver swap                                      | No clear difference between three drivers: 1,330 to 1,810 ms across them                                                                                                                                                                                     | A 500,000-edge indexing workload: better-sqlite3 about 1,400 ms, bun:sqlite about 1,500 ms, node:sqlite 1,330 to 1,810 ms. An isolated in-memory insert arm: node:sqlite and bun:sqlite about 0.5 µs per row, better-sqlite3 about 1.8 times slower. On the explore read path better-sqlite3 was 0.8% faster and both Bun drivers 8% to 11% slower than Node                                                                                                                                                 |
+| Micro-win that did not transfer                  | Foreign keys off ran 7.6 times faster alone and 32.9 to 32.8 s in the real loop                                                                                                                                                                              | One indexing workload                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Live-database copy                               | `sqlite3 .backup` restarted until stopped after reading 2.8 TB; `VACUUM INTO` took 54 s for 14 GB; driver `backup()` took 36.4 s for 15.2 GB                                                                                                                 | One sample each. Copying the files while a transaction is active can capture old and new content together (SQLite documentation). A restic restore of three live databases (14.6 GiB) with their WAL files passed `quick_check` and `integrity_check` in one drill                                                                                                                                                                                                                                           |
+| Polling a live database                          | Per-query page reads fell when the filter was made once per row. Figures omitted: tested versions not recorded                                                                                                                                               | The cut in rescans by checking `PRAGMA data_version` first is modeled, not measured on the deployed service                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Big database boot                                | Booting with the database took several times longer than with an empty one. Figures omitted: tested versions not recorded                                                                                                                                    | 14 GB database, 6 runs per arm. The default `cache_size`, `mmap_size` 0 and no `synchronous` setting were read from the code; the boot cost's cause is unproven                                                                                                                                                                                                                                                                                                                                              |
+| Reads on a worker connection                     | Longest event-loop stall median 165 ms (97 to 308) became 2.5 ms (2 to 4); wall time 165 and 157 ms, no clear change                                                                                                                                         | Text search over 86,163 messages in a WAL file, 12 runs per arm at `nice -n 10`, 2 ms timer probe. One workload; no test in this repository covers it; item 23 of `SKILL.md` gives the proof to run                                                                                                                                                                                                                                                                                                          |
+| WAL on `/mnt/<drive>` under WSL                  | A database on `/mnt/<drive>` failed with `disk I/O error`                                                                                                                                                                                                    | WSL. The cause was not isolated; a `-shm` locking cause was suspected and not confirmed. A separate failure reading Windows-side databases from WSL Python was not diagnosed, while a native read-only open succeeded                                                                                                                                                                                                                                                                                        |
+
+## Tested versions
+
+Recovered from the owner's records of each measurement session. A version counts
+only when the record of that session states it. "Not recorded" means the records
+do not state it, so treat that row as a historical result whose versions are
+unknown.
+
+| Setting or pattern                               | Versions and environment                                                                                                                                                           | Notes                                                                                                                                        |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Missing planner statistics                       | Node 26.11.1 with its bundled SQLite 3.53.4 (`node:sqlite`); Linux x86-64 under WSL2; 2026-10-11                                                                                   | Filesystem of the copies not recorded                                                                                                        |
+| `synchronous` FULL to NORMAL (microbenchmark)    | Node's bundled SQLite 3.53.4, WAL mode; local ext4 disk under WSL2; 2026-10-10                                                                                                     | Node patch version not recorded                                                                                                              |
+| `synchronous` FULL to NORMAL (application write) | ext4 disk under WSL2; about 2026-10-10                                                                                                                                             | SQLite and runtime versions not recorded                                                                                                     |
+| `synchronous` NORMAL on a small local mail store | Bun 1.4.2 with `bun:sqlite`; 2026-09-28                                                                                                                                            | Bun version is from the plan that records the run, not printed with the measurement. SQLite version not recorded                             |
+| `temp_store=MEMORY`, `mmap_size=256MB`           | Same as the row above                                                                                                                                                              | Same limits                                                                                                                                  |
+| Online `discard` on ext4                         | ext4 root filesystem under WSL2; 2026-10-11 and 2026-10-12                                                                                                                         | The measured wait is disk time, not SQLite time, so no SQLite version applies                                                                |
+| Two SQLite builds in one process                 | `node:sqlite` with SQLite 3.53.4; a Rust binding (rusqlite 0.40.2) bundling SQLite 3.53.x; Bun 1.4.2 and Node 26.8.2 were both used in the investigation; 2026-09-15 to 2026-09-16 | Which runtime ran the failing corpus runs, and the bundled SQLite patch digits, are not recorded                                             |
+| `TRUNCATE` checkpoint racing a WAL backfill      | Not recorded                                                                                                                                                                       |                                                                                                                                              |
+| Zero or late `busy_timeout`                      | Not recorded                                                                                                                                                                       |                                                                                                                                              |
+| Fresh-file WAL conversion                        | Windows 11; Bun 1.4.2 running a `node:sqlite` shim; 2026-09-06                                                                                                                     | SQLite version not recorded                                                                                                                  |
+| FTS5 delete by an unindexed column               | Not recorded                                                                                                                                                                       | A later assessment of the same work reports SQLite 3.46.1; the measurement receipt does not state it                                         |
+| FTS5 hit and context lookups                     | Not recorded                                                                                                                                                                       | The measurement receipt does not state the SQLite version; the index is the one in the row above                                             |
+| Covering index and rank-first FTS                | Node 24.21.0 with SQLite 3.53.4 and Bun 1.4.2 with SQLite 3.53.2; 2026-09-27 to 2026-10-03                                                                                         | Versions are for the benchmark campaign; the figures were not matched to one run                                                             |
+| Driver swap                                      | Indexing arms: Bun 1.4.2, Node 26.8.2, SQLite 3.53.4 for `node:sqlite`; 2026-09-16. Explore arms: Node 24.21.0, SQLite 3.53.2 for `bun:sqlite` and 3.53.4 for the others           | `better-sqlite3` package version not recorded                                                                                                |
+| Micro-win that did not transfer                  | Same session as the indexing arms of the row above; 2026-09-16                                                                                                                     | Runtime of the loop run not printed separately                                                                                               |
+| Live-database copy                               | `backup()`: Node 26.11.1, SQLite 3.53.4; 2026-10-11                                                                                                                                | Versions of `VACUUM INTO` and the `sqlite3` shell not recorded                                                                               |
+| Polling a live database                          | Not recorded                                                                                                                                                                       |                                                                                                                                              |
+| Big database boot                                | Not recorded                                                                                                                                                                       |                                                                                                                                              |
+| Reads on a worker connection                     | Not recorded                                                                                                                                                                       | Other runs of the same campaign used Node 26.11.1 on Linux under WSL2; the record does not tie that to this run. SQLite version not recorded |
+| WAL on `/mnt/<drive>` under WSL                  | Not recorded                                                                                                                                                                       |                                                                                                                                              |
+
+## Claims that did not hold
+
+These appeared in transcripts or records and were withdrawn, disproved or never
+confirmed. Do not repeat them without re-measuring.
+
+- **"`busy_timeout` does not cover `journal_mode`."** A 400 ms hold was waited
+  out in 429 ms. The failures came from a zero timeout, or from several
+  processes converting a new file at once.
+- **"A database-is-locked failure was fixed with a busy timeout and
+  `BEGIN IMMEDIATE`."** One indexer's case was a checkpoint racing a
+  background backfill.
+- **"The server sets `wal_autocheckpoint=0` and checkpoints by hand."** No
+  server code did; the claim was withdrawn.
+- **"A runtime's missing `SQLITE_DEFAULT_MEMSTATUS=0` explains its slower
+  concurrent reads."** The compile option is absent from that build (checked
+  with `PRAGMA compile_options` against another runtime's build of the same
+  SQLite version). A plain C program shows the flag matters for threaded reads.
+  No build of that runtime with the flag was run. Suspected only (U).
+- **"The slow query needs rewriting."** The cause was missing statistics.
+- **Ratios between stores of 84 to 563 times.** The comparison set one store at
+  `synchronous=NORMAL` against stores whose setting was not recorded.
+
+## Never measured here
+
+- `mmap_size`, `cache_size` or `temp_store` on a database of several gigabytes.
+- How long the WAL window of lost commits is under `synchronous=NORMAL`.
+- How long `ANALYZE` holds locks inside a live server.
+- A benchmarked connection pool, Turso or libSQL, or `sqlite-multiwriter`.

package/skills/hr-sqlite/references/tool-decisions.md

@@ -0,0 +1,39 @@
+# Tool decisions
+
+What was evaluated, what was decided and what would reopen it. Most of these are
+document assessments, not benchmarks; the basis is stated on each row. Re-check
+a decision when its trigger is met or when the project's own documentation has
+changed since the date.
+
+| Candidate                                                                                 | Decision (date)                       | Basis                                                                                                                                                                                                                                                                                                                                        | Reopen when                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Turso or libSQL engine for local stores                                                   | Keep SQLite (2026-09-30)              | Documentation and source read; no benchmark run. The engine's FTS was incompatible with the stores' FTS5 use, some pragmas were partial, and one database file could not be shared between the two engines across processes                                                                                                                  | Shared state must live across devices or machines                                                                                                               |
+| [sqlite-multiwriter](https://github.com/sqliteai/sqlite-multiwriter) (per-writer WAL VFS) | Watch (2026-10-09)                    | README read at release 0.5.2, one day after its creation; its figures (49,277 against 8,630 transactions per second for 16 threads) came from one Apple machine with `synchronous=FULL` and were not reproduced. WAL only; extra `-mw*` files are part of the database; callers must retry on `SQLITE_BUSY_SNAPSHOT`; local filesystems only | A measured workload shows writer throughput, `SQLITE_BUSY` retries or long commit tails on one database that `busy_timeout` and shorter transactions do not fix |
+| A Node connection-pool package                                                            | No adoption (2026-10-05)              | Code read: the driver in use is synchronous and there are no worker threads; no missing capability was shown. No benchmark                                                                                                                                                                                                                   | A new Node service needs leased connections, or a measured problem a pool would address                                                                         |
+| Swapping the SQLite driver for speed                                                      | Not worth it (2026-09-16)             | No clear difference between three drivers on an indexing workload, 1,330 to 1,810 ms (see the evidence); most call time was inside SQLite itself                                                                                                                                                                                             | No trigger was recorded. Suggested: a profile that shows time in driver binding or row materialization rather than in SQLite                                    |
+| Tantivy or another search engine in place of FTS5                                         | Keep FTS5 (2026-09-28 and 2026-10-04) | Source and documentation read; no engine performance measured. FTS5 runs in the same process and transaction as the writes, with no second searchable copy to keep in sync                                                                                                                                                                   | Profiling shows an FTS5 bottleneck on your corpus. Tantivy is then the first embedded alternative worth a controlled comparison                                 |
+
+## Runtime notes
+
+- **Bun's `node:sqlite` `get()`** was about 1.5 times slower than Node's when
+  returning table columns, because it builds a new row structure per call. A fix
+  pull request was open when this was written
+  ([oven-sh/bun#44084](https://github.com/oven-sh/bun/issues/44084)).
+- **`SQLITE_DEFAULT_MEMSTATUS`.** The SQLite documentation recommends
+  `SQLITE_DEFAULT_MEMSTATUS=0`. `PRAGMA compile_options` shows it on Node's
+  SQLite but not on Bun's (checked 2026-10-12, both SQLite 3.53.4). A plain C
+  program with 8 threads, each on its own connection, ran each thread about 25%
+  slower with memory statistics on. The 8-thread to 1-thread time ratio was 0.89
+  to 1.03 with them on and 0.71 to 0.82 with them off, over 3 alternating
+  rounds. One thread showed no difference. No Bun build with the flag was run,
+  so its share of Bun's slower multi-worker reads is suspected, not confirmed
+  ([oven-sh/bun#44187](https://github.com/oven-sh/bun/issues/44187)).
+- **Different runtimes in one process.** Two SQLite builds in one process on one
+  WAL file corrupted state; give the second library a checkpointed copy.
+
+## Held, unselected
+
+- A pre-backup `sqlite3 .backup` step ahead of file-level snapshots. One restore
+  of live database and WAL files opened cleanly, so it stayed a possible
+  hardening item. Against an active writer `.backup` restarts (see the
+  evidence), so it needs a quiet writer or a bounded retry.

package/skills/hr-sqlite/scripts/inspect-sqlite.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Read-only inspection of a SQLite database file and, optionally, the source
+that opens it.
+
+    inspect-sqlite.py DATABASE [--source PATH ...] [--quick-check] [--json]
+
+Reports what the file itself records (journal mode, page and freelist counts,
+planner statistics, FTS tables, WAL size) plus the filesystem it sits on. It
+never writes to the database. SQLite may create an empty `-shm` file beside a
+WAL database that no process has open.
+
+Connection settings such as busy_timeout, synchronous, foreign_keys and
+cache_size are not stored in the file, so no database inspection can show what
+an application sets. `--source` is a text scan: for each mention of
+journal_mode it reports whether a busy_timeout mention comes earlier in the
+same file. It does not establish run order or which connection each belongs
+to. Treat those lines as places to read, not verdicts. A source path that cannot
+be read is listed as not scanned and the exit status is 2.
+"""
+import argparse
+import json
+import os
+import pathlib
+import re
+import sqlite3
+import sys
+
+NETWORK_FILESYSTEMS = {"9p", "drvfs", "cifs", "smb3", "smbfs", "nfs", "nfs4", "fuse.sshfs", "virtiofs"}
+SHADOW_SUFFIXES = ("_data", "_idx", "_content", "_docsize", "_config", "_segments", "_segdir", "_stat", "_node", "_parent", "_rowid")
+SOURCE_SUFFIXES = {".py", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".rs", ".go", ".rb", ".java", ".kt", ".cs", ".c", ".cc", ".cpp", ".swift", ".php", ".sql"}
+
+
+def mount_for(path):
+    """Return (mount point, filesystem type, options) for the longest mount prefix."""
+    try:
+        with open("/proc/self/mountinfo", encoding="utf-8", errors="replace") as handle:
+            lines = handle.read().splitlines()
+    except OSError:
+        return None
+    real = os.path.realpath(path)
+    best = None
+    for line in lines:
+        left, _, right = line.partition(" - ")
+        fields = left.split()
+        if len(fields) < 6 or len(right.split()) < 3:
+            continue
+        point = fields[4].replace("\\040", " ")
+        if real == point or real.startswith(point.rstrip("/") + "/") or point == "/":
+            if best is None or len(point) > len(best[0]):
+                kind, _, super_options = right.split()[:3]
+                best = (point, kind, ",".join([fields[5], super_options]))
+    return best
+
+
+def scan_source(paths):
+    """For each file that mentions journal_mode, note where busy_timeout appears.
+
+    Returns (findings, errors). A path that cannot be read is an error, so a
+    failed scan never looks like a scan that found nothing.
+    """
+    findings = []
+    errors = []
+    files = []
+
+    def walk_error(error):
+        errors.append({"file": str(error.filename), "error": error.strerror or str(error)})
+
+    for entry in paths:
+        if os.path.isdir(entry):
+            for root, dirs, names in os.walk(entry, onerror=walk_error):
+                dirs[:] = [d for d in dirs if d not in {".git", "node_modules", ".venv", "target", "dist"}]
+                files.extend(
+                    os.path.join(root, n) for n in names if os.path.splitext(n)[1] in SOURCE_SUFFIXES
+                )
+        else:
+            files.append(entry)
+    for file in sorted(files):
+        try:
+            with open(file, encoding="utf-8", errors="replace") as handle:
+                lines = handle.read().splitlines()
+        except OSError as error:
+            errors.append({"file": file, "error": error.strerror or str(error)})
+            continue
+        journals = [i + 1 for i, l in enumerate(lines) if re.search(r"journal_mode", l, re.I)]
+        timeouts = [i + 1 for i, l in enumerate(lines) if re.search(r"busy_timeout|busyTimeout|set_busy_timeout", l, re.I)]
+        for journal in journals:
+            earlier = [t for t in timeouts if t < journal]
+            if earlier:
+                status = "busy_timeout at line %d comes before journal_mode at line %d" % (earlier[-1], journal)
+            elif timeouts:
+                status = "journal_mode at line %d comes before busy_timeout at line %d" % (journal, timeouts[0])
+            else:
+                status = "journal_mode at line %d; no busy_timeout in this file" % journal
+            findings.append({"file": file, "line": journal, "status": status, "ok": bool(earlier)})
+    return findings, errors
+
+
+def inspect(path, quick_check=False):
+    result = {"path": os.path.abspath(path)}
+    size = os.path.getsize(path)
+    result["fileBytes"] = size
+    uri = pathlib.Path(result["path"]).as_uri() + "?mode=ro"
+    connection = sqlite3.connect(uri, uri=True, timeout=2)
+    try:
+        connection.execute("PRAGMA busy_timeout = 2000")
+
+        def pragma(name):
+            row = connection.execute("PRAGMA " + name).fetchone()
+            return row[0] if row else None
+
+        result["library"] = {"version": sqlite3.sqlite_version}
+        options = [r[0] for r in connection.execute("PRAGMA compile_options")]
+        result["library"]["memstatusDisabled"] = "DEFAULT_MEMSTATUS=0" in options
+        result["library"]["threadsafe"] = next((o for o in options if o.startswith("THREADSAFE")), None)
+        result["journalMode"] = pragma("journal_mode")
+        result["pageSize"] = pragma("page_size")
+        result["pageCount"] = pragma("page_count")
+        result["freelistCount"] = pragma("freelist_count")
+        result["autoVacuum"] = pragma("auto_vacuum")
+        result["userVersion"] = pragma("user_version")
+        result["encoding"] = pragma("encoding")
+        names = connection.execute(
+            "SELECT name, sql FROM sqlite_master WHERE type = 'table' ORDER BY name"
+        ).fetchall()
+        tables = [n for n, _ in names if not n.startswith("sqlite_")]
+        virtual = {n: s for n, s in names if s and s.upper().startswith("CREATE VIRTUAL TABLE")}
+        shadow = {n for table in virtual for n in tables if n in {table + s for s in SHADOW_SUFFIXES}}
+        plain = [n for n in tables if n not in virtual and n not in shadow]
+        result["tables"] = len(plain)
+        result["indexes"] = connection.execute(
+            "SELECT count(*) FROM sqlite_master WHERE type = 'index' AND name NOT LIKE 'sqlite_%'"
+        ).fetchone()[0]
+        result["virtualTables"] = {
+            n: (re.search(r"USING\s+(\w+)", s, re.I) or [None, "unknown"])[1].lower()
+            for n, s in virtual.items()
+        }
+        has_stat = any(n == "sqlite_stat1" for n, _ in names)
+        analyzed = set()
+        if has_stat:
+            analyzed = {r[0] for r in connection.execute("SELECT DISTINCT tbl FROM sqlite_stat1")}
+        result["statistics"] = {
+            "sqliteStat1": has_stat,
+            "rows": connection.execute("SELECT count(*) FROM sqlite_stat1").fetchone()[0] if has_stat else 0,
+            "tablesWithoutStatistics": [n for n in plain if n not in analyzed],
+        }
+        if quick_check:
+            result["quickCheck"] = [r[0] for r in connection.execute("PRAGMA quick_check(10)")]
+    finally:
+        connection.close()
+    for suffix, key in (("-wal", "walBytes"), ("-shm", "shmBytes")):
+        side = result["path"] + suffix
+        result[key] = os.path.getsize(side) if os.path.exists(side) else None
+    mount = mount_for(result["path"])
+    if mount:
+        point, kind, options = mount
+        result["filesystem"] = {"mount": point, "type": kind, "options": options}
+    else:
+        result["filesystem"] = None
+    return result
+
+
+def notes(result):
+    out = []
+    if result["journalMode"] != "wal":
+        out.append("journal_mode is %s, not wal; in a rollback journal a writer's commit waits for readers and blocks new ones while it commits" % result["journalMode"])
+    stats = result["statistics"]
+    if not stats["sqliteStat1"]:
+        out.append("no sqlite_stat1: the planner has no statistics; run PRAGMA optimize at a time you choose (the first run on a large file can take over a minute and hold the write lock)")
+    elif stats["tablesWithoutStatistics"]:
+        out.append("tables with no statistics rows: " + ", ".join(stats["tablesWithoutStatistics"][:8]))
+    pages = result["pageCount"] or 0
+    if pages and result["freelistCount"] and result["freelistCount"] / pages > 0.2:
+        out.append("more than 20%% of pages are free (%d of %d); the file is larger than its content" % (result["freelistCount"], pages))
+    if result["walBytes"] and result["walBytes"] > result["fileBytes"]:
+        out.append("the WAL file is larger than the database; look for a long-running reader or a blocked checkpoint")
+    fs = result["filesystem"]
+    if fs:
+        if fs["type"] in NETWORK_FILESYSTEMS:
+            out.append("filesystem %s: WAL needs shared memory on one host and does not work reliably here" % fs["type"])
+        if re.search(r"(^|,)discard(,|$)", fs["options"]):
+            out.append("mounted with online discard; this stalled fsync on one host (see the evidence), so check fsync latency")
+    if "quickCheck" in result and result["quickCheck"] != ["ok"]:
+        out.append("quick_check reported: " + "; ".join(result["quickCheck"][:3]))
+    return out
+
+
+def render(result, source, source_errors=()):
+    lines = ["database: %s" % result["path"]]
+    lines.append("size: %d bytes; %s pages of %s bytes; %s free" % (
+        result["fileBytes"], result["pageCount"], result["pageSize"], result["freelistCount"]))
+    lines.append("journal_mode: %s; auto_vacuum: %s; user_version: %s; encoding: %s" % (
+        result["journalMode"], result["autoVacuum"], result["userVersion"], result["encoding"]))
+    lines.append("tables: %d; indexes: %d; virtual tables: %s" % (
+        result["tables"], result["indexes"],
+        ", ".join("%s (%s)" % kv for kv in result["virtualTables"].items()) or "none"))
+    stats = result["statistics"]
+    lines.append("statistics: sqlite_stat1 %s, %d rows" % ("present" if stats["sqliteStat1"] else "absent", stats["rows"]))
+    lines.append("wal file: %s; shm file: %s" % (result["walBytes"], result["shmBytes"]))
+    fs = result["filesystem"]
+    lines.append("filesystem: %s" % ("%s at %s (%s)" % (fs["type"], fs["mount"], fs["options"]) if fs else "not available on this platform"))
+    lines.append("inspector library: SQLite %s, %s" % (result["library"]["version"], result["library"]["threadsafe"]))
+    lines.append("not in the file: busy_timeout, synchronous, foreign_keys, cache_size, mmap_size, temp_store; read the code that opens the connection")
+    for note in notes(result):
+        lines.append("note: " + note)
+    if source is not None:
+        lines.append("source scan (journal_mode mentions): %d" % len(source))
+        for item in source:
+            lines.append("  %s: %s%s" % (item["file"], item["status"], "" if item["ok"] else "  <- read this"))
+        for item in source_errors:
+            lines.append("  not scanned: %s (%s)" % (item["file"], item["error"]))
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("database")
+    parser.add_argument("--source", nargs="+", metavar="PATH", help="files or directories to scan for busy_timeout order")
+    parser.add_argument("--quick-check", action="store_true", help="also run PRAGMA quick_check (reads the whole file)")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    if not os.path.isfile(args.database):
+        print("error: not a file: %s" % args.database, file=sys.stderr)
+        return 2
+    try:
+        result = inspect(args.database, args.quick_check)
+    except (sqlite3.Error, OSError) as error:
+        print("error: %s" % error, file=sys.stderr)
+        return 2
+    source, source_errors = scan_source(args.source) if args.source else (None, [])
+    if args.json:
+        payload = dict(result)
+        payload["notes"] = notes(result)
+        if source is not None:
+            payload["source"] = source
+            payload["sourceErrors"] = source_errors
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(render(result, source, source_errors))
+    for item in source_errors:
+        print("error: could not scan %s: %s" % (item["file"], item["error"]), file=sys.stderr)
+    return 2 if source_errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/hr-stock-ui-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hr-stock-ui-audit
-description: Find template-default styling in frontend code that nobody chose for this product (stock violet accents, purple-to-blue gradients, one stock font, emoji icons, glow and blur effects), triage each hit in context, and report or fix the real ones as the request asks. Use when asked to audit or remove generic or AI-looking styling in existing UI. It does not set a visual direction.
+description: Find template-default styling nobody chose for this product (stock violet accents, purple-to-blue gradients, one stock font, emoji icons, glow and blur effects), triage each hit in context, and report or fix the real ones. Use when asked to audit or remove generic or AI-looking styling in existing UI. It does not set a visual direction.
 ---
 
 # Stock UI audit

package/skills/hr-test-audit/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.