feat(db-3): Phase A — 3 new indexes + strategy doc#42
Merged
hyperpolymath merged 1 commit intoJun 1, 2026
Conversation
…+ strategy doc
DB-3 Phase A from the 2026-06-01 audit (quandledb#33). Adds three
B-tree indexes to `quandle_semantic_index` and documents the
column-by-column strategy.
## New indexes
* idx_semantic_writhe (writhe) — filter on /api/knots?writhe=X
(serve.jl:694) and KRL pushdown (line 176); ~100 distinct values.
* idx_semantic_genus (genus) — filter on both endpoints
(serve.jl:695, 754) and KRL pushdown (line 177); ~20 distinct.
* idx_semantic_gencount (quandle_generator_count) — currently
filtered in-memory after full fetch (serve.jl:779-780); ~100
distinct values.
Total indexes now: 10 (was 7). All use IF NOT EXISTS — idempotent
across server restarts.
## docs/db-3-index-strategy.md
Full column inventory (20 columns), cardinality estimates from the
agent audit, per-column filter-site citations, classification, and
index recommendations. Includes EXPLAIN QUERY PLAN snippets to
verify the planner uses the new indexes.
## What's left
* Phase B (upstream) — replace raw `CREATE INDEX` DDL with
Skein.jl public API calls. Blocked on
`create_index!`/`drop_index!`/`list_indices` being exposed.
* Phase C (deferred) — full-text indexes on polynomial strings,
materialised views on equivalence buckets, composite indexes.
#33 stays open for Phases B and C.
Cross-references:
* PROOF-NARRATIVE.md §3 DB-3
* Audit doc DB-3
* Issue #33 (DB-3 tracker)
* Issue #34 (DB-6 EXPLAIN — depends on this layout for
selectivity estimates)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath
deleted the
feat/db-3-phase-a-indexes-writhe-genus-gen-count
branch
This was referenced Jun 1, 2026
hyperpolymath
added a commit
that referenced
this pull request
Jun 2, 2026
Scope ===== Phase A landed: utility function `explain_query_plan(conn, sql, args)` that wraps SQLite `EXPLAIN QUERY PLAN`, plus a self-contained in-memory test harness, plus a strategy doc covering query inventory and the Skein.jl public-API gap that blocks Phase B. Phase A does NOT wire the utility into any public endpoint. That is Phase B (also blocked on the Skein.jl gap shared with DB-3 Phase B — see docs/db-3-index-strategy.md). Files ===== - `server/query_explain.jl`: `explain_query_plan`, `is_select_only`, `plan_summary`. Read-only by construction. - `server/test_query_explain.jl`: 6 testsets covering trivial plan, single-table SELECT, filtered SELECT structure, the DB-3 PR #42 `idx_semantic_writhe` regression hook, the QD-12 read-only discipline, and the `plan_summary` join. Self-contained in-memory DB — no seed-data dependency. - `docs/db-6-explain-strategy.md`: query inventory across `serve.jl` (split owned-by-quandledb vs owned-by-Skein.jl), Phase A acceptance, Phase B endpoint design (blocked), Phase C plan-snapshot regression (deferred). Echo-types audit ================ Per [[proofs-must-check-and-cross-doc-echo-types]]: echo-types is fibre-based loss-with-residue semantics. Zero SQL / HTTP / query-plan content. Verdict: NOT-RELEVANT. Single estate-wide audit record at `feedback_echo_types_audit_krl_tangle_quandledb_not_relevant.md` covers TG-1/TG-9/KR-6/DB-6/QD-2. Cross-document ============== - DB-3 (`docs/db-3-index-strategy.md`): index inventory consumed by Phase A test 4 (writhe filter → `idx_semantic_writhe`). - QD-12 (`.github/workflows/read-only-api-gate.yml`): the read-only discipline Phase B endpoint must honour. - VeriSimDB seam-walk (`hyperpolymath/verisimdb#80`): the plan-snapshot regression pattern Phase C will echo. Closes none. Tracking continues at quandledb#34. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds B-tree indexes on
writhe,genus,quandle_generator_counttoquandle_semantic_index. Addsdocs/db-3-index-strategy.mdcovering the 20-column inventory + cardinality + per-column recommendation + Phase B/C deferral notes. Closes Phase A of #33. Auto-merge armed.🤖 Generated with Claude Code