import { type Table as ArrowTable } from 'apache-arrow';
import type { Database as NativeDatabase, Transaction, ConditionSpec, Cell, PutResult, RowJs, TypedColumn, CacheStatsJs, TriggerConfigJs } from '@visorcraft/mongreldb/native.js';
import { IndexBuildPolicyJs, WriteBuffer } from '@visorcraft/mongreldb/native.js';
import { Schema } from './schema.js';
import type { TableSpec } from './types.js';
import { type ProcedureCallOptions, type ProcedureCallResult, type ProcedureSpec } from './procedure.js';
import { type TriggerSpec } from './trigger.js';
import { type ViewSpec, type VirtualTableSpec } from './external.js';
import { type Migration } from './migrate.js';
export interface SqlOptions {
    timeoutMs?: number;
    signal?: AbortSignal;
    queryId?: string;
    maxOutputRows?: number;
    maxOutputBytes?: number;
}
export type CancelOutcome = 'accepted' | 'already_cancelling' | 'too_late' | 'already_finished' | 'not_found' | 'pre_cancelled';
/** Structural HLC from server durable recovery (0.64+). */
export interface SqlCommitHlc {
    physicalMicros: number;
    logical: number;
    nodeTiebreaker: number;
}
export interface SqlDurableOutcome {
    committed: boolean | null;
    committedStatements: number | null;
    lastCommitEpoch?: bigint;
    /** Authoritative commit HLC when the server recorded one (0.64+). */
    lastCommitHlc?: SqlCommitHlc;
    firstCommitStatementIndex?: number;
    lastCommitStatementIndex?: number;
    /** Serialization phase name (parity with native serialization_state). */
    serializationState?: string;
}
export interface SqlQueryStatus {
    queryId: string;
    phase: string;
    terminalState?: string;
    serverState?: string;
    operation: string;
    committed: boolean | null;
    durableOutcome: SqlDurableOutcome;
    terminalErrorCode?: string;
    terminalErrorCategory?: string;
    completedStatements: number | null;
    statementIndex: number | null;
    cancellationReason: string;
    cancelOutcome?: CancelOutcome;
    retryable?: boolean;
}
export interface SqlQuery<T> {
    readonly id: string;
    readonly result: Promise<T>;
    cancel(): Promise<CancelOutcome>;
    status(): Promise<SqlQueryStatus>;
}
type NativeSqlOptions = {
    queryId?: string;
    timeoutMs?: number;
    maxOutputRows?: number;
    maxOutputBytes?: number;
};
/** A reservoir-sampled approximate aggregate with a confidence interval. */
export interface ApproxAggregate {
    point: number;
    ci_low: number;
    ci_high: number;
    n_population: number;
    n_sample_live: number;
    n_passing: number;
}
type MongrelColumnSpec = {
    id: number;
    name: string;
    ty: number;
    primaryKey: boolean;
    nullable: boolean;
    autoIncrement?: boolean;
    embeddingDim?: number;
    defaultValue?: Cell;
    defaultExpr?: string;
    enumVariants?: string[];
    encrypted?: boolean;
    encryptedIndexable?: boolean;
    embeddingSourceJson?: string;
};
type MongrelDatabase = NativeDatabase & {
    transaction(fn: (txn: Transaction) => void | Promise<void>, opts?: {
        maxRetries?: number;
        baseDelayMs?: number;
    }): Promise<bigint>;
    alterColumn(table: string, columnName: string, column: MongrelColumnSpec): bigint;
    tableColumnSpecs(table: string): MongrelColumnSpec[];
    createProcedure(spec: {
        json: string;
    }): bigint;
    createOrReplaceProcedure(spec: {
        json: string;
    }): bigint;
    dropProcedure(name: string): void;
    procedures(): {
        json: string;
    }[];
    procedure(name: string): {
        json: string;
    } | null;
    callProcedure(name: string, opts?: {
        argsJson?: string;
        idempotencyKey?: string;
    }): {
        epoch?: bigint;
        resultJson: string;
    };
    createTrigger(spec: {
        json: string;
    }): bigint;
    createOrReplaceTrigger(spec: {
        json: string;
    }): bigint;
    dropTrigger(name: string): void;
    triggers(): {
        json: string;
    }[];
    trigger(name: string): {
        json: string;
    } | null;
    sql(sql: string): Promise<Buffer>;
    sqlWithOptions(sql: string, options?: NativeSqlOptions): Promise<Buffer>;
    createUser(username: string, password: string): void;
    dropUser(username: string): void;
    alterUserPassword(username: string, newPassword: string): void;
    verifyUser(username: string, password: string): boolean;
    setUserAdmin(username: string, isAdmin: boolean): void;
    users(): string[];
    createRole(name: string): void;
    dropRole(name: string): void;
    roles(): string[];
    grantRole(username: string, roleName: string): void;
    revokeRole(username: string, roleName: string): void;
    grantPermission(roleName: string, permission: string): void;
    revokePermission(roleName: string, permission: string): void;
    enableAuth(adminUsername: string, adminPassword: string): void;
    disableAuth(): void;
    requireAuthEnabled(): boolean;
    refreshPrincipal(): void;
    startCreateIndex(table: string, index: MongrelIndexSpec): bigint;
    startReplaceIndex(table: string, expectedOldName: string, index: MongrelIndexSpec): bigint;
    resumeIndexBuild(jobId: bigint): void;
    cancelJob(jobId: bigint): void;
    indexJob(jobId: bigint): IndexJobInfo;
    waitIndexJob(jobId: bigint, timeoutMs?: number): Promise<IndexJobInfo>;
};
type MongrelIndexSpec = {
    name: string;
    columnId: number;
    kind: number;
    annQuantization?: number;
    annAlgorithm?: number;
    predicate?: string;
    annM?: number;
    annEfConstruction?: number;
    annEfSearch?: number;
    diskann?: {
        r?: number;
        l?: number;
        beamWidth?: number;
        alpha?: number;
    };
    ivf?: {
        nlist?: number;
        nprobe?: number;
        trainingSamples?: number;
    };
    product?: {
        numSubvectors: number;
        bits?: number;
        trainingSamples?: number;
        seed?: bigint;
        rerankFactor?: number;
    };
    minhashPermutations?: number;
    minhashBands?: number;
    learnedRangeEpsilon?: number;
};
export type IndexJobInfo = {
    jobId: bigint;
    state: string;
    progress: number;
    done: bigint;
    total: bigint;
    error?: string;
};
/**
 * Run `fn` inside a fresh transaction, retrying bounded-exponentially on
 * retryable conflicts. Exported so query builders and `KitDatabase` methods
 * can share one implementation.
 */
export declare function runSyncTxn(kit: KitDatabase, fn: (txn: Transaction) => void, opts?: {
    maxRetries?: number;
    baseDelayMs?: number;
}): void;
/**
 * Async twin of {@link runSyncTxn}: run `fn` inside a fresh transaction,
 * committing via the native `Transaction.commitAsync()` (off the Node event
 * loop) and retrying bounded-exponentially on retryable conflicts. `fn` may
 * itself be async; the staged writes are committed atomically after it
 * resolves. Exported so query builders and `KitDatabase` methods can share one
 * implementation.
 */
export declare function runTxn(kit: KitDatabase, fn: (txn: Transaction) => Promise<void> | void, opts?: {
    maxRetries?: number;
    baseDelayMs?: number;
}): Promise<void>;
export declare class KitDatabase {
    private readonly db;
    readonly schema: Schema;
    private constructor();
    static open(path: string, schema: Schema): Promise<KitDatabase>;
    static openSync(path: string, schema: Schema, options?: {
        encryption?: {
            passphrase: string;
        };
        credentials?: {
            username: string;
            password: string;
        };
    }): KitDatabase;
    static createEncryptedSync(path: string, schema: Schema, passphrase: string): KitDatabase;
    static openEncryptedSync(path: string, schema: Schema, passphrase: string): KitDatabase;
    /** Create a fresh database with `require_auth = true`, a single admin user,
     * and the given schema. The returned handle is already authenticated as
     * the admin. */
    static createWithCredentialsSync(path: string, schema: Schema, adminUsername: string, adminPassword: string): KitDatabase;
    /** Create a fresh encrypted database with `require_auth = true` and a single
     * admin user. Composes encryption-at-rest with credential enforcement. */
    static createEncryptedWithCredentialsSync(path: string, schema: Schema, passphrase: string, adminUsername: string, adminPassword: string): KitDatabase;
    private static initialize;
    private ensureInternalTables;
    private alignExistingTableColumnIds;
    private ensureAppTable;
    private writeSchemaCatalog;
    migrateSync(schema: Schema, migrations: Migration[]): void;
    close(): void;
    get nativeDb(): MongrelDatabase;
    /** Start an online single-column index build and return its durable job id. */
    startCreateIndex(tableName: string, index: TableSpec['indexes'][number]): bigint;
    /** Replace an existing single-column index without exposing a partial index. */
    startReplaceIndex(tableName: string, expectedOldName: string, replacement: TableSpec['indexes'][number]): bigint;
    resumeIndexBuild(jobId: bigint): void;
    cancelIndexBuild(jobId: bigint): void;
    indexBuild(jobId: bigint): IndexJobInfo;
    waitIndexBuild(jobId: bigint, timeoutMs?: number): Promise<IndexJobInfo>;
    tableNames(): string[];
    createProcedureSync(spec: ProcedureSpec): bigint;
    createOrReplaceProcedureSync(spec: ProcedureSpec): bigint;
    dropProcedureSync(name: string): void;
    procedures(): ProcedureSpec[];
    procedure(name: string): ProcedureSpec | null;
    callProcedureSync(name: string, opts?: ProcedureCallOptions): ProcedureCallResult;
    createTriggerSync(spec: TriggerSpec): bigint;
    createOrReplaceTriggerSync(spec: TriggerSpec): bigint;
    dropTriggerSync(name: string): void;
    triggers(): TriggerSpec[];
    trigger(name: string): TriggerSpec | null;
    startSql(sql: string, options?: SqlOptions): SqlQuery<ArrowTable>;
    private startSqlWithResult;
    sql(sql: string, options?: SqlOptions): Promise<ArrowTable>;
    sqlRows(sql: string, options?: SqlOptions): Promise<Record<string, unknown>[]>;
    createVirtualTable(spec: VirtualTableSpec): Promise<ArrowTable>;
    dropVirtualTable(name: string): Promise<ArrowTable>;
    /** Create a SQL view (`CREATE VIEW <name> AS <select>`). The engine
     * overwrites any existing view with the same name, so this also serves as
     * replace. The view lives in the kit's long-lived SQL session — see
     * [SQL views](./migrations.md#sql-views). */
    createView(spec: ViewSpec): Promise<ArrowTable>;
    /** Drop a SQL view by name (idempotent — `DROP VIEW IF EXISTS`). */
    dropView(name: string): Promise<ArrowTable>;
    /** Verify run footer checksums; returns integrity issues grouped by table. */
    check(): unknown;
    /** Drop corrupt runs; returns the doctor report. */
    doctor(): unknown;
    /**
     * Flush every table's in-memory writes to durable sorted runs. Besides
     * durability, this empties the memtable, which enables the engine's
     * incremental-aggregate fast path (see `incrementalAggregate`).
     */
    flush(): void;
    /** Compact every table: merge sorted runs into one clean run each so
     * query latency stays flat. Returns `{compacted, skipped}`. */
    compactAll(): {
        compacted: number;
        skipped: number;
    };
    /** Compact a single table by name. Returns `true` if compacted, `false`
     * if skipped (fewer than two runs). */
    compactTable(table: string): boolean;
    /**
     * Flush every table (memtable and mutable run), compact, and drop rotated
     * WAL segments so the next open replays only a small active segment.
     * Requires MongrelDB 0.64.18+. Credential-enforced databases need `Ddl`.
     * `vacuum()` / `compactAll()` do not rotate the WAL.
     */
    checkpoint(): void;
    /** Rebuild statistics/metadata for every table's indexes (the engine's
     * `ANALYZE` equivalent). Routes through the SQL surface for parity with the
     * engine's own definition. Safe to run at any time; useful after bulk loads
     * so the query planner and learned indexes have fresh data. */
    analyze(): Promise<void>;
    /** Reclaim space across all tables (the engine's `VACUUM` equivalent:
     * compact every sorted run, then gc). Routes through the SQL surface for
     * parity with the engine's own definition. Safe to run at any time.
     * Does not rotate the WAL; use {@link checkpoint} to bound recovery. */
    vacuum(): Promise<void>;
    /** The current visible commit epoch (monotonically increasing version). */
    snapshotEpoch(): bigint;
    /**
     * Set how many committed epochs of history to retain for MVCC time-travel
     * reads ({@link rowsAtEpoch}). The engine default keeps only the latest
     * epoch, so raise this *before* writing data you want to read back at a
     * past snapshot. The setting persists across close/reopen and cannot
     * restore history that was already pruned.
     */
    setHistoryRetentionEpochs(epochs: number): void;
    /** The configured history-retention depth — how many committed epochs are kept for time-travel reads. */
    historyRetentionEpochs(): bigint;
    /** The oldest epoch still retained for time-travel reads ({@link rowsAtEpoch}). */
    earliestRetainedEpoch(): bigint;
    /**
     * Async twin of {@link flush}. Yields a microtask between table flushes; the
     * underlying engine `flush` is synchronous (the addon ships no
     * `flushAsync` on `Database`), so each call still blocks — but the await
     * points let other pending microtasks run.
     */
    flushAsync(): Promise<void>;
    /**
     * Async twin of {@link compactAll}. **Caveat:** the addon has no native
     * `compactAllAsync`, so this wraps the sync call in a `Promise` — it
     * matches the async signature but the underlying compaction still blocks
     * the event loop. Use it for signature parity in async maintenance loops.
     */
    compactAllAsync(): Promise<{
        compacted: number;
        skipped: number;
    }>;
    /**
     * Async twin of {@link checkpoint}. Same caveat as
     * {@link compactAllAsync}: no native async variant; the call blocks.
     */
    checkpointAsync(): Promise<void>;
    /**
     * Async twin of {@link compactTable}. Same caveat as
     * {@link compactAllAsync}: no native async variant; the call blocks.
     */
    compactTableAsync(table: string): Promise<boolean>;
    /** Async twin of {@link snapshotEpoch}. Resolves immediately. */
    snapshotEpochAsync(): Promise<bigint>;
    /** Export every visible row of `table` as a TSV document. */
    exportTsv(table: string): string;
    /** Read every row of `table` visible at commit `epoch` (MVCC time-travel). */
    rowsAtEpoch(table: string, epoch: bigint): Record<string, unknown>[];
    /**
     * Reservoir-sampled approximate aggregate (`count`/`sum`/`avg`) with a
     * `z`-score confidence interval (default ~95%). Returns
     * `{ point, ci_low, ci_high, n_population, n_sample_live, n_passing }`, or
     * `null` when the reservoir is empty. `column` is required for `sum`/`avg`.
     */
    approxAggregate(table: string, agg: 'count' | 'sum' | 'avg', column?: string, z?: number): ApproxAggregate | null;
    /**
     * Async twin of {@link approxAggregate}. **Caveat:** the addon has no native
     * `approxAggregateAsync`, so this wraps the sync call in a `Promise` — the
     * underlying reservoir read still blocks the event loop.
     */
    approxAggregateAsync(table: string, agg: 'count' | 'sum' | 'avg', column?: string, z?: number): Promise<ApproxAggregate | null>;
    /** Stream `table` in batches of at most `batchSize` rows. */
    scanBatched(table: string, batchSize: number, cb: (rows: Record<string, unknown>[]) => void): void;
    /**
     * Rank rows of `table` by Jaccard set-similarity between `query` and the
     * string set stored (as a JSON array) in `column`, returning the top `k`
     * with similarity `> 0`, highest first. The set-similarity / dedup-join
     * primitive the `MinHash` index kind is meant to serve; an exact linear scan
     * (a sub-linear MinHash/LSH index remains engine future-work).
     */
    setSimilarity(table: string, column: string, query: string[], k: number): {
        row: Record<string, unknown>;
        similarity: number;
    }[];
    /**
     * Async twin of {@link setSimilarity}. The MinHash candidate fetch runs via
     * the native `queryAsync` (genuinely off the event loop via
     * `spawn_blocking`); the exact Jaccard re-scoring runs in JS. Falls back to
     * a sync `selectFrom().executeSync()` scan when there's no MinHash index.
     */
    setSimilarityAsync(table: string, column: string, query: string[], k: number): Promise<{
        row: Record<string, unknown>;
        similarity: number;
    }[]>;
    /** Async put of one row (`cells` = `{ columnId, int64|float64|text|... }[]`)
     * via the native `putAsync`. Returns the row id and any auto-increment
     * value. Bypasses Kit constraints. */
    putAsync(table: string, cells: RowJs['cells']): Promise<PutResult>;
    /** Async point-read by row id via the native `getAsync`. */
    getAsync(table: string, rowId: bigint): Promise<RowJs | null>;
    /** Async condition query via the native `queryAsync` — returns raw
     * `RowJs[]` (row id + typed cells). Build conditions with the `ConditionKind`
     * constants; the kit's `Predicate`/`compilePredicate` produces these too. */
    queryAsync(table: string, conditions: ConditionSpec[]): Promise<RowJs[]>;
    /** Async count of all rows in `table` via the native `countAsync`. */
    countAsync(table: string): Promise<bigint>;
    /** Async count of rows matching `conditions` via the native
     * `countWhereAsync`. */
    countWhereAsync(table: string, conditions: ConditionSpec[]): Promise<bigint>;
    /** Async condition query returning Arrow IPC bytes (zero-copy columnar) via
     * the native `queryArrowAsync`. Decode with `apache-arrow`'s
     * `tableFromIPC`. */
    queryArrowAsync(table: string, conditions: ConditionSpec[]): Promise<Buffer>;
    /**
     * Fastest ingest path: bulk-load typed columns (`Int64`/`Float64`/`Bool` only)
     * in one shot, bypassing the per-cell `Value` enum. **Commits internally**
     * and returns the commit epoch — not transactional, cannot be staged into a
     * `Transaction`. `Bytes`/`Embedding`/text columns are not supported here
     * (use {@link InsertManyBuilder} / `putBatch` for those). Bypasses Kit
     * constraints (defaults, unique guards, FK checks).
     *
     * Each `TypedColumn` carries a contiguous little-endian `data` buffer
     * (`Int64` = N×8 bytes, `Float64` = N×8 bytes, `Bool` = N bytes) plus an
     * optional `validity` bitmap (1 byte per row, `1`=non-null). All columns
     * must have the same row count.
     */
    bulkLoadTyped(table: string, columns: TypedColumn[]): bigint;
    /** Set the per-table spill threshold (bytes). */
    setSpillThreshold(bytes: bigint | number): void;
    /** Enable or disable recursive trigger execution (database-wide). */
    setRecursiveTriggers(enabled: boolean): void;
    /** Read the current trigger execution policy. */
    triggerConfig(): TriggerConfigJs;
    /** Set the trigger execution policy. `max_depth` must be > 0. */
    setTriggerConfig(config: TriggerConfigJs): void;
    /** Set a table's compaction zstd level (-1 = default, 0 = none, 1..22). */
    setTableCompactionZstdLevel(table: string, level: number): void;
    /** Set a table's result-cache max bytes. */
    setTableResultCacheMaxBytes(table: string, maxBytes: bigint | number): void;
    /** Set a table's mutable-run spill threshold (bytes). */
    setTableMutableRunSpillBytes(table: string, bytes: bigint | number): void;
    /** Set a table's WAL sync byte threshold (bytes between group-syncs). */
    setTableSyncByteThreshold(table: string, threshold: bigint | number): void;
    /** Set a table's index build policy (`Deferred` for fast ingest, `Eager`
     * for fast first query). */
    setTableIndexBuildPolicy(table: string, policy: IndexBuildPolicyJs): void;
    /** Page-cache statistics for a table. */
    tablePageCacheStats(table: string): CacheStatsJs;
    /** Number of sorted runs a table currently has (compaction target: 1). */
    tableRunCount(table: string): number;
    /** Memtable length (uncommitted staged rows) for a table. */
    tableMemtableLen(table: string): number;
    /** Mutable-run length for a table. */
    tableMutableRunLen(table: string): number;
    /** Page-cache entry count for a table. */
    tablePageCacheLen(table: string): number;
    /** Decoded-page-cache entry count for a table. */
    tableDecodedCacheLen(table: string): number;
    /**
     * Create a {@link WriteBuffer} over `table` — opt-in write micro-batching
     * where writes are **not durable until `flush()`** (the opposite contract of
     * `put()`). `threshold` rows trigger an auto-flush (default 1000). Useful
     * for high-throughput ingest where per-row commit latency isn't acceptable.
     * Bypasses Kit constraints (defaults, unique guards, FK checks).
     */
    writeBuffer(table: string, threshold?: number): WriteBuffer;
    /** Create a catalog user with an Argon2id-hashed password. */
    createUser(username: string, password: string): void;
    /** Drop a user by username. */
    dropUser(username: string): void;
    /** Change a user's password. */
    alterUserPassword(username: string, newPassword: string): void;
    /** Verify credentials. Returns `true` on success. */
    verifyUser(username: string, password: string): boolean;
    /** Grant or revoke admin privileges on a user. */
    setUserAdmin(username: string, isAdmin: boolean): void;
    /** List all usernames. */
    users(): string[];
    /** Create a role. */
    createRole(name: string): void;
    /** Drop a role. */
    dropRole(name: string): void;
    /** List all role names. */
    roles(): string[];
    /** Grant a role to a user. */
    grantRole(username: string, roleName: string): void;
    /** Revoke a role from a user. */
    revokeRole(username: string, roleName: string): void;
    /** Grant a permission to a role. Permission format: `"all"`, `"ddl"`,
     * `"admin"`, or `"select:table"`, `"insert:table"`, `"update:table"`,
     * `"delete:table"`. */
    grantPermission(roleName: string, permission: string): void;
    /** Revoke a permission from a role. */
    revokePermission(roleName: string, permission: string): void;
    /** Convert a credentialless database to a credentialed one in place.
     * Creates the first admin user, sets `require_auth = true`, and caches the
     * admin principal on this handle. */
    enableAuth(adminUsername: string, adminPassword: string): void;
    /** Disable `require_auth`, reverting to credentialless mode (recovery).
     * Users and roles are preserved but no longer enforced. */
    disableAuth(): void;
    /** Returns `true` if this database has `require_auth = true`. */
    requireAuthEnabled(): boolean;
    /** Re-resolve the cached principal from the on-disk catalog, picking up
     * role/permission changes made by other handles. */
    refreshPrincipal(): void;
    /** Import a TSV document into `table`; returns the number of rows inserted. */
    importTsv(table: string, text: string): number;
    /**
     * Rename a live table from `oldName` to `newName`. The source must exist and
     * be live; the target must not collide with an existing table (the engine
     * enforces both). The rename is durable: it is logged to the WAL and applied
     * again on reopen. The `table_id`, schema, and on-disk layout are unchanged,
     * so outstanding handles and indexes remain valid.
     *
     * Internal `__kit_`-prefixed names are off-limits in both directions: an app
     * table cannot be renamed to a `__kit_` name (it would vanish from
     * {@link KitDatabase.tableNames}, which filters that prefix) and an internal
     * table cannot be renamed away from its expected name (the Kit looks internal
     * tables up by name). This keeps the internal-table namespace invariant
     * intact without the engine needing to know about Kit conventions.
     */
    renameTable(oldName: string, newName: string): void;
    begin(): Transaction;
    /**
     * Reserve (without inserting) the next engine-native AUTO_INCREMENT value for
     * `tableName`, advancing the engine's per-table counter. Returns `null` when
     * the table has no auto-increment column.
     *
     * Pure in-memory counter bump (no extra commit) that becomes durable when a
     * row carrying the reserved id commits. An aborted reservation simply leaves
     * a gap, which the never-reuse rule permits. Used by `prepareInsertRowSync`
     * so a transaction can stage the row with an explicit id and still return it
     * from `executeSync()`.
     */
    reserveAutoIncSync(tableName: string): bigint | null;
}
export {};
//# sourceMappingURL=db.d.ts.map