trekoon 0.3.5 → 0.3.7

package/src/domain/tracker-domain.ts

@@ -123,6 +123,19 @@ interface ResolvedCompactEntity {
   readonly kind: "task" | "subtask";
 }
 
+interface TaskDeletionPlan {
+  readonly subtaskIds: readonly string[];
+  readonly touchingDependencies: readonly DependencyRecord[];
+}
+
+function chunkValues<T>(values: readonly T[], chunkSize: number): T[][] {
+  const chunks: T[][] = [];
+  for (let offset = 0; offset < values.length; offset += chunkSize) {
+    chunks.push([...values.slice(offset, offset + chunkSize)]);
+  }
+  return chunks;
+}
+
 function assertNonEmpty(field: string, value: string | undefined | null): string {
   const normalized: string = (value ?? "").trim();
   if (!normalized) {
@@ -525,8 +538,24 @@ export class TrackerDomain {
   }
 
   deleteTask(id: string): void {
-    this.getTaskOrThrow(id);
-    this.#db.query("DELETE FROM tasks WHERE id = ?;").run(id);
+    const normalizedTaskId: string = assertNonEmpty("id", id);
+    this.getTaskOrThrow(normalizedTaskId);
+
+    const plan = this.planTaskDeletion(normalizedTaskId);
+    for (const dependencyIdChunk of chunkValues(
+      plan.touchingDependencies.map((dependency) => dependency.id),
+      SQLITE_MAX_VARIABLES,
+    )) {
+      const placeholders = dependencyIdChunk.map(() => "?").join(", ");
+      this.#db.query(`DELETE FROM dependencies WHERE id IN (${placeholders});`).run(...dependencyIdChunk);
+    }
+
+    for (const subtaskIdChunk of chunkValues(plan.subtaskIds, SQLITE_MAX_VARIABLES)) {
+      const placeholders = subtaskIdChunk.map(() => "?").join(", ");
+      this.#db.query(`DELETE FROM subtasks WHERE id IN (${placeholders});`).run(...subtaskIdChunk);
+    }
+
+    this.#db.query("DELETE FROM tasks WHERE id = ?;").run(normalizedTaskId);
   }
 
   createSubtask(
@@ -761,9 +790,57 @@ export class TrackerDomain {
 
   deleteSubtask(id: string): void {
     this.getSubtaskOrThrow(id);
+    this.#db.query("DELETE FROM dependencies WHERE source_id = ? OR depends_on_id = ?;").run(id, id);
     this.#db.query("DELETE FROM subtasks WHERE id = ?;").run(id);
   }
 
+  listDependenciesTouchingNode(nodeId: string): readonly DependencyRecord[] {
+    const normalizedNodeId: string = assertNonEmpty("nodeId", nodeId);
+    this.resolveNodeKind(normalizedNodeId);
+
+    const rows = this.#db
+      .query(
+        "SELECT id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at FROM dependencies WHERE source_id = ? OR depends_on_id = ? ORDER BY created_at ASC, id ASC;",
+      )
+      .all(normalizedNodeId, normalizedNodeId) as DependencyRow[];
+
+    return rows.map(mapDependency);
+  }
+
+  planTaskDeletion(taskId: string): TaskDeletionPlan {
+    const normalizedTaskId: string = assertNonEmpty("taskId", taskId);
+    this.getTaskOrThrow(normalizedTaskId);
+
+    const subtaskRows = this.#db
+      .query("SELECT id FROM subtasks WHERE task_id = ? ORDER BY created_at ASC, id ASC;")
+      .all(normalizedTaskId) as Array<{ id: string }>;
+    const subtaskIds: string[] = subtaskRows.map((row) => row.id);
+    const nodeIds: string[] = [normalizedTaskId, ...subtaskIds];
+    const dependencyRows: DependencyRow[] = [];
+    const nodeIdChunks = chunkValues(nodeIds, Math.floor(SQLITE_MAX_VARIABLES / 2));
+    for (const nodeIdChunk of nodeIdChunks) {
+      const placeholders = nodeIdChunk.map(() => "?").join(", ");
+      const rows = this.#db
+        .query(
+          `SELECT id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at
+           FROM dependencies
+           WHERE source_id IN (${placeholders}) OR depends_on_id IN (${placeholders})
+           ORDER BY created_at ASC, id ASC;`,
+        )
+        .all(...nodeIdChunk, ...nodeIdChunk) as DependencyRow[];
+      dependencyRows.push(...rows);
+    }
+
+    const rows: DependencyRow[] = [...new Map(dependencyRows.map((row) => [row.id, row])).values()].sort(
+      (left, right) => left.created_at - right.created_at || left.id.localeCompare(right.id),
+    );
+
+    return {
+      subtaskIds,
+      touchingDependencies: rows.map(mapDependency),
+    };
+  }
+
   buildEpicTree(epicId: string): EpicTree {
     const epic: EpicRecord = this.getEpicOrThrow(epicId);
     const tasks: readonly TaskRecord[] = this.listTasks(epicId);
@@ -804,7 +881,7 @@ export class TrackerDomain {
 
   buildTaskTreeDetailed(taskId: string): TaskTreeDetailed {
     const task: TaskRecord = this.getTaskOrThrow(taskId);
-    const subtasks: readonly SubtaskRecord[] = this.listSubtasks(task.id);
+    const subtasks: readonly SubtaskRecord[] = this.listSubtasksByTaskIds([task.id]).get(task.id) ?? [];
 
     return {
       id: task.id,
@@ -825,13 +902,27 @@ export class TrackerDomain {
   buildEpicTreeDetailed(epicId: string): EpicTreeDetailed {
     const epic: EpicRecord = this.getEpicOrThrow(epicId);
     const tasks: readonly TaskRecord[] = this.listTasks(epic.id);
+    const subtasksByTaskId = this.listSubtasksByTaskIds(tasks.map((task) => task.id));
 
     return {
       id: epic.id,
       title: epic.title,
       description: epic.description,
       status: epic.status,
-      tasks: tasks.map((task) => this.buildTaskTreeDetailed(task.id)),
+      tasks: tasks.map((task) => ({
+        id: task.id,
+        epicId: task.epicId,
+        title: task.title,
+        description: task.description,
+        status: task.status,
+        subtasks: (subtasksByTaskId.get(task.id) ?? []).map((subtask) => ({
+          id: subtask.id,
+          taskId: subtask.taskId,
+          title: subtask.title,
+          description: subtask.description,
+          status: subtask.status,
+        })),
+      })),
     };
   }
 
@@ -1124,6 +1215,76 @@ export class TrackerDomain {
     return rows.map(mapDependency);
   }
 
+  listDependenciesBySourceIds(sourceIds: readonly string[]): Map<string, readonly DependencyRecord[]> {
+    const dependencyMap = new Map<string, DependencyRecord[]>();
+
+    if (sourceIds.length === 0) {
+      return dependencyMap;
+    }
+
+    const normalizedIds = sourceIds.map((sourceId) => assertNonEmpty("sourceId", sourceId));
+    for (const sourceId of normalizedIds) {
+      this.resolveNodeKind(sourceId);
+      dependencyMap.set(sourceId, []);
+    }
+
+    for (let offset = 0; offset < normalizedIds.length; offset += SQLITE_MAX_VARIABLES) {
+      const chunkIds = normalizedIds.slice(offset, offset + SQLITE_MAX_VARIABLES);
+      const inPlaceholders: string = chunkIds.map(() => "?").join(", ");
+      const rows = this.#db
+        .query(
+          `SELECT id, source_id, source_kind, depends_on_id, depends_on_kind, created_at, updated_at
+           FROM dependencies
+           WHERE source_id IN (${inPlaceholders})
+           ORDER BY created_at ASC, id ASC;`,
+        )
+        .all(...chunkIds) as DependencyRow[];
+
+      for (const row of rows) {
+        const existing = dependencyMap.get(row.source_id) ?? [];
+        existing.push(mapDependency(row));
+        dependencyMap.set(row.source_id, existing);
+      }
+    }
+
+    return dependencyMap;
+  }
+
+  listSubtasksByTaskIds(taskIds: readonly string[]): Map<string, readonly SubtaskRecord[]> {
+    const subtaskMap = new Map<string, SubtaskRecord[]>();
+
+    if (taskIds.length === 0) {
+      return subtaskMap;
+    }
+
+    const normalizedIds = taskIds.map((taskId) => assertNonEmpty("taskId", taskId));
+    for (const taskId of normalizedIds) {
+      this.getTaskOrThrow(taskId);
+      subtaskMap.set(taskId, []);
+    }
+
+    for (let offset = 0; offset < normalizedIds.length; offset += SQLITE_MAX_VARIABLES) {
+      const chunkIds = normalizedIds.slice(offset, offset + SQLITE_MAX_VARIABLES);
+      const inPlaceholders: string = chunkIds.map(() => "?").join(", ");
+      const rows = this.#db
+        .query(
+          `SELECT id, task_id, title, description, status, owner, created_at, updated_at
+           FROM subtasks
+           WHERE task_id IN (${inPlaceholders})
+           ORDER BY created_at ASC, id ASC;`,
+        )
+        .all(...chunkIds) as SubtaskRow[];
+
+      for (const row of rows) {
+        const existing = subtaskMap.get(row.task_id) ?? [];
+        existing.push(mapSubtask(row));
+        subtaskMap.set(row.task_id, existing);
+      }
+    }
+
+    return subtaskMap;
+  }
+
   /**
    * Resolves dependency statuses for multiple tasks using a single prepared
    * statement executed once per task ID.  This avoids the previous N+1 pattern
@@ -1646,6 +1807,9 @@ export class TrackerDomain {
     const dependencyTargetsBySource = new Map<string, Set<string>>();
     const dependents = new Map<string, Set<string>>();
     const indegree = new Map<string, number>();
+    const dependencyMap = this.listDependenciesBySourceIds(
+      changes.filter((change) => change.kind === "task" || change.kind === "subtask").map((change) => change.id),
+    );
 
     changes.forEach((change, index) => {
       indexById.set(change.id, index);
@@ -1656,7 +1820,7 @@ export class TrackerDomain {
         return;
       }
 
-      const dependencyTargets = new Set(this.listDependencies(change.id).map((dependency) => dependency.dependsOnId));
+      const dependencyTargets = new Set((dependencyMap.get(change.id) ?? []).map((dependency) => dependency.dependsOnId));
       dependencyTargetsBySource.set(change.id, dependencyTargets);
     });
 

package/src/storage/migrations.ts

@@ -72,11 +72,51 @@ const LOOKUP_INDEX_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
   "DROP INDEX IF EXISTS idx_dependencies_depends_on_kind;",
 ];
 
+const SYNC_SCALING_MIGRATION_UP_STATEMENTS: readonly string[] = [
+  "CREATE INDEX IF NOT EXISTS idx_events_branch_cursor ON events(git_branch, created_at, id);",
+  "CREATE INDEX IF NOT EXISTS idx_events_entity_branch_cursor ON events(entity_kind, entity_id, git_branch, created_at, id);",
+  "CREATE INDEX IF NOT EXISTS idx_conflicts_resolution_entity_field_id ON sync_conflicts(resolution, entity_id, field_name, id);",
+];
+
+const SYNC_SCALING_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_conflicts_resolution_entity_field_id;",
+  "DROP INDEX IF EXISTS idx_events_entity_branch_cursor;",
+  "DROP INDEX IF EXISTS idx_events_branch_cursor;",
+];
+
+const BOARD_IDEMPOTENCY_MIGRATION_UP_STATEMENTS: readonly string[] = [
+  `
+  CREATE TABLE IF NOT EXISTS board_idempotency_keys (
+    scope TEXT NOT NULL,
+    idempotency_key TEXT NOT NULL,
+    request_fingerprint TEXT NOT NULL,
+    state TEXT NOT NULL DEFAULT 'completed',
+    response_status INTEGER NOT NULL,
+    response_body TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (scope, idempotency_key)
+  );
+  `,
+  "CREATE INDEX IF NOT EXISTS idx_board_idempotency_created_at ON board_idempotency_keys(created_at);",
+];
+
+const BOARD_IDEMPOTENCY_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_board_idempotency_created_at;",
+  "DROP TABLE IF EXISTS board_idempotency_keys;",
+];
+
 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);
 }
 
+function tableExists(db: Database, tableName: string): boolean {
+  const row = db
+    .query("SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name = ?;")
+    .get(tableName) as { count: number } | null;
+  return (row?.count ?? 0) > 0;
+}
+
 function migrateWorktreeScopedSyncMetadata(db: Database): void {
   if (!tableHasColumn(db, "git_context", "metadata_scope")) {
     db.exec("ALTER TABLE git_context ADD COLUMN metadata_scope TEXT NOT NULL DEFAULT 'worktree';");
@@ -109,6 +149,32 @@ function migrateWorktreeScopedSyncMetadata(db: Database): void {
   );
 }
 
+function migrateBoardIdempotencyState(db: Database): void {
+  if (!tableExists(db, "board_idempotency_keys")) {
+    return;
+  }
+
+  if (!tableHasColumn(db, "board_idempotency_keys", "state")) {
+    db.exec("ALTER TABLE board_idempotency_keys ADD COLUMN state TEXT NOT NULL DEFAULT 'completed';");
+    db.exec("UPDATE board_idempotency_keys SET state = 'completed' WHERE state IS NULL OR state = ''; ");
+    return;
+  }
+
+  const row = db
+    .query(
+      `
+      SELECT COUNT(*) AS count
+      FROM board_idempotency_keys
+      WHERE state IS NULL OR state = '';
+      `,
+    )
+    .get() as { count: number } | null;
+
+  if ((row?.count ?? 0) > 0) {
+    db.exec("UPDATE board_idempotency_keys SET state = 'completed' WHERE state IS NULL OR state = ''; ");
+  }
+}
+
 interface Migration {
   readonly version: number;
   readonly name: string;
@@ -265,6 +331,34 @@ const MIGRATIONS: readonly Migration[] = [
       }
     },
   },
+  {
+    version: 8,
+    name: "0008_sync_scaling_indexes",
+    up(db: Database): void {
+      for (const statement of SYNC_SCALING_MIGRATION_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of SYNC_SCALING_MIGRATION_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+  {
+    version: 9,
+    name: "0009_board_idempotency_storage",
+    up(db: Database): void {
+      for (const statement of BOARD_IDEMPOTENCY_MIGRATION_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of BOARD_IDEMPOTENCY_MIGRATION_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
 ];
 
 function migrationTableExists(db: Database): boolean {
@@ -455,6 +549,7 @@ export function migrateDatabase(db: Database): void {
   // This reduces startup lock contention while keeping the explicit
   // transactional migration path for non-current/legacy schemas.
   if (isSchemaCurrentFastPath(db, latestVersion)) {
+    migrateBoardIdempotencyState(db);
     return;
   }
 
@@ -472,12 +567,15 @@ export function migrateDatabase(db: Database): void {
       migration.up(db);
       recordMigration(db, migration);
     }
+
+    migrateBoardIdempotencyState(db);
   });
 }
 
 export function describeMigrations(db: Database): MigrationStatus {
   ensureMigrationTable(db);
   ensureMigrationVersionColumn(db);
+  migrateBoardIdempotencyState(db);
   validateMigrationPlan();
 
   const appliedRows: AppliedMigrationRow[] = listAppliedMigrations(db);

package/src/storage/path.ts

@@ -72,6 +72,8 @@ export interface StoragePathDiagnostics {
   readonly errors: readonly StoragePathIssue[];
 }
 
+const storagePathCache: Map<string, StoragePaths> = new Map();
+
 function resolveGitPath(workingDirectory: string, argument: "--git-common-dir" | "--show-toplevel"): string | null {
   const result = spawnSync("git", ["rev-parse", argument], {
     cwd: workingDirectory,
@@ -93,6 +95,11 @@ function resolveGitPath(workingDirectory: string, argument: "--git-common-dir" |
 
 export function resolveStoragePaths(workingDirectory: string = process.cwd()): StoragePaths {
   const invocationCwd: string = resolve(workingDirectory);
+  const cachedPaths: StoragePaths | undefined = storagePathCache.get(invocationCwd);
+  if (cachedPaths) {
+    return cachedPaths;
+  }
+
   const worktreeRoot: string = resolveGitPath(invocationCwd, "--show-toplevel") ?? invocationCwd;
   const repoCommonDirRaw: string | null = resolveGitPath(invocationCwd, "--git-common-dir");
   const repoCommonDir: string | null = repoCommonDirRaw ? realpathSync(repoCommonDirRaw) : null;
@@ -148,7 +155,7 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
     errors: [],
   };
 
-  return {
+  const storagePaths: StoragePaths = {
     invocationCwd,
     storageMode,
     repoCommonDir,
@@ -161,4 +168,8 @@ export function resolveStoragePaths(workingDirectory: string = process.cwd()): S
     boardManifestFile,
     diagnostics,
   };
+
+  storagePathCache.set(invocationCwd, storagePaths);
+
+  return storagePaths;
 }

package/src/storage/schema.ts

@@ -1,4 +1,4 @@
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `PRAGMA foreign_keys = ON;`,
@@ -115,10 +115,26 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
     version INTEGER NOT NULL DEFAULT 1
   );
   `,
+  `
+  CREATE TABLE IF NOT EXISTS board_idempotency_keys (
+    scope TEXT NOT NULL,
+    idempotency_key TEXT NOT NULL,
+    request_fingerprint TEXT NOT NULL,
+    state TEXT NOT NULL DEFAULT 'completed',
+    response_status INTEGER NOT NULL,
+    response_body TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (scope, idempotency_key)
+  );
+  `,
   `CREATE INDEX IF NOT EXISTS idx_tasks_epic_id ON tasks(epic_id);`,
   `CREATE INDEX IF NOT EXISTS idx_subtasks_task_id ON subtasks(task_id);`,
   `CREATE INDEX IF NOT EXISTS idx_events_entity ON events(entity_kind, entity_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_events_branch_cursor ON events(git_branch, created_at, id);`,
+  `CREATE INDEX IF NOT EXISTS idx_events_entity_branch_cursor ON events(entity_kind, entity_id, git_branch, created_at, id);`,
   `CREATE INDEX IF NOT EXISTS idx_git_context_scope_path ON git_context(metadata_scope, worktree_path);`,
   `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_board_idempotency_created_at ON board_idempotency_keys(created_at);`,
 ];

package/src/storage/worktree-recovery.ts

@@ -36,6 +36,7 @@ export interface WorktreeRecoveryDiagnostics {
 
 interface WorktreeRecoveryOptions {
   readonly applyRecovery?: boolean;
+  readonly worktreeRoots?: readonly string[];
 }
 
 function readGitLines(workingDirectory: string, args: readonly string[]): string[] {
@@ -89,14 +90,18 @@ function listWorktreeRoots(paths: StoragePaths): string[] {
   return [...worktreeRoots];
 }
 
-function listTrackedStorageFiles(paths: StoragePaths): string[] {
+function resolveRecoveryWorktreeRoots(paths: StoragePaths, options: WorktreeRecoveryOptions): readonly string[] {
+  return options.worktreeRoots ?? listWorktreeRoots(paths);
+}
+
+function listTrackedStorageFiles(paths: StoragePaths, worktreeRoots: readonly string[]): string[] {
   if (paths.repoCommonDir === null) {
     return [];
   }
 
   const trackedFiles = new Set<string>();
 
-  for (const worktreeRoot of listWorktreeRoots(paths)) {
+  for (const worktreeRoot of worktreeRoots) {
     for (const entry of readGitLines(worktreeRoot, ["ls-files", "--cached", "--", ".trekoon"])) {
       trackedFiles.add(resolve(worktreeRoot, entry));
     }
@@ -105,10 +110,10 @@ function listTrackedStorageFiles(paths: StoragePaths): string[] {
   return [...trackedFiles].sort();
 }
 
-function listLegacyDatabaseFiles(paths: StoragePaths): string[] {
+function listLegacyDatabaseFiles(paths: StoragePaths, worktreeRoots: readonly string[]): string[] {
   const files = new Set<string>();
 
-  for (const worktreeRoot of listWorktreeRoots(paths)) {
+  for (const worktreeRoot of worktreeRoots) {
     const legacyDatabaseFile: string = resolveLegacyWorktreeDatabaseFile(worktreeRoot);
     if (legacyDatabaseFile === paths.databaseFile || !existsSync(legacyDatabaseFile)) {
       continue;
@@ -278,8 +283,9 @@ export function inspectWorktreeDatabaseState(
   options: WorktreeRecoveryOptions = {},
 ): WorktreeRecoveryDiagnostics {
   const applyRecovery: boolean = options.applyRecovery ?? false;
-  const trackedStorageFiles: string[] = listTrackedStorageFiles(paths);
-  const legacyDatabaseFiles: string[] = listLegacyDatabaseFiles(paths);
+  const worktreeRoots: readonly string[] = resolveRecoveryWorktreeRoots(paths, options);
+  const trackedStorageFiles: string[] = listTrackedStorageFiles(paths, worktreeRoots);
+  const legacyDatabaseFiles: string[] = listLegacyDatabaseFiles(paths, worktreeRoots);
 
   if (trackedStorageFiles.length > 0) {
     throw new DomainError({

package/src/sync/branch-db.ts

@@ -55,6 +55,15 @@ export function assertValidSourceRef(workingDirectory: string, sourceRef: string
 }
 
 export function queryBranchEventsSince(db: Database, branch: string, cursorToken: string): BranchEventRow[] {
+  return queryBranchEventsSinceBatch(db, branch, cursorToken);
+}
+
+export function queryBranchEventsSinceBatch(
+  db: Database,
+  branch: string,
+  cursorToken: string,
+  limit: number = 250,
+): BranchEventRow[] {
   const cursor = parseCursorToken(cursorToken);
 
   return db
@@ -67,13 +76,15 @@ export function queryBranchEventsSince(db: Database, branch: string, cursorToken
           created_at > @createdAt
           OR (created_at = @createdAt AND id > @id)
         )
-      ORDER BY created_at ASC, id ASC;
+      ORDER BY created_at ASC, id ASC
+      LIMIT @limit;
       `,
     )
     .all({
       "@branch": branch,
       "@createdAt": cursor.createdAt,
       "@id": cursor.id ?? "",
+      "@limit": limit,
     }) as BranchEventRow[];
 }
 

package/src/sync/event-writes.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 
 import { type Database } from "bun:sqlite";
 
-import { persistGitContext, resolveGitContext } from "./git-context";
+import { persistGitContext, resolveGitContext, type ResolvedGitContext } from "./git-context";
 
 interface EventRecordInput {
   readonly entityKind: string;
@@ -11,6 +11,13 @@ interface EventRecordInput {
   readonly fields: Record<string, unknown>;
 }
 
+interface EventWriteContext {
+  readonly git: ResolvedGitContext;
+  nextTimestamp: number;
+}
+
+const transactionEventContexts: WeakMap<Database, EventWriteContext> = new WeakMap();
+
 export function nextEventTimestamp(db: Database): number {
   const now: number = Date.now();
   const latestEvent = db
@@ -31,16 +38,43 @@ export function nextEventTimestamp(db: Database): number {
   return Math.max(now, latestEvent.created_at + 1);
 }
 
-/** Append a single event to the events table with git context. Returns void (event ID is not exposed). */
+export function withTransactionEventContext<T>(db: Database, cwd: string, fn: () => T): T {
+  const existingContext: EventWriteContext | undefined = transactionEventContexts.get(db);
+  if (existingContext) {
+    return fn();
+  }
+
+  const nextTimestamp: number = nextEventTimestamp(db);
+  const git: ResolvedGitContext = resolveGitContext(cwd, nextTimestamp);
+  const context: EventWriteContext = {
+    git,
+    nextTimestamp,
+  };
+  transactionEventContexts.set(db, context);
+
+  try {
+    return fn();
+  } finally {
+    transactionEventContexts.delete(db);
+  }
+}
+
+/** Append a single event to the events table with git context. Returns the event ID. */
 export function appendEventWithGitContext(
   db: Database,
   cwd: string,
   input: EventRecordInput,
-): void {
-  const git = resolveGitContext(cwd);
-  persistGitContext(db, git);
+): string {
+  const context: EventWriteContext | undefined = transactionEventContexts.get(db);
+  const now: number = context?.nextTimestamp ?? nextEventTimestamp(db);
+  const git: ResolvedGitContext = context?.git ?? resolveGitContext(cwd, now);
+  const eventId: string = randomUUID();
 
-  const now: number = nextEventTimestamp(db);
+  persistGitContext(db, git, now);
+
+  if (context) {
+    context.nextTimestamp += 1;
+  }
 
   db.query(
     `
@@ -58,7 +92,7 @@ export function appendEventWithGitContext(
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1);
     `,
   ).run(
-    randomUUID(),
+    eventId,
     input.entityKind,
     input.entityId,
     input.operation,
@@ -68,4 +102,6 @@ export function appendEventWithGitContext(
     now,
     now,
   );
+
+  return eventId;
 }

package/src/sync/git-context.ts

@@ -3,6 +3,10 @@ import { type Database } from "bun:sqlite";
 import { resolveStoragePaths } from "../storage/path";
 import { type GitContextSnapshot } from "./types";
 
+export interface ResolvedGitContext extends GitContextSnapshot {
+  readonly persistedAt: number;
+}
+
 function runGit(args: readonly string[], cwd: string): string | null {
   const command = Bun.spawnSync({
     cmd: ["git", ...args],
@@ -19,7 +23,7 @@ function runGit(args: readonly string[], cwd: string): string | null {
   return output.length > 0 ? output : null;
 }
 
-export function resolveGitContext(cwd: string): GitContextSnapshot {
+export function resolveGitContext(cwd: string, persistedAt: number = Date.now()): ResolvedGitContext {
   const storagePaths = resolveStoragePaths(cwd);
   const branchName: string | null = runGit(["branch", "--show-current"], cwd);
   const headSha: string | null = runGit(["rev-parse", "HEAD"], cwd);
@@ -28,11 +32,11 @@ export function resolveGitContext(cwd: string): GitContextSnapshot {
     worktreePath: storagePaths.worktreeRoot,
     branchName,
     headSha,
+    persistedAt,
   };
 }
 
-export function persistGitContext(db: Database, git: GitContextSnapshot): void {
-  const now: number = Date.now();
+export function persistGitContext(db: Database, git: GitContextSnapshot, persistedAt: number = Date.now()): void {
 
   db.query(
     `
@@ -51,8 +55,8 @@ export function persistGitContext(db: Database, git: GitContextSnapshot): void {
       @worktreePath,
       @branchName,
       @headSha,
-      @now,
-      @now,
+      @persistedAt,
+      @persistedAt,
       1
     )
     ON CONFLICT(id) DO UPDATE SET
@@ -67,6 +71,6 @@ export function persistGitContext(db: Database, git: GitContextSnapshot): void {
     "@worktreePath": git.worktreePath,
     "@branchName": git.branchName,
     "@headSha": git.headSha,
-    "@now": now,
+    "@persistedAt": persistedAt,
   });
 }