feat(db): add indexed uuid column to modules with backfill

engine/db/migrations_sql/003_add_uuid_column.sql

@@ -0,0 +1,17 @@
+-- 003_add_uuid_column.sql
+--
+-- Adds an explicit, indexed `uuid` column to the `modules` table.
+-- Backfills existing rows by extracting the trailing 8 hex chars of the
+-- generated id (`<prefix>_<slug>_<token_hex(4)>` per ModuleRepository._gen_id).
+--
+-- After this migration, server code that needs canonical UUID lookup
+-- (engine catalog, embed-bundle, drift hashes) does indexed equality
+-- queries against `uuid` instead of `LIKE '%_<8hex>'` string scans.
+
+ALTER TABLE modules ADD COLUMN uuid TEXT;
+
+UPDATE modules
+SET uuid = substr(id, -8)
+WHERE uuid IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_modules_uuid ON modules(uuid)

tests/engine/db/test_migrations.py

@@ -29,7 +29,7 @@ def test_migrate_records_version(tmp_path):
     migrate(conn)
     # Keep this assertion in sync with the highest-numbered migration in
     # ``engine/db/migrations_sql``.
-    assert current_version(conn) == 2
+    assert current_version(conn) == 3
     conn.close()
 
 
@@ -49,6 +49,59 @@ def test_modules_table_has_expected_columns(tmp_path):
     assert cols == {
         "id", "type", "name", "description", "category_id",
         "tags", "is_favorite", "payload", "version",
-        "created_at", "updated_at",
+        "created_at", "updated_at", "uuid",
     }
     conn.close()
+
+
+import sqlite3  # noqa: E402 — stdlib; placed here to keep patch minimal
+
+
+def test_003_adds_uuid_column_with_backfill_and_index(tmp_path):
+    """003_add_uuid_column.sql adds uuid column, backfills from id suffix,
+    and creates a unique index. Verified end-to-end against a real
+    sqlite3 connection so we catch syntax errors the runner ignores."""
+    db = tmp_path / "lib.db"
+    conn = sqlite3.connect(str(db))
+    conn.row_factory = sqlite3.Row
+
+    # Migrate to v002 first (current head before this plan), seed a row
+    # with the legacy schema (no uuid column).
+    from engine.db.migrations import _discover
+    pairs = _discover()
+    for version, sql_file in pairs:
+        if version >= 3:
+            break
+        with conn:
+            conn.executescript(sql_file.read_text())
+            conn.execute(
+                "INSERT OR IGNORE INTO migrations(version, applied_at) "
+                "VALUES (?, datetime('now'));",
+                (version,),
+            )
+    conn.execute(
+        "INSERT INTO modules(id, type, name, description, category_id, "
+        "tags, is_favorite, payload, version, created_at, updated_at) "
+        "VALUES ('wc_color_aabbccdd', 'wildcard', 'color', '', NULL, "
+        "'[]', 0, '{}', 1, datetime('now'), datetime('now'));"
+    )
+    conn.commit()
+
+    # Run full migrate (will pick up 003)
+    migrate(conn)
+
+    # Column exists
+    cols = {r["name"] for r in conn.execute("PRAGMA table_info(modules);")}
+    assert "uuid" in cols
+
+    # Backfill correct
+    row = conn.execute(
+        "SELECT uuid FROM modules WHERE id = 'wc_color_aabbccdd';"
+    ).fetchone()
+    assert row["uuid"] == "aabbccdd"
+
+    # Unique index present
+    idx = {r["name"] for r in conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='index';"
+    )}
+    assert "idx_modules_uuid" in idx