@bolvrk/engine-sqlite 0.1.4

package/src/metas/index.ts

@@ -0,0 +1,598 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `@bolvrk/engine-sqlite/metas` — RuleMeta objects ONLY. Nothing in this
+ * module may carry a `check` function or import the parser: the website
+ * bundles this entry into the browser to render the rule pages and the
+ * database filter. The implementations live in ../rules and import their
+ * meta from here, never the other way around. A test asserts no exported
+ * object has a `check` property.
+ *
+ * Every danger claim below is backed by the SQLite documentation named in
+ * the comment next to `verified`, and the "fails outright" claims are
+ * re-proven against a real SQLite in test/claims.test.ts.
+ */
+import type { RuleMeta } from "@bolvrk/engine";
+
+/** The SL corpus version. Bump on any rule addition, removal, or behavior change. */
+export const SL_RULE_CORPUS_VERSION = "0.4.0";
+
+export const sl001Meta: RuleMeta = {
+  id: "SL001",
+  version: "1.0.0",
+  name: "ADD COLUMN NOT NULL without a default",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "SQLite refuses to add a NOT NULL column unless it has a default other than NULL — the statement fails with \"Cannot add a NOT NULL column with default value NULL\", so the migration stops here in every environment, including the one that matters.",
+  example: "ALTER TABLE orders ADD COLUMN region TEXT NOT NULL;",
+  fix: {
+    description:
+      "Give the column a non-NULL default, or add it nullable, backfill, and enforce NOT NULL by rebuilding the table later. In SQLite a default on ADD COLUMN is free: existing rows are not rewritten, the default is read from the schema.",
+    example: "ALTER TABLE orders ADD COLUMN region TEXT NOT NULL DEFAULT 'eu';",
+  },
+  verified: true, // SQLite docs, ALTER TABLE ADD COLUMN: "If a NOT NULL constraint is specified, then the column must have a default value other than NULL."
+};
+
+export const sl002Meta: RuleMeta = {
+  id: "SL002",
+  version: "1.0.0",
+  name: "ADD COLUMN with PRIMARY KEY or UNIQUE",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "ALTER TABLE ADD COLUMN cannot carry a PRIMARY KEY or UNIQUE constraint — SQLite rejects the statement outright (\"Cannot add a PRIMARY KEY column\", \"Cannot add a UNIQUE column\"). The migration fails, and the constraint it wanted still does not exist.",
+  example: "ALTER TABLE orders ADD COLUMN external_id TEXT UNIQUE;",
+  fix: {
+    description:
+      "Add the column plain, then create the unique index as its own statement — that is what UNIQUE would have built anyway. A new primary key needs the table rebuilt: create the new table, copy, drop, rename.",
+    example: "ALTER TABLE orders ADD COLUMN external_id TEXT;\nCREATE UNIQUE INDEX orders_external_id ON orders (external_id);",
+  },
+  verified: true, // SQLite docs, ALTER TABLE ADD COLUMN: "The column may not have a PRIMARY KEY or UNIQUE constraint."
+};
+
+export const sl003Meta: RuleMeta = {
+  id: "SL003",
+  version: "1.0.0",
+  name: "ADD COLUMN with a non-constant default",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "A column added with ALTER TABLE may not default to CURRENT_TIME, CURRENT_DATE, CURRENT_TIMESTAMP or a parenthesised expression: SQLite rejects the statement (\"Cannot add a column with non-constant default\"). The pattern is common in migrations ported from Postgres, where it works.",
+  example: "ALTER TABLE orders ADD COLUMN created_at TEXT DEFAULT CURRENT_TIMESTAMP;",
+  fix: {
+    description:
+      "Add the column with a constant default (or none), and set the timestamp from application code or a trigger. If the default must be an expression, the column has to be part of a table rebuild.",
+    example: "ALTER TABLE orders ADD COLUMN created_at TEXT;\n-- then, from the application or a trigger:\n--    UPDATE orders SET created_at = CURRENT_TIMESTAMP WHERE created_at IS NULL;",
+  },
+  verified: true, // SQLite docs, ALTER TABLE ADD COLUMN: "The column may not have a default value of CURRENT_TIME, CURRENT_DATE, CURRENT_TIMESTAMP, or an expression in parentheses."
+};
+
+export const sl004Meta: RuleMeta = {
+  id: "SL004",
+  version: "1.0.0",
+  name: "ADD COLUMN GENERATED ... STORED",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "A STORED generated column cannot be added with ALTER TABLE — SQLite only allows VIRTUAL generated columns there (\"cannot add a STORED column\"). The statement fails; nothing is added.",
+  example: "ALTER TABLE orders ADD COLUMN total_cents INTEGER GENERATED ALWAYS AS (qty * unit_cents) STORED;",
+  fix: {
+    description:
+      "Declare the generated column VIRTUAL, which ALTER TABLE accepts and which costs nothing at write time. A STORED column belongs in CREATE TABLE — for an existing table that means a rebuild.",
+    example: "ALTER TABLE orders ADD COLUMN total_cents INTEGER GENERATED ALWAYS AS (qty * unit_cents) VIRTUAL;",
+  },
+  verified: true, // SQLite docs, ALTER TABLE ADD COLUMN: "The column may not be GENERATED ALWAYS ... STORED, though VIRTUAL columns are allowed."
+};
+
+export const sl005Meta: RuleMeta = {
+  id: "SL005",
+  version: "1.0.0",
+  name: "ADD COLUMN REFERENCES with a non-NULL default",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "When foreign keys are enforced (PRAGMA foreign_keys=ON, which most applications set on every connection), a column added with a REFERENCES clause must default to NULL — anything else fails with \"Cannot add a REFERENCES column with non-NULL default value\". Whether it fails depends on a per-connection pragma, so the same file passes in one runner and stops in another.",
+  example: "ALTER TABLE orders ADD COLUMN warehouse_id INTEGER REFERENCES warehouses(id) DEFAULT 1;",
+  fix: {
+    description:
+      "Add the referencing column with a NULL default, backfill the rows that need a value, and let the application set it from then on.",
+    example: "ALTER TABLE orders ADD COLUMN warehouse_id INTEGER REFERENCES warehouses(id);\n-- backfill from the application, in batches",
+  },
+  verified: true, // SQLite docs, ALTER TABLE ADD COLUMN: "If foreign key constraints are enabled and a column with a REFERENCES clause is added, the column must have a default value of NULL."
+};
+
+export const sl006Meta: RuleMeta = {
+  id: "SL006",
+  version: "1.0.0",
+  name: "DROP COLUMN rewrites the table",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "DROP COLUMN edits the schema and then rewrites every row of the table to purge the column's values — one write transaction that holds the database's single write lock for the length of the copy. It also fails outright if anything else in the schema names the column (an index, a foreign key, a view, a trigger, a generated column) and is unsupported before SQLite 3.35.",
+  example: "ALTER TABLE orders DROP COLUMN legacy_flag;",
+  fix: {
+    description:
+      "Stop reading the column in code first, let a release soak, and drop it in a scheduled migration — SQLite's write lock means every other writer waits for the rewrite. If the column is indexed or referenced, drop those objects first or the statement fails.",
+    example: "-- release N: remove every code reference to legacy_flag\n-- release N+1, scheduled:\n--    DROP INDEX IF EXISTS orders_legacy_flag;\n--    ALTER TABLE orders DROP COLUMN legacy_flag;",
+  },
+  verified: true, // SQLite docs, ALTER TABLE DROP COLUMN: "the table content is rewritten to purge the data associated with that column"; "only works if the column is not referenced by any other parts of the schema".
+};
+
+export const sl007Meta: RuleMeta = {
+  id: "SL007",
+  version: "1.0.0",
+  name: "RENAME COLUMN or RENAME TABLE during a deploy",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "A rename is instant in SQLite, and that is the problem: the moment it commits, every process still running the previous release fails on the old name. Views and triggers are rewritten to the new name, but application SQL is not.",
+  example: "ALTER TABLE orders RENAME COLUMN qty TO quantity;",
+  fix: {
+    description:
+      "Expand and contract: add the new column, dual-write from the application, backfill, switch readers, then drop the old column in a later release. For a table, create the new one, copy, and swap only when no deployed code reads the old name.",
+    example: "ALTER TABLE orders ADD COLUMN quantity INTEGER;\n-- dual-write from the application; backfill in batches\n-- later release, after readers moved:\n--    ALTER TABLE orders DROP COLUMN qty;",
+  },
+  verified: true, // SQLite docs, ALTER TABLE RENAME: renames modify the schema in place; references in views and triggers are rewritten, application SQL is not.
+};
+
+export const sl008Meta: RuleMeta = {
+  id: "SL008",
+  version: "1.0.0",
+  name: "ADD COLUMN with a CHECK constraint scans the table",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "Adding a column is normally a schema-only change in SQLite. With a CHECK constraint (or NOT NULL on a generated column) the whole table is scanned to verify existing rows first — under the write lock, proportional to the table's size.",
+  example: "ALTER TABLE orders ADD COLUMN priority INTEGER DEFAULT 0 CHECK (priority BETWEEN 0 AND 9);",
+  fix: {
+    description:
+      "Add the column without the CHECK when the table is large and the constraint is guaranteed by the default and the application; enforce it in a rebuild later, or accept the scan in a scheduled window.",
+    example: "ALTER TABLE orders ADD COLUMN priority INTEGER DEFAULT 0;",
+  },
+  verified: true, // SQLite docs, ALTER TABLE ADD COLUMN: "if the new column has a CHECK constraint, or a NOT NULL constraint on a generated column, then the entire table is scanned to verify" (3.37.0+).
+};
+
+export const sl009Meta: RuleMeta = {
+  id: "SL009",
+  version: "1.0.0",
+  name: "Table rebuild with foreign keys still enforced",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "This migration rebuilds a table the documented way — create the new table, copy, drop the old, rename — but never turns foreign keys off first. With PRAGMA foreign_keys=ON the DROP TABLE performs an implicit DELETE FROM: rows referencing the table fail the migration with a constraint error, or ON DELETE CASCADE quietly removes them.",
+  example: "CREATE TABLE orders_new (id INTEGER PRIMARY KEY, qty INTEGER NOT NULL);\nINSERT INTO orders_new SELECT id, qty FROM orders;\nDROP TABLE orders;\nALTER TABLE orders_new RENAME TO orders;",
+  fix: {
+    description:
+      "Follow the twelve steps from the SQLite manual: PRAGMA foreign_keys=OFF outside the transaction, rebuild inside it, PRAGMA foreign_key_check before COMMIT, and PRAGMA foreign_keys=ON after.",
+    example: "PRAGMA foreign_keys = OFF;\nBEGIN;\nCREATE TABLE orders_new (id INTEGER PRIMARY KEY, qty INTEGER NOT NULL);\nINSERT INTO orders_new SELECT id, qty FROM orders;\nDROP TABLE orders;\nALTER TABLE orders_new RENAME TO orders;\nPRAGMA foreign_key_check;\nCOMMIT;\nPRAGMA foreign_keys = ON;",
+  },
+  verified: true, // SQLite docs, Making Other Kinds Of Table Schema Changes (12 steps) and Foreign Key Support §5: "If foreign key constraints are enabled ... DROP TABLE ... performs an implicit DELETE FROM".
+};
+
+export const sl010Meta: RuleMeta = {
+  id: "SL010",
+  version: "1.0.0",
+  name: "PRAGMA that is a no-op inside a transaction",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "PRAGMA foreign_keys and PRAGMA journal_mode do nothing while a transaction is open — SQLite does not error, it silently leaves the setting as it was. A rebuild that switches foreign keys off after BEGIN runs with them on, and everything SL009 warns about applies.",
+  example: "BEGIN;\nPRAGMA foreign_keys = OFF;\nDROP TABLE orders;\nCOMMIT;",
+  fix: {
+    description: "Issue the pragma before BEGIN (and re-enable after COMMIT). If the migration runner wraps every file in a transaction, the pragma has to be set by the runner itself.",
+    example: "PRAGMA foreign_keys = OFF;\nBEGIN;\nDROP TABLE orders;\nCOMMIT;\nPRAGMA foreign_keys = ON;",
+  },
+  verified: true, // SQLite docs, PRAGMA foreign_keys: "This pragma is a no-op within a transaction"; PRAGMA journal_mode: "cannot be changed while a transaction is active".
+};
+
+export const sl011Meta: RuleMeta = {
+  id: "SL011",
+  version: "1.0.0",
+  name: "Foreign keys switched off and not back on",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "PRAGMA foreign_keys=OFF is per connection and does not reset at COMMIT. A migration that turns enforcement off for a rebuild and never turns it on leaves the runner's connection accepting orphans for as long as it lives — every later statement in the run, and any backfill sharing the connection, goes unchecked.",
+  example: "PRAGMA foreign_keys = OFF;\nDROP TABLE orders;",
+  fix: {
+    description: "End the file with PRAGMA foreign_keys=ON, after the transaction that needed it off.",
+    example: "PRAGMA foreign_keys = OFF;\nBEGIN;\nDROP TABLE orders;\nCOMMIT;\nPRAGMA foreign_keys = ON;",
+  },
+  verified: true, // SQLite docs, PRAGMA foreign_keys: the setting is per connection and persists until changed.
+};
+
+export const sl012Meta: RuleMeta = {
+  id: "SL012",
+  version: "1.0.0",
+  name: "Foreign keys re-enabled without a foreign_key_check",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "Turning foreign keys back on does not validate what happened while they were off. Step 10 of the SQLite rebuild recipe is PRAGMA foreign_key_check before COMMIT — without it, an orphaned row created during the rebuild is discovered by the first user query that joins on it.",
+  example: "PRAGMA foreign_keys = OFF;\nBEGIN;\nDROP TABLE orders;\nALTER TABLE orders_new RENAME TO orders;\nCOMMIT;\nPRAGMA foreign_keys = ON;",
+  fix: {
+    description: "Run PRAGMA foreign_key_check inside the transaction, before COMMIT, so a violation can still be rolled back.",
+    example: "PRAGMA foreign_keys = OFF;\nBEGIN;\nDROP TABLE orders;\nALTER TABLE orders_new RENAME TO orders;\nPRAGMA foreign_key_check;\nCOMMIT;\nPRAGMA foreign_keys = ON;",
+  },
+  verified: true, // SQLite docs, Making Other Kinds Of Table Schema Changes, step 10: "If foreign key constraints were originally enabled then run PRAGMA foreign_key_check".
+};
+
+export const sl013Meta: RuleMeta = {
+  id: "SL013",
+  version: "1.0.0",
+  name: "Unbounded UPDATE or DELETE",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "An UPDATE or DELETE with no WHERE touches every row in one write transaction. SQLite has one writer at a time: the whole application queues behind it (or hits SQLITE_BUSY) for as long as the statement runs, and the rollback journal or WAL grows by the size of the change.",
+  example: "UPDATE orders SET status = 'archived';",
+  fix: {
+    description:
+      "State the predicate, and batch by rowid range from an operational job so each chunk commits on its own and the write lock is released between batches.",
+    example: "-- batched job, not a migration statement:\n--    UPDATE orders SET status = 'archived'\n--    WHERE status = 'closed' AND rowid BETWEEN ? AND ?;",
+  },
+  verified: true, // SQLite docs, File Locking And Concurrency: a single writer holds the lock for the transaction; WAL: readers proceed, writers serialize.
+};
+
+export const sl014Meta: RuleMeta = {
+  id: "SL014",
+  version: "1.0.0",
+  name: "VACUUM in a migration",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "VACUUM rewrites the entire database file into a temporary copy and swaps it in: it needs up to twice the database's size in free disk space, holds the write lock for the whole rewrite, and fails outright if a transaction is open on the connection — so inside a migration runner's transaction it is an error, and outside one it is an outage-sized pause.",
+  example: "VACUUM;",
+  fix: {
+    description: "Vacuum from an operational job in a maintenance window, never from a migration. If space reclaim must be continuous, PRAGMA auto_vacuum=INCREMENTAL with incremental_vacuum in small steps.",
+    example: "-- operational runbook, not a migration:\n--    sqlite3 app.db 'VACUUM;'",
+  },
+  verified: true, // SQLite docs, VACUUM: "A VACUUM will fail if there is an open transaction"; "can require up to twice the ... disk space".
+};
+
+export const sl015Meta: RuleMeta = {
+  id: "SL015",
+  version: "1.0.0",
+  name: "REINDEX of everything",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "REINDEX with no argument rebuilds every index in every attached database in one write transaction — the write lock is held for the total, not per table. In a migration it is almost always broader than intended.",
+  example: "REINDEX;",
+  fix: {
+    description: "Name the index or table that actually needs rebuilding — REINDEX is only needed after a collation change.",
+    example: "REINDEX orders_status_idx;",
+  },
+  verified: true, // SQLite docs, REINDEX: "If no arguments ... all indices in all attached databases are rebuilt."
+};
+
+export const sl016Meta: RuleMeta = {
+  id: "SL016",
+  version: "1.0.0",
+  name: "Index build on an existing table",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "SQLite has no CONCURRENTLY: CREATE INDEX scans the table and writes the index under the database's write lock, and every other writer waits (or gets SQLITE_BUSY) for the duration. Fine on a small table; on a large one this is the moment the application stalls.",
+  example: "CREATE INDEX orders_status_idx ON orders (status);",
+  fix: {
+    description: "Build large indexes in a window, with busy_timeout set on the application's connections so a wait is a wait and not an error.",
+    example: "-- in the maintenance window, with PRAGMA busy_timeout set on application connections:\n--    CREATE INDEX orders_status_idx ON orders (status);",
+  },
+  verified: true, // SQLite docs, File Locking And Concurrency / WAL: one writer at a time; CREATE INDEX is a write transaction over the whole table.
+};
+
+export const sl017Meta: RuleMeta = {
+  id: "SL017",
+  version: "1.0.0",
+  name: "INT PRIMARY KEY is not a rowid alias",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "Only a column declared exactly INTEGER PRIMARY KEY becomes an alias for the rowid. INT PRIMARY KEY (or BIGINT, or INTEGER PRIMARY KEY DESC) is an ordinary column with a separate unique index: every lookup by primary key is an extra B-tree hop, the value is not the rowid, and VACUUM may renumber the real rowid underneath it.",
+  example: "CREATE TABLE orders (id INT PRIMARY KEY, qty INTEGER);",
+  fix: {
+    description: "Spell the type INTEGER, exactly, on the primary key column of a rowid table.",
+    example: "CREATE TABLE orders (id INTEGER PRIMARY KEY, qty INTEGER);",
+  },
+  verified: true, // SQLite docs, ROWIDs and the INTEGER PRIMARY KEY: "the declared type must be exactly INTEGER"; INTEGER PRIMARY KEY DESC quirk documented in the same section.
+};
+
+export const sl018Meta: RuleMeta = {
+  id: "SL018",
+  version: "1.0.0",
+  name: "AUTOINCREMENT where a plain INTEGER PRIMARY KEY would do",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "AUTOINCREMENT makes every insert also update the sqlite_sequence table, and the SQLite manual itself says it should be avoided unless strictly needed. Its one guarantee — a deleted rowid is never reused — is rarely what a migration author meant.",
+  example: "CREATE TABLE orders (id INTEGER PRIMARY KEY AUTOINCREMENT, qty INTEGER);",
+  fix: {
+    description: "Drop the keyword; INTEGER PRIMARY KEY already assigns increasing rowids. Keep AUTOINCREMENT only when reuse of a deleted id would be a correctness bug.",
+    example: "CREATE TABLE orders (id INTEGER PRIMARY KEY, qty INTEGER);",
+  },
+  verified: true, // SQLite docs, AUTOINCREMENT: "imposes extra CPU, memory, disk space, and disk I/O overhead and should be avoided if not strictly needed. It is usually not needed."
+};
+
+export const sl019Meta: RuleMeta = {
+  id: "SL019",
+  version: "1.0.0",
+  name: "Table rebuild that drops the old table before copying its rows",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "The rebuild recipe is create, copy, drop, rename. This migration creates the new table, drops the old one and renames the new one onto its name, but never copies the rows across before the DROP. DROP TABLE discards them; the rename brings back the name with an empty table, and nothing in SQLite fails to say so.",
+  example: "CREATE TABLE orders_new (id INTEGER PRIMARY KEY, qty INTEGER NOT NULL);\nDROP TABLE orders;\nALTER TABLE orders_new RENAME TO orders;",
+  fix: {
+    description:
+      "Copy before dropping: INSERT INTO the new table SELECT from the old, inside the same transaction, so a failed copy rolls the whole rebuild back. If the table is meant to come back empty, suppress the rule with a reason that says so.",
+    example: "BEGIN;\nCREATE TABLE orders_new (id INTEGER PRIMARY KEY, qty INTEGER NOT NULL);\nINSERT INTO orders_new SELECT id, qty FROM orders;\nDROP TABLE orders;\nALTER TABLE orders_new RENAME TO orders;\nCOMMIT;",
+  },
+  verified: true, // SQLite docs, Making Other Kinds Of Table Schema Changes: step 5 (copy) precedes step 6 (drop); DROP TABLE removes the table and its content. Re-proven in test/claims.test.ts.
+};
+
+export const sl020Meta: RuleMeta = {
+  id: "SL020",
+  version: "1.0.0",
+  name: "CREATE TABLE without STRICT",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "Without STRICT, SQLite's column types are suggestions: a TEXT value goes into an INTEGER column, a blob into a date, and nothing complains until the application reads it back. STRICT (3.37+) makes the declared type an actual constraint, and it only exists as a CREATE TABLE option — it cannot be added later without a rebuild.",
+  example: "CREATE TABLE orders (id INTEGER PRIMARY KEY, qty INTEGER, note TEXT);",
+  fix: {
+    description: "Add STRICT to every new table. Column types are then limited to INT, INTEGER, REAL, TEXT, BLOB and ANY, and a value of the wrong type is rejected at insert time instead of surfacing later.",
+    example: "CREATE TABLE orders (id INTEGER PRIMARY KEY, qty INTEGER, note TEXT) STRICT;",
+  },
+  verified: true, // SQLite docs, STRICT Tables: "SQLite strives to be flexible regarding the datatype of the content ... The STRICT keyword ... enforces" the declared type. Re-proven in test/claims.test.ts.
+};
+
+export const sl021Meta: RuleMeta = {
+  id: "SL021",
+  version: "1.0.0",
+  name: "Foreign key column without an index",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "SQLite indexes the parent side of a foreign key (the referenced key must be unique) but never the child side. Every DELETE or UPDATE of a parent row then scans the whole child table to look for references — with foreign keys on, deleting one user scans every order. The manual's advice is an index on every child key column.",
+  example: "CREATE TABLE orders (id INTEGER PRIMARY KEY, user_id INTEGER REFERENCES users(id));",
+  fix: {
+    description: "Create an index on the referencing column (or columns, in the foreign key's order) in the same migration.",
+    example: "CREATE TABLE orders (id INTEGER PRIMARY KEY, user_id INTEGER REFERENCES users(id));\nCREATE INDEX orders_user_id ON orders (user_id);",
+  },
+  verified: true, // SQLite docs, Foreign Key Support §3: "the child table ... should also have an index ... Usually, the parent key of a foreign key constraint is the primary key ... an index on the child key columns" avoids a full scan on parent DELETE/UPDATE. Re-proven with EXPLAIN QUERY PLAN in test/claims.test.ts.
+};
+
+export const sl022Meta: RuleMeta = {
+  id: "SL022",
+  version: "1.0.0",
+  name: "Rename with legacy_alter_table on",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "With PRAGMA legacy_alter_table=ON, RENAME TABLE and RENAME COLUMN go back to the pre-3.26 behaviour: references inside views and triggers are not rewritten. The rename succeeds, and the first query through a view that named the old table fails with \"no such table\".",
+  example: "PRAGMA legacy_alter_table = ON;\nALTER TABLE orders RENAME TO purchases;",
+  fix: {
+    description: "Leave legacy_alter_table off (the default) so SQLite rewrites views and triggers with the rename. If the pragma is on for a specific rebuild step, switch it off before any rename.",
+    example: "PRAGMA legacy_alter_table = OFF;\nALTER TABLE orders RENAME TO purchases;",
+  },
+  verified: true, // SQLite docs, PRAGMA legacy_alter_table and ALTER TABLE RENAME: with the legacy behaviour "references to the table within trigger bodies and view definitions are not updated". Re-proven in test/claims.test.ts.
+};
+
+export const sl023Meta: RuleMeta = {
+  id: "SL023",
+  version: "1.0.0",
+  name: "Dropping what a view or trigger in this migration depends on",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "This migration creates a view or trigger and then drops the table or column it depends on. SQLite does not stop it: the view fails with \"no such column\" the first time it is queried, and a trigger that names the column makes every later write to its table fail. Older releases refuse the DROP COLUMN instead. Either way the failure is guaranteed by the file itself, not by what production holds.",
+  example: "CREATE VIEW open_orders AS SELECT id, status FROM orders WHERE status = 'open';\nALTER TABLE orders DROP COLUMN status;",
+  fix: {
+    description: "Drop or redefine the view or trigger first, then drop the column or table, then recreate the view without the dependency.",
+    example: "DROP VIEW IF EXISTS open_orders;\nALTER TABLE orders DROP COLUMN status;\nCREATE VIEW open_orders AS SELECT id FROM orders;",
+  },
+  verified: true, // SQLite docs, ALTER TABLE DROP COLUMN: "only works if the column is not referenced by any other parts of the schema". Re-proven in test/claims.test.ts on 3.51: the drop goes through and the view / trigger break on first use.
+};
+
+export const sl024Meta: RuleMeta = {
+  id: "SL024",
+  version: "1.0.0",
+  name: "PRIMARY KEY column that accepts NULL",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "In a rowid table, a PRIMARY KEY column that is not INTEGER does not imply NOT NULL — a long-standing SQLite bug kept for compatibility — so NULL keys are accepted and the uniqueness the key promised is gone (every NULL is distinct). In a WITHOUT ROWID table the same NULL is refused at insert time instead, so the schema behaves differently depending on one table option.",
+  example: "CREATE TABLE orders (ref TEXT PRIMARY KEY, qty INTEGER);",
+  fix: {
+    description: "Spell NOT NULL on every non-INTEGER primary key column so the key is a key.",
+    example: "CREATE TABLE orders (ref TEXT PRIMARY KEY NOT NULL, qty INTEGER);",
+  },
+  verified: true, // SQLite docs, CREATE TABLE §PRIMARY KEY: "the value of the PRIMARY KEY column can be NULL ... due to a bug in some early versions" — unless the table is WITHOUT ROWID. Re-proven in test/claims.test.ts.
+};
+
+export const sl025Meta: RuleMeta = {
+  id: "SL025",
+  version: "1.0.0",
+  name: "Write migration in a DEFERRED transaction",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "A plain BEGIN is DEFERRED: it takes no lock until the first write, then tries to upgrade a read lock to a write lock. If another connection holds the write lock at that moment the upgrade fails immediately with SQLITE_BUSY — busy_timeout does not apply to a lock upgrade — and the migration aborts part way through its reads.",
+  example: "BEGIN;\nALTER TABLE orders ADD COLUMN region TEXT;\nCOMMIT;",
+  fix: {
+    description: "Start a migration that writes with BEGIN IMMEDIATE: the write lock is taken up front, busy_timeout applies, and there is no upgrade to fail.",
+    example: "BEGIN IMMEDIATE;\nALTER TABLE orders ADD COLUMN region TEXT;\nCOMMIT;",
+  },
+  verified: true, // SQLite docs, BEGIN TRANSACTION: "DEFERRED ... the transaction does not actually start until the database is first accessed"; a deferred transaction that needs to write after reading "may fail with SQLITE_BUSY" and the busy handler is not invoked for a lock upgrade that would deadlock.
+};
+
+export const sl026Meta: RuleMeta = {
+  id: "SL026",
+  version: "1.0.0",
+  name: "BEGIN inside a transaction, or COMMIT without one",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "SQLite has no nested transactions: a second BEGIN fails with \"cannot start a transaction within a transaction\", and COMMIT or ROLLBACK with nothing open fails with \"no transaction is active\". Either error stops the migration where it happens — usually because a runner already wraps the file.",
+  example: "BEGIN;\nBEGIN;\nALTER TABLE orders ADD COLUMN region TEXT;\nCOMMIT;",
+  fix: {
+    description: "One BEGIN, one COMMIT, in order — or none at all if the migration runner manages the transaction. Use SAVEPOINT for a nested scope.",
+    example: "BEGIN;\nALTER TABLE orders ADD COLUMN region TEXT;\nCOMMIT;",
+  },
+  verified: true, // SQLite docs, BEGIN TRANSACTION: "Transactions ... cannot be nested" ; "attempting to start a new transaction while one is active is an error". Re-proven in test/claims.test.ts.
+};
+
+export const sl027Meta: RuleMeta = {
+  id: "SL027",
+  version: "1.0.0",
+  name: "Unbounded DELETE that cascades to child tables",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "A DELETE with no WHERE on a table that other tables reference with ON DELETE CASCADE empties those tables too, in the same statement, with foreign keys on — and does nothing to them with foreign keys off. The blast radius depends on a per-connection pragma, and the statement itself names only one table.",
+  example: "CREATE TABLE lines (id INTEGER PRIMARY KEY, order_id INTEGER REFERENCES orders(id) ON DELETE CASCADE);\nDELETE FROM orders;",
+  fix: {
+    description: "State the predicate and batch the delete; if the intent is to clear the parent and its children, delete the children explicitly first so the migration reads the way it behaves.",
+    example: "-- batched job, children first, explicit:\n--    DELETE FROM lines WHERE order_id IN (SELECT id FROM orders WHERE status = 'closed' AND rowid BETWEEN ? AND ?);\n--    DELETE FROM orders WHERE status = 'closed' AND rowid BETWEEN ? AND ?;",
+  },
+  verified: true, // SQLite docs, Foreign Key Support §4.3: ON DELETE CASCADE "propagates the delete ... to each row in the child table"; enforcement depends on PRAGMA foreign_keys. Re-proven in test/claims.test.ts.
+};
+
+export const sl028Meta: RuleMeta = {
+  id: "SL028",
+  version: "1.0.0",
+  name: "Index on a non-deterministic expression",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "An index expression must give the same answer for the same row every time, so SQLite refuses random(), changes(), last_insert_rowid() and their kin in CREATE INDEX: \"non-deterministic functions prohibited in index expressions\". The statement fails and the migration stops.",
+  example: "CREATE INDEX orders_shuffle ON orders (id + random());",
+  fix: {
+    description: "Index a deterministic expression — lower(), a column arithmetic, a JSON path — or store the value in a column and index that.",
+    example: "CREATE INDEX orders_email_ci ON orders (lower(email));",
+  },
+  verified: true, // SQLite docs, Indexes On Expressions: "expressions ... may only use deterministic functions". Re-proven in test/claims.test.ts.
+};
+
+export const sl029Meta: RuleMeta = {
+  id: "SL029",
+  version: "1.0.0",
+  name: "AUTOINCREMENT on a WITHOUT ROWID table",
+  tier: 1,
+  defaultSeverity: "critical",
+  rationale:
+    "AUTOINCREMENT only exists for the rowid, and a WITHOUT ROWID table has none: SQLite refuses the CREATE TABLE with \"AUTOINCREMENT not allowed on WITHOUT ROWID tables\". The table is not created and the migration stops.",
+  example: "CREATE TABLE sessions (id INTEGER PRIMARY KEY AUTOINCREMENT, token TEXT) WITHOUT ROWID;",
+  fix: {
+    description: "Drop the keyword — or drop WITHOUT ROWID if a monotonically increasing integer key is the point of the table.",
+    example: "CREATE TABLE sessions (id INTEGER PRIMARY KEY, token TEXT);",
+  },
+  verified: true, // SQLite docs, WITHOUT ROWID tables: "AUTOINCREMENT does not work on WITHOUT ROWID tables"; the CREATE TABLE fails. Re-proven in test/claims.test.ts.
+};
+
+export const sl030Meta: RuleMeta = {
+  id: "SL030",
+  version: "1.0.0",
+  name: "ATTACH DATABASE in a migration",
+  tier: 1,
+  defaultSeverity: "warning",
+  rationale:
+    "ATTACH opens a second database file on the runner's connection, by a path that only makes sense on one machine, for the life of that connection. In a migration it is almost always an import script that got committed: it fails on any other host, and while it works it can read from or write to a file the migration never declared.",
+  example: "ATTACH DATABASE '/var/backups/legacy.db' AS legacy;\nINSERT INTO orders SELECT * FROM legacy.orders;",
+  fix: {
+    description: "Keep imports out of migrations: run them as an operational job with the file path as a parameter, and leave the migration to the schema.",
+    example: "-- operational import job, not a migration:\n--    sqlite3 app.db \"ATTACH '/path/legacy.db' AS legacy; INSERT INTO orders SELECT * FROM legacy.orders; DETACH legacy;\"",
+  },
+  verified: true, // SQLite docs, ATTACH DATABASE: the attachment is per connection and by file name; no other engine-level claim is made.
+};
+
+export const sl031Meta: RuleMeta = {
+  id: "SL031",
+  version: "1.0.0",
+  name: "Redundant index",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "An index whose columns are a leading prefix of another index on the same table, a duplicate of one, or an index on the INTEGER PRIMARY KEY (the rowid, which is the table's own B-tree) changes no query plan — SQLite already answers those lookups from the wider index or the table itself. It still costs a write on every insert, update and delete, and space in the file.",
+  example: "CREATE INDEX orders_user ON orders (user_id);\nCREATE INDEX orders_user_created ON orders (user_id, created_at);",
+  fix: {
+    description: "Keep the wider index and drop the prefix; never index the INTEGER PRIMARY KEY column or a column that is already UNIQUE.",
+    example: "CREATE INDEX orders_user_created ON orders (user_id, created_at);",
+  },
+  verified: true, // SQLite docs, Query Planning: a multi-column index serves any leading prefix of its columns; ROWIDs: INTEGER PRIMARY KEY is the rowid, the table B-tree's key. Re-proven with EXPLAIN QUERY PLAN in test/claims.test.ts.
+};
+
+export const sl032Meta: RuleMeta = {
+  id: "SL032",
+  version: "1.0.0",
+  name: "Indexes built before the bulk copy in a rebuild",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "In a table rebuild the copy is the expensive step. Creating the new table's indexes before INSERT ... SELECT makes SQLite maintain every index row by row during the copy — random B-tree inserts for each — instead of one sorted build per index afterwards. The manual's own recipe creates the indexes after the copy.",
+  example: "CREATE TABLE orders_new (id INTEGER PRIMARY KEY, user_id INTEGER, qty INTEGER) STRICT;\nCREATE INDEX orders_new_user ON orders_new (user_id);\nINSERT INTO orders_new SELECT id, user_id, qty FROM orders;",
+  fix: {
+    description: "Copy first, then create the indexes on the populated table.",
+    example: "CREATE TABLE orders_new (id INTEGER PRIMARY KEY, user_id INTEGER, qty INTEGER) STRICT;\nINSERT INTO orders_new SELECT id, user_id, qty FROM orders;\nCREATE INDEX orders_new_user ON orders_new (user_id);",
+  },
+  verified: true, // SQLite docs, Making Other Kinds Of Table Schema Changes: step 4 creates the new table, step 5 copies, step 6+ recreates indexes — the copy precedes index creation.
+};
+
+export const sl033Meta: RuleMeta = {
+  id: "SL033",
+  version: "1.0.0",
+  name: "Text or blob primary key on a rowid table",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "On a rowid table a TEXT or BLOB primary key is not the table's key: rows live in a B-tree keyed by the hidden rowid, and the primary key is a separate unique index. Every lookup by key walks the index and then the table, and every row is stored twice over (key in the index, key in the row). WITHOUT ROWID makes the primary key the table's own B-tree — the manual recommends it exactly for this shape.",
+  example: "CREATE TABLE sessions (token TEXT PRIMARY KEY NOT NULL, user_id INTEGER) STRICT;",
+  fix: {
+    description: "Declare the table WITHOUT ROWID when the primary key is not an integer and rows are small (under about a twentieth of a page). Keep a rowid table for wide rows or when code depends on rowid.",
+    example: "CREATE TABLE sessions (token TEXT PRIMARY KEY NOT NULL, user_id INTEGER) WITHOUT ROWID, STRICT;",
+  },
+  verified: true, // SQLite docs, The WITHOUT ROWID Optimization: "tables that have non-integer or composite PRIMARY KEYs and small rows" benefit; a rowid table's non-integer PRIMARY KEY is "just a UNIQUE index".
+};
+
+export const sl034Meta: RuleMeta = {
+  id: "SL034",
+  version: "1.0.0",
+  name: "Journal mode set to something other than WAL",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "journal_mode is stored in the database file: a migration that sets DELETE, TRUNCATE or PERSIST changes every future connection, not just the runner's. In those modes a writer blocks readers and readers block the writer for the length of each transaction; WAL lets readers proceed during a write and is the mode the application almost certainly wants.",
+  example: "PRAGMA journal_mode = DELETE;",
+  fix: {
+    description: "Set WAL once, from the application's connection setup or a deliberate operational step — and if a migration must set it, set WAL.",
+    example: "PRAGMA journal_mode = WAL;",
+  },
+  verified: true, // SQLite docs, PRAGMA journal_mode: the mode is persistent for WAL and stored in the file; Write-Ahead Logging: "readers do not block writers and a writer does not block readers". Re-proven across two connections in test/claims.test.ts.
+};
+
+export const sl035Meta: RuleMeta = {
+  id: "SL035",
+  version: "1.0.0",
+  name: "Connection-scoped pragma in a migration",
+  tier: 1,
+  defaultSeverity: "note",
+  rationale:
+    "cache_size, synchronous, temp_store, mmap_size and busy_timeout live on the connection that set them. In a migration they tune the runner's connection for a few seconds and reach the application never — and synchronous=OFF removes durability for exactly the connection doing the schema change.",
+  example: "PRAGMA synchronous = OFF;\nPRAGMA mmap_size = 268435456;\nALTER TABLE orders ADD COLUMN region TEXT;",
+  fix: {
+    description: "Set connection pragmas where connections are opened, in the application, so every connection gets them. Leave migrations to the schema.",
+    example: "ALTER TABLE orders ADD COLUMN region TEXT;\n-- application connection setup: PRAGMA synchronous = NORMAL; PRAGMA mmap_size = 268435456;",
+  },
+  verified: true, // SQLite docs, PRAGMA synchronous / cache_size / temp_store / mmap_size / busy_timeout: each applies to the current connection only. Re-proven across two connections in test/claims.test.ts.
+};
+
+/** Every SL meta, in corpus order. */
+export const sqliteMetas: readonly RuleMeta[] = [
+  sl001Meta, sl002Meta, sl003Meta, sl004Meta, sl005Meta, sl006Meta, sl007Meta, sl008Meta, sl009Meta,
+  sl010Meta, sl011Meta, sl012Meta, sl013Meta, sl014Meta, sl015Meta, sl016Meta, sl017Meta, sl018Meta, sl019Meta,
+  sl020Meta, sl021Meta, sl022Meta, sl023Meta, sl024Meta, sl025Meta, sl026Meta, sl027Meta, sl028Meta, sl029Meta, sl030Meta,
+  sl031Meta, sl032Meta, sl033Meta, sl034Meta, sl035Meta,
+];
+
+export const SQLITE_RULE_IDS: ReadonlySet<string> = new Set(sqliteMetas.map((meta) => meta.id));