trekoon 0.4.0 → 0.4.2

package/src/storage/migrations.ts

@@ -1,7 +1,27 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
 import { Database } from "bun:sqlite";
 
+import { DomainError } from "../domain/types";
 import { BASE_SCHEMA_STATEMENTS, SCHEMA_VERSION } from "./schema";
 
+const BACKUP_HINT = "Run 'trekoon migrate backup' to snapshot .trekoon/trekoon.db before any manual recovery.";
+
+function migrationDownUnsupported(migrationName: string, version: number): DomainError {
+  return new DomainError({
+    code: "migration_down_unsupported",
+    message:
+      `Migration ${migrationName} is irreversible: rolling back below version ${version} is not supported. ` +
+      `${BACKUP_HINT}`,
+    details: {
+      migrationName,
+      version,
+      backupCommand: "trekoon migrate backup",
+    },
+  });
+}
+
 const BASE_MIGRATION_VERSION = 1;
 const BASE_MIGRATION_NAME = `0001_base_schema_v${SCHEMA_VERSION}`;
 const LEGACY_BASE_MIGRATION_NAME_PATTERNS: readonly string[] = [
@@ -113,6 +133,57 @@ const BOARD_IDEMPOTENCY_RETENTION_INDEX_DOWN_STATEMENTS: readonly string[] = [
   "DROP INDEX IF EXISTS idx_board_idempotency_state_created_at;",
 ];
 
+const SYNC_CONFLICTS_SCOPE_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_sync_conflicts_scope_entity;",
+  "DROP INDEX IF EXISTS idx_sync_conflicts_scope_resolution;",
+];
+
+function migrateSyncConflictsScope(db: Database): void {
+  if (!tableExists(db, "sync_conflicts")) {
+    return;
+  }
+
+  if (!tableHasColumn(db, "sync_conflicts", "worktree_path")) {
+    db.exec("ALTER TABLE sync_conflicts ADD COLUMN worktree_path TEXT NOT NULL DEFAULT '';");
+  }
+
+  if (!tableHasColumn(db, "sync_conflicts", "current_branch")) {
+    db.exec("ALTER TABLE sync_conflicts ADD COLUMN current_branch TEXT NOT NULL DEFAULT '';");
+  }
+
+  // Backfill legacy rows from the most-recent git_context entry so existing
+  // pending conflicts remain reachable to the current worktree. Pre-existing
+  // rows from peer worktrees (rare in practice — pre-fix the bug erased
+  // them anyway) end up scoped to the current worktree's branch; this is a
+  // best-effort migration since we have no historical context to recover.
+  db.exec(`
+    UPDATE sync_conflicts
+    SET worktree_path = COALESCE(
+      NULLIF(worktree_path, ''),
+      (SELECT worktree_path FROM git_context ORDER BY updated_at DESC LIMIT 1),
+      ''
+    )
+    WHERE worktree_path IS NULL OR worktree_path = '';
+  `);
+
+  db.exec(`
+    UPDATE sync_conflicts
+    SET current_branch = COALESCE(
+      NULLIF(current_branch, ''),
+      (SELECT branch_name FROM git_context ORDER BY updated_at DESC LIMIT 1),
+      ''
+    )
+    WHERE current_branch IS NULL OR current_branch = '';
+  `);
+
+  db.exec(
+    "CREATE INDEX IF NOT EXISTS idx_sync_conflicts_scope_entity ON sync_conflicts(worktree_path, current_branch, entity_kind, entity_id);",
+  );
+  db.exec(
+    "CREATE INDEX IF NOT EXISTS idx_sync_conflicts_scope_resolution ON sync_conflicts(worktree_path, current_branch, resolution);",
+  );
+}
+
 function tableHasColumn(db: Database, tableName: string, columnName: string): boolean {
   const columns = db.query(`PRAGMA table_info(${tableName});`).all() as Array<{ name: string }>;
   return columns.some((column) => column.name === columnName);
@@ -266,12 +337,7 @@ const MIGRATIONS: readonly Migration[] = [
       migrateWorktreeScopedSyncMetadata(db);
     },
     down(_db: Database): void {
-      throw new Error(
-        "Migration 0004 (worktree_scoped_sync_metadata) is irreversible. " +
-        "It adds columns via ALTER TABLE that cannot be removed without " +
-        "reconstructing tables and risking data loss. " +
-        "Rollback below version 4 is not supported.",
-      );
+      throw migrationDownUnsupported("0004_worktree_scoped_sync_metadata", 4);
     },
   },
   {
@@ -298,11 +364,7 @@ const MIGRATIONS: readonly Migration[] = [
       db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_dependencies_edge ON dependencies (source_id, depends_on_id);");
     },
     down(_db: Database): void {
-      throw new Error(
-        "Migration 0005 (dependency_edge_integrity) is irreversible. " +
-        "It removes orphaned rows and deduplicates dependency edges. " +
-        "Rollback below version 5 is not supported.",
-      );
+      throw migrationDownUnsupported("0005_dependency_edge_integrity", 5);
     },
   },
   {
@@ -317,12 +379,7 @@ const MIGRATIONS: readonly Migration[] = [
       }
     },
     down(_db: Database): void {
-      throw new Error(
-        "Migration 0006 (add_owner_column) is irreversible. " +
-        "It adds columns via ALTER TABLE that cannot be removed without " +
-        "reconstructing tables and risking data loss. " +
-        "Rollback below version 6 is not supported.",
-      );
+      throw migrationDownUnsupported("0006_add_owner_column", 6);
     },
   },
   {
@@ -381,6 +438,22 @@ const MIGRATIONS: readonly Migration[] = [
       }
     },
   },
+  {
+    version: 11,
+    name: "0011_sync_conflicts_worktree_branch_scope",
+    up(db: Database): void {
+      migrateSyncConflictsScope(db);
+    },
+    down(db: Database): void {
+      // Dropping columns requires a table rewrite in SQLite (PRAGMA) — not
+      // strictly reversible without potential data loss. We drop the new
+      // indexes; the columns persist with their default empty-string values
+      // so a re-up no-ops cleanly.
+      for (const statement of SYNC_CONFLICTS_SCOPE_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
 ];
 
 function migrationTableExists(db: Database): boolean {
@@ -525,6 +598,243 @@ function recordMigration(db: Database, migration: Migration): void {
   );
 }
 
+/** Name of the marker file relative to the .trekoon storage directory. */
+const MIGRATION_VERSION_MARKER_FILENAME = "migration-version";
+
+/**
+ * On-disk marker payload. The legacy v1 format was a bare integer. v2 stores a
+ * JSON object so we can pin the marker to a content fingerprint of the DB
+ * (PRAGMA user_version) instead of relying on filesystem mtimes — which the
+ * old defensive check could not distinguish from a DB restored from a backup
+ * with an older user_version but a newer mtime.
+ */
+interface MarkerPayload {
+  readonly version: number;
+  readonly userVersion: number;
+}
+
+/**
+ * Derive the path to the migration-version marker file from the database
+ * connection's filename. Returns null for in-memory databases.
+ */
+function resolveMarkerPath(db: Database): string | null {
+  const dbFile: string = db.filename;
+  if (!dbFile || dbFile === ":memory:") {
+    return null;
+  }
+  return join(dirname(dbFile), MIGRATION_VERSION_MARKER_FILENAME);
+}
+
+/**
+ * Read `PRAGMA user_version` from the connection. SQLite stores this as a
+ * 32-bit signed integer in the database header — every restore-from-backup
+ * naturally carries the original `user_version` along with the bytes.
+ */
+function readUserVersion(db: Database): number {
+  const row = db.query("PRAGMA user_version;").get() as { user_version: number } | null;
+  return row?.user_version ?? 0;
+}
+
+/**
+ * Set `PRAGMA user_version`. Used as a content-stamp written inside the same
+ * transaction that applies (or rolls back) migrations so the DB header is
+ * always authoritative for the current schema state — independent of the
+ * sidecar marker file.
+ *
+ * NOTE: PRAGMA does not support parameter binding. The caller must pass an
+ * integer or a value that will throw at the SQL level otherwise.
+ */
+function setUserVersion(db: Database, version: number): void {
+  if (!Number.isInteger(version) || version < 0) {
+    throw new Error(`PRAGMA user_version must be a non-negative integer (got ${version}).`);
+  }
+  db.exec(`PRAGMA user_version = ${version};`);
+}
+
+/**
+ * Read the marker payload from disk. Falls back to parsing the legacy v1
+ * format (bare integer) so previously-installed markers still work without a
+ * cold reset.
+ */
+function readMarkerPayload(markerPath: string): MarkerPayload | null {
+  try {
+    if (!existsSync(markerPath)) {
+      return null;
+    }
+
+    const raw: string = readFileSync(markerPath, "utf8").trim();
+    if (raw.length === 0) {
+      return null;
+    }
+
+    if (raw.startsWith("{")) {
+      const parsed = JSON.parse(raw) as Partial<MarkerPayload>;
+      const version: number | undefined = parsed.version;
+      const userVersion: number | undefined = parsed.userVersion;
+      if (
+        typeof version !== "number" ||
+        !Number.isFinite(version) ||
+        version < 0 ||
+        typeof userVersion !== "number" ||
+        !Number.isFinite(userVersion) ||
+        userVersion < 0
+      ) {
+        return null;
+      }
+      return { version, userVersion };
+    }
+
+    // Legacy v1 format: bare integer. Treat it as having no fingerprint;
+    // returning userVersion: -1 forces canSkipProbeViaMarker to fall through
+    // to the slow path, which then rewrites the marker in v2 form.
+    const legacyVersion: number = parseInt(raw, 10);
+    if (!Number.isFinite(legacyVersion) || legacyVersion < 0) {
+      return null;
+    }
+    return { version: legacyVersion, userVersion: -1 };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the migration version stored in the marker file. Returns null when the
+ * file is absent, unreadable, or malformed. Kept for backwards-compatible
+ * test/inspection use; the in-process fast-path uses {@link readMarkerPayload}.
+ */
+export function readMigrationVersionMarker(db: Database): number | null {
+  const markerPath: string | null = resolveMarkerPath(db);
+  if (!markerPath) {
+    return null;
+  }
+
+  const payload: MarkerPayload | null = readMarkerPayload(markerPath);
+  return payload?.version ?? null;
+}
+
+interface WriteMarkerResult {
+  readonly written: boolean;
+  readonly skipped: boolean;
+}
+
+/**
+ * Internal marker writer that surfaces the outcome to callers. Writes
+ * atomically via temp + rename. Returns `{written:false}` on filesystem
+ * errors so callers (e.g. {@link rollbackDatabase}) can attempt a stale-marker
+ * cleanup instead of silently leaving a misleading hint on disk.
+ */
+function writeMarkerPayload(
+  db: Database,
+  payload: MarkerPayload,
+): WriteMarkerResult {
+  const markerPath: string | null = resolveMarkerPath(db);
+  if (!markerPath) {
+    return { written: false, skipped: true };
+  }
+
+  try {
+    mkdirSync(dirname(markerPath), { recursive: true });
+    const tmpPath = `${markerPath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(payload), "utf8");
+    renameSync(tmpPath, markerPath);
+    return { written: true, skipped: false };
+  } catch {
+    return { written: false, skipped: false };
+  }
+}
+
+/**
+ * Best-effort: remove a stale marker so the next cold start re-probes the
+ * schema. Used when a fresh marker write fails after a rollback (or other
+ * version-changing op) to avoid leaving the previous version's marker on disk
+ * pointing at a now-incorrect schema state.
+ */
+function unlinkMarkerIfExists(db: Database): void {
+  const markerPath: string | null = resolveMarkerPath(db);
+  if (!markerPath) {
+    return;
+  }
+  try {
+    if (existsSync(markerPath)) {
+      unlinkSync(markerPath);
+    }
+  } catch (error) {
+    // Defense-in-depth — the worst case is that the next cold start spends
+    // one extra schema probe noticing the marker mismatch. We surface the
+    // failure at warn level (System Hardening 0.4.2, finding 30) so that
+    // operators can spot recurring stale-marker issues without escalating
+    // a one-off cleanup failure to a hard error.
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `[trekoon] failed to unlink stale schema marker at ${markerPath}: ${message}`,
+    );
+  }
+}
+
+/**
+ * Write the migration version to the marker file atomically (temp + rename).
+ * Public, backwards-compatible signature. Reads the current PRAGMA user_version
+ * from the connection so fast-path consumers can verify the marker against the
+ * DB header on the next call.
+ */
+export function writeMigrationVersionMarker(db: Database, version: number): void {
+  const markerPath: string | null = resolveMarkerPath(db);
+  if (!markerPath) {
+    return;
+  }
+  const userVersion: number = readUserVersion(db);
+  writeMarkerPayload(db, { version, userVersion });
+}
+
+/**
+ * Determine whether the marker file allows skipping the schema probe query.
+ * Returns true only when:
+ *   1. The marker file exists, parses cleanly, and reports
+ *      `version === LATEST_MIGRATION_VERSION`.
+ *   2. The DB's PRAGMA user_version matches the marker's recorded user_version
+ *      AND equals `LATEST_MIGRATION_VERSION`.
+ *
+ * The user_version match is the load-bearing freshness check — replacing the
+ * previous mtime heuristic, which could not distinguish a DB restored from an
+ * older backup (older user_version, fresh mtime) from a healthy current DB.
+ * Restoring a backup brings the original user_version with the bytes, so the
+ * pragma check naturally fails over to the slow path even when the marker
+ * file is "newer" than the DB on disk.
+ */
+function canSkipProbeViaMarker(db: Database): boolean {
+  const markerPath: string | null = resolveMarkerPath(db);
+  if (!markerPath) {
+    return false;
+  }
+
+  try {
+    const payload: MarkerPayload | null = readMarkerPayload(markerPath);
+    if (!payload) {
+      return false;
+    }
+
+    if (payload.version !== LATEST_MIGRATION_VERSION) {
+      return false;
+    }
+
+    if (payload.userVersion !== LATEST_MIGRATION_VERSION) {
+      // Legacy v1 markers report userVersion: -1; force probe so the marker
+      // gets rewritten in v2 form.
+      return false;
+    }
+
+    const dbFile: string = db.filename;
+    if (!dbFile || !existsSync(dbFile)) {
+      return false;
+    }
+
+    const dbUserVersion: number = readUserVersion(db);
+    return dbUserVersion === payload.userVersion;
+  } catch {
+    return false;
+  }
+}
+
 function isSchemaCurrentFastPath(db: Database, latestVersion: number): boolean {
   if (latestVersion === 0 || !migrationTableExists(db) || !hasMigrationVersionColumn(db)) {
     return false;
@@ -567,12 +877,49 @@ export function migrateDatabase(db: Database): void {
 
   const latestVersion: number = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
 
-  // Fast path: avoid BEGIN EXCLUSIVE when schema is already current.
+  // Marker fast path: skip ALL probe queries when the persisted marker file
+  // records the latest version and is newer than the DB file. This saves the
+  // schema_migrations SELECT on warm CLI starts.
+  if (canSkipProbeViaMarker(db)) {
+    migrateBoardIdempotencyState(db);
+    return;
+  }
+
+  // Schema fast path: avoid BEGIN EXCLUSIVE when schema is already current.
   // This reduces startup lock contention while keeping the explicit
   // transactional migration path for non-current/legacy schemas.
   if (isSchemaCurrentFastPath(db, latestVersion)) {
     migrateBoardIdempotencyState(db);
-    return;
+
+    // Re-confirm the schema state under an EXCLUSIVE lock before stamping
+    // the DB header. Without the lock, a concurrent rollback in another
+    // process can interleave between the unlocked probe above and the
+    // setUserVersion call below, leaving PRAGMA user_version pointing at a
+    // higher version than schema_migrations actually reflects. If the
+    // recheck disagrees we bail to the slow migrate path which will
+    // re-apply any missing migrations transactionally.
+    let fastPathConfirmed = false;
+    runExclusive(db, (): void => {
+      if (currentVersion(db) !== latestVersion) {
+        return;
+      }
+      // Stamp the DB header inside the same exclusive transaction so the
+      // user_version cannot diverge from schema_migrations on commit.
+      // This also covers first runs after the v1 marker format upgrade and
+      // restored-from-backup DBs whose schema_migrations happens to match
+      // latest but whose user_version still trails.
+      setUserVersion(db, latestVersion);
+      fastPathConfirmed = true;
+    });
+
+    if (fastPathConfirmed) {
+      // Persist the marker so the next cold start can short-circuit. The
+      // marker is a sidecar hint — even if this write fails, the DB header
+      // (stamped inside the tx above) remains authoritative.
+      writeMigrationVersionMarker(db, latestVersion);
+      return;
+    }
+    // Disagreement: fall through to the slow path below.
   }
 
   runExclusive(db, (): void => {
@@ -594,7 +941,37 @@ export function migrateDatabase(db: Database): void {
       migration.up(db);
       recordMigration(db, migration);
     }
+
+    // Stamp the DB header inside the same exclusive transaction so the
+    // user_version cannot diverge from schema_migrations on commit.
+    setUserVersion(db, latestVersion);
   });
+
+  // Persist the new version so the next cold start can skip the probe.
+  writeMigrationVersionMarker(db, latestVersion);
+}
+
+export const LATEST_MIGRATION_VERSION: number = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+
+/**
+ * Read the highest applied migration version from a database without mutating
+ * it. Safe to call against a connection opened in `readonly: true` mode.
+ * Returns 0 when the schema_migrations table does not exist or has no rows.
+ */
+export function readCurrentMigrationVersionReadOnly(db: Database): number {
+  if (!migrationTableExists(db)) {
+    return 0;
+  }
+
+  if (!hasMigrationVersionColumn(db)) {
+    return 0;
+  }
+
+  const row = db
+    .query("SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations WHERE version IS NOT NULL;")
+    .get() as { version: number } | null;
+
+  return row?.version ?? 0;
 }
 
 export function describeMigrations(db: Database): MigrationStatus {
@@ -628,7 +1005,7 @@ export function rollbackDatabase(db: Database, targetVersion: number): RollbackS
     throw new Error("Rollback target version must be a non-negative integer.");
   }
 
-  return runExclusive(db, (): RollbackSummary => {
+  const summary: RollbackSummary = runExclusive(db, (): RollbackSummary => {
     ensureMigrationTable(db);
     ensureMigrationVersionColumn(db);
     validateMigrationPlan();
@@ -658,6 +1035,13 @@ export function rollbackDatabase(db: Database, targetVersion: number): RollbackS
       rolledBackMigrations.push(migration.name);
     }
 
+    // Stamp the DB header inside the rollback transaction so the
+    // user_version is authoritative for the post-rollback schema state. If
+    // the sidecar marker write below fails for any reason, the next
+    // canSkipProbeViaMarker() check will see a stale marker.userVersion and
+    // fall through to the slow probe path — no silent drift.
+    setUserVersion(db, targetVersion);
+
     return {
       fromVersion,
       toVersion: targetVersion,
@@ -665,4 +1049,22 @@ export function rollbackDatabase(db: Database, targetVersion: number): RollbackS
       rolledBackMigrations,
     };
   });
+
+  // Update the marker so the next start reflects the rolled-back version.
+  // If the write fails, attempt to delete the now-stale marker so a future
+  // cold start re-probes instead of trusting a marker that points at the
+  // pre-rollback version.
+  const markerPath: string | null = resolveMarkerPath(db);
+  if (markerPath) {
+    const userVersion: number = readUserVersion(db);
+    const markerResult: WriteMarkerResult = writeMarkerPayload(db, {
+      version: targetVersion,
+      userVersion,
+    });
+    if (!markerResult.written && !markerResult.skipped) {
+      unlinkMarkerIfExists(db);
+    }
+  }
+
+  return summary;
 }

package/src/storage/path.ts

@@ -74,6 +74,14 @@ export interface StoragePathDiagnostics {
 
 const storagePathCache: Map<string, StoragePaths> = new Map();
 
+/**
+ * Clear the process-level storage path cache.
+ * Intended for test isolation only — production code should never call this.
+ */
+export function clearStoragePathCache(): void {
+  storagePathCache.clear();
+}
+
 function resolveGitPath(workingDirectory: string, argument: "--git-common-dir" | "--show-toplevel"): string | null {
   const result = spawnSync("git", ["rev-parse", argument], {
     cwd: workingDirectory,

package/src/storage/schema.ts

@@ -112,7 +112,9 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
     resolution TEXT NOT NULL DEFAULT 'pending',
     created_at INTEGER NOT NULL,
     updated_at INTEGER NOT NULL,
-    version INTEGER NOT NULL DEFAULT 1
+    version INTEGER NOT NULL DEFAULT 1,
+    worktree_path TEXT NOT NULL DEFAULT '',
+    current_branch TEXT NOT NULL DEFAULT ''
   );
   `,
   `
@@ -136,6 +138,8 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `CREATE INDEX IF NOT EXISTS idx_sync_cursors_owner ON sync_cursors(owner_scope, owner_worktree_path, source_branch);`,
   `CREATE INDEX IF NOT EXISTS idx_conflicts_resolution ON sync_conflicts(resolution);`,
   `CREATE INDEX IF NOT EXISTS idx_conflicts_resolution_entity_field_id ON sync_conflicts(resolution, entity_id, field_name, id);`,
+  `CREATE INDEX IF NOT EXISTS idx_sync_conflicts_scope_entity ON sync_conflicts(worktree_path, current_branch, entity_kind, entity_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_sync_conflicts_scope_resolution ON sync_conflicts(worktree_path, current_branch, resolution);`,
   `CREATE INDEX IF NOT EXISTS idx_board_idempotency_created_at ON board_idempotency_keys(created_at);`,
   `CREATE INDEX IF NOT EXISTS idx_board_idempotency_state_created_at ON board_idempotency_keys(state, created_at);`,
 ];

package/src/sync/event-writes.ts

@@ -18,6 +18,14 @@ interface EventWriteContext {
 
 const transactionEventContexts: WeakMap<Database, EventWriteContext> = new WeakMap();
 
+/**
+ * Compute the next safe event timestamp INSIDE a write lock.
+ *
+ * Must only be called after BEGIN IMMEDIATE has been issued on `db`.
+ * Reading the max(created_at) while holding the write lock guarantees no
+ * concurrent writer can commit a higher timestamp between the read and the
+ * subsequent INSERT, preventing (created_at, id) collisions.
+ */
 export function nextEventTimestamp(db: Database): number {
   const now: number = Date.now();
   const latestEvent = db
@@ -38,22 +46,41 @@ export function nextEventTimestamp(db: Database): number {
   return Math.max(now, latestEvent.created_at + 1);
 }
 
-export function prepareEventWriteContext(db: Database, cwd: string): EventWriteContext {
-  const nextTimestamp: number = nextEventTimestamp(db);
-  const git: ResolvedGitContext = resolveGitContext(cwd, nextTimestamp);
-
-  return {
-    git,
-    nextTimestamp,
-  };
-}
-
-export function withTransactionEventContext<T>(db: Database, context: EventWriteContext, fn: () => T): T {
+/**
+ * Execute `fn` inside a transaction event context, computing the event
+ * timestamp AFTER the write lock is held (i.e. after BEGIN IMMEDIATE).
+ *
+ * The caller MUST resolve the git context BEFORE entering the write
+ * transaction and pass it in via `git`. This keeps the (potentially slow)
+ * `git branch` / `git rev-parse` subprocesses outside the SQLite write lock,
+ * so concurrent writers on a cold git-context cache do not serialize on
+ * subprocess invocations behind BEGIN IMMEDIATE.
+ *
+ * Only `nextEventTimestamp(db)` runs inside the lock — reading
+ * `MAX(created_at)` while the write lock is held is what guarantees no
+ * concurrent writer can commit a higher timestamp before our INSERT.
+ *
+ * If a context is already active for this database connection (nested call),
+ * `fn` is invoked directly so the outer context's monotonic counter is
+ * reused; the supplied `git` argument is ignored in that case.
+ *
+ * @param db   - The database connection that is already inside BEGIN IMMEDIATE.
+ * @param git  - Pre-resolved git context (resolved BEFORE the write lock).
+ * @param fn   - The transaction body to run.
+ */
+export function withTransactionEventContext<T>(db: Database, git: ResolvedGitContext, fn: () => T): T {
   const existingContext: EventWriteContext | undefined = transactionEventContexts.get(db);
   if (existingContext) {
     return fn();
   }
 
+  // Compute the timestamp NOW — the write lock is already held. The git
+  // context was resolved by the caller before BEGIN IMMEDIATE, so no
+  // subprocess invocations happen here.
+  const nextTimestamp: number = nextEventTimestamp(db);
+  const resolvedGit: ResolvedGitContext = { ...git, persistedAt: nextTimestamp };
+  const context: EventWriteContext = { git: resolvedGit, nextTimestamp };
+
   transactionEventContexts.set(db, context);
 
   try {