[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7EGWWWW8FAB2GCBX68VWVSP":3,"skill-same:01M7EGWWWW8FAB2GCBX68VWVSP":45},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M7EGWWWW8FAB2GCBX68VWVSP","database-engineer-vnx-orchestration",null,"lza6\u002FArmor-piercing-system-prompts","lza6","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F128880206?v=4","01M7EB3K7WPX5T28EJ2NVHE6EG","Chinese-tingfeng","01M7EB3K97E1KQ16QWKJMFNGX8",11,"MIT","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F04-安全渗透\u002Fdatabase-engineer-vnx-orchestration\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: database-engineer\ndescription: SQLite database expertise for migrations, multi-tenant patterns, transactional safety, FTS5 virtual tables, and schema evolution. Use this skill for ANY work involving schema changes, data migrations, INSERT\u002FUPSERT semantics, FTS5 rebuilds, transaction rollback design, multi-tenant data isolation, or SQLite performance tuning. Triggers include: writing migration SQL, modifying `_import_table`-style importers, designing UNIQUE\u002FPK constraints, adding indexes for JOINs, debugging \"rows missing\" \u002F \"wrong count\" \u002F \"stuck for hours\" symptoms in SQLite-backed systems.\nallowed-tools: [Read, Write, Edit, MultiEdit, Bash, Grep, Glob]\npaths: [\"schemas\u002F**\", \"scripts\u002F**\", \"tests\u002F**\"]\n---\n\n# Database Engineer\n\nSQLite-domain specialist for migrations and data integrity.\n\n## Core Mission\n\nMigrations are integration code. Most \"data\" bugs aren't algorithmic — they're contract bugs between schema, importer, and verifier. This skill exists because P4 (the VNX one-shot consolidation migrator) consumed **5 fix-forward rounds** before converging, and the bugs were almost entirely SQLite\u002Fmulti-tenant gotchas a generalist would miss.\n\nThe specific recurring failure-modes are catalogued in `references\u002Fbug-taxonomy.md` with concrete VNX examples. Read it before writing any migration code.\n\n## When to Use\n\n- Writing or editing files under `schemas\u002Fmigrations\u002F`\n- Touching `_import_table`, `_compare_counts`, or any code that ATTACHes \u002F SELECTs \u002F INSERTs across tenant boundaries\n- Designing UNIQUE constraints or primary keys for any table that will hold multi-project rows\n- Adding `JOIN` or correlated-subquery code that scans tables ≥10k rows\n- Debugging a migration that \"completed\" but produced wrong row counts\n- Operator complains \"stuck at 100% CPU for hours\" — likely O(N×M) (see `references\u002Fsqlite-fts5-gotchas.md`)\n- Any code that calls `INSERT OR IGNORE` or `INSERT OR REPLACE`\n\n## STEP 0 — Foundational Check (Mandatory)\n\nBEFORE proposing any design, fix, or implementation:\n\n1. **Consult relevant ADRs** in `docs\u002Fgovernance\u002Fdecisions\u002F`. Special attention to:\n   - ADR-005 (NDJSON audit ledger as primary observability)\n   - ADR-007 (multi-tenant project_id stamping; composite keys for central state DBs)\n   - ADR-010 (subprocess adapter as canonical Claude routing)\n   List any ADR that applies to the task and how it constrains your solution.\n\n2. **Consult relevant memory** in `~\u002F.claude\u002Fprojects\u002F-Users-vincentvandeth-Development-vnx-dev-githost\u002Fmemory\u002FMEMORY.md` — particularly entries about past architectural incidents.\n\n3. **Check P4-style incident docs** in `claudedocs\u002F` for analogous failures (e.g., `2026-05-09-p4-migration-architecture-lessons.md` for multi-tenant migration patterns).\n\n4. **State your foundational read aloud** at the start of your response. Example: \"ADR-007 applies: new tabel X needs composite PK over project_id. Per P4 §4.2, single-column UNIQUE is a smell. Memory [[adr-007-multitenant-composite-keys]] confirms.\"\n\nSkipping STEP 0 is a process violation, not a shortcut. The FUT-1 chain (2026-05-28) burned 6 codex rounds because ADR-007 was not consulted at design time.\n\n## Decision Protocol\n\nBefore writing migration code, walk through `references\u002Fmigration-defense-checklist.md` (loaded explicitly when needed; checklist is reproduced inline below for fast access).\n\nWhen asked to fix a \"data missing\" or \"data wrong\" bug, the first investigative step is `EXPLAIN QUERY PLAN` on the failing query and `.indexes` on the related tables. Two-thirds of the bugs in the P4 history were diagnosable this way in under five minutes once anyone thought to look.\n\n## 1. SQLite Mechanics\n\n### Journal modes\nSQLite supports two journal modes operators commonly hit: `DELETE` (rollback journal as a sibling file `\u003Cdb>-journal`) and `WAL` (`\u003Cdb>-wal` + `\u003Cdb>-shm`). Never copy a DB file mid-write without one of:\n\n- `sqlite3.Connection.backup(dest)` — handles both modes correctly, locks briefly, copies all pages including in-flight ones\n- `BEGIN IMMEDIATE; .dump | sqlite3 newfile; COMMIT;` — slower but produces SQL text\n- For WAL specifically: `PRAGMA wal_checkpoint(TRUNCATE)` flushes the WAL into the base file, then a normal file copy is consistent\n\n`shutil.copy2(src, dst)` of a WAL DB is **not safe**: committed state may live in `-wal` and the copy will be partial. R2 of P4 hit this; fixed by switching to `Connection.backup()`.\n\n### Hot journal recovery\nIf a writer process is killed mid-transaction, the journal\u002FWAL file remains. The next process to open the DB reads it and replays\u002Frolls back. This is automatic but has two implications:\n\n1. After SIGTERM\u002FSIGKILL of a migrator, **open the DB once** (e.g. `sqlite3 \u003Cdb> \"SELECT 1;\"`) before inspecting it. Otherwise the file size you see includes the in-flight transaction's pages and reads can be confusing.\n2. Pre-snapshot files (`\u003Cdb>.presnap.*`) created by `_snapshot_central` are belt-and-suspenders on top of journal recovery, useful when the rollback semantics need to span multiple migrations rather than a single transaction. Don't delete them while a migrator is alive.\n\n### FTS5 virtual tables\nFTS5 is a separate physical store with its own segments. Schema-altering it usually means **drop + recreate + re-INSERT-from-temp-table**. There is no `ALTER TABLE … ADD COLUMN` for FTS5 vtabs; column changes require rebuild. See `references\u002Fsqlite-fts5-gotchas.md` for the rebuild pattern and the perf trap that almost shipped in P4 round 4.\n\n### ATTACH DATABASE for multi-source migrations\nRead-only attach uses a URI:\n```python\ncon.execute(\"ATTACH DATABASE ? AS src\", (f\"file:{src_path}?mode=ro\",))\n```\nThe `mode=ro` flag is critical — without it, the attach opens a write connection that briefly modifies the source's `-shm` file and breaks the read-only contract (operator backups can fail integrity checks).\n\n## 2. Multi-Tenant Patterns\n\nIn a single-tenant database, `id INTEGER PRIMARY KEY` is fine. In a multi-tenant central DB, that same constraint causes silent data loss the moment two tenants happen to have overlapping `id` values. The P4 chain shipped this bug twice (in `terminal_leases` and `execution_targets`).\n\n### Composite uniqueness is the default\nFor any table that will hold rows from multiple tenants, the unique constraints should be `(project_id, \u003Cnatural_key>)`, not `\u003Cnatural_key>` alone. Examples that bit P4:\n- `terminal_leases.terminal_id` UNIQUE → must be `(project_id, terminal_id)` UNIQUE\n- `execution_targets.target_key` UNIQUE → composite\n- `tag_combinations.tag_tuple` UNIQUE → composite\n- `code_snippets` FTS5 row identity is `rowid` + `project_id` column; queries must always filter on `project_id`\n\n### Stamping vs deriving project_id\nTwo patterns coexist in VNX:\n\n1. **Stamp at import**: importer overwrites the `project_id` column with the runtime project's id, regardless of what the source row contained. Used by `_import_table`. Risk: silent skip on PK conflict (see T2 in bug taxonomy).\n2. **Stamp at write-time**: writer code (e.g. `dispatch_register`, `append_receipt`) takes a `project_id` parameter and writes it explicitly. Used by per-project state code. Risk: callers forget; helper enforcement matters.\n\nPrefer pattern 2 for new code. When migrating legacy single-tenant data, pattern 1 is unavoidable — pair it with `ON CONFLICT … DO UPDATE SET project_id=excluded.project_id` so re-stamping wins on collision (see Section 3).\n\n### Verifier scoping\nPer-project verification queries MUST include `WHERE project_id = ?`. The P4 verifier had a bug where `code_snippets` count was reported as the global total for every project; this only manifests because of FTS5 vtab semantics but the lesson is broader: **never aggregate without scope** in a multi-tenant verifier.\n\n## 3. Migration Safety\n\n### UPSERT vs INSERT OR IGNORE\nThis decision shipped wrong in P4. Cheat sheet:\n\n| Situation | Use |\n|---|---|\n| Re-running migration; rows might already exist; want to skip duplicates | `INSERT OR IGNORE` **only if** PK includes tenant scope |\n| Same as above but PK is single-column | `INSERT … ON CONFLICT(\u003Cpk>) DO UPDATE SET \u003Csafe_cols>=excluded.\u003Csafe_cols>` (UPSERT) — be explicit about which columns are safe to overwrite |\n| Multiple tenants might have same PK natural key | Composite `(project_id, key)` UNIQUE; `INSERT OR IGNORE` becomes safe again |\n| Want strict \"fail if duplicate\" | Plain `INSERT` — sqlite raises `IntegrityError` |\n| Replacing entire row | `INSERT OR REPLACE` — but this **deletes-then-inserts**, breaking FK CASCADE in surprising ways |\n\n**Default for migration code: composite UNIQUE + `INSERT OR IGNORE`.** It's the simplest invariant: each tenant's row is uniquely identified, retries are no-ops, and there's no \"stale row wins\" surprise.\n\n### Idempotency\nA migrator that can be safely re-run is worth orders of magnitude more than one that requires careful manual cleanup on every retry. Idempotency means:\n\n- Each row has an `imported_at` or `run_id` so repeat imports are detectable\n- A bookkeeping table like `p4_import_idempotency(project_id, source_table, source_rowid)` records what's been done\n- Verification looks at \"this run's results\" not \"all results\" — see T9 in bug taxonomy for what happens when run_id scoping is missing\n\n### Schema-first vs imperative migrations\nThe P4 design uses ALTER-TABLE migrations layered on whatever central schema happened to exist. This works for incremental changes but fragile for greenfield (`--fresh-central` had to be added in R3 because empty central produced empty migration runs).\n\nFor new migrators, prefer **explicit central schema file** + descriptor-driven importer — see `references\u002Fmulti-tenant-patterns.md` Section 3 for the pattern.\n\n### Rollback semantics\nSQLite's transaction rollback (`BEGIN`\u002F`ROLLBACK`) is automatic on Python `sqlite3.Connection` exceptions. But cross-DB rollback (e.g. central QI + central RC) requires explicit coordination — the P4 pattern uses `_snapshot_central` to create `\u003Cdb>.presnap.\u003Cphase>.\u003Cpid>` files before risky migrations, then restores them on failure. This is correct only if every writer respects the contract.\n\n## 4. Performance\n\n### Indexes for JOINs and correlated subqueries\nThe R4 perf bug: migration `0016_rebuild_fts5.sql` had:\n```sql\nINSERT INTO code_snippets (...)\nSELECT ..., COALESCE(\n  (SELECT project_id FROM snippet_metadata m\n   WHERE m.snippet_rowid = code_snippets_rebuild_tmp.rowid),\n  'vnx-dev'\n)\nFROM code_snippets_rebuild_tmp;\n```\n`snippet_metadata.snippet_rowid` was not indexed. For 727k snippets × 119k metadata rows = ~87B row scans = ~3-5h ETA.\n\nFix: add `CREATE INDEX IF NOT EXISTS idx_snippet_metadata_rowid ON snippet_metadata(snippet_rowid);` **before** the rebuild SELECT. Reduces to O(N log M) ≈ 17M ops, completes in seconds.\n\n**Rule:** any migration with `JOIN` or correlated subquery involving a table ≥10k rows MUST include the supporting index in the same migration file.\n\n### EXPLAIN QUERY PLAN\nAlways run before shipping a migration that touches large tables:\n```sql\nEXPLAIN QUERY PLAN \u003Cyour-INSERT\u002FSELECT>;\n```\nLook for `SCAN TABLE` (bad for inner loops). Want to see `SEARCH TABLE … USING INDEX …`.\n\n### FTS5 rebuild costs at scale\n~5k rows\u002Fsec on a modern SSD, dominated by tokenizer work. For 727k rows expect ~150 sec on the rebuild alone, plus journal write overhead (~30% extra). If observed >10 min for ~1M rows, suspect missing index on subquery columns.\n\n## 5. Verifier Patterns\n\nA verifier that shares code paths with the importer is structurally co-blind: any helper bug affects both, neither catches the other. Three rules:\n\n1. **Different connection \u002F different process**: open the central DB in a fresh `sqlite3.Connection`, ideally via a different code module. The P4 verifier opens via `_compare_counts` which reuses importer helpers; this is why R5 shipped a verifier-aggregate bug.\n2. **Per-project scoped queries**: every COUNT must filter by `project_id`. A \"central total\" check is fine as a *separate* check, not as the per-project verification.\n3. **Fail-fast on missing scope**: if a table is expected to have `project_id` and it doesn't, the verifier must raise (or write to `read_errors`) — not silently fall back to global COUNT(*). The P4 R5 fix made `_compare_counts` strict about this.\n\n## 6. Migration Defense Checklist (mandatory pre-merge)\n\nApply each item before merging migration code. Each line corresponds to a real bug from the P4 history.\n\n- [ ] **Composite UNIQUE on multi-tenant tables**: every imported table with a natural key has `UNIQUE(project_id, key)` not `UNIQUE(key)` alone (T3, T6 in `references\u002Fbug-taxonomy.md`)\n- [ ] **UPSERT chosen, not IGNORE**: `INSERT OR IGNORE` only used where the unique constraint already includes `project_id`; otherwise switch to `ON CONFLICT … DO UPDATE` (T2)\n- [ ] **Verifier filters per-project**: every COUNT\u002Fchecksum query in the verifier has `WHERE project_id = ?`; no aggregate fallback (T4)\n- [ ] **Bootstrap path tested empty**: there is a test where central DB file does not exist at start, and the migration produces a valid central with all expected tables and zero data (T5)\n- [ ] **DEFAULT used only for NOT NULL backfill**: any `DEFAULT '\u003Cvalue>'` on a column added by ALTER must be reasoned about in the importer's stamp logic. If the default is \"vnx-dev\" or another sentinel that could mask un-stamped rows, add a NOT NULL CHECK in the same migration that forbids the sentinel post-migration (T1)\n- [ ] **Indexes for JOIN\u002Fcorrelated columns**: any migration with `JOIN` or `(SELECT … WHERE x = outer.y)` against a table ≥10k rows includes the supporting `CREATE INDEX` (T7)\n- [ ] **Real-data fixture test**: there is at least one integration test that runs the migration against fixtures sized within 1 OOM of production data; not just synthetic 5-row examples (Section 3.2 of lessons doc)\n- [ ] **Read failures distinguishable**: source-table-missing and source-table-unreadable are separate codes in the importer's `read_errors`; never silently degrade to count=0 (T8)\n- [ ] **run_id scoping on retryable records**: any `\u003Cfeature>_skipped` \u002F `\u003Cfeature>_failed` table includes `run_id` and `resolved_at` to filter cross-run state (T9)\n- [ ] **WAL-safe snapshots**: pre-migration snapshots of source DBs use `Connection.backup()` or `wal_checkpoint(TRUNCATE) + cp`, not bare `shutil.copy2` (T10)\n\n## Reference Files\n\n- `references\u002Fbug-taxonomy.md` — the 10 recurring patterns with VNX examples; READ FIRST when triggered\n- `references\u002Fsqlite-fts5-gotchas.md` — FTS5 rebuild patterns + perf traps\n- `references\u002Fmulti-tenant-patterns.md` — composite key design, stamping strategies, descriptor-driven importers\n- `references\u002Fp4-postmortem-summary.md` — links to full lessons doc + key code:line citations\n\n## Companion Skills\n\n- For VNX-specific schema knowledge (which tables hold what, the dispatch lifecycle, intelligence-injection flow): use `intelligence-engineer` instead. This skill is the *generic* SQLite layer; `intelligence-engineer` is the *VNX domain* layer.\n- For general code review: `reviewer` may request a `database-engineer` second-opinion review when a PR touches `schemas\u002F`, `_import_table`-style code, or migration files.\n\n## Codex Defense Checklist (inherited from backend-developer)\n\nDatabase work still ships through the same code-review pipeline. The patterns in `backend-developer\u002FSKILL.md` Section \"Codex Defense Checklist\" apply: atomic writes, fcntl locking on shared NDJSON, null guards, schema version checks. Treat that as a baseline and the Migration Defense Checklist above as additive for any migration-touching work.\n","# Database Engineer\n\nSQLite-domain specialist for migrations and data integrity.\n\n## Core Mission\n\nMigrations are integration code. Most \"data\" bugs aren't algorithmic — they're contract bugs between schema, importer, and verifier. This skill exists because P4 (the VNX one-shot consolidation migrator) consumed **5 fix-forward rounds** before converging, and the bugs were almost entirely SQLite\u002Fmulti-tenant gotchas a generalist would miss.\n\nThe specific recurring failure-modes are catalogued in `references\u002Fbug-taxonomy.md` with concrete VNX examples. Read it before writing any migration code.\n\n## When to Use\n\n- Writing or editing files under `schemas\u002Fmigrations\u002F`\n- Touching `_import_table`, `_compare_counts`, or any code that ATTACHes \u002F SELECTs \u002F INSERTs across tenant boundaries\n- Designing UNIQUE constraints or primary keys for any table that will hold multi-project rows\n- Adding `JOIN` or correlated-subquery code that scans tables ≥10k rows\n- Debugging a migration that \"completed\" but produced wrong row counts\n- Operator complains \"stuck at 100% CPU for hours\" — likely O(N×M) (see `references\u002Fsqlite-fts5-gotchas.md`)\n- Any code that calls `INSERT OR IGNORE` or `INSERT OR REPLACE`\n\n## STEP 0 — Foundational Check (Mandatory)\n\nBEFORE proposing any design, fix, or implementation:\n\n1. **Consult relevant ADRs** in `docs\u002Fgovernance\u002Fdecisions\u002F`. Special attention to:\n   - ADR-005 (NDJSON audit ledger as primary observability)\n   - ADR-007 (multi-tenant project_id stamping; composite keys for central state DBs)\n   - ADR-010 (subprocess adapter as canonical Claude routing)\n   List any ADR that applies to the task and how it constrains your solution.\n\n2. **Consult relevant memory** in `~\u002F.claude\u002Fprojects\u002F-Users-vincentvandeth-Development-vnx-dev-githost\u002Fmemory\u002FMEMORY.md` — particularly entries about past architectural incidents.\n\n3. **Check P4-style incident docs** in `claudedocs\u002F` for analogous failures (e.g., `2026-05-09-p4-migration-architecture-lessons.md` for multi-tenant migration patterns).\n\n4. **State your foundational read aloud** at the start of your response. Example: \"ADR-007 applies: new tabel X needs composite PK over project_id. Per P4 §4.2, single-column UNIQUE is a smell. Memory [[adr-007-multitenant-composite-keys]] confirms.\"\n\nSkipping STEP 0 is a process violation, not a shortcut. The FUT-1 chain (2026-05-28) burned 6 codex rounds because ADR-007 was not consulted at design time.\n\n## Decision Protocol\n\nBefore writing migration code, walk through `references\u002Fmigration-defense-checklist.md` (loaded explicitly when needed; checklist is reproduced inline below for fast access).\n\nWhen asked to fix a \"data missing\" or \"data wrong\" bug, the first investigative step is `EXPLAIN QUERY PLAN` on the failing query and `.indexes` on the related tables. Two-thirds of the bugs in the P4 history were diagnosable this way in under five minutes once anyone thought to look.\n\n## 1. SQLite Mechanics\n\n### Journal modes\nSQLite supports two journal modes operators commonly hit: `DELETE` (rollback journal as a sibling file `\u003Cdb>-journal`) and `WAL` (`\u003Cdb>-wal` + `\u003Cdb>-shm`). Never copy a DB file mid-write without one of:\n\n- `sqlite3.Connection.backup(dest)` — handles both modes correctly, locks briefly, copies all pages including in-flight ones\n- `BEGIN IMMEDIATE; .dump | sqlite3 newfile; COMMIT;` — slower but produces SQL text\n- For WAL specifically: `PRAGMA wal_checkpoint(TRUNCATE)` flushes the WAL into the base file, then a normal file copy is consistent\n\n`shutil.copy2(src, dst)` of a WAL DB is **not safe**: committed state may live in `-wal` and the copy will be partial. R2 of P4 hit this; fixed by switching to `Connection.backup()`.\n\n### Hot journal recovery\nIf a writer process is killed mid-transaction, the journal\u002FWAL file remains. The next process to open the DB reads it and replays\u002Frolls back. This is automatic but has two implications:\n\n1. After SIGTERM\u002FSIGKILL of a migrator, **open the DB once** (e.g. `sqlite3 \u003Cdb> \"SELECT 1;\"`) before inspecting it. Otherwise the file size you see includes the in-flight transaction's pages and reads can be confusing.\n2. Pre-snapshot files (`\u003Cdb>.presnap.*`) created by `_snapshot_central` are belt-and-suspenders on top of journal recovery, useful when the rollback semantics need to span multiple migrations rather than a single transaction. Don't delete them while a migrator is alive.\n\n### FTS5 virtual tables\nFTS5 is a separate physical store with its own segments. Schema-altering it usually means **drop + recreate + re-INSERT-from-temp-table**. There is no `ALTER TABLE … ADD COLUMN` for FTS5 vtabs; column changes require rebuild. See `references\u002Fsqlite-fts5-gotchas.md` for the rebuild pattern and the perf trap that almost shipped in P4 round 4.\n\n### ATTACH DATABASE for multi-source migrations\nRead-only attach uses a URI:\n```python\ncon.execute(\"ATTACH DATABASE ? AS src\", (f\"file:{src_path}?mode=ro\",))\n```\nThe `mode=ro` flag is critical — without it, the attach opens a write connection that briefly modifies the source's `-shm` file and breaks the read-only contract (operator backups can fail integrity checks).\n\n## 2. Multi-Tenant Patterns\n\nIn a single-tenant database, `id INTEGER PRIMARY KEY` is fine. In a multi-tenant central DB, that same constraint causes silent data loss the moment two tenants happen to have overlapping `id` values. The P4 chain shipped this bug twice (in `terminal_leases` and `execution_targets`).\n\n### Composite uniqueness is the default\nFor any table that will hold rows from multiple tenants, the unique constraints should be `(project_id, \u003Cnatural_key>)`, not `\u003Cnatural_key>` alone. Examples that bit P4:\n- `terminal_leases.terminal_id` UNIQUE → must be `(project_id, terminal_id)` UNIQUE\n- `execution_targets.target_key` UNIQUE → composite\n- `tag_combinations.tag_tuple` UNIQUE → composite\n- `code_snippets` FTS5 row identity is `rowid` + `project_id` column; queries must always filter on `project_id`\n\n### Stamping vs deriving project_id\nTwo patterns coexist in VNX:\n\n1. **Stamp at import**: importer overwrites the `project_id` column with the runtime project's id, regardless of what the source row contained. Used by `_import_table`. Risk: silent skip on PK conflict (see T2 in bug taxonomy).\n2. **Stamp at write-time**: writer code (e.g. `dispatch_register`, `append_receipt`) takes a `project_id` parameter and writes it explicitly. Used by per-project state code. Risk: callers forget; helper enforcement matters.\n\nPrefer pattern 2 for new code. When migrating legacy single-tenant data, pattern 1 is unavoidable — pair it with `ON CONFLICT … DO UPDATE SET project_id=excluded.project_id` so re-stamping wins on collision (see Section 3).\n\n### Verifier scoping\nPer-project verification queries MUST include `WHERE project_id = ?`. The P4 verifier had a bug where `code_snippets` count was reported as the global total for every project; this only manifests because of FTS5 vtab semantics but the lesson is broader: **never aggregate without scope** in a multi-tenant verifier.\n\n## 3. Migration Safety\n\n### UPSERT vs INSERT OR IGNORE\nThis decision shipped wrong in P4. Cheat sheet:\n\n| Situation | Use |\n|---|---|\n| Re-running migration; rows might already exist; want to skip duplicates | `INSERT OR IGNORE` **only if** PK includes tenant scope |\n| Same as above but PK is single-column | `INSERT … ON CONFLICT(\u003Cpk>) DO UPDATE SET \u003Csafe_cols>=excluded.\u003Csafe_cols>` (UPSERT) — be explicit about which columns are safe to overwrite |\n| Multiple tenants might have same PK natural key | Composite `(project_id, key)` UNIQUE; `INSERT OR IGNORE` becomes safe again |\n| Want strict \"fail if duplicate\" | Plain `INSERT` — sqlite raises `IntegrityError` |\n| Replacing entire row | `INSERT OR REPLACE` — but this **deletes-then-inserts**, breaking FK CASCADE in surprising ways |\n\n**Default for migration code: composite UNIQUE + `INSERT OR IGNORE`.** It's the simplest invariant: each tenant's row is uniquely identified, retries are no-ops, and there's no \"stale row wins\" surprise.\n\n### Idempotency\nA migrator that can be safely re-run is worth orders of magnitude more than one that requires careful manual cleanup on every retry. Idempotency means:\n\n- Each row has an `imported_at` or `run_id` so repeat imports are detectable\n- A bookkeeping table like `p4_import_idempotency(project_id, source_table, source_rowid)` records what's been done\n- Verification looks at \"this run's results\" not \"all results\" — see T9 in bug taxonomy for what happens when run_id scoping is missing\n\n### Schema-first vs imperative migrations\nThe P4 design uses ALTER-TABLE migrations layered on whatever central schema happened to exist. This works for incremental changes but fragile for greenfield (`--fresh-central` had to be added in R3 because empty central produced empty migration runs).\n\nFor new migrators, prefer **explicit central schema file** + descriptor-driven importer — see `references\u002Fmulti-tenant-patterns.md` Section 3 for the pattern.\n\n### Rollback semantics\nSQLite's transaction rollback (`BEGIN`\u002F`ROLLBACK`) is automatic on Python `sqlite3.Connection` exceptions. But cross-DB rollback (e.g. central QI + central RC) requires explicit coordination — the P4 pattern uses `_snapshot_central` to create `\u003Cdb>.presnap.\u003Cphase>.\u003Cpid>` files before risky migrations, then restores them on failure. This is correct only if every writer respects the contract.\n\n## 4. Performance\n\n### Indexes for JOINs and correlated subqueries\nThe R4 perf bug: migration `0016_rebuild_fts5.sql` had:\n```sql\nINSERT INTO code_snippets (...)\nSELECT ..., COALESCE(\n  (SELECT project_id FROM snippet_metadata m\n   WHERE m.snippet_rowid = code_snippets_rebuild_tmp.rowid),\n  'vnx-dev'\n)\nFROM code_snippets_rebuild_tmp;\n```\n`snippet_metadata.snippet_rowid` was not indexed. For 727k snippets × 119k metadata rows = ~87B row scans = ~3-5h ETA.\n\nFix: add `CREATE INDEX IF NOT EXISTS idx_snippet_metadata_rowid ON snippet_metadata(snippet_rowid);` **before** the rebuild SELECT. Reduces to O(N log M) ≈ 17M ops, completes in seconds.\n\n**Rule:** any migration with `JOIN` or correlated subquery involving a table ≥10k rows MUST include the supporting index in the same migration file.\n\n### EXPLAIN QUERY PLAN\nAlways run before shipping a migration that touches large tables:\n```sql\nEXPLAIN QUERY PLAN \u003Cyour-INSERT\u002FSELECT>;\n```\nLook for `SCAN TABLE` (bad for inner loops). Want to see `SEARCH TABLE … USING INDEX …`.\n\n### FTS5 rebuild costs at scale\n~5k rows\u002Fsec on a modern SSD, dominated by tokenizer work. For 727k rows expect ~150 sec on the rebuild alone, plus journal write overhead (~30% extra). If observed >10 min for ~1M rows, suspect missing index on subquery columns.\n\n## 5. Verifier Patterns\n\nA verifier that shares code paths with the importer is structurally co-blind: any helper bug affects both, neither catches the other. Three rules:\n\n1. **Different connection \u002F different process**: open the central DB in a fresh `sqlite3.Connection`, ideally via a different code module. The P4 verifier opens via `_compare_counts` which reuses importer helpers; this is why R5 shipped a verifier-aggregate bug.\n2. **Per-project scoped queries**: every COUNT must filter by `project_id`. A \"central total\" check is fine as a *separate* check, not as the per-project verification.\n3. **Fail-fast on missing scope**: if a table is expected to have `project_id` and it doesn't, the verifier must raise (or write to `read_errors`) — not silently fall back to global COUNT(*). The P4 R5 fix made `_compare_counts` strict about this.\n\n## 6. Migration Defense Checklist (mandatory pre-merge)\n\nApply each item before merging migration code. Each line corresponds to a real bug from the P4 history.\n\n- [ ] **Composite UNIQUE on multi-tenant tables**: every imported table with a natural key has `UNIQUE(project_id, key)` not `UNIQUE(key)` alone (T3, T6 in `references\u002Fbug-taxonomy.md`)\n- [ ] **UPSERT chosen, not IGNORE**: `INSERT OR IGNORE` only used where the unique constraint already includes `project_id`; otherwise switch to `ON CONFLICT … DO UPDATE` (T2)\n- [ ] **Verifier filters per-project**: every COUNT\u002Fchecksum query in the verifier has `WHERE project_id = ?`; no aggregate fallback (T4)\n- [ ] **Bootstrap path tested empty**: there is a test where central DB file does not exist at start, and the migration produces a valid central with all expected tables and zero data (T5)\n- [ ] **DEFAULT used only for NOT NULL backfill**: any `DEFAULT '\u003Cvalue>'` on a column added by ALTER must be reasoned about in the importer's stamp logic. If the default is \"vnx-dev\" or another sentinel that could mask un-stamped rows, add a NOT NULL CHECK in the same migration that forbids the sentinel post-migration (T1)\n- [ ] **Indexes for JOIN\u002Fcorrelated columns**: any migration with `JOIN` or `(SELECT … WHERE x = outer.y)` against a table ≥10k rows includes the supporting `CREATE INDEX` (T7)\n- [ ] **Real-data fixture test**: there is at least one integration test that runs the migration against fixtures sized within 1 OOM of production data; not just synthetic 5-row examples (Section 3.2 of lessons doc)\n- [ ] **Read failures distinguishable**: source-table-missing and source-table-unreadable are separate codes in the importer's `read_errors`; never silently degrade to count=0 (T8)\n- [ ] **run_id scoping on retryable records**: any `\u003Cfeature>_skipped` \u002F `\u003Cfeature>_failed` table includes `run_id` and `resolved_at` to filter cross-run state (T9)\n- [ ] **WAL-safe snapshots**: pre-migration snapshots of source DBs use `Connection.backup()` or `wal_checkpoint(TRUNCATE) + cp`, not bare `shutil.copy2` (T10)\n\n## Reference Files\n\n- `references\u002Fbug-taxonomy.md` — the 10 recurring patterns with VNX examples; READ FIRST when triggered\n- `references\u002Fsqlite-fts5-gotchas.md` — FTS5 rebuild patterns + perf traps\n- `references\u002Fmulti-tenant-patterns.md` — composite key design, stamping strategies, descriptor-driven importers\n- `references\u002Fp4-postmortem-summary.md` — links to full lessons doc + key code:line citations\n\n## Companion Skills\n\n- For VNX-specific schema knowledge (which tables hold what, the dispatch lifecycle, intelligence-injection flow): use `intelligence-engineer` instead. This skill is the *generic* SQLite layer; `intelligence-engineer` is the *VNX domain* layer.\n- For general code review: `reviewer` may request a `database-engineer` second-opinion review when a PR touches `schemas\u002F`, `_import_table`-style code, or migration files.\n\n## Codex Defense Checklist (inherited from backend-developer)\n\nDatabase work still ships through the same code-review pipeline. The patterns in `backend-developer\u002FSKILL.md` Section \"Codex Defense Checklist\" apply: atomic writes, fcntl locking on shared NDJSON, null guards, schema version checks. Treat that as a baseline and the Migration Defense Checklist above as additive for any migration-touching work.\n",{},"main","d69096e239f2a89aabc2cd078c47664a9d3b1e11","04-安全渗透\u002Fdatabase-engineer-vnx-orchestration",3,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts","https:\u002F\u002Fgithub.com\u002Flza6","个人vx：Tf00798\r\n个人✈：@TFGY999","2026-10-08 14:29:22",{"source":7,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add lza6\u002FArmor-piercing-system-prompts --skill database-engineer-vnx-orchestration",{"tool":37,"command":38},"bunx","bunx skills add lza6\u002FArmor-piercing-system-prompts --skill database-engineer-vnx-orchestration",{"tool":40,"command":41},"pnpm","pnpm dlx skills add lza6\u002FArmor-piercing-system-prompts --skill database-engineer-vnx-orchestration","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F04-安全渗透\u002Fdatabase-engineer-vnx-orchestration\u002FSKILL.md",true,[],[46,54,59,66,73,80],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":53},"01M7FFG485KY83TD6HSC4YPCMC","obsidian-clipper-template-creator","Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobsidian-clipper-template-creator\u002FSKILL.md",[],[],"2026-11-16 10:05:34",{"skillNo":55,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":53},"01M7FFG0T6AZ0STEJPSB3CX84K","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobsidian-clipper-template-creator-antigravity-awesome-skills-main\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":53},"01M7FFFY0QEM14SKWPDYGMXM2P","python-api","Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP\u002FmAP semantics, and source-style import diagnostics.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002Fsub-skills\u002Fpython-api\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":53},"01M7FFFVZQZ2GJ0C0TGP7JHD20","file-evaluation","Folder-based PASCAL VOC AP\u002FmAP evaluation from ground-truth and detection text files.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002Fsub-skills\u002Ffile-evaluation\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":53},"01M7FFFSFNYSE77SJ6PE1CK2DA","object-detection-metrics","Guides legacy Object-Detection-Metrics PASCAL VOC AP\u002FmAP evaluation from detection text folders and direct Python API classes.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":53},"01M7FFFP0GCK1RVXBCPQ8APBMT","nx-workspace-patterns","Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fnx-workspace-patterns\u002FSKILL.md",[],[]]