@optave/codegraph 3.9.0 → 3.9.2

package/src/cli/commands/batch.ts

@@ -1,26 +1,11 @@
 import fs from 'node:fs';
 import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
-import { BATCH_COMMANDS, multiBatchData, splitTargets } from '../../features/batch.js';
-import { batch } from '../../presentation/batch.js';
+import { BATCH_COMMANDS, splitTargets } from '../../features/batch.js';
+import { batchQuery } from '../../presentation/batch.js';
 import { ConfigError, toErrorMessage } from '../../shared/errors.js';
 import type { CommandDefinition } from '../types.js';
 
-interface MultiBatchItem {
-  command: string;
-  target: string;
-  opts?: Record<string, unknown>;
-}
-
-function isMultiBatch(targets: unknown[]): targets is MultiBatchItem[] {
-  return (
-    targets.length > 0 &&
-    typeof targets[0] === 'object' &&
-    targets[0] !== null &&
-    'command' in targets[0]
-  );
-}
-
 export const command: CommandDefinition = {
   name: 'batch <command> [targets...]',
   description: `Run a query against multiple targets in one call. Output is always JSON.\nValid commands: ${Object.keys(BATCH_COMMANDS).join(', ')}`,
@@ -69,18 +54,12 @@ export const command: CommandDefinition = {
       );
     }
 
-    const batchOpts = {
+    batchQuery(targets as Array<string | { command: string; target: string }>, opts.db, {
+      command,
       depth: opts.depth ? parseInt(opts.depth as string, 10) : undefined,
       file: opts.file,
       kind: opts.kind,
       noTests: ctx.resolveNoTests(opts),
-    };
-
-    if (isMultiBatch(targets)) {
-      const data = multiBatchData(targets as MultiBatchItem[], opts.db, batchOpts);
-      console.log(JSON.stringify(data, null, 2));
-    } else {
-      batch(command!, targets as string[], opts.db, batchOpts);
-    }
+    });
   },
 };

package/src/cli/commands/structure.ts

@@ -15,9 +15,29 @@ export const command: CommandDefinition = {
     ['--limit <number>', 'Max results to return'],
     ['--offset <number>', 'Skip N results (default: 0)'],
     ['--ndjson', 'Newline-delimited JSON output'],
+    ['--modules', 'Show module boundaries (directories with high cohesion)'],
+    ['--threshold <number>', 'Cohesion threshold for --modules (default: 0.3)'],
   ],
   async execute([dir], opts, ctx) {
-    const { structureData, formatStructure } = await import('../../presentation/structure.js');
+    const { structureData, formatStructure, moduleBoundariesData, formatModuleBoundaries } =
+      await import('../../presentation/structure.js');
+
+    if (opts.modules) {
+      const parsed = opts.threshold ? parseFloat(opts.threshold as string) : undefined;
+      if (parsed !== undefined && Number.isNaN(parsed)) {
+        console.error('Error: --threshold must be a number');
+        process.exitCode = 1;
+        return;
+      }
+      const data = moduleBoundariesData(opts.db, {
+        threshold: parsed,
+      });
+      if (!ctx.outputResult(data, 'modules', opts)) {
+        console.log(formatModuleBoundaries(data));
+      }
+      return;
+    }
+
     const qOpts = ctx.resolveQueryOpts(opts);
     const data = structureData(opts.db, {
       directory: dir,

package/src/db/connection.ts

@@ -109,7 +109,7 @@ function isProcessAlive(pid: number): boolean {
   }
 }
 
-function acquireAdvisoryLock(dbPath: string): void {
+export function acquireAdvisoryLock(dbPath: string): void {
   const lockPath = `${dbPath}.lock`;
   try {
     if (fs.existsSync(lockPath)) {
@@ -129,7 +129,7 @@ function acquireAdvisoryLock(dbPath: string): void {
   }
 }
 
-function releaseAdvisoryLock(lockPath: string): void {
+export function releaseAdvisoryLock(lockPath: string): void {
   try {
     const content = fs.readFileSync(lockPath, 'utf-8').trim();
     if (Number(content) === process.pid) {
@@ -311,6 +311,7 @@ export function openReadonlyOrFail(customPath?: string): BetterSqlite3Database {
   }
   const Database = getDatabase();
   const db = new Database(dbPath, { readonly: true }) as unknown as BetterSqlite3Database;
+  db.pragma('busy_timeout = 5000');
 
   warnOnVersionMismatch(() => {
     const row = db
@@ -359,7 +360,7 @@ function openRepoNative(customDbPath?: string): { repo: Repository; close(): voi
  */
 export function openRepo(
   customDbPath?: string,
-  opts: { repo?: Repository } = {},
+  opts: { repo?: Repository; engine?: 'native' | 'wasm' | 'auto' } = {},
 ): { repo: Repository; close(): void } {
   if (opts.repo != null) {
     if (!(opts.repo instanceof Repository)) {
@@ -370,15 +371,25 @@ export function openRepo(
     return { repo: opts.repo, close() {} };
   }
 
+  // Respect explicit engine selection: opts.engine > CODEGRAPH_ENGINE env > auto.
+  // This ensures --engine wasm and benchmark workers bypass the native path.
+  const engine = opts.engine || process.env.CODEGRAPH_ENGINE || 'auto';
+
   // Try native rusqlite path first (Phase 6.14)
-  if (isNativeAvailable()) {
+  if (engine !== 'wasm' && isNativeAvailable()) {
     try {
       return openRepoNative(customDbPath);
     } catch (e) {
       // Re-throw user-visible errors (e.g. DB not found) — only silently
       // fall back for native-engine failures (e.g. incompatible native binary).
       if (e instanceof DbError) throw e;
-      debug(`openRepo: native path failed, falling back to better-sqlite3: ${toErrorMessage(e)}`);
+      // Re-throw locking/busy errors — falling back to better-sqlite3 would
+      // hit the same contention (and potentially hang without busy_timeout).
+      const msg = toErrorMessage(e);
+      if (/\b(busy|locked|SQLITE_BUSY|SQLITE_LOCKED)\b/i.test(msg)) {
+        throw new DbError(`Database is busy (another process may be writing): ${msg}`, {});
+      }
+      debug(`openRepo: native path failed, falling back to better-sqlite3: ${msg}`);
     }
   }
 
@@ -405,14 +416,22 @@ export function openReadonlyWithNative(customPath?: string): {
 } {
   const db = openReadonlyOrFail(customPath);
 
+  // Respect explicit engine selection, consistent with openRepo().
+  const engine = process.env.CODEGRAPH_ENGINE || 'auto';
+
   let nativeDb: NativeDatabase | undefined;
-  if (isNativeAvailable()) {
+  if (engine !== 'wasm' && isNativeAvailable()) {
     try {
       const dbPath = findDbPath(customPath);
       const native = getNative();
       nativeDb = native.NativeDatabase.openReadonly(dbPath);
     } catch (e) {
-      debug(`openReadonlyWithNative: native path failed: ${toErrorMessage(e)}`);
+      const msg = toErrorMessage(e);
+      if (/\b(busy|locked|SQLITE_BUSY|SQLITE_LOCKED)\b/i.test(msg)) {
+        debug(`openReadonlyWithNative: native path busy, skipping native DB: ${msg}`);
+      } else {
+        debug(`openReadonlyWithNative: native path failed: ${msg}`);
+      }
     }
   }
 

package/src/db/index.ts

@@ -2,6 +2,7 @@
 
 export type { LockedDatabase, LockedDatabasePair } from './connection.js';
 export {
+  acquireAdvisoryLock,
   closeDb,
   closeDbDeferred,
   closeDbPair,
@@ -13,6 +14,7 @@ export {
   openReadonlyOrFail,
   openReadonlyWithNative,
   openRepo,
+  releaseAdvisoryLock,
 } from './connection.js';
 export { getBuildMeta, initSchema, MIGRATIONS, setBuildMeta } from './migrations.js';
 export {

package/src/db/repository/base.ts

@@ -223,4 +223,47 @@ export class Repository implements IRepository {
   hasCoChangesTable(): boolean {
     return false;
   }
+
+  // ── Composite queries ──────────────────────────────────────────────
+  /**
+   * Complete fnDeps query in a single call. Returns null when not natively
+   * supported — callers should fall back to the JS-orchestrated path.
+   */
+  fnDeps(
+    _name: string,
+    _opts?: { depth?: number; noTests?: boolean; file?: string; kind?: string },
+  ): FnDepsResult | null {
+    return null;
+  }
+}
+
+// ── Composite query result types ────────────────────────────────────────
+
+export interface FnDepsNode {
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+}
+
+export interface FnDepsCallerNode extends FnDepsNode {
+  viaHierarchy?: string;
+}
+
+export interface FnDepsEntry {
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+  endLine: number | null;
+  role: string | null;
+  fileHash: string | null;
+  callees: FnDepsNode[];
+  callers: FnDepsCallerNode[];
+  transitiveCallers: Record<number, FnDepsNode[]>;
+}
+
+export interface FnDepsResult {
+  name: string;
+  results: FnDepsEntry[];
 }

package/src/db/repository/index.ts

@@ -1,5 +1,6 @@
 // Barrel re-export for repository/ modules.
 
+export type { FnDepsCallerNode, FnDepsEntry, FnDepsNode, FnDepsResult } from './base.js';
 export { Repository } from './base.js';
 export { purgeFileData, purgeFilesData } from './build-stmts.js';
 export { cachedStmt } from './cached-stmt.js';

package/src/db/repository/native-repository.ts

@@ -45,7 +45,13 @@ import type {
   TriageNodeRow,
   TriageQueryOpts,
 } from '../../types.js';
-import { Repository } from './base.js';
+import {
+  type FnDepsCallerNode,
+  type FnDepsEntry,
+  type FnDepsNode,
+  type FnDepsResult,
+  Repository,
+} from './base.js';
 
 // ── Row converters (napi camelCase → Repository snake_case) ─────────────
 
@@ -461,4 +467,64 @@ export class NativeRepository extends Repository {
     }
     return false;
   }
+
+  // ── Composite queries ──────────────────────────────────────────────
+  fnDeps(
+    name: string,
+    opts?: { depth?: number; noTests?: boolean; file?: string; kind?: string },
+  ): FnDepsResult | null {
+    if (typeof this.#ndb.fnDeps !== 'function') return null;
+    const raw = this.#ndb.fnDeps(
+      name,
+      opts?.depth ?? undefined,
+      opts?.noTests ?? undefined,
+      opts?.file ?? undefined,
+      opts?.kind ?? undefined,
+    );
+    // Convert from native format (transitive_callers as array of groups)
+    // to JS format (transitiveCallers as Record<number, Array>)
+    return {
+      name: raw.name,
+      results: raw.results.map((entry: any): FnDepsEntry => {
+        const transitiveCallers: Record<number, FnDepsNode[]> = {};
+        for (const group of entry.transitiveCallers ?? []) {
+          transitiveCallers[group.depth] = (group.callers ?? []).map(
+            (c: any): FnDepsNode => ({
+              name: c.name,
+              kind: c.kind,
+              file: c.file,
+              line: c.line ?? null,
+            }),
+          );
+        }
+        return {
+          name: entry.name,
+          kind: entry.kind,
+          file: entry.file,
+          line: entry.line ?? null,
+          endLine: entry.endLine ?? entry.end_line ?? null,
+          role: entry.role ?? null,
+          fileHash: entry.fileHash ?? entry.file_hash ?? null,
+          callees: (entry.callees ?? []).map(
+            (c: any): FnDepsNode => ({
+              name: c.name,
+              kind: c.kind,
+              file: c.file,
+              line: c.line ?? null,
+            }),
+          ),
+          callers: (entry.callers ?? []).map(
+            (c: any): FnDepsCallerNode => ({
+              name: c.name,
+              kind: c.kind,
+              file: c.file,
+              line: c.line ?? null,
+              viaHierarchy: c.viaHierarchy ?? c.via_hierarchy ?? undefined,
+            }),
+          ),
+          transitiveCallers,
+        };
+      }),
+    };
+  }
 }

package/src/domain/analysis/context.ts

@@ -27,7 +27,7 @@ import {
   readSourceRange,
 } from '../../shared/file-utils.js';
 import { resolveMethodViaHierarchy } from '../../shared/hierarchy.js';
-import { normalizeSymbol } from '../../shared/normalize.js';
+import { normalizeSymbol, toSymbolRef } from '../../shared/normalize.js';
 import { paginateResult } from '../../shared/paginate.js';
 import type {
   BetterSqlite3Database,
@@ -177,7 +177,7 @@ function buildImplementationInfo(db: BetterSqlite3Database, node: NodeRow, noTes
     let impls = findImplementors(db, node.id) as RelatedNodeRow[];
     if (noTests) impls = impls.filter((n) => !isTestFile(n.file));
     return {
-      implementors: impls.map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line })),
+      implementors: impls.map(toSymbolRef),
     };
   }
   // For classes/structs: show what they implement
@@ -186,7 +186,7 @@ function buildImplementationInfo(db: BetterSqlite3Database, node: NodeRow, noTes
     if (noTests) ifaces = ifaces.filter((n) => !isTestFile(n.file));
     if (ifaces.length > 0) {
       return {
-        implements: ifaces.map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line })),
+        implements: ifaces.map(toSymbolRef),
       };
     }
   }
@@ -359,21 +359,11 @@ function explainFunctionImpl(
     const summary = fileLines ? extractSummary(fileLines, node.line, displayOpts) : null;
     const signature = fileLines ? extractSignature(fileLines, node.line, displayOpts) : null;
 
-    const callees = (findCallees(db, node.id) as RelatedNodeRow[]).map((c) => ({
-      name: c.name,
-      kind: c.kind,
-      file: c.file,
-      line: c.line,
-    }));
+    const callees = (findCallees(db, node.id) as RelatedNodeRow[]).map(toSymbolRef);
 
     const allCallerRows = findCallers(db, node.id) as RelatedNodeRow[];
 
-    let callers = allCallerRows.map((c) => ({
-      name: c.name,
-      kind: c.kind,
-      file: c.file,
-      line: c.line,
-    }));
+    let callers = allCallerRows.map(toSymbolRef);
     if (noTests) callers = callers.filter((c) => !isTestFile(c.file));
 
     const seenFiles = new Set<string>();

package/src/domain/analysis/dependencies.ts

@@ -2,7 +2,7 @@ import { findFileNodes, type Repository } from '../../db/index.js';
 import { cachedStmt } from '../../db/repository/cached-stmt.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
 import { resolveMethodViaHierarchy } from '../../shared/hierarchy.js';
-import { normalizeSymbol } from '../../shared/normalize.js';
+import { normalizeSymbol, toSymbolRef } from '../../shared/normalize.js';
 import { paginateResult } from '../../shared/paginate.js';
 import type {
   BetterSqlite3Database,
@@ -143,12 +143,8 @@ function buildNodeDepsResult(
 
   return {
     ...normalizeSymbol(node, repo, hc),
-    callees: filteredCallees.map((c) => ({
-      name: c.name,
-      kind: c.kind,
-      file: c.file,
-      line: c.line,
-    })),
+    callees: filteredCallees.map(toSymbolRef),
+    // Not using toSymbolRef — callers include the extra viaHierarchy field
     callers: callers.map((c) => ({
       name: c.name,
       kind: c.kind,
@@ -173,6 +169,19 @@ export function fnDepsData(
   } = {},
 ) {
   return withRepo(customDbPath, (repo) => {
+    // Try native composite path — single NAPI call for the entire query.
+    const nativeResult = repo.fnDeps(name, {
+      depth: opts.depth,
+      noTests: opts.noTests,
+      file: opts.file,
+      kind: opts.kind,
+    });
+    if (nativeResult) {
+      const base = { name: nativeResult.name, results: nativeResult.results };
+      return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
+    }
+
+    // Fallback: JS-orchestrated path (used when native engine is unavailable)
     const depth = opts.depth || 3;
     const noTests = opts.noTests || false;
     const hc = new Map();
@@ -232,20 +241,14 @@ function resolveEndpoints(
         to,
         found: false,
         error: `No symbol matching "${to}"`,
-        fromCandidates: fromNodes
-          .slice(0, 5)
-          .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line })),
+        fromCandidates: fromNodes.slice(0, 5).map(toSymbolRef),
         toCandidates: [],
       },
     };
   }
 
-  const fromCandidates = fromNodes
-    .slice(0, 5)
-    .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line }));
-  const toCandidates = toNodes
-    .slice(0, 5)
-    .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line }));
+  const fromCandidates = fromNodes.slice(0, 5).map(toSymbolRef);
+  const toCandidates = toNodes.slice(0, 5).map(toSymbolRef);
 
   return {
     sourceNode: fromNodes[0],

package/src/domain/analysis/fn-impact.ts

@@ -1,6 +1,6 @@
 import { Repository, SqliteRepository } from '../../db/index.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
-import { normalizeSymbol } from '../../shared/normalize.js';
+import { normalizeSymbol, toSymbolRef } from '../../shared/normalize.js';
 import { paginateResult } from '../../shared/paginate.js';
 import type { BetterSqlite3Database, NodeRow, RelatedNodeRow } from '../../types.js';
 import { resolveAnalysisOpts, withRepo } from './query-helpers.js';
@@ -125,7 +125,7 @@ export function bfsTransitiveCallers(
           visited.add(c.id);
           nextFrontier.push(c.id);
           if (!levels[d]) levels[d] = [];
-          levels[d]!.push({ name: c.name, kind: c.kind, file: c.file, line: c.line });
+          levels[d]!.push(toSymbolRef(c));
           if (onVisit) onVisit(c, fid, d);
         }
         if (resolveImplementors && INTERFACE_LIKE_KINDS.has(c.kind)) {

package/src/domain/analysis/implementations.ts

@@ -1,6 +1,6 @@
 import { isTestFile } from '../../infrastructure/test-filter.js';
 import { CORE_SYMBOL_KINDS } from '../../shared/kinds.js';
-import { normalizeSymbol } from '../../shared/normalize.js';
+import { normalizeSymbol, toSymbolRef } from '../../shared/normalize.js';
 import { paginateResult } from '../../shared/paginate.js';
 import type { RelatedNodeRow } from '../../types.js';
 import { withRepo } from './query-helpers.js';
@@ -34,12 +34,7 @@ export function implementationsData(
 
       return {
         ...normalizeSymbol(node, repo, hc),
-        implementors: implementors.map((impl) => ({
-          name: impl.name,
-          kind: impl.kind,
-          file: impl.file,
-          line: impl.line,
-        })),
+        implementors: implementors.map(toSymbolRef),
       };
     });
 
@@ -76,12 +71,7 @@ export function interfacesData(
 
       return {
         ...normalizeSymbol(node, repo, hc),
-        interfaces: interfaces.map((iface) => ({
-          name: iface.name,
-          kind: iface.kind,
-          file: iface.file,
-          line: iface.line,
-        })),
+        interfaces: interfaces.map(toSymbolRef),
       };
     });
 

package/src/domain/graph/builder/context.ts

@@ -33,6 +33,10 @@ export class PipelineContext {
   forceFullRebuild: boolean = false;
   schemaVersion!: number;
   nativeDb?: NativeDatabase;
+  /** Whether native engine is available (deferred — DB opened only when needed). */
+  nativeAvailable: boolean = false;
+  /** True when ctx.db is a NativeDbProxy — single rusqlite connection for the entire pipeline. */
+  nativeFirstProxy: boolean = false;
 
   // ── File collection (set by collectFiles stage) ────────────────────
   allFiles!: string[];

package/src/domain/graph/builder/incremental.ts

@@ -366,6 +366,27 @@ function buildImportEdges(
       stmts.insertEdge.run(fileNodeId, targetRow.id, edgeKind, 1.0, 0);
       edgesAdded++;
 
+      // Type-only imports: create symbol-level edges so the target symbols
+      // get fan-in credit and aren't falsely classified as dead code.
+      if (imp.typeOnly) {
+        for (const name of imp.names) {
+          const cleanName = name.replace(/^\*\s+as\s+/, '');
+          let targetFile = resolvedPath;
+          if (db && isBarrelFile(db, resolvedPath)) {
+            const actual = resolveBarrelTarget(db, resolvedPath, cleanName);
+            if (actual) targetFile = actual;
+          }
+          const candidates = stmts.findNodeInFile.all(cleanName, targetFile) as Array<{
+            id: number;
+            file: string;
+          }>;
+          if (candidates.length > 0) {
+            stmts.insertEdge.run(fileNodeId, candidates[0]!.id, 'imports-type', 1.0, 0);
+            edgesAdded++;
+          }
+        }
+      }
+
       // Barrel resolution: create edges through re-export chains
       if (!imp.reexport && db) {
         edgesAdded += resolveBarrelImportEdges(db, stmts, fileNodeId, resolvedPath, imp);

package/src/domain/graph/builder/native-db-proxy.ts

@@ -0,0 +1,98 @@
+/**
+ * NativeDbProxy — wraps a NativeDatabase (rusqlite via napi-rs) to satisfy the
+ * BetterSqlite3Database interface.  When the native addon is available, the
+ * build pipeline uses this proxy as `ctx.db` so that every stage operates on a
+ * single rusqlite connection — no dual-connection WAL corruption, no
+ * open/close/reopen dance.
+ *
+ * When native is unavailable, the pipeline falls back to real better-sqlite3.
+ */
+
+import type { BetterSqlite3Database, NativeDatabase, SqliteStatement } from '../../../types.js';
+
+/** Sanitize params for napi-rs: better-sqlite3 treats `undefined` as NULL,
+ *  but serde_json cannot represent `undefined`. Replace with `null`. */
+function sanitize(params: unknown[]): Array<string | number | null> {
+  return params.map((p) => (p === undefined ? null : p)) as Array<string | number | null>;
+}
+
+export class NativeDbProxy implements BetterSqlite3Database {
+  readonly #ndb: NativeDatabase;
+  /** Advisory lock path — set by the pipeline so closeDb() can release it. */
+  __lockPath?: string;
+
+  constructor(nativeDb: NativeDatabase) {
+    this.#ndb = nativeDb;
+  }
+
+  prepare<TRow = unknown>(sql: string): SqliteStatement<TRow> {
+    const ndb = this.#ndb;
+    const stmt: SqliteStatement<TRow> = {
+      all(...params: unknown[]): TRow[] {
+        return ndb.queryAll(sql, sanitize(params)) as TRow[];
+      },
+      get(...params: unknown[]): TRow | undefined {
+        return (ndb.queryGet(sql, sanitize(params)) ?? undefined) as TRow | undefined;
+      },
+      run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint } {
+        ndb.queryAll(sql, sanitize(params));
+        // Retrieve last_insert_rowid via SQLite scalar function so callers
+        // that depend on it (e.g. CFG block edge mapping) get correct values.
+        const row = ndb.queryGet('SELECT last_insert_rowid() AS rid', []) as { rid: number } | null;
+        return { changes: 0, lastInsertRowid: row?.rid ?? 0 };
+      },
+      iterate(): IterableIterator<TRow> {
+        throw new Error('iterate() is not supported via NativeDbProxy');
+      },
+      raw(): SqliteStatement<TRow> {
+        return stmt; // no-op — .raw() is not used in the build pipeline
+      },
+    };
+    return stmt;
+  }
+
+  exec(sql: string): this {
+    this.#ndb.exec(sql);
+    return this;
+  }
+
+  pragma(sql: string): unknown {
+    return this.#ndb.pragma(sql);
+  }
+
+  close(): void {
+    // No-op: the pipeline manages the NativeDatabase lifecycle directly.
+    // closeDbPair() calls nativeDb.close() separately.
+  }
+
+  get open(): boolean {
+    return this.#ndb.isOpen;
+  }
+
+  get name(): string {
+    return this.#ndb.dbPath;
+  }
+
+  transaction<F extends (...args: any[]) => any>(
+    fn: F,
+  ): (...args: F extends (...a: infer A) => unknown ? A : never) => ReturnType<F> {
+    const ndb = this.#ndb;
+    return ((...args: unknown[]) => {
+      // NOTE: nested transactions (savepoints) are not supported — ensure callers
+      // do not invoke a transaction() wrapper from within an existing transaction.
+      ndb.exec('BEGIN');
+      try {
+        const result = fn(...args);
+        ndb.exec('COMMIT');
+        return result;
+      } catch (e) {
+        try {
+          ndb.exec('ROLLBACK');
+        } catch {
+          // Ignore rollback errors — the original error is more important
+        }
+        throw e;
+      }
+    }) as any;
+  }
+}