@geodedb/client 1.0.2 → 1.1.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as tls from 'node:tls';
+import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import { Decimal } from 'decimal.js-light';
 export { default as Decimal } from 'decimal.js-light';
 
@@ -79,6 +80,16 @@ interface GeodeConfig {
     tls?: boolean;
     /** Graph name for DSN graph binding. When set, the server binds the session to this graph. */
     graph?: string;
+    /**
+     * Tenant identifier sent in the HELLO handshake (proto field 3). Required for
+     * multi-tenant deployments so the server scopes the session to this tenant.
+     */
+    tenant?: string;
+    /**
+     * FLE role sent in the HELLO handshake (proto field 8). Selects the
+     * field-level-encryption role for the session when set.
+     */
+    role?: string;
 }
 /**
  * Connection pool configuration.
@@ -122,6 +133,9 @@ declare function defaultConfig(): GeodeConfig;
  *   - server_name: SNI server name
  *   - connect_timeout: Connection timeout in ms
  *   - request_timeout: Request timeout in ms
+ *   - graph: Graph to bind the session to
+ *   - tenant/tenant_id: Tenant identifier for multi-tenant deployments
+ *   - role: FLE role for field-level access control
  *
  * Environment variables (used as defaults):
  *   - GEODE_HOST: Default host
@@ -129,6 +143,8 @@ declare function defaultConfig(): GeodeConfig;
  *   - GEODE_TLS_CA: Default CA certificate path
  *   - GEODE_USERNAME: Default username
  *   - GEODE_PASSWORD: Default password
+ *   - GEODE_TENANT: Default tenant identifier
+ *   - GEODE_ROLE: Default FLE role
  *   - GEODE_TRANSPORT: Default transport type (quic or grpc)
  */
 declare function parseDSN(dsn: string): GeodeConfig;
@@ -140,6 +156,13 @@ declare function validateConfig(cfg: GeodeConfig): void;
  * Get the server address in host:port format.
  */
 declare function getAddress(cfg: GeodeConfig): string;
+/**
+ * Serialise a GeodeConfig back to a DSN string. Inverse of parseDSN: only
+ * non-default values are emitted as query parameters to keep the DSN minimal.
+ * Credentials go in the userinfo segment when both username and password are
+ * present; a lone username uses userinfo, a lone password uses a `pass` param.
+ */
+declare function formatDSN(cfg: GeodeConfig): string;
 /**
  * Clone configuration.
  */
@@ -275,6 +298,8 @@ declare class StateError extends Error implements GeodeError {
  * Connection state enumeration.
  */
 type ConnectionState = 'idle' | 'executing' | 'in_transaction' | 'fetching' | 'closed' | 'error';
+declare const ERR_INVALID_IDENT_MESSAGE = "geode: identifier contains forbidden characters";
+declare const ERR_INVALID_STRING_MESSAGE = "geode: string literal contains forbidden characters";
 declare const ERR_CLOSED_MESSAGE = "geode: connection closed";
 declare const ERR_QUERY_IN_PROGRESS_MESSAGE = "geode: query already in progress";
 declare const ERR_TX_IN_PROGRESS_MESSAGE = "geode: transaction already in progress";
@@ -282,6 +307,9 @@ declare const ERR_NO_TX_MESSAGE = "geode: no transaction in progress";
 declare const ERR_TX_DONE_MESSAGE = "geode: transaction already committed or rolled back";
 declare const ERR_ROWS_CLOSED_MESSAGE = "geode: rows closed";
 declare const ERR_BAD_CONN_MESSAGE = "geode: bad connection";
+declare const ERR_NO_ROWS_MESSAGE = "geode: no rows in result set";
+declare function ErrInvalidIdent(): Error;
+declare function ErrInvalidString(): Error;
 declare function ErrClosed(): Error;
 declare function ErrQueryInProgress(): Error;
 declare function ErrTxInProgress(): Error;
@@ -289,6 +317,7 @@ declare function ErrNoTx(): Error;
 declare function ErrTxDone(): Error;
 declare function ErrRowsClosed(): Error;
 declare function ErrBadConn(): Error;
+declare function ErrNoRows(): Error;
 /**
  * Check if an error is a specific sentinel error by message.
  */
@@ -305,282 +334,664 @@ declare function isGeodeError(err: unknown): err is GeodeError;
  * Check if an error is retryable.
  */
 declare function isRetryableError(err: unknown): boolean;
-
 /**
- * Geode Protobuf Wire Protocol
- *
- * Uses protobufjs for encoding/decoding protocol messages.
- * Wire format for QUIC: 4-byte Big Endian length prefix + protobuf message body.
+ * Reports whether `err` is a Geode authentication/authorization failure
+ * (GQL status class 28000 or the Geode-specific 08P01 password-reset
+ * extension). Returns false for null and for non-driver errors.
+ */
+declare function isAuthError(err: unknown): boolean;
+/**
+ * Reports whether `err` is a GQL parse/syntax error (status class 42000).
+ * Returns false for null and for non-driver errors.
+ */
+declare function isSyntaxError(err: unknown): boolean;
+
+declare enum IntKind {
+    INT_KIND_UNSPECIFIED = 0,
+    INT = 1,
+    SMALLINT = 2,
+    BIGINT = 3
+}
+declare enum FloatKind {
+    FLOAT_KIND_UNSPECIFIED = 0,
+    DOUBLE = 1,
+    REAL = 2
+}
+declare enum StringKind {
+    STRING_KIND_UNSPECIFIED = 0,
+    STRING = 1,
+    CHAR = 2,
+    VARCHAR = 3,
+    TEXT = 4
+}
+declare enum BytesKind {
+    BYTES_KIND_UNSPECIFIED = 0,
+    BYTEA = 1,
+    RAW = 2
+}
+/**
+ * ============================================================================
+ * QUIC Messages
+ * ============================================================================
+ */
+interface QuicClientMessage {
+    hello?: HelloRequest | undefined;
+    execute?: ExecuteRequest | undefined;
+    pull?: PullRequest | undefined;
+    ping?: PingRequest | undefined;
+    cdcDiag?: CdcDiagnosticsRequest | undefined;
+    cdcCtrl?: CdcControlRequest | undefined;
+    begin?: BeginRequest | undefined;
+    commit?: CommitRequest | undefined;
+    rollback?: RollbackRequest | undefined;
+    savepoint?: SavepointRequest | undefined;
+    rollbackTo?: RollbackToRequest | undefined;
+    backup?: BackupRequest | undefined;
+    restore?: RestoreRequest | undefined;
+    uploadBackup?: UploadBackupRequest | undefined;
+}
+declare const QuicClientMessage: MessageFns<QuicClientMessage>;
+interface QuicServerMessage {
+    hello?: HelloResponse | undefined;
+    execute?: ExecutionResponse | undefined;
+    pull?: PullResponse | undefined;
+    ping?: PingResponse | undefined;
+    cdcDiag?: CdcDiagnosticsResponse | undefined;
+    cdcCtrl?: CdcControlResponse | undefined;
+    begin?: BeginResponse | undefined;
+    commit?: CommitResponse | undefined;
+    rollback?: RollbackResponse | undefined;
+    savepoint?: SavepointResponse | undefined;
+    rollbackTo?: RollbackToResponse | undefined;
+    backup?: BackupResponse | undefined;
+    restore?: RestoreResponse | undefined;
+    uploadBackup?: UploadBackupResponse | undefined;
+}
+declare const QuicServerMessage: MessageFns<QuicServerMessage>;
+/**
+ * ============================================================================
+ * Authentication (HELLO)
+ * ============================================================================
  */
 interface HelloRequest {
     username: string;
     password: string;
-    tenantId?: string;
+    tenantId?: string | undefined;
     clientName: string;
     clientVersion: string;
     wantedConformance: string;
-    graph?: string;
+    graph?: string | undefined;
+    /** FLE role for field-level access control */
+    role?: string | undefined;
 }
+declare const HelloRequest: MessageFns<HelloRequest>;
 interface HelloResponse {
     success: boolean;
     sessionId: string;
     errorMessage: string;
     capabilities: string[];
-    passwordResetRequired?: boolean;
-    graph?: string;
-}
-interface Param {
-    name: string;
-    value: ProtoValue;
+    passwordResetRequired: boolean;
+    graph?: string | undefined;
 }
+declare const HelloResponse: MessageFns<HelloResponse>;
+/**
+ * ============================================================================
+ * Query Execution (RUN_GQL + PULL)
+ * ============================================================================
+ */
 interface ExecuteRequest {
     sessionId: string;
     query: string;
     params: Param[];
 }
+declare const ExecuteRequest: MessageFns<ExecuteRequest>;
+interface Param {
+    name: string;
+    value?: Value | undefined;
+}
+declare const Param: MessageFns<Param>;
 interface PullRequest {
-    requestId: bigint | number;
+    requestId: number;
     pageSize: number;
+    /** Required for gRPC; ignored for QUIC */
     sessionId: string;
 }
+declare const PullRequest: MessageFns<PullRequest>;
 interface PullResponse {
-    response?: ExecutionResponse;
+    response?: ExecutionResponse | undefined;
 }
+declare const PullResponse: MessageFns<PullResponse>;
+/**
+ * ============================================================================
+ * Execution Responses
+ * ============================================================================
+ */
 interface Status {
+    /** e.g., "00000" */
     statusClass: string;
     statusSubclass: string;
     additionalStatuses: string[];
     flaggerFindings: string[];
 }
+declare const Status: MessageFns<Status>;
+interface ExecutionResponse {
+    status?: Status | undefined;
+    schema?: SchemaDefinition | undefined;
+    page?: DataPage | undefined;
+    error?: Error$1 | undefined;
+    metrics?: ExecutionMetrics | undefined;
+    explain?: ExplainPayload | undefined;
+    profile?: ProfilePayload | undefined;
+    heartbeat?: Heartbeat | undefined;
+}
+declare const ExecutionResponse: MessageFns<ExecutionResponse>;
+interface SchemaDefinition {
+    columns: ColumnDefinition[];
+}
+declare const SchemaDefinition: MessageFns<SchemaDefinition>;
 interface ColumnDefinition {
     name: string;
     type: string;
 }
-interface SchemaDefinition {
-    columns: ColumnDefinition[];
-}
-interface ProtoValue {
-    nullVal?: NullValue;
-    intVal?: IntValue;
-    doubleVal?: DoubleValue;
-    boolVal?: boolean;
-    stringVal?: StringValue;
-    decimalVal?: DecimalValue;
-    bytesVal?: BytesValue;
-    listVal?: ListValue;
-    mapVal?: MapValue;
-    nodeVal?: NodeValue;
-    edgeVal?: EdgeValue;
-    pathVal?: PathValue;
-    extVal?: ExtendedValue;
+declare const ColumnDefinition: MessageFns<ColumnDefinition>;
+interface DataPage {
+    rows: Row$1[];
+    final: boolean;
+    ordered: boolean;
+    orderKeys: string[];
 }
+declare const DataPage: MessageFns<DataPage>;
+interface Row$1 {
+    values: Value[];
+}
+declare const Row$1: MessageFns<Row$1>;
+/**
+ * ----------------------------------------------------------------------------
+ * Value Encoding
+ * ----------------------------------------------------------------------------
+ */
+interface Value {
+    nullVal?: NullValue | undefined;
+    intVal?: IntValue | undefined;
+    doubleVal?: DoubleValue | undefined;
+    boolVal?: boolean | undefined;
+    stringVal?: StringValue | undefined;
+    decimalVal?: DecimalValue | undefined;
+    bytesVal?: BytesValue | undefined;
+    listVal?: ListValue | undefined;
+    mapVal?: MapValue | undefined;
+    nodeVal?: NodeValue | undefined;
+    edgeVal?: EdgeValue | undefined;
+    pathVal?: PathValue | undefined;
+    extVal?: ExtendedValue | undefined;
+}
+declare const Value: MessageFns<Value>;
 interface NullValue {
 }
+declare const NullValue: MessageFns<NullValue>;
 interface IntValue {
-    value: bigint | number;
-    kind: number;
+    value: number;
+    kind: IntKind;
 }
+declare const IntValue: MessageFns<IntValue>;
 interface DoubleValue {
     value: number;
-    kind: number;
+    kind: FloatKind;
 }
+declare const DoubleValue: MessageFns<DoubleValue>;
 interface StringValue {
     value: string;
-    kind: number;
+    kind: StringKind;
 }
+declare const StringValue: MessageFns<StringValue>;
 interface DecimalValue {
+    /** i128 as decimal string */
     coeff: string;
     scale: number;
     origScale: number;
     origRepr: string;
 }
+declare const DecimalValue: MessageFns<DecimalValue>;
 interface BytesValue {
     value: Uint8Array;
-    kind: number;
+    kind: BytesKind;
 }
+declare const BytesValue: MessageFns<BytesValue>;
 interface ListValue {
-    values: ProtoValue[];
+    values: Value[];
 }
+declare const ListValue: MessageFns<ListValue>;
 interface MapEntry {
     key: string;
-    value: ProtoValue;
+    value?: Value | undefined;
 }
+declare const MapEntry: MessageFns<MapEntry>;
 interface MapValue {
     entries: MapEntry[];
 }
+declare const MapValue: MessageFns<MapValue>;
 interface NodeValue {
-    id: bigint | number;
+    id: number;
     labels: string[];
     properties: MapEntry[];
 }
+declare const NodeValue: MessageFns<NodeValue>;
 interface EdgeValue {
-    id: bigint | number;
-    fromId: bigint | number;
-    toId: bigint | number;
+    id: number;
+    fromId: number;
+    toId: number;
     label: string;
     properties: MapEntry[];
 }
+declare const EdgeValue: MessageFns<EdgeValue>;
 interface PathValue {
     nodes: NodeValue[];
     edges: EdgeValue[];
 }
+declare const PathValue: MessageFns<PathValue>;
 interface ExtendedValue {
     typeName: string;
-    text?: string;
-    bytes?: Uint8Array;
-    intVal?: bigint | number;
-    doubleVal?: number;
-    boolVal?: boolean;
-}
-interface Row$1 {
-    values: ProtoValue[];
-}
-interface DataPage {
-    rows: Row$1[];
-    final: boolean;
-    ordered: boolean;
-    orderKeys: string[];
-}
-interface ProtoError {
+    text?: string | undefined;
+    bytes?: Uint8Array | undefined;
+    intVal?: number | undefined;
+    doubleVal?: number | undefined;
+    boolVal?: boolean | undefined;
+}
+declare const ExtendedValue: MessageFns<ExtendedValue>;
+interface Error$1 {
     code: string;
     message: string;
+    /** "ERROR" */
     type: string;
     anchor: string;
 }
+declare const Error$1: MessageFns<Error$1>;
 interface ExecutionMetrics {
-    parseDurationNs: bigint | number;
-    planDurationNs: bigint | number;
-    executeDurationNs: bigint | number;
-    totalDurationNs: bigint | number;
-}
+    parseDurationNs: number;
+    planDurationNs: number;
+    executeDurationNs: number;
+    totalDurationNs: number;
+}
+declare const ExecutionMetrics: MessageFns<ExecutionMetrics>;
+interface ExplainOp {
+    idx: number;
+    kind: string;
+    estRows: number;
+    cost: number;
+}
+declare const ExplainOp: MessageFns<ExplainOp>;
 interface ExplainTotals {
-    cost?: number;
-    est_rows?: number;
+    estRows: number;
+    cost: number;
 }
+declare const ExplainTotals: MessageFns<ExplainTotals>;
+interface ExplainProperties {
+    ordered: boolean;
+    limit: number;
+    offset: number;
+    distinct: boolean;
+    unionMode: string;
+    unionPartCount: number;
+}
+declare const ExplainProperties: MessageFns<ExplainProperties>;
+interface ExplainCalibrationEntry {
+    idx: number;
+    estRows: number;
+    actualRows: number;
+}
+declare const ExplainCalibrationEntry: MessageFns<ExplainCalibrationEntry>;
+interface ExplainCalibration {
+    mape: number;
+    entries: ExplainCalibrationEntry[];
+}
+declare const ExplainCalibration: MessageFns<ExplainCalibration>;
 interface ExplainPayload {
     schema: string;
-    ops: unknown[];
-    totals?: ExplainTotals;
-    properties: unknown;
-    calibration: unknown;
+    ops: ExplainOp[];
+    totals?: ExplainTotals | undefined;
+    properties?: ExplainProperties | undefined;
+    calibration?: ExplainCalibration | undefined;
     profileVersion: number;
 }
+declare const ExplainPayload: MessageFns<ExplainPayload>;
+interface ProfileOp {
+    op: string;
+    phase: string;
+    id: number;
+    opIndex: number;
+    inputRows: number;
+    rows: number;
+    timeNs: number;
+    cpuTimeNs: number;
+    bytesOut: number;
+    bytesAlloc: number;
+    estimateBytes: number;
+    estimateVsActual: number;
+    percentPeak: number;
+    percentNet: number;
+    cumulativeTimeNs: number;
+    freedBytes: number;
+    netAfterOp: number;
+    errorBytes: number;
+    errorAbsPct: number;
+    indexName: string;
+    selectivityEst: number;
+}
+declare const ProfileOp: MessageFns<ProfileOp>;
+interface ProfilePeakContributor {
+    op: string;
+    bytesAlloc: number;
+}
+declare const ProfilePeakContributor: MessageFns<ProfilePeakContributor>;
+interface ProfileTotals {
+    timeNs: number;
+    peakBytes: number;
+}
+declare const ProfileTotals: MessageFns<ProfileTotals>;
+interface ProfileSpills {
+    sortSpills: number;
+    distinctSpills: number;
+    unionSpills: number;
+    spillReason: string;
+    peakBytesAtSpill: number;
+    firstSpillOpIndex: number;
+}
+declare const ProfileSpills: MessageFns<ProfileSpills>;
 interface ProfileMemory {
-    netBytes?: number | bigint;
-    peakBytes?: number | bigint;
-    totalAllocBytes?: number | bigint;
+    netBytes: number;
+    peakBytes: number;
+    totalAllocBytes: number;
+}
+declare const ProfileMemory: MessageFns<ProfileMemory>;
+interface ProfilePlannerEstimates {
+    sumEstimateBytes: number;
+    sumActualBytes: number;
+    countEstimatedOps: number;
+    minErrorAbsPct: number;
+    maxErrorAbsPct: number;
+    meanErrorAbsPct: number;
+    medianErrorAbsPct: number;
+    stddevErrorAbsPct: number;
+    adjustedEstimateFactor: number;
+}
+declare const ProfilePlannerEstimates: MessageFns<ProfilePlannerEstimates>;
+interface ProfileMemCurvePoint {
+    opIndex: number;
+    netAfterOp: number;
+}
+declare const ProfileMemCurvePoint: MessageFns<ProfileMemCurvePoint>;
+interface ProfileSetOp {
+    type: string;
+    mode: string;
+    inputRows: number;
+    outputRows: number;
+    hashDedupSize: number;
+    distinctFillPct: number;
 }
+declare const ProfileSetOp: MessageFns<ProfileSetOp>;
 interface ProfilePayload {
     profileVersion: number;
-    ops: unknown[];
-    peakContributors: unknown[];
-    totals: unknown;
-    totalTimeNs: bigint | number;
-    spills: unknown;
-    memory?: ProfileMemory;
-    plannerEstimates: unknown;
-    memCurve: unknown[];
-    setop: unknown;
-    hashaggSpills: bigint | number;
+    ops: ProfileOp[];
+    peakContributors: ProfilePeakContributor[];
+    totals?: ProfileTotals | undefined;
+    totalTimeNs: number;
+    spills?: ProfileSpills | undefined;
+    memory?: ProfileMemory | undefined;
+    plannerEstimates?: ProfilePlannerEstimates | undefined;
+    memCurve: ProfileMemCurvePoint[];
+    setop?: ProfileSetOp | undefined;
+    hashaggSpills: number;
     hashaggSpillReason: string;
-    committedTxns: bigint | number;
-    graphStoreNodes: bigint | number;
-    graphStoreEdges: bigint | number;
+    committedTxns: number;
+    graphStoreNodes: number;
+    graphStoreEdges: number;
     graphStoreDirty: boolean;
     flaggerFindings: string[];
     compact: boolean;
 }
+declare const ProfilePayload: MessageFns<ProfilePayload>;
 interface Heartbeat {
 }
-interface ExecutionResponse {
-    status?: Status;
-    schema?: SchemaDefinition;
-    page?: DataPage;
-    error?: ProtoError;
-    metrics?: ExecutionMetrics;
-    explain?: ExplainPayload;
-    profile?: ProfilePayload;
-    heartbeat?: Heartbeat;
-}
+declare const Heartbeat: MessageFns<Heartbeat>;
+/**
+ * ============================================================================
+ * Utilities (PING)
+ * ============================================================================
+ */
 interface PingRequest {
 }
+declare const PingRequest: MessageFns<PingRequest>;
 interface PingResponse {
     ok: boolean;
 }
+declare const PingResponse: MessageFns<PingResponse>;
+/**
+ * ============================================================================
+ * Transactions
+ * ============================================================================
+ */
 interface BeginRequest {
     readOnly: boolean;
+    /** Required for gRPC; ignored for QUIC */
     sessionId: string;
 }
+declare const BeginRequest: MessageFns<BeginRequest>;
 interface BeginResponse {
     sessionId: string;
     txId: string;
 }
+declare const BeginResponse: MessageFns<BeginResponse>;
 interface CommitRequest {
+    /** Required for gRPC; ignored for QUIC */
     sessionId: string;
 }
+declare const CommitRequest: MessageFns<CommitRequest>;
 interface CommitResponse {
     success: boolean;
 }
+declare const CommitResponse: MessageFns<CommitResponse>;
 interface RollbackRequest {
+    /** Required for gRPC; ignored for QUIC */
     sessionId: string;
 }
+declare const RollbackRequest: MessageFns<RollbackRequest>;
 interface RollbackResponse {
     success: boolean;
 }
+declare const RollbackResponse: MessageFns<RollbackResponse>;
 interface SavepointRequest {
     name: string;
+    /** Required for gRPC; ignored for QUIC */
     sessionId: string;
 }
+declare const SavepointRequest: MessageFns<SavepointRequest>;
 interface SavepointResponse {
     success: boolean;
 }
+declare const SavepointResponse: MessageFns<SavepointResponse>;
 interface RollbackToRequest {
     name: string;
+    /** Required for gRPC; ignored for QUIC */
     sessionId: string;
 }
+declare const RollbackToRequest: MessageFns<RollbackToRequest>;
 interface RollbackToResponse {
     success: boolean;
 }
-interface QuicClientMessage {
-    hello?: HelloRequest;
-    execute?: ExecuteRequest;
-    pull?: PullRequest;
-    ping?: PingRequest;
-    cdcDiag?: unknown;
-    cdcCtrl?: unknown;
-    begin?: BeginRequest;
-    commit?: CommitRequest;
-    rollback?: RollbackRequest;
-    savepoint?: SavepointRequest;
-    rollbackTo?: RollbackToRequest;
-    backup?: unknown;
-    restore?: unknown;
-    uploadBackup?: unknown;
+declare const RollbackToResponse: MessageFns<RollbackToResponse>;
+/**
+ * ============================================================================
+ * CDC
+ * ============================================================================
+ */
+interface CdcDiagnosticsRequest {
 }
-interface QuicServerMessage {
-    hello?: HelloResponse;
-    execute?: ExecutionResponse;
-    pull?: PullResponse;
-    ping?: PingResponse;
-    cdcDiag?: unknown;
-    cdcCtrl?: unknown;
-    begin?: BeginResponse;
-    commit?: CommitResponse;
-    rollback?: RollbackResponse;
-    savepoint?: SavepointResponse;
-    rollbackTo?: RollbackToResponse;
-    backup?: unknown;
-    restore?: unknown;
-    uploadBackup?: unknown;
+declare const CdcDiagnosticsRequest: MessageFns<CdcDiagnosticsRequest>;
+interface CdcDiagnosticsConfig {
+    enabled: boolean;
+    malformedSnapshotInterval: number;
+    malformedHashRetain: number;
+    malformedWarnPct: number;
+    malformedAbortPct: number;
+    flushIntervalMs: number;
+    batchSize: number;
+    pendingBackpressureWatermark: number;
+}
+declare const CdcDiagnosticsConfig: MessageFns<CdcDiagnosticsConfig>;
+interface CdcDiagnosticsEngine {
+    isRunning: boolean;
+    lastFlushMs: number;
+    peakBuffer: number;
+    currentBuffer: number;
+    dynamicBatchSize: number;
+    batchAdjustments: number;
+}
+declare const CdcDiagnosticsEngine: MessageFns<CdcDiagnosticsEngine>;
+interface CdcMalformedSnapshot {
+    count: number;
+    tsMs: number;
+}
+declare const CdcMalformedSnapshot: MessageFns<CdcMalformedSnapshot>;
+interface CdcMalformedHash {
+    count: number;
+    hash: number;
+    tsMs: number;
+    prefixHex: string;
+}
+declare const CdcMalformedHash: MessageFns<CdcMalformedHash>;
+interface CdcDiagnosticsResponse {
+    malformedChangeRecords: number;
+    totalChangeAttempts: number;
+    malformedRatio: number;
+    guardrailWarnTriggered: boolean;
+    guardrailAbortTriggered: boolean;
+    firstWarnTsMs: number;
+    firstAbortTsMs: number;
+    guardrailEpoch: number;
+    uptimeMs: number;
+    backpressure: boolean;
+    config?: CdcDiagnosticsConfig | undefined;
+    engine?: CdcDiagnosticsEngine | undefined;
+    malformedSnapshots: CdcMalformedSnapshot[];
+    malformedHashes: CdcMalformedHash[];
+    version: string;
+    timestampMs: number;
+}
+declare const CdcDiagnosticsResponse: MessageFns<CdcDiagnosticsResponse>;
+interface CdcControlRequest {
+    action: string;
+}
+declare const CdcControlRequest: MessageFns<CdcControlRequest>;
+interface CdcControlResponse {
+    success: boolean;
+    status: string;
+    guardrailEpoch: number;
 }
+declare const CdcControlResponse: MessageFns<CdcControlResponse>;
+/**
+ * ============================================================================
+ * Backup / Restore
+ * ============================================================================
+ */
+interface BackupRequest {
+    /** "full" */
+    backupType: string;
+    sessionId: string;
+    compress: boolean;
+}
+declare const BackupRequest: MessageFns<BackupRequest>;
+interface BackupResponse {
+    success: boolean;
+    message: string;
+    backupId: string;
+    backupType: string;
+    sizeBytes: number;
+    compression: string;
+    checksum: string;
+}
+declare const BackupResponse: MessageFns<BackupResponse>;
+interface RestoreRequest {
+    targetTime: string;
+    confirm: boolean;
+    sessionId: string;
+}
+declare const RestoreRequest: MessageFns<RestoreRequest>;
+interface RestoreResponse {
+    success: boolean;
+    message: string;
+    restoreDir: string;
+    targetTime: string;
+    restoreTimestamp: number;
+}
+declare const RestoreResponse: MessageFns<RestoreResponse>;
+interface UploadBackupRequest {
+    sizeBytes: number;
+    checksum: string;
+    sessionId: string;
+    /**
+     * GAP-0880: full backup artifact bytes (GEOB header + payload). Required;
+     * metadata-only uploads are rejected by the server.
+     */
+    payload: Uint8Array;
+}
+declare const UploadBackupRequest: MessageFns<UploadBackupRequest>;
+interface UploadBackupResponse {
+    success: boolean;
+    message: string;
+    uploadPath: string;
+}
+declare const UploadBackupResponse: MessageFns<UploadBackupResponse>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}
+
+/**
+ * Geode Protobuf Wire Protocol
+ *
+ * Encoding/decoding of protocol messages using the protoc + ts-proto generated
+ * bindings (src/generated/geode.ts), which are produced from the canonical
+ * geode server proto. This eliminates proto drift: there are no longer any
+ * hand-written message interfaces, and the proto is no longer parsed at runtime
+ * via protobufjs.
+ *
+ * Wire format for QUIC: 4-byte Big Endian length prefix + protobuf message body.
+ *
+ * The public API (the build/encode/decode/value-conversion helpers and the
+ * exported types) is preserved exactly. Legacy type names that differ from the
+ * proto message names are aliased: the proto `Value` message is exported as
+ * `ProtoValue`, and the proto `Error` message as `ProtoError`.
+ */
+
+/** A protobuf `Value` message (alias preserved for API stability). */
+type ProtoValue = Value;
+/** A protobuf `Error` message (alias preserved for API stability). */
+type ProtoError = Error$1;
 /**
  * Initialize protobuf types synchronously.
- * Safe to call multiple times; only loads on first call.
- * Prefer ensureProtoInitialized() in async contexts to avoid blocking the event loop.
+ *
+ * No-op: bindings are generated at build time (protoc + ts-proto) and statically
+ * imported, so no runtime initialization is required. Retained for API stability.
  */
 declare function initProtoSync(): void;
 /**
  * Ensure proto is initialized.
+ *
+ * No-op: see {@link initProtoSync}. Retained for API stability.
  */
 declare function ensureProtoInitialized(): Promise<void>;
 /**
@@ -610,7 +1021,7 @@ declare function decodeLengthPrefix(data: Buffer): number;
 /**
  * Build a HelloRequest message.
  */
-declare function buildHelloRequest(username: string, password: string, clientName: string, clientVersion: string, conformance: string, tenantId?: string, graph?: string): QuicClientMessage;
+declare function buildHelloRequest(username: string, password: string, clientName: string, clientVersion: string, conformance: string, tenantId?: string, graph?: string, role?: string): QuicClientMessage;
 /**
  * Build an ExecuteRequest message.
  */
@@ -1635,6 +2046,11 @@ declare class Connection {
     query(query: string, options?: QueryOptions): Promise<QueryResult>;
     /** Execute a query and return all rows as an array. */
     queryAll(query: string, options?: QueryOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute a query and return exactly the first row. Throws ErrNoRows when
+     * the result set is empty, mirroring database/sql's ErrNoRows.
+     */
+    queryRow(query: string, options?: QueryOptions): Promise<Record<string, unknown>>;
     /** Execute a query that doesn't return rows. */
     exec(query: string, options?: QueryOptions): Promise<void>;
     /** @internal Fetch the next page of results. Called by QueryResult. */
@@ -2268,6 +2684,11 @@ declare class ConnectionPool {
      * Execute a query and return all rows.
      */
     queryAll(query: string, options?: QueryOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute a query using a pooled connection and return the first row.
+     * Throws ErrNoRows when the result set is empty.
+     */
+    queryRow(query: string, options?: QueryOptions): Promise<Record<string, unknown>>;
     /**
      * Execute a statement that doesn't return rows.
      */
@@ -2342,6 +2763,32 @@ declare function defaultRetryPolicy(): RetryPolicy;
  */
 declare function withRetry<T>(fn: () => Promise<T>, policy?: RetryPolicy): Promise<T>;
 
+/**
+ * GQL Quoting Helpers
+ *
+ * Ports geode-client-go quote.go: safe inlining of identifiers, string
+ * literals, and graph names into GQL admin statements.
+ */
+/**
+ * Return `name` stripped of any character that is not alphanumeric, underscore,
+ * or hyphen, so it can be inlined safely into a USE GRAPH statement.
+ */
+declare function sanitizeGraphName(name: string): string;
+/**
+ * Validate and return `name` in a form safe to inline into a GQL admin
+ * statement that takes an identifier. Valid identifiers consist of letters,
+ * digits, underscore, and hyphen, and must not start with a hyphen. Digits are
+ * permitted at any position. Throws ErrInvalidIdent for empty or invalid input.
+ */
+declare function quoteIdent(name: string): string;
+/**
+ * Return `s` wrapped in GQL single quotes with backslashes and single quotes
+ * escaped. ASCII control characters (< 0x20 or 0x7F) are rejected with
+ * ErrInvalidString. Escape order: backslash first (\ -> \\), then single
+ * quotes (' -> '').
+ */
+declare function quoteString(s: string): string;
+
 /**
  * gRPC Transport Layer
  *
@@ -2882,4 +3329,97 @@ declare function node(): NodePatternBuilder;
  */
 declare function edge(): EdgePatternBuilder;
 
-export { AuthClient, BaseTransport, type BatchOptions, type BatchQuery, type BatchResult, type BatchSummary, type BeginRequest, type BeginResponse, type ClientOptions, type ColumnDef, type ColumnDefinition, type ColumnInfo, type CommitRequest, type CommitResponse, ConfigError, Connection, ConnectionPool, type ConnectionState, type CreateRLSPolicyOptions, type CreateRoleOptions, type CreateUserOptions, DEFAULT_CONFORMANCE, DEFAULT_GRPC_PORT, DEFAULT_HELLO_NAME, DEFAULT_HELLO_VERSION, DEFAULT_PAGE_SIZE, DEFAULT_PORT, type DSNScheme, type DataPage, DriverError, ERR_BAD_CONN_MESSAGE, ERR_CLOSED_MESSAGE, ERR_NO_TX_MESSAGE, ERR_QUERY_IN_PROGRESS_MESSAGE, ERR_ROWS_CLOSED_MESSAGE, ERR_TX_DONE_MESSAGE, ERR_TX_IN_PROGRESS_MESSAGE, type EdgeDirection, type EdgePattern, EdgePatternBuilder, ErrBadConn, ErrClosed, ErrNoTx, ErrQueryInProgress, ErrRowsClosed, ErrTxDone, ErrTxInProgress, type ExecuteRequest, type ExecutionResponse, type ExplainOptions, type GQLEdge, type GQLId, type GQLNode, type GQLPath, type GQLRange, type GQLType, GQLValue, type GQLValueKind, GeodeClient, type GeodeConfig, type GeodeError, GrpcTransport, type HelloRequest, type HelloResponse, MAX_PAGE_SIZE, MAX_QUERY_LENGTH, MockTransport, type NodePattern, NodePatternBuilder, type OperationTiming, type Param, type ParameterInfo, PatternBuilder, type PatternElement, type Permission, type PingRequest, type PingResponse, type PlanOperation, type PoolConfig, PredicateBuilder, type PredicateOp, PreparedStatement, type ProtoError, type Row$1 as ProtoRow, type ProtoValue, type PullRequest, type PullResponse, QueryBuilder, type QueryOptions, type QueryParams, type QueryPlan, type QueryProfile, QueryResult, QueryResultIterator, type QuicClientMessage, type QuicServerMessage, QuicTransport, QuicTransport as QuicheTransport, type RLSPolicy, type RawEdge, type RetryPolicy, type Role, type RollbackRequest, type RollbackResponse, type Row, SUPPORTED_SCHEMES, type SchemaDefinition, SecurityError, type SortDirection, StateError, type Status, StatusClass, type StatusClassType, Transaction, type Transport, TransportError, type TransportType, type User, batch, batchAll, batchFirst, batchMap, batchParallel, buildBeginRequest, buildCommitRequest, buildExecuteRequest, buildHelloRequest, buildPingRequest, buildPullRequest, buildRollbackRequest, buildRollbackToRequest, buildSavepointRequest, buildTLSConfig, cloneConfig, createAuthClient, createClient, createClientWithConfig, createTransport, decodeLengthPrefix, decodeQuicServerMessage, defaultConfig, defaultRetryPolicy, edge, encodeQuicClientMessage, encodeWithLengthPrefix, ensureProtoInitialized, explain, extractParameters, formatPlan, formatProfile, fromJSON, getAddress, getProtoPath, initProtoSync, isDriverError, isGeodeError, isRetryableError, isSentinelError, jsToProtoValue, node, parseDSN, parseGQLType, parseRow, pattern, predicate, prepare, profile, protoValueToJS, query, redactConfig, redactDSN, rowToObject, rowToRecord, sanitizeForLog, validateConfig, validateHostname, validatePageSize, validateParamName, validateParamValue, validatePort, validateQuery, validateSavepointName, withRetry, withTransaction };
+/**
+ * Schema Loading
+ *
+ * Ports geode-client-go schema.go: read .gql files from a directory and turn
+ * them into Statements suitable for batchExec / pipelineExec.
+ */
+/** A GQL query paired with optional bound parameters. */
+interface Statement {
+    query: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * Read all direct-child `.gql` files from `dir` and return Statements.
+ *
+ * Subdirectories are not traversed. Lines are split into statements at
+ * semicolons after stripping blank lines, line comments (`//` and `--`), and
+ * lines that do not start with a recognised GQL keyword.
+ */
+declare function parseSchemaFS(dir: string): Promise<Statement[]>;
+
+/**
+ * Pipeline / Batch Execution (GAP-0900)
+ *
+ * Ports geode-client-go batch.go PipelineExec/BatchExec:
+ *  - batchExec runs all statements inside one transaction, with retry.
+ *  - pipelineExec splits into chunks and runs up to maxWorkers concurrently;
+ *    the first error stops launching new chunks while in-flight chunks finish.
+ */
+
+/** Default number of statements per chunk in pipelineExec. */
+declare const DEFAULT_CHUNK_SIZE = 100;
+/** Default maximum number of concurrent chunk workers in pipelineExec. */
+declare const DEFAULT_MAX_WORKERS = 8;
+/** Minimal transaction surface pipelineExec needs. */
+interface PipelineTx {
+    exec(query: string, options?: {
+        params?: Record<string, unknown>;
+    }): Promise<void>;
+}
+/** Minimal pool surface pipelineExec needs (ConnectionPool satisfies this). */
+interface PipelineExecutor {
+    withTransaction<T>(fn: (tx: PipelineTx) => Promise<T>): Promise<T>;
+}
+/**
+ * Execute `stmts` inside a single transaction with automatic retry on
+ * retryable errors. An empty list is a no-op.
+ */
+declare function batchExec(pool: PipelineExecutor, stmts: Statement[]): Promise<void>;
+/**
+ * Execute `stmts` in parallel chunks. Splits into chunks of `chunkSize` and
+ * runs up to `maxWorkers` chunks concurrently; each chunk runs through
+ * batchExec. Returns the first error encountered; once an error occurs no new
+ * chunks are launched but in-flight chunks complete.
+ */
+declare function pipelineExec(pool: PipelineExecutor, stmts: Statement[], opts?: {
+    chunkSize?: number;
+    maxWorkers?: number;
+    signal?: AbortSignal;
+}): Promise<void>;
+
+/**
+ * Field-Level Encryption (FLE)
+ *
+ * Ports geode-client-go crypto/cipher.go using node:crypto:
+ *  - AES-256-GCM authenticated encryption (random 12-byte nonce, prepended).
+ *  - HKDF-SHA256 derives separate encryption and HMAC keys from a >= 32-byte
+ *    master key.
+ *  - HMAC-SHA256 hex digest for deterministic searchable encryption.
+ */
+/** Holds derived encryption and HMAC keys for field-level encryption. */
+declare class GeodeCipher {
+    private readonly encKey;
+    private readonly hmacKey;
+    /** @internal Use createCipher(). */
+    constructor(masterKey: Uint8Array);
+    /** Encrypt with AES-256-GCM, prepending a random nonce. */
+    encrypt(plaintext: Uint8Array): Buffer;
+    /** Decrypt a ciphertext produced by encrypt(). Throws on short input or auth failure. */
+    decrypt(ciphertext: Uint8Array): Buffer;
+    /** Encrypt a string, returning a base64-encoded result. */
+    encryptString(plaintext: string): string;
+    /** Base64-decode and decrypt, returning the original string. */
+    decryptString(encoded: string): string;
+    /**
+     * Compute HMAC-SHA256 of `data` using the derived HMAC key, returning a
+     * 64-char lowercase hex digest. Deterministic; use for equality lookups on
+     * encrypted fields.
+     */
+    hmacHex(data: string): string;
+}
+/** Create a GeodeCipher from a master key (>= 32 bytes). */
+declare function createCipher(masterKey: Uint8Array): GeodeCipher;
+
+export { AuthClient, BaseTransport, type BatchOptions, type BatchQuery, type BatchResult, type BatchSummary, BeginRequest, BeginResponse, type ClientOptions, type ColumnDef, ColumnDefinition, type ColumnInfo, CommitRequest, CommitResponse, ConfigError, Connection, ConnectionPool, type ConnectionState, type CreateRLSPolicyOptions, type CreateRoleOptions, type CreateUserOptions, DEFAULT_CHUNK_SIZE, DEFAULT_CONFORMANCE, DEFAULT_GRPC_PORT, DEFAULT_HELLO_NAME, DEFAULT_HELLO_VERSION, DEFAULT_MAX_WORKERS, DEFAULT_PAGE_SIZE, DEFAULT_PORT, type DSNScheme, DataPage, DriverError, ERR_BAD_CONN_MESSAGE, ERR_CLOSED_MESSAGE, ERR_INVALID_IDENT_MESSAGE, ERR_INVALID_STRING_MESSAGE, ERR_NO_ROWS_MESSAGE, ERR_NO_TX_MESSAGE, ERR_QUERY_IN_PROGRESS_MESSAGE, ERR_ROWS_CLOSED_MESSAGE, ERR_TX_DONE_MESSAGE, ERR_TX_IN_PROGRESS_MESSAGE, type EdgeDirection, type EdgePattern, EdgePatternBuilder, ErrBadConn, ErrClosed, ErrInvalidIdent, ErrInvalidString, ErrNoRows, ErrNoTx, ErrQueryInProgress, ErrRowsClosed, ErrTxDone, ErrTxInProgress, ExecuteRequest, ExecutionResponse, type ExplainOptions, type GQLEdge, type GQLId, type GQLNode, type GQLPath, type GQLRange, type GQLType, GQLValue, type GQLValueKind, GeodeCipher, GeodeClient, type GeodeConfig, type GeodeError, GrpcTransport, HelloRequest, HelloResponse, MAX_PAGE_SIZE, MAX_QUERY_LENGTH, MockTransport, type NodePattern, NodePatternBuilder, type OperationTiming, Param, type ParameterInfo, PatternBuilder, type PatternElement, type Permission, PingRequest, PingResponse, type PipelineExecutor, type PipelineTx, type PlanOperation, type PoolConfig, PredicateBuilder, type PredicateOp, PreparedStatement, type ProtoError, Row$1 as ProtoRow, type ProtoValue, PullRequest, PullResponse, QueryBuilder, type QueryOptions, type QueryParams, type QueryPlan, type QueryProfile, QueryResult, QueryResultIterator, QuicClientMessage, QuicServerMessage, QuicTransport, QuicTransport as QuicheTransport, type RLSPolicy, type RawEdge, type RetryPolicy, type Role, RollbackRequest, RollbackResponse, type Row, SUPPORTED_SCHEMES, SchemaDefinition, SecurityError, type SortDirection, StateError, type Statement, Status, StatusClass, type StatusClassType, Transaction, type Transport, TransportError, type TransportType, type User, batch, batchAll, batchExec, batchFirst, batchMap, batchParallel, buildBeginRequest, buildCommitRequest, buildExecuteRequest, buildHelloRequest, buildPingRequest, buildPullRequest, buildRollbackRequest, buildRollbackToRequest, buildSavepointRequest, buildTLSConfig, cloneConfig, createAuthClient, createCipher, createClient, createClientWithConfig, createTransport, decodeLengthPrefix, decodeQuicServerMessage, defaultConfig, defaultRetryPolicy, edge, encodeQuicClientMessage, encodeWithLengthPrefix, ensureProtoInitialized, explain, extractParameters, formatDSN, formatPlan, formatProfile, fromJSON, getAddress, getProtoPath, initProtoSync, isAuthError, isDriverError, isGeodeError, isRetryableError, isSentinelError, isSyntaxError, jsToProtoValue, node, parseDSN, parseGQLType, parseRow, parseSchemaFS, pattern, pipelineExec, predicate, prepare, profile, protoValueToJS, query, quoteIdent, quoteString, redactConfig, redactDSN, rowToObject, rowToRecord, sanitizeForLog, sanitizeGraphName, validateConfig, validateHostname, validatePageSize, validateParamName, validateParamValue, validatePort, validateQuery, validateSavepointName, withRetry, withTransaction };