@kedem/okdb 1.0.0

package/types/features/pipelines.d.ts

@@ -0,0 +1,19 @@
+export interface OKDBPipelineDefinition {
+    name: string;
+    sourceType: string;
+    steps: OKDBPipelineStep[];
+    [key: string]: unknown;
+}
+
+export interface OKDBPipelineStep {
+    type: string;
+    [key: string]: unknown;
+}
+
+export declare class OKDBPipelines {
+    register(definition: OKDBPipelineDefinition): Promise<void>;
+    unregister(name: string): Promise<void>;
+    get(name: string): OKDBPipelineDefinition | null;
+    list(): OKDBPipelineDefinition[];
+    bootSyncedPipelines(): Promise<void>;
+}

package/types/features/queue.d.ts

@@ -0,0 +1,189 @@
+import type { OKDBIndexKey } from '../options';
+import type { EventEmitter } from 'events';
+
+export type OKDBJobStatus = 'pending' | 'running' | 'done' | 'failed';
+
+export interface OKDBJobBucket {
+    id: string;
+    tokens: number;
+}
+
+export interface OKDBJob {
+    id: string;
+    type: string;
+    idempotency_key: string | null;
+    status: OKDBJobStatus;
+    status_code: string | null;
+    status_message: string | null;
+    error_stack: string | null;
+    progress: string | null;
+    when: number;
+    priority: number;
+    tags: string[];
+    tag: string | null;
+    bucket: string | null;
+    bucket_tokens: number | null;
+    buckets: OKDBJobBucket[] | null;
+    cron: string | null;
+    created: number;
+    updated: number;
+    finished: number | null;
+    tries: number;
+    max_tries: number | null;
+    retry_delay: number;
+    backoff_multiplier: number;
+    claim_id: string | null;
+    claim_expires: number | null;
+    done_ttl: number | null;
+    failed_ttl: number | null;
+    payload?: unknown;
+}
+
+export interface OKDBJobBucketRecord {
+    id: string;
+    tokens: number;
+    capacity: number;
+    refill_amount: number;
+    refill_every: number;
+    updated: number;
+}
+
+export type OKDBJobTypeStatus = 'active' | 'paused' | 'draining';
+
+export interface OKDBJobType {
+    id: string;
+    status: OKDBJobTypeStatus;
+    max_concurrency: number | null;
+    defaults: Partial<OKDBJobDefaults>;
+    payload_schema: { definition: unknown; enforce: boolean } | null;
+    created_at: number;
+    updated_at: number;
+}
+
+export interface OKDBJobDefaults {
+    max_tries: number | null;
+    retry_delay: number;
+    backoff_multiplier: number;
+    priority: number;
+    ttl: number | null;
+    done_ttl: number | null;
+    failed_ttl: number | null;
+    buckets: OKDBJobBucket[] | null;
+}
+
+export interface OKDBEnqueueOptions {
+    when?: number;
+    priority?: number;
+    tags?: string[];
+    bucket?: string;
+    bucket_tokens?: number;
+    buckets?: OKDBJobBucket[];
+    cron?: string;
+    max_tries?: number | null;
+    retry_delay?: number;
+    backoff_multiplier?: number;
+    done_ttl?: number | null;
+    failed_ttl?: number | null;
+    idempotency_key?: string | number;
+    txn?: OKDBQueueTransaction;
+}
+
+export interface OKDBClaimOptions {
+    ttl?: number;
+    tags?: string[];
+    bucket?: string;
+}
+
+export interface OKDBListJobsOptions {
+    type?: string | null;
+    status?: OKDBJobStatus | null;
+    bucket?: string | null;
+    tag?: string | null;
+    sort?: 'when' | 'priority';
+    direction?: 'asc' | 'desc';
+    limit?: number;
+    cursor?: OKDBIndexKey | null;
+}
+
+export interface OKDBAddBucketOptions {
+    capacity?: number;
+    tokens?: number;
+    refill_amount?: number;
+    refill_every?: number;
+    txn?: OKDBQueueTransaction;
+}
+
+export interface OKDBAddJobTypeOptions {
+    status?: OKDBJobTypeStatus;
+    max_concurrency?: number | null;
+    defaults?: Partial<OKDBJobDefaults>;
+}
+
+export interface OKDBQueueTransaction {
+    put(type: string, key: string | number, value: unknown): void;
+    remove(type: string, key: string | number): void;
+    update(type: string, key: string | number, value: unknown, opts?: unknown): void;
+    commit(): Promise<void>;
+}
+
+export interface OKDBQueueWorker {
+    stop(timeout?: number): Promise<void>;
+}
+
+export interface OKDBQueueSpawnedWorker {
+    stop(timeout?: number): Promise<void>;
+}
+
+export declare class OKDBQueue {
+    events: EventEmitter;
+
+    // ── Core job lifecycle ────────────────────────────────────────────────────
+    enqueue(type: string, payload: unknown, options?: OKDBEnqueueOptions): Promise<string>;
+    claim(type: string, options?: OKDBClaimOptions): Promise<OKDBJob | null>;
+    worker(type: string, handler: (job: OKDBJob) => Promise<unknown> | unknown, options?: Record<string, unknown>): OKDBQueueWorker;
+    spawn(type: string, modulePath: string, options?: Record<string, unknown>): Promise<OKDBQueueSpawnedWorker>;
+    stopAll(timeout?: number): Promise<void>;
+
+    // ── Job retrieval / management ────────────────────────────────────────────
+    getJob(id: string): Promise<OKDBJob | null>;
+    updateJob(id: string, patch: Partial<OKDBJob & { payload: unknown }>, options?: { txn?: OKDBQueueTransaction }): Promise<OKDBJob>;
+    removeJob(id: string, options?: { txn?: OKDBQueueTransaction }): Promise<boolean>;
+    retryJob(id: string): Promise<OKDBJob>;
+    cancelJob(id: string): Promise<OKDBJob>;
+    list(options?: OKDBListJobsOptions): Promise<{ items: OKDBJob[]; cursor: OKDBIndexKey | null }>;
+
+    // ── Worker callbacks ──────────────────────────────────────────────────────
+    heartbeat(jobId: string, claimId: string, ttl?: number | null): Promise<OKDBJob>;
+    markJobHeartbeat(jobId: string, claimId: string, ttl?: number | null): Promise<OKDBJob>;
+    markJobProgress(jobId: string, claimId: string, message: string): Promise<OKDBJob>;
+    markJobComplete(jobId: string, claimId: string, result?: unknown): Promise<OKDBJob>;
+    completeJob(jobId: string, claimId: string, result?: unknown): Promise<OKDBJob>;
+    markJobFail(jobId: string, claimId: string, err: Error | unknown, code?: string): Promise<{ permanentlyFailed: boolean; job: OKDBJob }>;
+    failJob(jobId: string, claimId: string, err: Error | unknown, code?: string): Promise<{ permanentlyFailed: boolean; job: OKDBJob }>;
+    releaseClaim(jobId: string, claimId: string, options?: { when?: number; statusCode?: string; keepTry?: boolean }): Promise<boolean>;
+
+    // ── Bulk operations ───────────────────────────────────────────────────────
+    clearDone(type?: string | null, limit?: number): Promise<number>;
+    clearFailed(type?: string | null, limit?: number): Promise<number>;
+    clearStuck(type?: string | null, limit?: number): Promise<number>;
+    retryFailed(type?: string | null, limit?: number): Promise<number>;
+
+    // ── Token buckets ─────────────────────────────────────────────────────────
+    addBucket(id: string, options?: OKDBAddBucketOptions): Promise<void>;
+    updateBucket(id: string, patch: Partial<OKDBJobBucketRecord>): Promise<void>;
+    removeBucket(id: string): Promise<void>;
+    getBucket(id: string): OKDBJobBucketRecord | null;
+    tryClaimTokens(bucketId: string, tokens?: number): Promise<boolean>;
+
+    // ── Job types ─────────────────────────────────────────────────────────────
+    addJobType(id: string, options?: OKDBAddJobTypeOptions): Promise<OKDBJobType>;
+    getJobType(id: string): Promise<OKDBJobType | null>;
+    listJobTypes(): Promise<OKDBJobType[]>;
+    removeJobType(id: string): Promise<boolean>;
+    pauseJobType(id: string): Promise<OKDBJobType>;
+    resumeJobType(id: string): Promise<OKDBJobType>;
+    drainJobType(id: string): Promise<OKDBJobType>;
+    setJobTypeSchema(id: string, definition: unknown, enforce?: boolean): Promise<OKDBJobType>;
+    removeJobTypeSchema(id: string): Promise<OKDBJobType>;
+    samplePayloads(type: string, limit?: number): Promise<unknown[]>;
+}

package/types/features/sync.d.ts

@@ -0,0 +1,34 @@
+export interface OKDBSyncNode {
+    id: string;
+    address: string | null;
+    meta: Record<string, unknown>;
+    tags: string[];
+    updated: number;
+    publicKey?: string;
+}
+
+export interface OKDBSyncLink {
+    id: string;
+    nodeA: string;
+    nodeB: string;
+    createdAt: number;
+    [key: string]: unknown;
+}
+
+export interface OKDBSyncInfo {
+    node_id: string;
+    clock: number;
+    auto_reconcile: boolean;
+    peers: number;
+    reconciling: string[];
+}
+
+export declare class OKDBSync {
+    info(): OKDBSyncInfo;
+    getSelfNode(): OKDBSyncNode;
+    addPeer(address: string, options?: Record<string, unknown>): Promise<void>;
+    removePeer(nodeId: string): Promise<void>;
+    listPeers(): OKDBSyncNode[];
+    reconcile(nodeId?: string): Promise<void>;
+    stop(): void;
+}

package/types/features/time-machine.d.ts

@@ -0,0 +1,32 @@
+import type { OKDBPrimaryKey } from '../options';
+
+export interface OKDBTimeMachineSnapshot {
+    clock: number;
+    timestamp: number;
+    [key: string]: unknown;
+}
+
+export interface OKDBTimeMachineDiff {
+    key: OKDBPrimaryKey;
+    type: string;
+    action: 'put' | 'remove';
+    oldValue?: unknown;
+    newValue?: unknown;
+    clock: number;
+    timestamp: number;
+}
+
+export interface OKDBTimeMachineQueryOptions {
+    from?: number;
+    to?: number;
+    limit?: number;
+    types?: string[];
+}
+
+export declare class OKDBTimeMachine {
+    start(): void;
+    stop(): Promise<void>;
+    getAt(type: string, key: OKDBPrimaryKey, clock: number): unknown;
+    getDiff(options?: OKDBTimeMachineQueryOptions): Iterable<OKDBTimeMachineDiff>;
+    listSnapshots(options?: { limit?: number }): OKDBTimeMachineSnapshot[];
+}

package/types/features/views.d.ts

@@ -0,0 +1,16 @@
+export interface OKDBViewDefinition {
+    name: string;
+    sourceType: string;
+    targetType: string;
+    map?: string;
+    reduce?: string;
+    [key: string]: unknown;
+}
+
+export declare class OKDBViews {
+    register(definition: OKDBViewDefinition): Promise<void>;
+    unregister(name: string): Promise<void>;
+    get(name: string): OKDBViewDefinition | null;
+    list(): OKDBViewDefinition[];
+    bootSyncedViews(): Promise<void>;
+}

package/types/index.d.ts

@@ -0,0 +1,153 @@
+// ── Re-export all public types ────────────────────────────────────────────────
+export type * from './options';
+export type * from './errors';
+export type { OKDBTransaction, OKDBEnvironment } from './environment';
+
+// Features
+export type { OKDBQueue, OKDBJob, OKDBJobStatus, OKDBJobType, OKDBJobBucket, OKDBJobBucketRecord, OKDBEnqueueOptions, OKDBClaimOptions, OKDBListJobsOptions } from './features/queue';
+export type { OKDBFiles, OKDBFileRecord, OKDBUploadOptions } from './features/files';
+export type { OKDBSync, OKDBSyncNode, OKDBSyncInfo } from './features/sync';
+export type { OKDBAuth, OKDBToken, OKDBAuthContext, OKDBLoginResult } from './features/auth';
+export type { OKDBEmbeddings, OKDBEmbeddingsPipeline, OKDBEmbeddingsSearchResult } from './features/embeddings';
+export type { OKDBFts, OKDBFtsIndex, OKDBFtsQueryResult } from './features/fts';
+export type { OKDBEngines, OKDBEngineDefinition } from './features/engines';
+export type { OKDBFunctions, OKDBFunctionDefinition } from './features/functions';
+export type { OKDBPipelines, OKDBPipelineDefinition } from './features/pipelines';
+export type { OKDBViews, OKDBViewDefinition } from './features/views';
+export type { OKDBMcp, OKDBMcpTool } from './features/mcp';
+export type { OKDBTimeMachine, OKDBTimeMachineDiff, OKDBTimeMachineSnapshot } from './features/time-machine';
+export type { OKDBAdmin } from './features/admin';
+export type { OKDBApi } from './features/api';
+
+// ── Main OKDB class ───────────────────────────────────────────────────────────
+import type { OKDBOptions, OKDBEnvironmentConfig, OKDBPrimaryKey, OKDBIndexKey, OKDBFilter, OKDBRangeOptions, OKDBQueryOptions, OKDBGeoQueryOptions, OKDBFtsQueryOptions, OKDBWriteOptions, OKDBEntry, OKDBIndexEntry, OKDBChangeEntry, OKDBIndexDefinition, OKDBRemoveEnvironmentResult, OKDBTtlListOptions, OKDBInfoResult } from './options';
+import type { OKDBEnvironment, OKDBTransaction } from './environment';
+import type { OKDBQueue } from './features/queue';
+import type { OKDBFiles } from './features/files';
+import type { OKDBSync } from './features/sync';
+import type { OKDBAuth } from './features/auth';
+import type { OKDBEmbeddings } from './features/embeddings';
+import type { OKDBFts } from './features/fts';
+import type { OKDBEngines } from './features/engines';
+import type { OKDBFunctions } from './features/functions';
+import type { OKDBPipelines } from './features/pipelines';
+import type { OKDBMcp } from './features/mcp';
+import type { OKDBAdmin } from './features/admin';
+import type { OKDBApi } from './features/api';
+import type { EventEmitter } from 'events';
+
+export declare class OKDB {
+    static defaults: OKDBOptions;
+    static HIGH_SENTINEL: Buffer;
+
+    readonly path: string;
+    readonly id: string;
+    readonly options: OKDBOptions;
+    readonly events: EventEmitter;
+
+    // ── Subsystems ────────────────────────────────────────────────────────────
+    readonly http: unknown;
+    readonly auth: OKDBAuth;
+    readonly log: unknown;
+    readonly bus: unknown;
+    readonly admin: OKDBAdmin;
+    readonly api: OKDBApi;
+    readonly sync: OKDBSync;
+    readonly embeddings: OKDBEmbeddings;
+    readonly fts: OKDBFts;
+    readonly engines: OKDBEngines;
+    readonly pipelines: OKDBPipelines;
+    readonly functions: OKDBFunctions;
+    readonly mcp: OKDBMcp;
+    readonly meta: unknown;
+    readonly migrate: unknown;
+    readonly plugins: unknown;
+
+    // ── Queue and files are shortcuts to default env ──────────────────────────
+    readonly queue: OKDBQueue;
+    readonly files: OKDBFiles;
+
+    constructor(dbPath: string, options?: OKDBOptions);
+
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+    open(): Promise<void>;
+    close(): Promise<void>;
+
+    // ── Environment management ────────────────────────────────────────────────
+    readonly default: OKDBEnvironment;
+    env(name?: string): OKDBEnvironment;
+    createEnvironment(name: string, config?: OKDBEnvironmentConfig): Promise<OKDBEnvironment>;
+    removeEnvironment(name: string, options?: { keepSubEnvs?: string[] }): Promise<OKDBRemoveEnvironmentResult>;
+
+    // ── Info ──────────────────────────────────────────────────────────────────
+    readonly info: OKDBInfoResult;
+
+    // ── Transactions ──────────────────────────────────────────────────────────
+    transaction(options?: Record<string, unknown>): OKDBTransaction;
+    txn<T = void>(work: (txn: OKDBTransaction) => T | Promise<T>, options?: Record<string, unknown>): Promise<T>;
+
+    // ── CRUD (delegates to default env) ───────────────────────────────────────
+    put(type: string, key: OKDBPrimaryKey, value: unknown, options?: OKDBWriteOptions): Promise<void>;
+    update(type: string, key: OKDBPrimaryKey, value: unknown, options?: OKDBWriteOptions): Promise<void>;
+    patch(type: string, key: OKDBPrimaryKey, patch: Record<string, unknown>, options?: OKDBWriteOptions): Promise<void>;
+    create(type: string, key: OKDBPrimaryKey, value: unknown, options?: OKDBWriteOptions): Promise<void>;
+    remove(type: string, key: OKDBPrimaryKey, options?: Pick<OKDBWriteOptions, 'ifVersion'>): Promise<void>;
+
+    // ── Read ──────────────────────────────────────────────────────────────────
+    get<T = unknown>(type: string, key: OKDBPrimaryKey, options?: Record<string, unknown>): T | undefined;
+    getMany<T = unknown>(type: string, keys: OKDBPrimaryKey[], options?: Record<string, unknown>): (T | undefined)[];
+    getEntry<T = unknown>(type: string, key: OKDBPrimaryKey, options?: Record<string, unknown>): OKDBEntry<T> | undefined;
+    getRange<T = unknown>(type: string, options?: OKDBRangeOptions): Iterable<OKDBEntry<T>>;
+    getValues<T = unknown>(type: string, options?: OKDBRangeOptions): Iterable<T>;
+    getKeys(type: string, options?: OKDBRangeOptions): Iterable<OKDBPrimaryKey>;
+    getCount(type: string, options?: OKDBRangeOptions): number;
+    getByPrefix<T = unknown>(type: string, prefix: OKDBPrimaryKey, options?: OKDBRangeOptions): Iterable<OKDBEntry<T>>;
+
+    // ── Index queries ─────────────────────────────────────────────────────────
+    getIndex<T = unknown>(type: string, index: string[], options?: OKDBQueryOptions): Iterable<OKDBIndexEntry<T>>;
+    byIndex<T = unknown>(type: string, index: string[], options?: OKDBQueryOptions): Iterable<OKDBIndexEntry<T>>;
+    query<T = unknown>(type: string, filter: OKDBFilter, options?: OKDBQueryOptions): Iterable<OKDBIndexEntry<T>>;
+    geoQuery<T = unknown>(type: string, field: string, options: OKDBGeoQueryOptions): Iterable<OKDBEntry<T>>;
+    ftsQuery<T = unknown>(type: string, name: string, text: string, filter?: OKDBFilter, options?: OKDBFtsQueryOptions): Iterable<OKDBEntry<T>>;
+
+    // ── Type management ───────────────────────────────────────────────────────
+    registerType(type: string, timestamp?: number): Promise<void>;
+    ensureType(type: string, options?: { timestamp?: number; indexes?: Array<string[] | OKDBIndexDefinition> }): Promise<void>;
+    hasType(type: string): boolean;
+    dropType(type: string, timestamp?: number): Promise<void>;
+
+    // ── Index management ──────────────────────────────────────────────────────
+    registerIndex(type: string, index: string[], options?: { type?: 'geo'; precision?: number; unique?: boolean; timestamp?: number }): Promise<void>;
+    hasIndex(type: string, index: string[]): boolean;
+    dropIndex(type: string, index: string[], timestamp?: number): Promise<void>;
+    resetIndex(type: string, index: string[], clear?: boolean): Promise<void>;
+    indexReady(type: string, index: string[]): Promise<boolean>;
+    getIndexStatus(type: string, index: string[]): string;
+    getUniqueViolations(type: string, index: string[]): unknown[];
+    hasUniqueViolations(type: string, index: string[]): boolean;
+    getUniqueViolation(type: string, index: string[], key: OKDBPrimaryKey): unknown;
+
+    // ── Change tracking ───────────────────────────────────────────────────────
+    getClock(type?: string, options?: Record<string, unknown>): number;
+    getChanges(type?: string, from?: number, to?: number, options?: Record<string, unknown>): Iterable<OKDBChangeEntry>;
+
+    // ── TTL ───────────────────────────────────────────────────────────────────
+    setTTL(type: string, key: OKDBPrimaryKey, ttlMs: number): Promise<void>;
+    getTTL(type: string, key: OKDBPrimaryKey): number | null;
+    clearTTL(type: string, key: OKDBPrimaryKey): Promise<void>;
+    sweepExpiredTTL(batchSize?: number): Promise<number>;
+    listTTL(options?: OKDBTtlListOptions): Iterable<{ type: string; key: OKDBPrimaryKey; expiresAt: number }>;
+    ttlStats(type?: string): unknown;
+    setDefaultTTL(type: string, ttlMs: number): Promise<void>;
+    getDefaultTTL(type: string): number | null;
+    clearDefaultTTL(type: string): Promise<void>;
+
+    // ── Utilities ─────────────────────────────────────────────────────────────
+    count(iterable: Iterable<unknown>): number;
+    range(iterable: Iterable<unknown>): Generator<unknown>;
+    now(): number;
+    equal(a: unknown, b: unknown): boolean;
+    getResolvedOptions(): { durability: string; lmdbOptions: unknown; warnings: string[] };
+}
+
+export default OKDB;

package/types/options.d.ts

@@ -0,0 +1,202 @@
+// Core option types and data shapes
+
+export type OKDBPrimaryKey = string | number;
+export type OKDBIndexKey = Array<string | number | null | Buffer>;
+export type OKDBFilter = Record<string, unknown>;
+
+// ── Constructor options ───────────────────────────────────────────────────────
+
+export interface OKDBOptions {
+    maxDbs?: number;
+    pageSize?: number;
+    compression?: boolean;
+    encryptionKey?: string | Buffer;
+    mapSize?: number;
+    durability?: 'strict' | 'balanced' | 'fast' | 'custom';
+    allowUnsafe?: boolean;
+    lmdb?: Record<string, unknown>;
+    auth?: OKDBAuthOptions;
+    sync?: OKDBSyncOptions;
+    queue?: OKDBQueueOptions;
+    bus?: boolean | Record<string, unknown>;
+    functions?: Record<string, unknown>;
+    timeMachine?: OKDBTimeMachineOptions;
+    runtimeDeclarations?: boolean;
+    log?: { retainDays?: number };
+    shutdownTimeout?: number;
+}
+
+export interface OKDBAuthOptions {
+    open?: boolean | string | string[];
+    session?: { secure?: boolean; sameSite?: 'Lax' | 'Strict' | 'None' };
+    token?: { secret?: string; ttl?: number };
+    oauth?: OKDBOAuthConfig;
+    providers?: Record<string, OKDBOAuthProviderConfig>;
+}
+
+export interface OKDBOAuthConfig {
+    providerLabel?: string;
+    issuer?: string;
+    clientId?: string;
+    scopes?: string[];
+    [key: string]: unknown;
+}
+
+export interface OKDBOAuthProviderConfig {
+    issuer: string;
+    clientId: string;
+    scopes?: string[];
+    [key: string]: unknown;
+}
+
+export interface OKDBSyncOptions {
+    address?: string;
+    delta_limit?: number;
+    reconcile_concurrency?: number;
+    auto_reconcile?: boolean;
+    gcPeerStalenessLimitDays?: number;
+    gcIntervalMs?: number;
+    [key: string]: unknown;
+}
+
+export interface OKDBQueueOptions {
+    default_ttl?: number;
+    claim_batch_limit?: number;
+    reconcile_batch_limit?: number;
+    default_bucket_tokens?: number;
+    default_max_tries?: number | null;
+    default_retry_delay?: number;
+    default_backoff_multiplier?: number;
+    cron_next?: ((cronExpr: string, fromTimestamp: number) => number) | null;
+    done_ttl?: number | null;
+    failed_ttl?: number | null;
+    [key: string]: unknown;
+}
+
+export interface OKDBTimeMachineOptions {
+    [key: string]: unknown;
+}
+
+export interface OKDBEnvironmentConfig {
+    sync?: boolean;
+    durability?: 'strict' | 'balanced' | 'fast' | 'custom';
+    lmdb?: Record<string, unknown>;
+    compression?: boolean;
+    encryptionKey?: string | Buffer;
+    parentEnv?: string;
+    [key: string]: unknown;
+}
+
+// ── Query and range options ───────────────────────────────────────────────────
+
+export interface OKDBRangeOptions {
+    start?: OKDBPrimaryKey;
+    end?: OKDBPrimaryKey;
+    limit?: number;
+    reverse?: boolean;
+    offset?: number;
+    snapshot?: boolean;
+}
+
+export interface OKDBQueryOptions {
+    index?: string[];
+    prefix?: OKDBIndexKey;
+    start?: OKDBIndexKey;
+    end?: OKDBIndexKey;
+    startIndex?: OKDBIndexKey;
+    limit?: number;
+    reverse?: boolean;
+    offset?: number;
+}
+
+export interface OKDBGeoQueryOptions {
+    lat: number;
+    lon: number;
+    radius?: number;
+    limit?: number;
+    reverse?: boolean;
+}
+
+export interface OKDBFtsQueryOptions {
+    limit?: number;
+    offset?: number;
+    [key: string]: unknown;
+}
+
+export interface OKDBWriteOptions {
+    ifVersion?: number;
+    timestamp?: number;
+    ttl?: number;
+}
+
+// ── Result shapes ─────────────────────────────────────────────────────────────
+
+export interface OKDBEntry<T = unknown> {
+    key: OKDBPrimaryKey;
+    value: T;
+    version: number;
+}
+
+export interface OKDBIndexEntry<T = unknown> extends OKDBEntry<T> {
+    indexKey: OKDBIndexKey;
+}
+
+export interface OKDBChangeEntry {
+    clock: number;
+    origin: string;
+    type: string;
+    key: OKDBPrimaryKey;
+    action: string;
+    version?: number;
+    timestamp: number;
+    newValue?: unknown;
+    oldValue?: unknown;
+    txnId?: string;
+}
+
+export interface OKDBIndexDefinition {
+    fields: string[];
+    type?: 'geo';
+    precision?: number;
+    unique?: boolean;
+}
+
+export interface OKDBTypeSchema {
+    definition: Record<string, unknown>;
+    enforce?: boolean;
+}
+
+export interface OKDBCompactResult {
+    ok: boolean;
+    sizeBefore: number;
+    sizeAfter: number;
+    saved: number;
+    savedPct: number;
+}
+
+export interface OKDBRemoveEnvironmentResult {
+    ok: boolean;
+    name: string;
+    filesRemoved: string[];
+    filesLocked: string[];
+    keptSubEnvs?: string[];
+}
+
+export interface OKDBTtlListOptions {
+    limit?: number;
+    reverse?: boolean;
+}
+
+export interface OKDBInfoResult {
+    id: string;
+    pageSize: number;
+    lastPageNumber: number;
+    mapSize: number;
+    clock: number;
+    plugins: string[];
+    versions: { okdb: string; lmdb: string | null; lmdbNative: string };
+    version: string;
+    ttl: unknown;
+    types: Record<string, unknown>;
+    config: unknown;
+}