import { ResolvedRef } from "../validation/dolt-schemas.js";
import { AgentsManageDatabaseClient } from "../db/manage/manage-client.js";
import { Pool } from "pg";

//#region src/dolt/ref-scope.d.ts

/**
 * Context stored in AsyncLocalStorage to detect nested withRef calls
 */
interface RefScopeContext {
  db: AgentsManageDatabaseClient;
  ref: string;
  connectionId: string;
}
/**
 * Error thrown when nested withRef calls are detected with different refs
 */
declare class NestedRefScopeError extends Error {
  constructor(existingRef: string, attemptedRef: string);
}
/**
 * Options for withRef function
 */
interface WithRefOptions {
  /**
   * Whether to auto-commit changes after successful callback execution.
   * Only applies to branch refs (tags/commits are immutable).
   * @default false
   */
  commit?: boolean;
  /**
   * Commit message to use when committing changes.
   * @default 'withRef auto-commit'
   */
  commitMessage?: string;
  /**
   * Author information for the commit.
   * @default { name: 'agents-api', email: 'api@inkeep.com' }
   */
  author?: {
    name: string;
    email: string;
  };
}
/**
 * Execute a function with a database connection scoped to a specific ref (branch/tag/commit).
 *
 * This function:
 * 1. Gets a dedicated connection from the pool
 * 2. For branches: checks out the branch directly
 * 3. For tags/commits: creates a temporary branch from the hash, then checks out
 * 4. Executes the callback with a Drizzle client scoped to that connection
 * 5. Optionally auto-commits changes on success (if commit: true)
 * 6. Cleans up: checks out main, deletes temp branch if created, releases connection
 *
 * Important:
 * - The callback should only perform database operations
 * - Do NOT hold the connection while making external API calls
 *
 * @param pool - The PostgreSQL connection pool
 * @param resolvedRef - The resolved ref (branch, tag, or commit)
 * @param dataAccessFn - The function to execute with the scoped database client
 * @param options - Optional configuration for commit behavior
 * @returns The result of the callback function
 *
 * @example
 * ```typescript
 * // Simple read (no commit)
 * const agent = await withRef(pool, resolvedRef, (db) =>
 *   getAgent(db, agentId)
 * );
 *
 * // Write with auto-commit
 * await withRef(pool, resolvedRef, async (db) => {
 *   await updateAgent(db, agentId, data);
 * }, { commit: true, commitMessage: 'Update agent config' });
 *
 * // Batch multiple operations with commit
 * const result = await withRef(pool, resolvedRef, async (db) => {
 *   await createCredential(db, credData);
 *   await updateTool(db, toolId, { credentialId });
 *   return { success: true };
 * }, { commit: true, author: { name: 'oauth', email: 'oauth@inkeep.com' } });
 * ```
 */
declare function withRef<T>(pool: Pool, resolvedRef: ResolvedRef, dataAccessFn: (db: AgentsManageDatabaseClient) => Promise<T>, options?: WithRefOptions): Promise<T>;
/**
 * Check if currently inside a withRef scope
 */
declare function isInRefScope(): boolean;
/**
 * Get the current ref scope context if inside one
 */
declare function getCurrentRefScope(): RefScopeContext | undefined;
/**
 * Get the database client from the current ref scope.
 * Throws if not inside a withRef scope.
 */
declare function getRefScopedDb(): AgentsManageDatabaseClient;
//#endregion
export { NestedRefScopeError, WithRefOptions, getCurrentRefScope, getRefScopedDb, isInRefScope, withRef };