Make SetMeta transactional for #1753

Author: Widthdom

DEVELOPER_GUIDE.md

@@ -157,6 +157,16 @@ Incremental refreshes that mutate `fts_chunks` increment `codeindex_meta.fts_inc
 
 Successful writer sessions attempt `PRAGMA wal_checkpoint(TRUNCATE)` before closing a writable `DbContext`, so large WAL files are reclaimed after index, backfill, optimize, prune, and other DB-writing commands. `cdidx db schema [--json]` dumps `sqlite_master` entries plus `PRAGMA user_version` for schema inspection, and `cdidx db prune --dry-run|--apply [--json]` counts or deletes orphaned `symbol_references`, `reference_lines`, and `symbols` rows before running `PRAGMA optimize` on apply.
 
+### Metadata invariants
+
+`DbWriter.SetMeta` participates in the caller's writer transaction when one is
+active. When no writer transaction is active, it wraps the metadata UPSERT in a
+SQLite savepoint so standalone stamps still have a commit boundary and calls
+from raw SQL transactions do not attempt a nested `BEGIN`. Dependent metadata
+and row rewrites that must succeed or fail together should be placed inside the
+same `DbWriter.BeginTransaction()` scope; do not stamp readiness or schema
+trust metadata before the dependent rows are written.
+
 ### Extending the indexer
 
 Out-of-tree post-extraction hooks can implement `CodeIndex.Indexer.Hooks.IPostExtractionHook` in a `.dll` placed under `~/.config/cdidx/hooks/` (or the directory named by `CDIDX_HOOKS_DIR`). Hook assemblies are discovered in path order. Each concrete hook type is instantiated with a public parameterless constructor, then called after built-in symbol extraction and again after built-in reference extraction, before rows are persisted. Hooks receive a `FileContext` plus mutable `IList<SymbolRecord>` / `IList<ReferenceRecord>` values, so they can annotate extracted records, add synthetic symbols, or add domain-specific references.

changelog.d/unreleased/1753.fixed.md

@@ -0,0 +1,17 @@
+---
+category: fixed
+issues:
+  - 1753
+affected:
+  - src/CodeIndex/Database/DbWriter.cs
+  - tests/CodeIndex.Tests/DatabaseTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Made metadata stamps participate in transaction boundaries (#1753)** — `SetMeta` now joins writer transactions or uses a SQLite savepoint for standalone writes so metadata and dependent rows can roll back together.
+
+## 日本語
+
+- **metadata stamp が transaction 境界に参加するようにしました (#1753)** — `SetMeta` は writer transaction に参加し、単独書き込みでは SQLite savepoint を使うため、metadata と依存 row をまとめて rollback できます。

src/CodeIndex/Database/DbWriter.cs

@@ -3025,7 +3025,30 @@ public void SetMeta(string key, string? value)
         if (!HasMetaTable())
             return;
 
+        if (!IsInTransaction())
+        {
+            Execute("SAVEPOINT set_meta_atomic");
+            try
+            {
+                SetMetaCore(key, value);
+                Execute("RELEASE SAVEPOINT set_meta_atomic");
+            }
+            catch
+            {
+                try { Execute("ROLLBACK TO SAVEPOINT set_meta_atomic"); } catch (SqliteException) { /* best effort */ }
+                try { Execute("RELEASE SAVEPOINT set_meta_atomic"); } catch (SqliteException) { /* best effort */ }
+                throw;
+            }
+            return;
+        }
+
+        SetMetaCore(key, value);
+    }
+
+    private void SetMetaCore(string key, string? value)
+    {
         using var cmd = _conn.CreateCommand();
+        cmd.Transaction = _activeTransaction;
         cmd.CommandText = @"INSERT INTO codeindex_meta (key, value) VALUES (@key, @value)
                             ON CONFLICT(key) DO UPDATE SET value = excluded.value";
         cmd.Parameters.AddWithValue("@key", key);

tests/CodeIndex.Tests/DatabaseTests.cs

@@ -2429,6 +2429,45 @@ public void DbContext_NewDatabaseRestrictsFileModeOnPosix()
         Assert.Equal("0600", DbContext.GetUnixFileModeString(_dbPath));
     }
 
+    [Fact]
+    public void SetMeta_InsideWriterTransaction_RollsBackWithDependentRows_Issue1753()
+    {
+        using (var transaction = _writer.BeginTransaction())
+        {
+            _writer.SetMeta("schema_phase", "new");
+            _writer.UpsertFile(new FileRecord
+            {
+                Path = "src/partial.cs",
+                Lang = "csharp",
+                Size = 12,
+                Lines = 1,
+                Modified = new DateTime(2026, 5, 31, 0, 0, 0, DateTimeKind.Utc),
+                Checksum = "partial",
+            });
+        }
+
+        Assert.Null(ReadMeta("schema_phase"));
+        Assert.False(_writer.HasFileAtPath("src/partial.cs"));
+    }
+
+    [Fact]
+    public void SetMeta_InsideRawSqlTransaction_UsesSavepointWithoutNestedBegin_Issue1753()
+    {
+        ExecuteNonQuery(_db.Connection, "BEGIN IMMEDIATE");
+        try
+        {
+            _writer.SetMeta("raw_phase", "new");
+            ExecuteNonQuery(_db.Connection, "ROLLBACK");
+        }
+        catch
+        {
+            ExecuteNonQuery(_db.Connection, "ROLLBACK");
+            throw;
+        }
+
+        Assert.Null(ReadMeta("raw_phase"));
+    }
+
     private void DeleteDbPath()
     {
         DeleteDbFiles(_dbPath);
@@ -2476,6 +2515,14 @@ private string ExecuteScalarString(string sql)
     private long ExecuteScalarLong(string sql)
         => ExecuteScalarLong(_db.Connection, sql);
 
+    private string? ReadMeta(string key)
+    {
+        using var cmd = _db.Connection.CreateCommand();
+        cmd.CommandText = "SELECT value FROM codeindex_meta WHERE key = @key";
+        cmd.Parameters.AddWithValue("@key", key);
+        return cmd.ExecuteScalar() as string;
+    }
+
     private static long ExecuteScalarLong(SqliteConnection connection, string sql)
     {
         using var cmd = connection.CreateCommand();