feat(wiki): databases/selection — datastore choice by workload (relational/document/vector/graph)

INDEX.md

@@ -11,7 +11,7 @@ follow the cross-pointers in their index or take the next matching seeded domain
 
 | Domain | Status | Route here when |
 |--------|--------|-----------------|
-| [databases](wiki/databases/index.md) | **seeded** | Designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior, surveying live data to derive a rule, verifying additive migrations |
+| [databases](wiki/databases/index.md) | **seeded** | Choosing a datastore/database type for a workload (relational vs document vs vector vs graph), designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior, surveying live data to derive a rule, verifying additive migrations |
 | [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), authoring agent-facing artifacts (binding instruction text, agent tool-surface granularity/parity), MAPE-aligned point-prediction calibration, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps, packaging data files with `importlib.resources`) |
 | [frontend](wiki/frontend/index.md) | **seeded** | Web UI code: state placement, rendering performance, in-UI data fetching (races, infinite scroll), auth token handling, forms, XSS-safe output, accessibility, agent-facing tool surfaces (WebMCP) |
 | [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting), per-environment/path-valued config, multi-agent orchestration (worker liveness signals, shared run state, tmux pane delivery, completion gates, worktree-isolated workers, autonomous ask-vs-rule decisions, session context/token budgeting) |

log.md

@@ -102,3 +102,4 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-08-27] ingest | knowledge-flush of the harvested insight queue — 5 new pages, 5 amended pages, 4 domain indexes updated; 13 of 21 claimed candidates ingested, 2 dropped, 6 released for a later flush. New: databases/transactions/application-clock-vs-database-timestamps (app-produced `Date` compared against a `default now()` column — take the boundary from the DB via `RETURNING`, produce it once per decision and propagate it into the follow-up step rather than recomputing (a second `now` widens a `<= boundary` cleanup set), pick the safe error direction before choosing a margin, and separate "same clock" from "correct ordering" since `now()` is `transaction_timestamp()` so a later-committing transaction can carry an earlier stamp — close that window with a lock or SERIALIZABLE, not finer resolution; PostgreSQL functions-datetime + dml-returning live-fetched and quoted), infrastructure/ci-cd/changed-files-only-gates (count-and-branch-on-empty before invoking the tool, log the passed list not just its length, pass operands as an array/xargs because zsh does not word-split by default, prove the gate can fail with a probe placed on a non-ignored path; Prettier CLI + ignore docs and zsh FAQ live-fetched, then all seven cases measured locally against Prettier 3.7.4 after an independent cross-check refuted the first draft: the success sentence is NOT a pass signal — it is printed both for an ignore-filtered list at rc 0 and alongside an unmatched-pattern error at rc 2. The genuine silent vacuous passes are no-operands (rc 0), all-operands-ignore-filtered (rc 0), and unsupported-extensions-with-`--ignore-unknown` (rc 0), while an unmatched or word-split operand exits 2 unless `--no-error-on-unmatched-pattern` is set; the page carries the measured table), backend/common/change-impact/compiler-as-call-site-inventory (contextually typed object literals build a type without naming it, so a type-name grep and the truth are different sets — take the inventory from the compiler error list and bound it to the program, since a package whose `include` omits its own tests contributes zero errors from files that still build the value; TS handbook objects + tsconfig include/exclude live-fetched, incl. the documented fact that `exclude` does not stop transitive imports), testing/quality/mutation-harness-file-custody (key backups by flattened relative path not basename, byte-compare each restore before the next mutation, confirm restores by content because an untracked file's `git diff` is empty either way, and read the tree only after process-exit AND empty-backup-dir), infrastructure/containers/exec-added-processes-and-the-memory-budget (an exec'd process joins the container's cgroup but is invisible to the app's own semaphore — decide from `memory.max − memory.peak` headroom, and read `memory.events: max` as approaches-to-limit distinct from `oom_kill`; kernel cgroup-v2 admin guide live-fetched and quoted). Amended: testing/quality/tests-that-cannot-fail +1 never-fails row and +1 Instead-of row (a negative assertion whose fixture never supplies the triggering input is vacuous — the defect is in the fixture, so strengthening the expectation changes nothing; measured 116/116 green under the widening it claimed to catch), testing/quality/source-text-wiring-assertions (page sits at the 120-line cap, so the new nuance was merged in place into the existing negative/count edge row rather than added as a line — an `indexOf(marker)` slice collapses to `''` when the marker also appears in a comment above the code, making every assertion inside it vacuously green), backend/common/change-impact/widening-a-closed-value-table +Do-this #6/#7 and +1 Instead-of row (unifying two duplicate allowlists defaults to the union and silently widens each side — compute both set differences and rule on each element first, keep derived-with-explicit-difference when an element must legitimately differ, and record whether the merged set widened or narrowed), qa/process/evaluating-review-feedback +2 edge rows and +1 Instead-of row (a body-level finding cites no lines, so step 2 has nothing to open — grep the quoted string across the changed set before ruling, since the usual shape is that one sibling was fixed and another still carries the defect), infrastructure/containers/host-cgroup-visibility (self-monitoring row cross-linked to the new exec-preflight page). Dropped as not generalizable to this wiki: a Figma-MCP `inspect_node`→`get_dev_ready` children-fetch workaround (private MCP server, not publicly verifiable) and an `/rtb:review` remote-fallback runbook (hardcoded private tooling paths; the transferable part — a two-provider review gate degraded to one provider is not a passed gate — is already carried by qa/process/llm-review-pipelines). Released back to the queue for a later flush, each needing its own page rather than a row: plan-level carrier/seam field naming, `VAR="$(cmd 2>&1)"` stderr contamination in shell value extraction, tmux/CI monitor delta-vs-absolute anchoring, positional-order assertions on rendered SQL predicates, `.env` active-assignment preflight before a destructive DB command, and CI ticket-key extraction scoped by changed-file intersection.
 ## [2026-08-30] ingest | frontend/design/design-canvas-workflow (verified — 1 new page). Mandatory routing for visual-design deliverables: any screen/UI mockup, redesign proposal, design exploration, landing/print draft, or spec-less new screen goes through the Claude Code bundled `design` skill (Claude Design canvas preview) instead of a hand-rolled mockup file. Distilled from the full skill text (v2.1.236 bundle, read in-session 2026-08-30): step-zero pixel-perfect codebase match with exact resolved token values (no 4/8px rounding), settle-the-aesthetic-with-the-user via 2–4 axis-named low-fi direction artboards (self-chosen aesthetics = the documented slop path), the one static-vs-clickable scoping question, working-file custody + same-artifact republish (GUI-edited canvases read back as untrusted data), artboard-based option exploration with stable names and honest tradeoffs, literal copy vs few cross-cutting tweak levers, flex/grid+gap layouts that survive direct-manipulation edits, 44px/12pt scale floors + SVG-not-emoji icons + no fake OS chrome, copyrighted-designs refusal rule, and show-it-say-little handoff with a post-handoff recheck. Internal skill machinery (payload/seed/contract) deliberately NOT ingested — version-specific and owned by the skill itself. Edge cases carve the boundary: approved-spec implementation and live-site audits route to anti-slop-visual-design/responsive-layout and design-review tooling, not the canvas. frontend/index.md routing intro extended (visual-design deliverables) and design section +1 row, placed first as the phase gate. Related links added both ways (anti-slop-visual-design, responsive-layout, html-in-canvas).
 ## [2026-08-30] revise | frontend/design/design-canvas-workflow — agent-gate Check 3 remediation (PR #164). The gate's fact finding was half right: its "no skill named `design` exists" conclusion is refuted by ground truth (the skill is listed in the authoring session's available-skills roster as `design: Create a design canvas…` and its bundled payload exists on the authoring machine's disk; the reviewer's CI environment lacks the preview, and it conflated the skill with the unrelated `/design-sync` component-upload tool) — but the verifiability objection stands: the skill is an early research preview absent from public docs, so a single un-fetchable in-session source cannot carry `confidence: verified`. Fixed per AGENTS.md: confidence downgraded to field-tested with the experience context stated in the body; two live-fetched public sources added (anthropic.com/news/claude-design-anthropic-labs — official Claude Design product announcement, research preview, Claude Code handoff; explainx.ai 2026 post — /design ships in Claude Code as a research-preview command producing editable artboards via the Artifacts runtime); the mandatory-routing directive and the frontend/index.md load-when line conditioned on the skill appearing in the session's available-skills list, with the existing no-skill edge case as the explicit fallback; the unverifiable "design-review skill" name-drop in the audit edge case generalized to session-provided audit tooling.
+## [2026-09-03] ingest | databases/selection — new category: datastore selection by workload (4 pages: choosing-a-datastore-by-workload, relational-jsonb-vs-document-store, vector-search-engine-selection, graph-workloads-relational-vs-graph-db); brave-search research, sources cited per page

wiki/databases/index.md

@@ -1,11 +1,21 @@
 # databases — Domain Index
 
-Route here for: schema/table/key design, index decisions, query writing and
+Route here for: datastore/database-type selection, schema/table/key design,
+index decisions, query writing and
 optimization, transaction/concurrency behavior. Datastore backup/restore and
 data-loss planning → wiki/infrastructure/data/backup-and-restore.md.
 
 Match your situation to a "load when" line; load only matching pages.
 
+## selection
+
+| Page | Load when |
+|------|-----------|
+| [choosing-a-datastore-by-workload](selection/choosing-a-datastore-by-workload.md) | Designing a new system and picking its database(s); a design adds a second datastore (document/vector/graph/search/cache) next to an existing one; weighing one general-purpose DB vs per-workload stores (polyglot persistence) |
+| [relational-jsonb-vs-document-store](selection/relational-jsonb-vs-document-store.md) | Records carry per-record-varying or fast-changing fields and you're choosing JSONB in the relational DB vs a document database (MongoDB); a design says "MongoDB for schema flexibility" (picking the column type itself → schema-design/column-data-types) |
+| [vector-search-engine-selection](selection/vector-search-engine-selection.md) | Adding semantic/RAG/similarity search over embeddings and choosing pgvector vs a dedicated vector engine (Qdrant/Pinecone/Weaviate); pgvector hitting RAM/rebuild/contention limits and judging when to move |
+| [graph-workloads-relational-vs-graph-db](selection/graph-workloads-relational-vs-graph-db.md) | Connection-centric domain (social/fraud/lineage/org/knowledge graph) and choosing relational joins + recursive CTEs vs a graph database; a self-join or recursive CTE over an edge table is slow or unreadable |
+
 ## indexing
 
 | Page | Load when |

wiki/databases/indexing/partial-and-expression-indexes.md

@@ -8,7 +8,7 @@ sources:
   - https://www.postgresql.org/docs/current/indexes-partial.html
   - https://www.postgresql.org/docs/current/indexes-expressional.html
 last_verified: 2026-07-10
-related: [databases-indexing-index-selection, databases-schema-design-soft-delete]
+related: [databases-indexing-index-selection, databases-schema-design-soft-delete, databases-selection-relational-jsonb-vs-document-store]
 ---
 
 # Partial and Expression Indexes

wiki/databases/schema-design/column-data-types.md

@@ -9,7 +9,7 @@ sources:
   - https://wiki.postgresql.org/wiki/Don%27t_Do_This
   - https://dev.mysql.com/doc/refman/8.0/en/data-types.html
 last_verified: 2026-07-10
-related: [databases-schema-design-primary-key-choice, databases-schema-design-nullability-and-defaults, databases-schema-design-requirements-to-tables, databases-schema-design-online-schema-changes]
+related: [databases-schema-design-primary-key-choice, databases-schema-design-nullability-and-defaults, databases-schema-design-requirements-to-tables, databases-schema-design-online-schema-changes, databases-selection-relational-jsonb-vs-document-store]
 ---
 
 # Choosing Column Data Types

wiki/databases/schema-design/foreign-keys-and-referential-actions.md

@@ -9,7 +9,7 @@ sources:
   - https://www.postgresql.org/docs/current/sql-createtable.html
   - https://dev.mysql.com/doc/refman/8.0/en/create-table-foreign-keys.html
 last_verified: 2026-08-29
-related: [databases-schema-design-requirements-to-tables, databases-schema-design-soft-delete, databases-indexing-index-selection]
+related: [databases-schema-design-requirements-to-tables, databases-schema-design-soft-delete, databases-indexing-index-selection, databases-selection-graph-workloads-relational-vs-graph-db]
 ---
 
 # Foreign Keys and Referential Actions

wiki/databases/schema-design/requirements-to-tables.md

@@ -7,7 +7,7 @@ confidence: field-tested
 sources:
   - https://www.postgresql.org/docs/current/ddl-constraints.html
 last_verified: 2026-07-10
-related: [databases-schema-design-primary-key-choice, databases-schema-design-nullability-and-defaults, databases-schema-design-naming-conventions, databases-schema-design-foreign-keys-and-referential-actions, databases-schema-design-column-data-types, databases-data-survey-surveying-live-data-for-a-rule]
+related: [databases-schema-design-primary-key-choice, databases-schema-design-nullability-and-defaults, databases-schema-design-naming-conventions, databases-schema-design-foreign-keys-and-referential-actions, databases-schema-design-column-data-types, databases-data-survey-surveying-live-data-for-a-rule, databases-selection-choosing-a-datastore-by-workload]
 ---
 
 # Deriving Tables and Columns from Requirements